Author: larry Date: Fri Apr 7 19:15:01 2006 New Revision: 8610 Modified: doc/trunk/design/syn/S02.pod
Log: Embedded comments are much more generally useful than long dots, especially when formatted to look good as a pseudo .method call. Modified: doc/trunk/design/syn/S02.pod ============================================================================== --- doc/trunk/design/syn/S02.pod (original) +++ doc/trunk/design/syn/S02.pod Fri Apr 7 19:15:01 2006 @@ -53,6 +53,62 @@ =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. Certain quoting +tokens may make use of C<#> characters as delimiters without starting +a comment. + +=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>. (Doesn't have to be "comment"--any unrecognized POD +stream will do to make it a comment. Bare C<=begin> and C<=end> +probably aren't good enough though, unless you want all your comments +to end up in the manpage...) + +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> +and C<=end> combined. As with C<=begin> and C<=end>, a comment started +in code reverts to code afterwards. + +Since there is a newline before the first C<=>, the POD form of comment +counts as whitespace equivalent to a newline. + +=item * + +Embedded comments are supported as a variant on quoting syntax, introduced +by C<.#> and delimited by user-selected characters. + + say .#( embedded comment ) "hello, world!"; + + $object.#/ embedded comments /.say; + + $object.#[ + embedded comments + ].say; + +The delimiters of the C<.#//> embedded comment form may be chosen +from the same set that are valid for ordinary C<q//> quote forms, +and follow the same policy on the nesting of bracketing characters. +Unlike the other two forms of comment, the embedded form does not +count as whitespace. + +As a variant of the embedded form, a single dot followed by a space +is equivalent to C<.#.> (plus an extra dot at the end) so you can +write a small (generally whitespace only) comment as: + + %hash. .{$key} + @array. .{$key} + +which is useful for lining up postfixes. This is known as the "long dot", +partly because it substitutes for a dot without the need for a third dot: + + $object. .say(); + +=item * + In general, whitespace is optional in Perl 6 except where it is needed to separate constructs that would be misconstrued as a single token or other syntactic unit. (In other words, Perl 6 follows the standard @@ -68,13 +124,9 @@ may occur after a term. If a given token may be interpreted as either a postfix operator or an infix operator, the infix operator requires space before it. Postfix operators may never have intervening -space, though they may have an intervening dot, or a "long dot" that begins -and ends with dots and contains whitespace and commentary between the dots. -The pattern for "long dot" is C<< m:p/\.+ \s<ws> \./ >>. (A minor -consequence of this is that the C<< postfix:<...> >> operator should not -be followed by whitespace. Also, if you put space after the C<..> range -operator, it should have space before it as well. But you already do it -that way, right?) +space, though they may have an intervening dot. If further separation +is desired, an embedded comment may be used as described above, as long +as no whitespace occurs outside the embedded comment. For instance, if you were to add your own C<< infix:<++> >> operator, then it must have space before it. The normal autoincrementing @@ -87,64 +139,39 @@ $x. .++ - $x... .++ + $x.#. .++ - $x.................. .++ + $x. comment .++ - $x... - .++ + $x.#( comment ).++ - $x... # comment - # more comment + $x. .++ - $x... # comment - =begin podstuff - whatever - =end podstuff + $x.#. .++ -A consequence of this rule is that, in the absence of a "long dot", -a dot with whitespace in front of it is always considered a method -call on C<$_> where a term is expected. If a term is not expected -at this point, it is a syntax error. (Unless, of course, there is -an infix operator of that name beginning with dot. You could define -a Fortranly C<< infix:<.EQ.> >>, for instance, if the fit took you. -But you'll have to be sure to always put whitespace in front of it, or -it would be interpreted as a postfix method call instead.) - -The long dot form of the C<...> postfix is C<0. ...> rather than -C<0. ....> because the long dot eats the first dot after the whitespace. -It does not follow that you can write C<0....> because that would -take the first three dots under the longest token rule. (The long dot -does not count as a longer token because the longest-token rule only -applies to the fixed prefix of any rule with variable components.) - -=item * - -Single-line comments work as in Perl 5, starting with a C<#> character -and ending with the subsequent newline. They count as whitespace for -purposes of separation. Certain quoting tokens may make use of C<#> -characters as delimiters without starting a comment. - -=item * - -Multiline comments will be provided by extending the syntax of POD -to nest C<=begin comment>/C<=end comment> correctly without the need -for C<=cut>. (Doesn't have to be "comment"--any unrecognized POD -stream will do to make it a comment. Bare C<=begin> and C<=end> -probably aren't good enough though, unless you want all your comments -to end up in the manpage...) - -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> -and C<=end> combined. As with C<=begin> and C<=end>, a comment started -in code reverts to code afterwards. + $x.#[ # comment + # more comment + ].++ -=item * + $x.#[ comment 1 + comment 2 + =begin podstuff + whatever (pod comments ignore current parser state) + =end podstuff + comment 3 + ].++ -Intra-line comments will not be supported in standard Perl (but it would -be trivial to declare them as a macro). +A consequence of the postfix rule is that (except when delimiting a +a quote or comment) a dot with whitespace in front of it is always +considered a method call on C<$_> where a term is expected. If a +term is not expected at this point, it is a syntax error. (Unless, +of course, there is an infix operator of that name beginning with +dot. You could, for instance, define a Fortranly C<< infix:<.EQ.> >> +if the fit took you. But you'll have to be sure to always put +whitespace in front of it, or it would be interpreted as a postfix +method call instead.) =back @@ -390,9 +417,7 @@ Subscripts now consistently dereference the container produced by whatever was to their left. Whitespace is not allowed between a variable name and its subscript. However, there is a corresponding -B<dot> form of each subscript (C<@foo.[1]> and C<%bar.{'a'}>). -There is also a "long dot" form which allows optional whitespace -between dots. (The long dot is not allowed when interpolating). Constant +B<dot> form of each subscript (C<@foo.[1]> and C<%bar.{'a'}>). Constant string subscripts may be placed in angles, so C<%bar.{'a'}> may also be written as C<< %bar<a> >> or C<< %bar.<a> >>. @@ -482,12 +507,14 @@ &foo($arg1, $arg2); -Whitespace is not allowed before the parens, but there is a corresponding -C<.()> operator, plus a "long dot" form which allows you to insert optional whitespace between dots: +Whitespace is not allowed before the parens, but there is a +corresponding C<.()> operator, plus the "long dot" forms that allow +you to insert optional whitespace between dots: &foo. .($arg1, $arg2); - &foo... #comment - .($arg1, $arg2); + &foo.#[ + embedded comment + ].($arg1, $arg2); =item * @@ -1134,15 +1161,18 @@ =item 6. A sequence of one or more unparenthesized method call, followed by any of 1 through 5 +=item 7. An embedded comment that uses bracketing characters, such +as .#(comment). + =back In other words, this is legal: - "Val = $a.ord.as('%x')\n" + "Val = $a.ord.#( Yikes! ).as('%x')\n" and is equivalent to - "Val = { $a.ord.as('%x') }\n" + "Val = { $a.ord.#( Yikes! ).as('%x') }\n" =item *