Revision 27959

Date:
2009/08/11 17:28:07
Author:
lwall
Revision Log:
change embedded comment syntax to #`[...] and variants
define statement_prefix:<void> to return Nil
more s/Capture/Parcel/ mods
Files:

Legend:

 
Added
 
Removed
 
Modified

  • docs/Perl6/Spec/S02-bits.pod

     
    13 13
    14 14 Created: 10 Aug 2004
    15 15
    16 Last Modified: 6 Aug 2009
    17 Version: 172
    16 Last Modified: 11 Aug 2009
    17 Version: 173
    18 18
    19 19 This document summarizes Apocalypse 2, which covers small-scale
    20 20 lexical items and typological issues. (These Synopses also contain
    … …  
    135 135
    136 136 Except within a string literal, a C<#> character always introduces a comment in
    137 137 Perl 6. There are two forms of comment based on C<#>. Embedded
    138 comments require the C<#> to be followed by one
    138 comments require the C<#> to be followed by a backtick (C<`>) plus one
    139 139 or more opening bracketing characters.
    140 140
    141 141 All other uses of C<#> are interpreted as single-line comments that
    … …  
    147 147 =item *
    148 148
    149 149 Embedded comments are supported as a variant on quoting syntax, introduced
    150 by C<#> plus any user-selected bracket characters (as defined in
    150 by C<#`> plus any user-selected bracket characters (as defined in
    151 151 L</Lexical Conventions> above):
    152 152
    153 say #( embedded comment ) "hello, world!";
    153 say #`( embedded comment ) "hello, world!";
    154 154
    155 $object\#{ embedded comments }.say;
    155 $object\#`{ embedded comments }.say;
    156 156
    157 $object\ #「
    157 $object\ #`「
    158 158 embedded comments
    159 159 」.say;
    160 160
    161 161 Brackets may be nested, following the same policy as ordinary quote brackets.
    162 162
    163 There must be no space between the C<#> and the opening bracket character.
    163 There must be no space between the C<#`> and the opening bracket character.
    164 164 (There may be the I<visual appearance> of space for some double-wide
    165 165 characters, however, such as the corner quotes above.)
    166 166
    167 An embedded comment is not allowed as the first thing on the line.
    167 For multiline comments it is recommended (but not required) to use two or
    168 more brackets both for visual clarity and to avoid relying too much on
    169 internal bracket counting heuristics when commenting code that may accidentally
    170 miscount single brackets:
    168 171
    169 #sub foo # line-end comment
    170 #{ # ILLEGAL, syntax error
    171 # ...
    172 #}
    172 #`{{
    173 say "here is an unmatched } character";
    174 }}
    173 175
    174 If you wish to have a comment there, you must disambiguate it to
    175 either an embedded comment or a line-end comment. You can put a
    176 space in front of it to make it an embedded comment:
    176 However, it's sometimes better to use pod comments because they are
    177 implicitly line-oriented.
    177 178
    178 #sub foo # line end comment
    179 #{ # okay, comment
    180 ... # extends
    181 } # to here
    182
    183 Or you can put something other than a single C<#>
    184 to make it a line-end comment. Therefore, if you are commenting out a
    185 block of code using the line-comment form, we recommend that you use
    186 C<##>, or C<#> followed by some whitespace, preferably a tab to keep
    187 any tab formatting consistent:
    188
    189 ##sub foo
    190 ##{ # okay
    191 ## ...
    192 ##}
    193
    194 # sub foo
    195 # { # okay
    196 # ...
    197 # }
    198
    199
    200 # sub foo
    201 # { # okay
    202 # ...
    203 # }
    204
    205 However, it's often better to use pod comments because they are
    206 implicitly line-oriented. And if you have an intelligent syntax
    207 highlighter that will mark pod comments in a different color, there's
    208 less visual need for a C<#> on every line.
    209
    210 179 =item *
    211 180
    212 181 For all quoting constructs that use user-selected brackets, you can open
    … …  
    214 183 same number of closing brackets. Counting of nested brackets applies only
    215 184 to pairs of brackets of the same length as the opening brackets:
    216 185
    217 say #{{
    186 say #`{{
    218 187 This comment contains unmatched } and { { { { (ignored)
    219 188 Plus a nested {{ ... }} pair (counted)
    220 189 }} q<< <<woot>> >> # says " <<woot>> "
    221 190
    222 191 Note however that bare circumfix or postcircumfix C<<< <<...>> >>> is
    223 192 not a user-selected bracket, but the ASCII variant of the C<< «...» >>
    224 interpolating word list. Only C<#> and the C<q>-style quoters (including
    193 interpolating word list. Only C<#`> and the C<q>-style quoters (including
    225 194 C<m>, C<s>, C<tr>, and C<rx>) enable subsequent user-selected brackets.
    226 195
    227 196 =item *
    … …  
    264 233 $number\ --;
    265 234 1+3\ i;
    266 235 $object\ .say();
    267 $object\#{ your ad here }.say
    236 $object\#`{ your ad here }.say
    268 237
    269 238 Another normal use of a you-don't-see-this-space is typically to put
    270 239 a dotted postfix on the next line:
    … …  
    272 241 $object\ # comment
    273 242 .say
    274 243
    275 $object\#[ comment
    244 $object\#`[ comment
    276 245 ].say
    277 246
    278 247 $object\
    … …  
    286 255 Although we say that the unspace hides the whitespace from the parser,
    287 256 it does not hide whitespace from the lexer. As a result, unspace is not
    288 257 allowed within a token. Additionally, line numbers are still
    289 counted if the unspace contains one or more newlines. A C<#> following
    290 such a newline is always an end-of-line comment, as described above.
    258 counted if the unspace contains one or more newlines.
    291 259 Since Pod chunks count as whitespace to the language, they are also
    292 260 swallowed up by unspace. Heredoc boundaries are suppressed, however,
    293 261 so you can split excessively long heredoc intro lines like this:
    … …  
    320 288 In particular, end-of-line comments do not treat backslash as significant.
    321 289 If you say:
    322 290
    323 #\ (...
    291 #`\ (...
    324 292
    293 or
    294
    295 #\ `(...
    296
    325 297 it is an end-of-line comment, not an embedded comment. Write:
    326 298
    327 \ #(
    328 ...
    329 )
    299 \ #`(
    300 ...
    301 )
    330 302
    331 303 to mean the other thing.
    332 304
    … …  
    366 338
    367 339 $x\ .++
    368 340
    369 $x\#( comment ).++
    370 $x\#((( comment ))).++
    341 $x\#`( comment ).++
    342 $x\#`((( comment ))).++
    371 343
    372 344 $x\
    373 345 .++
    … …  
    380 352 # inside unspace
    381 353 ++ # (but without the optional postfix dot)
    382 354
    383 $x\#『 comment
    355 $x\#`『 comment
    384 356 more comment
    385 357 』.++
    386 358
    387 $x\#[ comment 1
    359 $x\#`[ comment 1
    388 360 comment 2
    389 361 =begin podstuff
    390 362 whatever (pod comments ignore current parser state)
    … …  
    990 962 $_ + 1;
    991 963 }
    992 964
    993 Or if you want to test the how many results you got back from
    965 Or if you want to test whether you got any results back from
    994 966 the C<map> or C<for>:
    995 967
    996 @inclist = map { $_ + 1 }, @list or Nil( warn 'Empty @list!' );
    968 @inclist = do map { $_ + 1 }, @list or Nil( warn 'Empty @list!' );
    997 969
    998 970 @inclist = do for @list {
    999 971 $_ + 1;
    1000 972 } or Nil( warn 'Empty @list!' )
    1001 973
    974 Since the construct is in the form of a type cast, the parens are required.
    975 If that syntax is unappealing or you wish to run multiple statements
    976 in a block, it happens that the C<void> statement prefix also converts
    977 any value to C<Nil>, so the examples above can be expressed
    978 without parentheses:
    979
    980 @inclist = map { $_ + 1 }, @list || void warn 'Empty @list!';
    981
    982 @inclist = do for @list || void { warn 'Empty @list!'; $warnings++; } {
    983 $_ + 1;
    984 }
    985
    986 @inclist = do map { $_ + 1 }, @list or void warn 'Empty @list!';
    987
    988 @inclist = do for @list {
    989 $_ + 1;
    990 } or void { warn 'Empty @list!'; $warnings++; }
    991
    1002 992 =head2 Immutable types
    1003 993
    1004 994 Objects with these types behave like values, i.e. C<$x === $y> is true
    … …  
    1686 1676
    1687 1677 &foo\ ($arg1, $arg2);
    1688 1678 &foo\ .($arg1, $arg2);
    1689 &foo\#[
    1679 &foo\#`[
    1690 1680 embedded comment
    1691 1681 ].($arg1, $arg2);
    1692 1682
    … …  
    2646 2636 Colon pairs (but not arrow pairs) are recognized within double angles.
    2647 2637 In addition, the double angles allow for comments beginning with C<#>.
    2648 2638 These comments work exactly like ordinary comments in Perl code.
    2649 That is, C<#> at beginning of line is always a line-end comment,
    2650 otherwise a following bracket sequence implies an inline comment;
    2651 also, unlike in the shells, any literal C<#> must be quoted, even
    2639 Unlike in the shells, any literal C<#> must be quoted, even
    2652 2640 ones without whitespace in front of them, but note that this comes
    2653 more or less for free with a colon pair like C<< :char<#x263a> >>.
    2641 more or less for free with a colon pair like C<< :char<#x263a> >>, since
    2642 comments only work in double angles, not single.
    2654 2643
    2655 2644 =item *
    2656 2645

  • docs/Perl6/Spec/S04-control.pod

     
    720 720 X<do>
    721 721
    722 722 Other similar forms, where a keyword is followed by code to be controlled by it, may also take bare statements,
    723 including C<try>, C<contend>, C<async>, and C<lazy>. These constructs
    723 including C<try>, C<contend>, C<async>, C<lazy>, and C<void>. These constructs
    724 724 establish a dynamic scope without necessarily establishing a lexical
    725 725 scope. (You can always establish a lexical scope explicitly by using
    726 726 the block form of argument.) As statement introducers, all these

  • docs/Perl6/Spec/S05-regex.pod

     
    16 16
    17 17 Created: 24 Jun 2002
    18 18
    19 Last Modified: 25 Jul 2009
    20 Version: 100
    19 Last Modified: 11 Aug 2009
    20 Version: 101
    21 21
    22 22 This document summarizes Apocalypse 5, which is about the new regex
    23 23 syntax. We now try to call them I<regex> rather than "regular
    … …  
    272 272 m:pos($p)/ pattern / # match at position $p
    273 273
    274 274 If the argument is omitted, it defaults to C<$/.to>. (Unlike in
    275 Perl 5, the string itself has no clue where its last match ended.)
    275 Perl 5, the string itself has no clue where its last match ended.)
    276 276 All subrule matches are implicitly passed their starting position.
    277 277 Likewise, the pattern you supply to a Perl macro's C<is parsed>
    278 278 trait has an implicit C<:p> modifier.
    … …  
    601 601 =item *
    602 602
    603 603 An unescaped C<#> now always introduces a comment. If followed
    604 by an opening bracket character (and if not in the first column),
    604 by a backtick and an opening bracket character,
    605 605 it introduces an embedded comment that terminates with the closing
    606 606 bracket. Otherwise the comment terminates at the newline.
    607 607

  • docs/Perl6/Spec/S32-setting-library/Containers.pod

     
    82 82
    83 83 =item zip
    84 84
    85 our List of Capture multi zip ( *@@list )
    86 our List of Capture multi infix:<Z> ( *@@list )
    85 our List of Parcel multi zip ( *@@list )
    86 our List of Parcel multi infix:<Z> ( *@@list )
    87 87
    88 88 zip takes any number of arrays and returns one tuple for every index.
    89 89 This is easier to read in an example:
    … …  
    187 187
    188 188 =item first
    189 189
    190 our Item multi method first ( @values: Matcher $test )
    191 our Item multi first ( Matcher $test, *@values )
    190 our Parcel multi method first ( @values: Matcher $test )
    191 our Parcel multi first ( Matcher $test, *@values )
    192 192
    193 C<first> works exactly like C<grep> but returns only the first matching value.
    193 C<first> searches exactly like C<grep> but returns only the first matching value.
    194 194
    195 195 =item pick
    196 196
    … …  
    216 216 @byte = (0,1).pick(8, :repl);
    217 217 for (1..20).pick(*, :repl) -> $die_roll { ... }
    218 218
    219 Due to the normal semantics of returning a C<Capture>, a pick of a
    219 Due to the normal semantics of returning a C<Parcel>, a pick of a
    220 220 single element may be used as an item without requiring C<.[0]>.
    221 221
    222 222 =item join
    … …  
    234 234
    235 235 =item map
    236 236
    237 our List of Capture multi method map ( @values: Code *&expression )
    238 our List of Capture multi map ( Code $expression, *@values )
    237 our List of Parcel multi method map ( @values: Code *&expression )
    238 our List of Parcel multi map ( Code $expression, *@values )
    239 239
    240 240 C<map> returns a lazily evaluated list which is comprised of
    241 241 the return value of the expression, evaluated once for every
    … …  
    417 417
    418 418 =item shape
    419 419
    420 our Capture method shape (@array: ) is export
    420 our Parcel method shape (@array: ) is export
    421 421
    422 422 Returns the declared shape of the array, as described in S09.
    423 423
    … …  
    475 475
    476 476 This adverb may be applied to any subscripting operation. The
    477 477 operation returns true if specified element exists. If a slice
    478 is specified by the subscript, a C<Capture> of C<Bool> is returned,
    478 is specified by the subscript, a C<Parcel> of C<Bool> is returned,
    479 479 which can be processed using junctions.
    480 480
    481 481
    … …  
    560 560 If C<@array> is multidimensional, C<splice> operates only on the first
    561 561 dimension, and works with Array References.
    562 562
    563 C<splice> returns a C<Capture> of the deleted elements, which behaves as
    563 C<splice> returns a C<Parcel> of the deleted elements, which behaves as
    564 564 expected in either list or scalar context.
    565 565
    566 566
    … …  
    619 619
    620 620 This adverb may be applied to any subscripting operation. The
    621 621 operation returns true if specified element exists. If a slice
    622 is specified by the subscript, a C<Capture> of C<Bool> is returned,
    622 is specified by the subscript, a C<Parcel> of C<Bool> is returned,
    623 623 which can be processed using junctions.
    624 624
    625 625 =item keys