Author: lwall
Date: 2009-08-11 19:28:07 +0200 (Tue, 11 Aug 2009)
New Revision: 27959
Modified:
docs/Perl6/Spec/S02-bits.pod
docs/Perl6/Spec/S04-control.pod
docs/Perl6/Spec/S05-regex.pod
docs/Perl6/Spec/S32-setting-library/Containers.pod
Log:
change embedded comment syntax to #`[...] and variants
define statement_prefix:<void> to return Nil
more s/Capture/Parcel/ mods
Modified: docs/Perl6/Spec/S02-bits.pod
===================================================================
--- docs/Perl6/Spec/S02-bits.pod 2009-08-11 16:14:19 UTC (rev 27958)
+++ docs/Perl6/Spec/S02-bits.pod 2009-08-11 17:28:07 UTC (rev 27959)
@@ -13,8 +13,8 @@
Created: 10 Aug 2004
- Last Modified: 6 Aug 2009
- Version: 172
+ Last Modified: 11 Aug 2009
+ Version: 173
This document summarizes Apocalypse 2, which covers small-scale
lexical items and typological issues. (These Synopses also contain
@@ -135,7 +135,7 @@
Except within a string literal, a C<#> character always introduces a comment in
Perl 6. There are two forms of comment based on C<#>. Embedded
-comments require the C<#> to be followed by one
+comments require the C<#> to be followed by a backtick (C<`>) plus one
or more opening bracketing characters.
All other uses of C<#> are interpreted as single-line comments that
@@ -147,66 +147,35 @@
=item *
Embedded comments are supported as a variant on quoting syntax, introduced
-by C<#> plus any user-selected bracket characters (as defined in
+by C<#`> plus any user-selected bracket characters (as defined in
L</Lexical Conventions> above):
- say #( embedded comment ) "hello, world!";
+ say #`( embedded comment ) "hello, world!";
- $object\#{ embedded comments }.say;
+ $object\#`{ embedded comments }.say;
- $object\ #「
+ $object\ #`「
embedded comments
」.say;
Brackets may be nested, following the same policy as ordinary quote brackets.
-There must be no space between the C<#> and the opening bracket character.
+There must be no space between the C<#`> and the opening bracket character.
(There may be the I<visual appearance> of space for some double-wide
characters, however, such as the corner quotes above.)
-An embedded comment is not allowed as the first thing on the line.
+For multiline comments it is recommended (but not required) to use two or
+more brackets both for visual clarity and to avoid relying too much on
+internal bracket counting heuristics when commenting code that may accidentally
+miscount single brackets:
- #sub foo # line-end comment
- #{ # ILLEGAL, syntax error
- # ...
- #}
+ #`{{
+ say "here is an unmatched } character";
+ }}
-If you wish to have a comment there, you must disambiguate it to
-either an embedded comment or a line-end comment. You can put a
-space in front of it to make it an embedded comment:
+However, it's sometimes better to use pod comments because they are
+implicitly line-oriented.
- #sub foo # line end comment
- #{ # okay, comment
- ... # extends
- } # to here
-
-Or you can put something other than a single C<#>
-to make it a line-end comment. Therefore, if you are commenting out a
-block of code using the line-comment form, we recommend that you use
-C<##>, or C<#> followed by some whitespace, preferably a tab to keep
-any tab formatting consistent:
-
- ##sub foo
- ##{ # okay
- ## ...
- ##}
-
- # sub foo
- # { # okay
- # ...
- # }
-
-
- # sub foo
- # { # okay
- # ...
- # }
-
-However, it's often better to use pod comments because they are
-implicitly line-oriented. And if you have an intelligent syntax
-highlighter that will mark pod comments in a different color, there's
-less visual need for a C<#> on every line.
-
=item *
For all quoting constructs that use user-selected brackets, you can open
@@ -214,14 +183,14 @@
same number of closing brackets. Counting of nested brackets applies only
to pairs of brackets of the same length as the opening brackets:
- say #{{
+ say #`{{
This comment contains unmatched } and { { { { (ignored)
Plus a nested {{ ... }} pair (counted)
}} q<< <<woot>> >> # says " <<woot>> "
Note however that bare circumfix or postcircumfix C<<< <<...>> >>> is
not a user-selected bracket, but the ASCII variant of the C<< «...» >>
-interpolating word list. Only C<#> and the C<q>-style quoters (including
+interpolating word list. Only C<#`> and the C<q>-style quoters (including
C<m>, C<s>, C<tr>, and C<rx>) enable subsequent user-selected brackets.
=item *
@@ -264,7 +233,7 @@
$number\ --;
1+3\ i;
$object\ .say();
- $object\#{ your ad here }.say
+ $object\#`{ your ad here }.say
Another normal use of a you-don't-see-this-space is typically to put
a dotted postfix on the next line:
@@ -272,7 +241,7 @@
$object\ # comment
.say
- $object\#[ comment
+ $object\#`[ comment
].say
$object\
@@ -286,8 +255,7 @@
Although we say that the unspace hides the whitespace from the parser,
it does not hide whitespace from the lexer. As a result, unspace is not
allowed within a token. Additionally, line numbers are still
-counted if the unspace contains one or more newlines. A C<#> following
-such a newline is always an end-of-line comment, as described above.
+counted if the unspace contains one or more newlines.
Since Pod chunks count as whitespace to the language, they are also
swallowed up by unspace. Heredoc boundaries are suppressed, however,
so you can split excessively long heredoc intro lines like this:
@@ -320,13 +288,17 @@
In particular, end-of-line comments do not treat backslash as significant.
If you say:
- #\ (...
+ #`\ (...
+or
+
+ #\ `(...
+
it is an end-of-line comment, not an embedded comment. Write:
- \ #(
- ...
- )
+ \ #`(
+ ...
+ )
to mean the other thing.
@@ -366,8 +338,8 @@
$x\ .++
- $x\#( comment ).++
- $x\#((( comment ))).++
+ $x\#`( comment ).++
+ $x\#`((( comment ))).++
$x\
.++
@@ -380,11 +352,11 @@
# inside unspace
++ # (but without the optional postfix dot)
- $x\#『 comment
+ $x\#`『 comment
more comment
』.++
- $x\#[ comment 1
+ $x\#`[ comment 1
comment 2
=begin podstuff
whatever (pod comments ignore current parser state)
@@ -990,15 +962,33 @@
$_ + 1;
}
-Or if you want to test the how many results you got back from
+Or if you want to test whether you got any results back from
the C<map> or C<for>:
- @inclist = map { $_ + 1 }, @list or Nil( warn 'Empty @list!' );
+ @inclist = do map { $_ + 1 }, @list or Nil( warn 'Empty @list!' );
@inclist = do for @list {
$_ + 1;
} or Nil( warn 'Empty @list!' )
+Since the construct is in the form of a type cast, the parens are required.
+If that syntax is unappealing or you wish to run multiple statements
+in a block, it happens that the C<void> statement prefix also converts
+any value to C<Nil>, so the examples above can be expressed
+without parentheses:
+
+ @inclist = map { $_ + 1 }, @list || void warn 'Empty @list!';
+
+ @inclist = do for @list || void { warn 'Empty @list!'; $warnings++; } {
+ $_ + 1;
+ }
+
+ @inclist = do map { $_ + 1 }, @list or void warn 'Empty @list!';
+
+ @inclist = do for @list {
+ $_ + 1;
+ } or void { warn 'Empty @list!'; $warnings++; }
+
=head2 Immutable types
Objects with these types behave like values, i.e. C<$x === $y> is true
@@ -1686,7 +1676,7 @@
&foo\ ($arg1, $arg2);
&foo\ .($arg1, $arg2);
- &foo\#[
+ &foo\#`[
embedded comment
].($arg1, $arg2);
@@ -2646,11 +2636,10 @@
Colon pairs (but not arrow pairs) are recognized within double angles.
In addition, the double angles allow for comments beginning with C<#>.
These comments work exactly like ordinary comments in Perl code.
-That is, C<#> at beginning of line is always a line-end comment,
-otherwise a following bracket sequence implies an inline comment;
-also, unlike in the shells, any literal C<#> must be quoted, even
+Unlike in the shells, any literal C<#> must be quoted, even
ones without whitespace in front of them, but note that this comes
-more or less for free with a colon pair like C<< :char<#x263a> >>.
+more or less for free with a colon pair like C<< :char<#x263a> >>, since
+comments only work in double angles, not single.
=item *
Modified: docs/Perl6/Spec/S04-control.pod
===================================================================
--- docs/Perl6/Spec/S04-control.pod 2009-08-11 16:14:19 UTC (rev 27958)
+++ docs/Perl6/Spec/S04-control.pod 2009-08-11 17:28:07 UTC (rev 27959)
@@ -720,7 +720,7 @@
X<do>
Other similar forms, where a keyword is followed by code to be controlled by
it, may also take bare statements,
-including C<try>, C<contend>, C<async>, and C<lazy>. These constructs
+including C<try>, C<contend>, C<async>, C<lazy>, and C<void>. These constructs
establish a dynamic scope without necessarily establishing a lexical
scope. (You can always establish a lexical scope explicitly by using
the block form of argument.) As statement introducers, all these
Modified: docs/Perl6/Spec/S05-regex.pod
===================================================================
--- docs/Perl6/Spec/S05-regex.pod 2009-08-11 16:14:19 UTC (rev 27958)
+++ docs/Perl6/Spec/S05-regex.pod 2009-08-11 17:28:07 UTC (rev 27959)
@@ -16,8 +16,8 @@
Created: 24 Jun 2002
- Last Modified: 25 Jul 2009
- Version: 100
+ Last Modified: 11 Aug 2009
+ Version: 101
This document summarizes Apocalypse 5, which is about the new regex
syntax. We now try to call them I<regex> rather than "regular
@@ -272,7 +272,7 @@
m:pos($p)/ pattern / # match at position $p
If the argument is omitted, it defaults to C<$/.to>. (Unlike in
-Perl 5, the string itself has no clue where its last match ended.)
+Perl 5, the string itself has no clue where its last match ended.)
All subrule matches are implicitly passed their starting position.
Likewise, the pattern you supply to a Perl macro's C<is parsed>
trait has an implicit C<:p> modifier.
@@ -601,7 +601,7 @@
=item *
An unescaped C<#> now always introduces a comment. If followed
-by an opening bracket character (and if not in the first column),
+by a backtick and an opening bracket character,
it introduces an embedded comment that terminates with the closing
bracket. Otherwise the comment terminates at the newline.
Modified: docs/Perl6/Spec/S32-setting-library/Containers.pod
===================================================================
--- docs/Perl6/Spec/S32-setting-library/Containers.pod 2009-08-11 16:14:19 UTC
(rev 27958)
+++ docs/Perl6/Spec/S32-setting-library/Containers.pod 2009-08-11 17:28:07 UTC
(rev 27959)
@@ -82,8 +82,8 @@
=item zip
- our List of Capture multi zip ( *@@list )
- our List of Capture multi infix:<Z> ( *@@list )
+ our List of Parcel multi zip ( *@@list )
+ our List of Parcel multi infix:<Z> ( *@@list )
zip takes any number of arrays and returns one tuple for every index.
This is easier to read in an example:
@@ -187,10 +187,10 @@
=item first
- our Item multi method first ( @values: Matcher $test )
- our Item multi first ( Matcher $test, *...@values )
+ our Parcel multi method first ( @values: Matcher $test )
+ our Parcel multi first ( Matcher $test, *...@values )
-C<first> works exactly like C<grep> but returns only the first matching value.
+C<first> searches exactly like C<grep> but returns only the first matching
value.
=item pick
@@ -216,7 +216,7 @@
@byte = (0,1).pick(8, :repl);
for (1..20).pick(*, :repl) -> $die_roll { ... }
-Due to the normal semantics of returning a C<Capture>, a pick of a
+Due to the normal semantics of returning a C<Parcel>, a pick of a
single element may be used as an item without requiring C<.[0]>.
=item join
@@ -234,8 +234,8 @@
=item map
- our List of Capture multi method map ( @values: Code *&expression )
- our List of Capture multi map ( Code $expression, *...@values )
+ our List of Parcel multi method map ( @values: Code *&expression )
+ our List of Parcel multi map ( Code $expression, *...@values )
C<map> returns a lazily evaluated list which is comprised of
the return value of the expression, evaluated once for every
@@ -417,7 +417,7 @@
=item shape
- our Capture method shape (@array: ) is export
+ our Parcel method shape (@array: ) is export
Returns the declared shape of the array, as described in S09.
@@ -475,7 +475,7 @@
This adverb may be applied to any subscripting operation. The
operation returns true if specified element exists. If a slice
-is specified by the subscript, a C<Capture> of C<Bool> is returned,
+is specified by the subscript, a C<Parcel> of C<Bool> is returned,
which can be processed using junctions.
@@ -560,7 +560,7 @@
If C<@array> is multidimensional, C<splice> operates only on the first
dimension, and works with Array References.
-C<splice> returns a C<Capture> of the deleted elements, which behaves as
+C<splice> returns a C<Parcel> of the deleted elements, which behaves as
expected in either list or scalar context.
@@ -619,7 +619,7 @@
This adverb may be applied to any subscripting operation. The
operation returns true if specified element exists. If a slice
-is specified by the subscript, a C<Capture> of C<Bool> is returned,
+is specified by the subscript, a C<Parcel> of C<Bool> is returned,
which can be processed using junctions.
=item keys
