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