Author: larry
Date: Tue Jun 12 11:33:55 2007
New Revision: 14418

Modified:
   doc/trunk/design/syn/S02.pod
   doc/trunk/design/syn/S03.pod

Log:
Line-initial #{ is no longer a line-end comment, but starts a "block comment",
    guaranteed to catch at compile time the accidental use of "#{...} foo();".
    (Old behavior would silently not execute foo().)
Also some more random filling-out of S3.  Work in progress.


Modified: doc/trunk/design/syn/S02.pod
==============================================================================
--- doc/trunk/design/syn/S02.pod        (original)
+++ doc/trunk/design/syn/S02.pod        Tue Jun 12 11:33:55 2007
@@ -12,9 +12,9 @@
 
   Maintainer: Larry Wall <[EMAIL PROTECTED]>
   Date: 10 Aug 2004
-  Last Modified: 8 Jun 2007
+  Last Modified: 12 Jun 2007
   Number: 2
-  Version: 110
+  Version: 111
 
 This document summarizes Apocalypse 2, which covers small-scale
 lexical items and typological issues.  (These Synopses also contain
@@ -97,19 +97,14 @@
 
 =item *
 
-Single-line comments work as in Perl 5, starting with a C<#> character
-and ending at the subsequent newline.  They count as whitespace
-equivalent to newline for purposes of separation.  Unlike in Perl 5,
-C<#> may not be used as the delimiter in quoting constructs.
-
-=item *
-
-Multiline comments are provided by extending the syntax of POD
-to nest C<=begin comment>/C<=end comment> correctly without the need
-for C<=cut>.  The format name does not have to be C<comment> -- any
-unrecognized format name will do to make it a comment.  (However,
-bare C<=begin> and C<=end> probably aren't good enough, because all
-comments in them will show up in the formatted output.)
+POD sections may be used reliably as multiline comments in Perl 6.
+Unlike in Perl 5, POD syntax now requires that C<=begin comment>
+and C<=end comment> delimit a POD block correctly without the need
+for C<=cut>.  (In fact, C<=cut> is now gone.)  The format name does
+not have to be C<comment> -- any unrecognized format name will do
+to make it a comment.  (However, bare C<=begin> and C<=end> probably
+aren't good enough, because all comments in them will show up in the
+formatted output.)
 
 We have single paragraph comments with C<=for comment> as well.
 That lets C<=for> keep its meaning as the equivalent of a C<=begin>
@@ -121,6 +116,19 @@
 
 =item *
 
+Except when quoted, a C<#> character always introduces a comment in
+Perl 6.  There are three forms of comment based on C<#>.  Embedded
+comments and block comments require the C<#> to be followed by one
+or more opening bracketing character.
+
+All other uses of C<#> are interpreted as single-line comments that
+work just as in Perl 5, starting with a C<#> character and
+ending at the subsequent newline.  They count as whitespace equivalent
+to newline for purposes of separation.  Unlike in Perl 5, C<#>
+may not be used as the delimiter in quoting constructs.
+
+=item *
+
 Embedded comments are supported as a variant on quoting syntax, introduced
 by C<#> plus any user-selected bracket characters (as defined in
 L</Lexical Conventions> above):
