Sync synopses

share/Spec/S01-overview.pod

@@ -1,3 +1,4 @@
+
 =encoding utf8
 
 =head1 TITLE

share/Spec/S02-bits.pod

@@ -1,3 +1,4 @@
+
 =encoding utf8
 
 =head1 TITLE
@@ -377,7 +378,7 @@ be written in any of these forms:
 
     $x\         # comment
                 # inside unspace
-    ++          # (but without the optional postfix dot) 
+    ++          # (but without the optional postfix dot)
 
     $x\#『      comment
                 more comment
@@ -416,7 +417,7 @@ will always be interpreted as
 
 but never as
 
-    foo.method  
+    foo.method
 
 Use some variant of
 
@@ -1185,7 +1186,7 @@ type on its left. Parametric types are named using square brackets, so:
 
 actually means:
 
-    my Hash:of(Array:of(Recipe)) %book; 
+    my Hash:of(Array:of(Recipe)) %book;
 
 Because the actual variable can be hard to find when complex types are
 specified, there is a postfix form as well:
@@ -1601,7 +1602,7 @@ hash, all named arguments.
 
 All prefix sigil operators accept one positional argument, evaluated in
 item context as a rvalue.  They can interpolate in strings if called with
-parentheses.  The special syntax form C<$()> translates into C<$( $.ast // Str($/) )> 
+parentheses.  The special syntax form C<$()> translates into C<$( $.ast // Str($/) )>
 to operate on the current match object; similarly C<@()> and C<%()> can
 extract positional and named submatches.
 
@@ -1761,7 +1762,7 @@ elements, then the second elements, etc.  For more on C<sort> see S29.
 Many of the special variables of Perl 5 are going away.  Those that
 apply to some object such as a filehandle will instead be attributes
 of the appropriate object.  Those that are truly global will have
-global alphabetic names, such as C<$*PID> or C<@*ARGS>. 
+global alphabetic names, such as C<$*PID> or C<@*ARGS>.
 
 =item *
 
@@ -2416,8 +2417,8 @@ An identifier may be extended with multiple named identifier
 extensions, in which case the names matter but their order does not.
 These name the same module:
 
-    use ThatModule:ver<2.7.18.28.18>:auth<Somebody>
     use ThatModule:auth<Somebody>:ver<2.7.18.28.18>
+    use ThatModule:ver<2.7.18.28.18>:auth<Somebody>
 
 Adverbial syntax will be described more fully later.
 
@@ -3092,11 +3093,11 @@ a single character:
 
 You may also put one or more decimal numbers inside the square brackets:
 
-    "\c[13,10]"	# CRLF
+    "\c[13,10]" # CRLF
 
 Any single decimal number may omit the brackets:
 
-    "\c8"	# backspace
+    "\c8" # backspace
 
 (Within a regex you may also use C<\C> to match a character that is
 not the specified character.)

share/Spec/S03-operators.pod

@@ -481,7 +481,7 @@ For digits we have ranges like:
     0..9        # ASCII
     ٠..٩        # Arabic-Indic
     ०..९        # Devangari
-    ০..৯        # Bengali 
+    ০..৯        # Bengali
     ੦..੯        # Gurmukhi
     ૦..૯        # Gujarati
     ୦..୯        # Oriya
@@ -1062,8 +1062,8 @@ See L</Range and RangeIterator semantics>.
 
 Note that these differ:
 
-    0 ..^ 10	# 0 .. 9
-    0 .. ^10	# 0 .. (0..9)
+    0 ..^ 10  # 0 .. 9
+    0 .. ^10  # 0 .. (0..9)
 
 (It's not yet clear what the second one should mean, but whether it
 succeeds or fails, it won't do what you want.)
@@ -1702,23 +1702,23 @@ how many of the preceding values to pay attention to (and which the
 operator must track internally).  Demonstration of this falls to the
 lot of the venerable Fibonacci sequence:
 
-    1, 1 ... { $^y + $^z }	# 1,1,2,3,5,8...
-    1, 1 ... &infix:<+>		# 1,1,2,3,5,8...
+    1, 1 ... { $^y + $^z }   # 1,1,2,3,5,8...
+    1, 1 ... &infix:<+>      # 1,1,2,3,5,8...
 
 More typically the function is unary, in which case any extra values
 in the list may be construed as human-readable documentation:
 
-    0,2,4 ... { $_ + 2 }	# same as 1..*:by(2)
-    <a b c> ... { .succ }	# same as 'a'..*
+    0,2,4 ... { $_ + 2 }    # same as 1..*:by(2)
+    <a b c> ... { .succ }   # same as 'a'..*
 
 The function need not be monotonic, of course:
 
-    1 ... { -$_ }		# 1, -1, 1, -1, 1, -1...
-    False ... &prefix:<!>	# False, True, False...
+    1 ... { -$_ }          # 1, -1, 1, -1, 1, -1...
+    False ... &prefix:<!>  # False, True, False...
 
 The function can be 0-ary as well:
 
-    () ... { rand }		# list of random numbers
+    () ... { rand }   # list of random numbers
 
 The function may also be slurpy (*-ary), in which case all the
 preceding values are passed in (which means they must all be cached
@@ -1732,8 +1732,8 @@ if they do match you may interleave unrelated sequences:
 If the right operand is C<*> (Whatever) and the sequence is obviously
 arithmetic or geometric, the appropriate function is deduced:
 
-    1, 3, 5 ... *		# odd numbers
-    1, 2, 4 ... *		# powers of 2
+    1, 3, 5 ... *   # odd numbers
+    1, 2, 4 ... *   # powers of 2
 
 Conjecture: other such patterns may be recognized in the future,
 depending on which unrealistic benchmarks we want to run faster.  C<:)>
@@ -3076,8 +3076,8 @@ as a default because the more specific types listed above it didn't match.
     Any       Num       numeric equality        +$_ == X
     Any       Str       string equality         ~$_ eq X
 
-    Hash      Pair      test hash mapping       $_{Xkey} ~~ Xval
-    Any       Pair      test object attribute   .Xkey ~~ Xval (e.g. filetests)
+    Hash      Pair      test hash mapping       $_{X.key} ~~ X.value
+    Any       Pair      test object attribute   ."{X.key}" ~~ X.value (e.g. filetests)
 
     Set       Set       identical sets          $_ === X
     Hash      Set       hash keys same set      $_.keys === X
@@ -3152,8 +3152,8 @@ the table assumes the following types will behave similarly:
     List Seq                    Array
     KeySet KeyBag KeyHash       Hash
     named values created with
-	   Class, Enum, or Role,
-	   or generic type binding  Type
+      Class, Enum, or Role,
+      or generic type binding   Type
     Subst                       Regex
     Char Cat                    Str
     Int UInt etc.               Num
@@ -3481,7 +3481,7 @@ autovivifies to the operator's identify value.  So if you say:
 
 it is more or less equivalent to:
 
-    $x = [-]() unless defined $x;	# 0 for [-]()
+    $x = [-]() unless defined $x;  # 0 for [-]()
     $x = $x - 1;
 
 and $x ends up with -1 in it, as expected.
@@ -3490,7 +3490,7 @@ Hence you may correctly write:
 
     my Num $prod;
     for @factors -> $f {
-	$prod *= $f;
+        $prod *= $f;
     }
 
 While this may seem marginally useful in the scalar variable case,
@@ -4061,7 +4061,7 @@ to include:
     our $foo            # lexically scoped alias to package variable
     has $foo            # object attribute
     state $foo          # persistent lexical (cloned with closures)
-    constant $foo       # lexically scoped compile-time constant
+    constant $foo       # "our" scoped compile-time constant
 
 Variable declarators such as C<my> now take a I<signature> as their
 argument.  (The syntax of function signatures is described more fully in S06.)

share/Spec/S04-control.pod

@@ -1,3 +1,4 @@
+
 =encoding utf8
 
 =head1 TITLE
@@ -12,8 +13,8 @@ Synopsis 4: Blocks and Statements
 
     Created: 19 Aug 2004
 
-    Last Modified: 16 Jun 2009
-    Version: 80
+    Last Modified: 3 Jul 2009
+    Version: 81
 
 This document summarizes Apocalypse 4, which covers the block and
 statement syntax of Perl.
@@ -94,7 +95,7 @@ declared "C<my $x>".
 As in Perl 5, "C<our $foo>" introduces a lexically scoped alias for
 a variable in the current package.
 
-The new C<constant> declarator introduces a lexically scoped name
+The new C<constant> declarator introduces an "our"-scoped name
 for a compile-time constant, either a variable or named value, which
 may be initialized with a pseudo-assignment:
 
@@ -150,7 +151,7 @@ this still works:
 
     my $x = [
         sub { 3 },  # this comma is not optional
-        sub { 3 }   # the statement won't terminate here 
+        sub { 3 }   # the statement won't terminate here
     ];
 
 However, a hash composer may never occur at the end of a line.  If the
@@ -521,7 +522,7 @@ the bare block is not a do-once.  Instead C<do {...}> is the do-once
 loop (which is another reason you can't put a statement
 modifier on it; use C<repeat> for a test-at-the-end loop).
 
-For any statement, prefixing with a C<do> allows you to 
+For any statement, prefixing with a C<do> allows you to
 return the value of that statement and use it in an expression:
 
     $x = do if $a { $b } else { $c };
@@ -573,23 +574,23 @@ block C<CONTEXT::> refers to the scope surrounding the block.  But unlike
 an explicit call, C<CALLER::> doesn't count it as a routine boundary.
 
 If you wish to return a closure from a function, you must use an
-explicit prefix such as C<return> or C<sub> or C<< -> >>.  
-
-	sub f1
-	{
-		# lots of stuff ...
-		{ say "I'm a closure." }
-	}
-	
-	my $x1= f1;  # fall-off return is result of the say, not the closure.
-	
-	sub f2
-	{
-		# lots of stuff ...
-		return { say "I'm a closure." }
-	}
-	
-	my $x2= f2;  # returns a Block object.
+explicit prefix such as C<return> or C<sub> or C<< -> >>.
+
+    sub f1
+    {
+        # lots of stuff ...
+        { say "I'm a closure." }
+    }
+
+    my $x1= f1;  # fall-off return is result of the say, not the closure.
+
+    sub f2
+    {
+        # lots of stuff ...
+        return { say "I'm a closure." }
+    }
+
+    my $x2= f2;  # returns a Block object.
 
 Use of a placeholder parameter in statement-level blocks triggers a
 syntax error, because the parameter is not out front where it can be
@@ -700,11 +701,11 @@ which can't see the caller's lexical scope except through the CALLER::
 pseudo package.  For example, Perl forces generic C<eq> to coerce to
 string comparison, like this:
 
-    proto infix:<eq> (Any $a, Any $b)	{ lift ~$a eq ~$b }		# user's eq, user's ~
-    multi infix:<eq> (Whatever, Any $b)	{ -> $a { lift $a eq $b } }	# user's eq
-    multi infix:<eq> (Any $a, Whatever)	{ -> $b { lift $a eq $b } }	# user's eq
-    multi infix:<eq> (&f:($), Any $b)	{ -> $a { lift f($a) eq $b } }	# user's eq
-    multi infix:<eq> (Str $a, Str $b)	{ !Str::leg($a, $b) }		# primitive leg, primitive !
+    proto infix:<eq> (Any $a, Any $b)   { lift ~$a eq ~$b }            # user's eq, user's ~
+    multi infix:<eq> (Whatever, Any $b) { -> $a { lift $a eq $b } }    # user's eq
+    multi infix:<eq> (Any $a, Whatever) { -> $b { lift $a eq $b } }    # user's eq
+    multi infix:<eq> (&f:($), Any $b)   { -> $a { lift f($a) eq $b } } # user's eq
+    multi infix:<eq> (Str $a, Str $b)   { !Str::leg($a, $b) }          # primitive leg, primitive !
 
 
 Note that in each piece of lifted code there are references to
@@ -1116,7 +1117,7 @@ exceptions and exit values:
       START {...}*      on first ever execution, once per closure clone
 
       ENTER {...}*      at every block entry time, repeats on loop blocks.
-      LEAVE {...}       at every block exit time 
+      LEAVE {...}       at every block exit time
        KEEP {...}       at every successful block exit, part of LEAVE queue
        UNDO {...}       at every unsuccessful block exit, part of LEAVE queue
 
@@ -1135,6 +1136,23 @@ Those marked with a C<*> can also be used within an expression:
     my $compiletime = BEGIN { localtime };
     our $temphandle = START { maketemp() };
 
+As with other statement prefixes, these value-producing constructs
+may be placed in front of either a block or a statement:
+
+    my $compiletime = BEGIN localtime;
+    our $temphandle = START maketemp();
+
+This can be particularly useful to expose a lexically scoped
+declaration to the surrounding context.  Hence these declare the same
+variables with the same scope as the preceding example, but run the
+statements as a whole at the indicated time:
+
+    BEGIN my $compiletime = localtime;
+    START our $temphandle = maketemp();
+
+(Note, however, that the value of a variable calculated at compile
+time may not persist under run-time cloning of any surrounding closure.)
+
 Code that is generated at run time can still fire off C<CHECK>
 and C<INIT> blocks, though of course those blocks can't do things that
 would require travel back in time.
@@ -1253,9 +1271,9 @@ Note that the parser cannot intuit how many arguments a list operator
 is taking, so if you mean 0 arguments, you must parenthesize the
 argument list to force the block to appear after a term:
 
-    if caller {...}	# WRONG, parsed as caller({...})
-    if caller() {...}	# okay
-    if (caller) {...}	# okay
+    if caller {...}    # WRONG, parsed as caller({...})
+    if caller() {...}  # okay
+    if (caller) {...}  # okay
 
 Note that common idioms work as expected though:
 
@@ -1449,7 +1467,7 @@ they perform a C<:=> binding to the lexical symbol at clone time
 possibly deferred.)
 
     sub foo {
-	# conceptual cloning happens to both blocks below
+        # conceptual cloning happens to both blocks below
         my $x = 1;
         my sub bar { print $x }         # already conceptualy cloned, but can be lazily deferred
         my &baz := { bar(); print $x }; # block is cloned immediately, forcing cloning of bar