@@ -139,12 +147,47 @@
 (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 since it
+would instead be parsed as a block comment, as described next.
+
 =item *
 
-As a special case to facilitate commenting out sections of code with
-C<s/^/#/>, C<#> on the beginning of line is always considered a line-end
-comment rather than an embedded comment, even if followed by a bracketing
-character.
+Unlike embedded comments, which are character-oriented, block comments
+are line-oriented.  To facilitate the common practice of commenting out
+sections of code by prefixing each line with C<#>, if the initial C<#>
+on the line is immediately followed by one or more opening brackets,
+it is treated as a line-oriented form of bracket quoting, and may
+be terminated I<only> by a line matching the corresponding close
+bracket, which (unlike embedded comments) must also be prefixed with
+an initial C<#>.  For example, a opening line matching
+
+    /^^ '#{' \s /
+
+it may be terminated I<only> by a line matching
+
+    /^^ '#}' \s /
+
+The entire final line counts as part of the comment.  It does
+not matter whether the intervening lines start with C<#> or not.
+Block comments may be nested within other block comments (with
+the same or differing brackets) but will ignore any other comment
+mechanism including POD, so this mechanism may be used to hide POD
+even from the pod parser, along with any associated code.  The parser
+must report mismatched openers or closers to prevent, for example,
+unwitting use of bare C<}> as a closer for an opening C<#{>.
+
+In addition to supporting the practice of commenting out code with
+line comments, an additional motivation for this is to promote human
+recognition of the end of the comment when the opener could be quite
+far away, without requiring that all intervening lines use C</^'#'/> comments.
+Also, using the ordinary embedded comment mechanism tends to be fragile
+in the face of strings containing bracket characters, and the probability
+of such bracket skew increases with the length of the commented code.
+
+The POD parser must also recognize these comments in order to ignore
+them.  For instance, it could treat C<#[[> and C<#]]> as a shorthand for
+C<=begin comment_2square> and C<=end comment_2square>.  (The C<2> indicates
+degree of repetition, as described below.)
 
 =item *
 

Modified: doc/trunk/design/syn/S03.pod
==============================================================================
--- doc/trunk/design/syn/S03.pod        (original)
+++ doc/trunk/design/syn/S03.pod        Tue Jun 12 11:33:55 2007
@@ -605,7 +605,7 @@
 
 =item *
 
-infix:<x>, string replication
+infix:<x>, string/buffer replication
 
     $string x $count
 
@@ -647,34 +647,34 @@
 
 infix:{'+<'}, numeric shift left
 
-    +<
+    $integer +< $bits
 
 =item *
 
 infix:{'+>'}, numeric shift right
 
-    +>
+    $integer +> $bits
 
 By default, signed types do sign extension, while unsigned types do not, but
 this may be enabled or disabled with a C<:signed> or C<:!signed> adverb.
 
 =item *
 
-infix:<~&>, string bitwise and
+infix:<~&>, buffer bitwise and
 
-    ~&
+    $x ~& $y
 
 =item *
 
 infix:{'~<'}, buffer bitwise shift left
 
-    ~<
+    $buf ~< $bits
 
 =item *
 
 infix:{'~>'}, buffer bitwise shift right
 
-    ~>
+    $buf ~> $bits
 
 Sign extension is not done by default but may be enabled with a C<:signed>
 adverb.
@@ -683,7 +683,7 @@
 
 infix:<?&>, boolean bitwise and
 
-    ?&
+    $x ?& $y
 
 =back
 
@@ -699,55 +699,55 @@
 
 infix:<+>, numeric addition
 
-    +
+    $x + $y
 
 =item *
 
 infix:<->, numeric subtraction
 
-    -
+    $x - $y
 
 =item *
 
-infix:<~>, string concatenation
+infix:<~>, string/buffer concatenation
 
-    ~
+    $x ~ $y
 
 =item *
 
 infix:<+|>, numeric bitwise inclusive or
 
-    +|
+    $x +| $y
 
 =item *
 
 infix:<+^> numeric bitwise exclusive or
 
-    +^
+    $x +^ $y
 
 =item *
 
-infix:<~|>, string bitwise inclusive or
+infix:<~|>, buffer bitwise inclusive or
 
-    ~|
+    $x ~| $y
 
 =item *
 
-infix:<~^> string bitwise exclusive or
+infix:<~^> buffer bitwise exclusive or
 
-    ~^
+    $x ~^ $y
 
 =item *
 
 infix:<?|>, boolean bitwise inclusive or
 
-    ?|
+    $x ?| $y
 
 =item *
 
 infix:<?^> boolean bitwise exclusive or
 
-    ?^
+    $x ?^ $y
 
 =back
 
@@ -759,7 +759,7 @@
 
 infix:<&>, all() operator
 
-    &
+    $x & $y
 
 =back
 
@@ -771,13 +771,13 @@
 
 infix:<|>, any() operator
 
-    |
+    $x | $y
 
 =item *
 
 infix:<^>, one() operator
 
-    ^
+    $x ^ $y
 
 =back
 
@@ -804,13 +804,13 @@
 
 infix:<but>
 
-    but
+    $value but Mixin
 
 =item *
 
 infix:<does>
 
-    does
+    $object does Mixin
 
 =item *
 
@@ -891,7 +891,7 @@
 
 Smart match
 
-    ~~
+    $obj ~~ $pattern
 
 Perl 5's C<=~> becomes the "smart match" operator C<~~>, with an
 extended set of semantics.  See L</Smart matching> for details.
@@ -958,7 +958,7 @@
 
 infix:<&&>, short-circuit and
 
-    &&
+    $condition && $whentrue
 
 Returns the left argument if the left argument is false, otherwise
 evaluates and returns the right argument.  In list context forces
@@ -975,7 +975,7 @@
 
 infix:<||>, short-circuiting inclusive-or
 
-    ||
+    $condition || $whenfalse
 
 Returns the left argument if it's true, otherwise evaluates and returns
 the right argument.  It is specifically allowed to use a list or array
@@ -990,7 +990,7 @@
 
 infix:<^^>, exclusive-or
 
-    ^^
+    $x ^^ $y
 
 Returns the true argument if there is one (and only one).  Returns
 C<Bool::False> if both arguments are false or both arguments are true.
@@ -1001,7 +1001,7 @@
 
 infix:<//>, defined-or
 
-    //
+    $value // $default
 
 Returns the left argument if it's defined, otherwise evaluates and
 returns the right argument.  In list context forces a false return
@@ -1026,7 +1026,7 @@
 
 =item *
 
-?? !!
+Conditional operator
 
     say "My answer is: ", $maybe ?? "yes" !! "no";
 
@@ -1092,7 +1092,7 @@
 
 infix:<:=>, run-time binding
 
-    :=
+    $signature := $capture
 
 A new form of assignment is present in Perl 6, called I<binding>, used in
 place of typeglob assignment.  It is performed with the C<:=> operator.
@@ -1127,7 +1127,7 @@
 
 infix:<::=>, compile-time binding
 
-    ::=
+    $signature ::= $capture
 
 This does the same as C<:=> except it does it at compile time.  (This implies
 that the expression on the right is also evaluated at compile time; it does
@@ -1250,9 +1250,9 @@
 
 Cross hyperoperators
 
-    X~X
-    X*X
-    XeqvX
+    @files X~X '.' X~X @extensions
+    1..10 X*X 1..10
+    @x XeqvX @y
     etc.
 
 See L</Cross operators>.
@@ -1437,7 +1437,7 @@
 
 infix:<and>, short-circuit and
 
-    and
+    $condition and $whentrue
 
 Returns the left argument if the left argument is false, otherwise
 evaluates and returns the right argument.  In list context forces
@@ -1454,7 +1454,7 @@
 
 infix:<or>, short-circuit inclusive or
 
-    or
+    $condition or $whenfalse
 
 Returns the left argument if it's true, otherwise evaluates and
 returns the right argument.  In list context forces a false return
@@ -1464,7 +1464,7 @@
 
 infix:<xor>, exclusive or
 
-    xor
+    $x xor $y
 
 Returns the true argument if there is one (and only one).  Returns
 C<Bool::False> if both arguments are false or both arguments are true.
@@ -1475,7 +1475,7 @@
 
 infix:<err>, short-circuit defined-or
 
-    err
+    $value err $default
 
 Returns the left argument if it's defined, otherwise evaluates and
 returns the right argument.  In list context forces a false return

Reply via email to