Skip to content
This repository
Browse code

Move synopses to their new home.

git-svn-id: http://svn.pugscode.org/pugs@24058 c213334d-75ef-0310-aa23-eaa082d1ae64
  • Loading branch information...
commit 68d062fcaaa4e6e6a032e30775e3d7782e95eb28 1 parent b876595
pmichaud authored
165 S01.pod
Source Rendered
... ... @@ -0,0 +1,165 @@
  1 +=encoding utf8
  2 +
  3 +=head1 TITLE
  4 +
  5 +Synopsis 1: Overview
  6 +
  7 +=head1 AUTHOR
  8 +
  9 +Larry Wall <larry@wall.org>
  10 +
  11 +=head1 VERSION
  12 +
  13 + Maintainer: Larry Wall <larry@wall.org>
  14 + Date: 10 Aug 2004
  15 + Last Modified: 30 Jan 2007
  16 + Number: 1
  17 + Version: 6
  18 +
  19 +This document originally summarized Apocalypse 1, which covers the
  20 +initial design concept. That original summary may be found below
  21 +under "Random Thoughts". However, these Synopses also contain
  22 +updates to reflect the evolving design of Perl 6 over time, unlike
  23 +the Apocalypses, which are frozen in time as "historical documents".
  24 +These updates are not marked--if a Synopsis disagrees with its
  25 +Apocalypse, assume the Synopsis is correct.
  26 +
  27 +Another assumption has been that if we don't talk about something in these
  28 +Synopses, it's the same as it is in Perl 5. Soon we plan to fill in
  29 +the gaps with the Perl 5 details though.
  30 +
  31 +=head1 Project Plan
  32 +
  33 +Mostly, we're just a bunch of ants all cooperating (sort of) to haul
  34 +food toward the nest (on average). There are many groups of people
  35 +working on various bits and pieces as they see fit, since this is
  36 +primarily a volunteer effort.
  37 +
  38 +This document does not attempt to summarize all these subprojects--see
  39 +the various websites for Parrot and Pugs and Perl 6 for such
  40 +information. What we can say here is that, unlike how it was with
  41 +Perl 5, none of these projects is designed to be the Official Perl.
  42 +Perl 6 is anything that passes the official test suite. This test
  43 +suite was initially developed under the Pugs project because that
  44 +project is the furthest along in exploring the high-level semantics
  45 +of Perl 6. (Other projects are better at other things, such as speed
  46 +or interoperability.) However, the Pugs project views the test suite
  47 +as community property, and is working towards platform neutrality,
  48 +so that Perl 6 is defined primarily by its desired semantics, not by
  49 +accidents of history.
  50 +
  51 +Another aspect of this is the Perl 6 compiler will be self-hosting.
  52 +That is, the compiler will eventually compile itself, at least down
  53 +to the point where various code-generating backends can take over.
  54 +This largely removes platform dependencies from the frontend, so that
  55 +only the backends need to worry about platform-specific issues.
  56 +
  57 +But above all, our project plan is simply to help people find a
  58 +spot where they can feel like they're creating the future, both for
  59 +themselves and for others. Around here, that's what we call fun.
  60 +
  61 +=head1 Random Thoughts
  62 +
  63 +=over 4
  64 +
  65 +=item *
  66 +
  67 +The word "apocalypse" historically meant merely "a revealing",
  68 +and we're using it in that unexciting sense.
  69 +
  70 +=item *
  71 +
  72 +If you ask for RFCs from the general public, you get a lot of
  73 +interesting but contradictory ideas, because people tend to stake
  74 +out polar positions, and none of the ideas can build on each other.
  75 +
  76 +=item *
  77 +
  78 +Larry's First Law of Language Redesign: Everyone wants the colon.
  79 +
  80 +=item *
  81 +
  82 +RFCs are rated on "PSA": whether they point out a real Problem,
  83 +whether they present a viable Solution, and whether that solution is
  84 +likely to be Accepted as part of Perl 6.
  85 +
  86 +=item *
  87 +
  88 +Languages should be redesigned in roughly the same order as you would
  89 +present the language to a new user.
  90 +
  91 +=item *
  92 +
  93 +Perl 6 should be malleable enough that it can evolve into the imaginary
  94 +perfect language, Perl 7. This darwinian imperative implies support
  95 +for multiple syntaxes above and multiple platforms below.
  96 +
  97 +=item *
  98 +
  99 +Many details may change, but the essence of Perl will remain unchanged.
  100 +Perl will continue to be a multiparadigmatic, context-sensitive
  101 +language. We are not turning Perl into any other existing language.
  102 +
  103 +=item *
  104 +
  105 +Migration is important. The perl interpreter will assume that it
  106 +is being fed Perl 5 code unless the code starts with a "class" or
  107 +"module" keyword, or you specifically tell it you're running Perl 6
  108 +code in some other way, such as by:
  109 +
  110 + #!/usr/bin/perl6
  111 + use v6.0;
  112 + v6;
  113 +
  114 +=item *
  115 +
  116 +Migration in the other direction is also important. In Perl 6
  117 +mode, one can drop back to Perl 5 mode with C<use v5> at the
  118 +beginning of a lexical block. Such blocks may be nested:
  119 +
  120 + use v6;
  121 + # ...some Perl 6 code...
  122 + {
  123 + use v5;
  124 + # ...some Perl 5 code...
  125 + {
  126 + use v6;
  127 + # ...more Perl 6 code...
  128 + }
  129 + }
  130 +
  131 +=item *
  132 +
  133 +Scaling is one of those areas where Perl needs to be multiparadigmatic
  134 +and context sensitive. Perl 5 code is not strict by default, while
  135 +Perl 6 code is. But it should be easy to relax with C<-e> or
  136 +a bare version number:
  137 +
  138 + perl -e '$x = 1'
  139 +
  140 + #!/usr/bin/perl
  141 + v6; $x = 1;
  142 +
  143 +=item *
  144 +
  145 +It must be possible to write policy metamodules that invoke other
  146 +modules on the user's behalf.
  147 +
  148 +=item *
  149 +
  150 +If you want to treat everything as objects in Perl 6, Perl will help
  151 +you do that. If you don't want to treat everything as objects, Perl
  152 +will help you with that viewpoint as well.
  153 +
  154 +=item *
  155 +
  156 +Operators are just functions with funny names and syntax.
  157 +
  158 +=item *
  159 +
  160 +Language designers are still necessary to synthesize unrelated ideas
  161 +into a coherent whole.
  162 +
  163 +=back
  164 +
  165 +=for vim:set expandtab sw=4:
3,549 S02.pod
Source Rendered
3,549 additions, 0 deletions not shown
4,345 S03.pod
Source Rendered
4,345 additions, 0 deletions not shown
1,334 S04.pod
Source Rendered
... ... @@ -0,0 +1,1334 @@
  1 +=encoding utf8
  2 +
  3 +=head1 TITLE
  4 +
  5 +Synopsis 4: Blocks and Statements
  6 +
  7 +=head1 AUTHOR
  8 +
  9 +Larry Wall <larry@wall.org>
  10 +
  11 +=head1 VERSION
  12 +
  13 + Maintainer: Larry Wall <larry@wall.org>
  14 + Date: 19 Aug 2004
  15 + Last Modified: 14 Oct 2008
  16 + Number: 4
  17 + Version: 70
  18 +
  19 +This document summarizes Apocalypse 4, which covers the block and
  20 +statement syntax of Perl.
  21 +
  22 +=head1 The Relationship of Blocks and Declarations
  23 +
  24 +Every block is a closure. (That is, in the abstract, they're all
  25 +anonymous subroutines that take a snapshot of their lexical scope.)
  26 +How a block is invoked and how its results are used are matters of
  27 +context, but closures all work the same on the inside.
  28 +
  29 +Blocks are delimited by curlies, or by the beginning and end of the
  30 +current compilation unit (either the current file or the current
  31 +C<eval> string). Unlike in Perl 5, there are (by policy) no implicit
  32 +blocks around standard control structures. (You could write a macro
  33 +that violates this, but resist the urge.) Variables that mediate
  34 +between an outer statement and an inner block (such as loop variables)
  35 +should generally be declared as formal parameters to that block. There
  36 +are three ways to declare formal parameters to a closure.
  37 +
  38 + $func = sub ($a, $b) { .print if $a eq $b }; # standard sub declaration
  39 + $func = -> $a, $b { .print if $a eq $b }; # a "pointy" block
  40 + $func = { .print if $^a eq $^b } # placeholder arguments
  41 +
  42 +A bare closure without placeholder arguments that uses C<$_>
  43 +(either explicitly or implicitly) is treated as though C<$_> were a
  44 +formal parameter:
  45 +
  46 + $func = { .print if $_ }; # Same as: $func = -> $_ { .print if $_ };
  47 + $func("printme");
  48 +
  49 +In any case, all formal parameters are the equivalent of C<my> variables
  50 +within the block. See S06 for more on function parameters.
  51 +
  52 +Except for such formal parameter declarations, all lexically scoped
  53 +declarations are visible from the point of declaration to the end of
  54 +the enclosing block. Period. Lexicals may not "leak" from a block to any
  55 +other external scope (at least, not without some explicit aliasing
  56 +action on the part of the block, such as exportation of a symbol
  57 +from a module). The "point of declaration" is the moment the compiler
  58 +sees "C<my $foo>", not the end of the statement as in Perl 5, so
  59 +
  60 + my $x = $x;
  61 +
  62 +will no longer see the value of the outer C<$x>; you'll need to say
  63 +either
  64 +
  65 + my $x = $OUTER::x;
  66 +
  67 +or
  68 +
  69 + my $x = OUTER::<$x>;
  70 +
  71 +instead.
  72 +
  73 +If you declare a lexical twice in the same scope, it is the same lexical:
  74 +
  75 + my $x;
  76 + my $x;
  77 +
  78 +By default the second declaration will get a compiler warning.
  79 +You may suppress this by modifying the first declaration
  80 +with C<proto>:
  81 +
  82 + my proto $x;
  83 + ...
  84 + while my $x = @x.shift {...} # no warning
  85 + while my $x = @x.shift {...} # no warning
  86 +
  87 +If you've referred to C<$x> prior to the first declaration, and the compiler
  88 +tentatively bound it to C<$OUTER::x>, then it's an error to declare it, and
  89 +the compiler is required to complain at that point. If such use can't
  90 +be detected because it is hidden in an eval, then it is erroneous, since
  91 +the C<eval()> compiler might bind to either C<$OUTER::x> or the subsequently
  92 +declared "C<my $x>".
  93 +
  94 +As in Perl 5, "C<our $foo>" introduces a lexically scoped alias for
  95 +a variable in the current package.
  96 +
  97 +The new C<constant> declarator introduces a lexically scoped name
  98 +for a compile-time constant, either a variable or a 0-ary sub, which
  99 +may be initialized with a pseudo-assignment:
  100 +
  101 + constant Num $pi = 3;
  102 + constant Num π = atan(2,2) * 4;
  103 +
  104 +The initializing expression is evaluated at BEGIN time.
  105 +
  106 +There is a new C<state> declarator that introduces a lexically scoped
  107 +variable like C<my> does, but with a lifetime that persists for the
  108 +life of the closure, so that it keeps its value from the end of one
  109 +call to the beginning of the next. Separate clones of the closure
  110 +get separate state variables.
  111 +
  112 +Perl 5's "C<local>" function has been renamed to C<temp> to better
  113 +reflect what it does. There is also a C<let> function that sets a
  114 +hypothetical value. It works exactly like C<temp>, except that the
  115 +value will be restored only if the current block exits unsuccessfully.
  116 +(See Definition of Success below for more.) C<temp> and C<let> temporize
  117 +or hypotheticalize the value or the variable depending on whether you
  118 +do assignment or binding. One other difference from Perl 5 is that
  119 +the default is not to undefine a variable. So
  120 +
  121 + temp $x;
  122 +
  123 +causes C<$x> to start with its current value. Use
  124 +
  125 + temp undefine $x;
  126 +
  127 +to get the Perl 5 behavior.
  128 +
  129 +Note that temporizations that are undone upon scope exit must be
  130 +prepared to be redone if a continuation within that scope is taken.
  131 +
  132 +=head1 The Relationship of Blocks and Statements
  133 +
  134 +The return value of a block is the value of its final statement.
  135 +(This is subtly different from Perl 5's behavior, which was to return
  136 +the value of the last expression evaluated, even if that expression
  137 +was just a conditional.)
  138 +
  139 +=head1 Statement-ending blocks
  140 +
  141 +A line ending with a closing brace "C<}>", followed by nothing but
  142 +whitespace or comments, will terminate a statement if an end of statement
  143 +can occur there. That is, these two statements are equivalent:
  144 +
  145 + my $x = sub { 3 }
  146 + my $x = sub { 3 };
  147 +
  148 +End-of-statement cannot occur within a bracketed expression, so
  149 +this still works:
  150 +
  151 + my $x = [
  152 + sub { 3 }, # this comma is not optional
  153 + sub { 3 } # the statement won't terminate here
  154 + ];
  155 +
  156 +However, a hash composer may never occur at the end of a line. If the
  157 +parser sees anything that looks like a hash composer at the end of
  158 +the line, it fails with "closing hash curly may not terminate line"
  159 +or some such.
  160 +
  161 + my $hash = {
  162 + 1 => { 2 => 3, 4 => 5 }, # OK
  163 + 2 => { 6 => 7, 8 => 9 } # ERROR
  164 + };
  165 +
  166 +Because subroutine declarations are expressions, not statements,
  167 +this is now invalid:
  168 +
  169 + sub f { 3 } sub g { 3 } # two terms occur in a row
  170 +
  171 +But these two are valid:
  172 +
  173 + sub f { 3 }; sub g { 3 };
  174 + sub f { 3 }; sub g { 3 } # the trailing semicolon is optional
  175 +
  176 +Though certain control statements could conceivably be parsed in a
  177 +self-contained way, for visual consistency all statement-terminating
  178 +blocks that end in the middle of a line I<must> be terminated by
  179 +semicolon unless they are naturally terminated by some other statement
  180 +terminator:
  181 +
  182 + while yin() { yang() } say "done"; # ILLEGAL
  183 + while yin() { yang() }; say "done"; # okay, explicit semicolon
  184 + @yy := [ while yin() { yang() } ]; # okay within outer [...]
  185 + while yin() { yang() } ==> sort # okay, ==> separates statements
  186 +
  187 +=head1 Conditional statements
  188 +
  189 +The C<if> and C<unless> statements work much as they do in
  190 +Perl 5. However, you may omit the parentheses on the conditional:
  191 +
  192 + if $foo == 123 {
  193 + ...
  194 + }
  195 + elsif $foo == 321 {
  196 + ...
  197 + }
  198 + else {
  199 + ...
  200 + }
  201 +
  202 +If the final statement is a conditional which does not execute any
  203 +branch, the return value is C<undef> in item context and C<()> in
  204 +list context.
  205 +
  206 +The C<unless> statement does not allow an C<elsif> or C<else> in Perl 6.
  207 +
  208 +The value of the conditional expression may be optionally bound to
  209 +a closure parameter:
  210 +
  211 + if testa() -> $a { say $a }
  212 + elsif testb() -> $b { say $b }
  213 + else -> $b { say $b }
  214 +
  215 +Note that the value being evaluated for truth and subsequently bound is
  216 +not necessarily a value of type Bool. (All normal types in Perl may
  217 +be evaluated for truth. In fact, this construct would be relatively
  218 +useless if you could bind only boolean values as parameters, since
  219 +within the closure you already know whether it evaluated to true
  220 +or false.) Binding within an C<else> automatically binds the value
  221 +tested by the previous C<if> or C<elsif>, which, while known to be
  222 +false, might nevertheless be an I<interesting> value of false. (By similar
  223 +reasoning, an C<unless> allows binding of a false parameter.)
  224 +
  225 +An explicit placeholder may also be used:
  226 +
  227 + if blahblah() { return $^it }
  228 +
  229 +However, use of C<$_> with a conditional statement's block is I<not>
  230 +considered sufficiently explicit to turn a 0-ary block into a 1-ary
  231 +function, so both these methods use the same invocant:
  232 +
  233 + if .haste { .waste }
  234 +
  235 +(Contrast with a non-conditional statement such as:
  236 +
  237 + for .haste { .waste }
  238 +
  239 +where each call to the block would bind a new invocant for the
  240 +C<.waste> method, each of which is likely different from the original
  241 +invocant to the C<.haste> method.)
  242 +
  243 +Conditional statement modifiers work as in Perl 5. So do the
  244 +implicit conditionals implied by short-circuit operators. Note though that
  245 +the first expression within parens or brackets is parsed as a statement,
  246 +so you can say:
  247 +
  248 + @x = 41, (42 if $answer), 43;
  249 +
  250 +and that is equivalent to:
  251 +
  252 + @x = 41, ($answer ?? 42 !! ()), 43
  253 +
  254 +=head1 Loop statements
  255 +
  256 +Looping statement modifiers are the same as in Perl 5 except that,
  257 +for ease of writing list comprehensions, a looping statement modifier
  258 +is allowed to contain a single conditional statement modifier:
  259 +
  260 + @evens = ($_ * 2 if .odd for 0..100);
  261 +
  262 +Loop modifiers C<next>, C<last>, and C<redo> also work as in Perl 5.
  263 +However, the labelled forms use method call syntax: C<LABEL.next>, etc.
  264 +The C<.next> and C<.last> methods take an optional argument giving
  265 +the final value of that loop iteration. So the old C<next LINE>
  266 +syntax is still allowed but is really short for C<next LINE:> using
  267 +indirect object syntax. Any block object can be used, not just labels,
  268 +so to return a value from this iteration of the current block you can say:
  269 +
  270 + &?BLOCK.next($retval);
  271 +
  272 +[Conjecture: a bare C<next($retval)> function could be taught to do
  273 +the same, as long as C<$retval> isn't a loop label. Presumably multiple
  274 +dispatch could sort this out.]
  275 +
  276 +There is no longer a C<continue> block. Instead, use a C<NEXT> block
  277 +within the body of the loop. See below.
  278 +
  279 +The value of a loop statement is the list of values from each
  280 +iteration. Iterations that return a null list (such as by calling
  281 +C<next> with no extra return arguments) interpolate no values in the
  282 +resulting list. (This list is actually a two-dimensional list of
  283 +Captures (a "slice") with dimensional boundaries at each iteration.
  284 +Normal list context ignores these boundaries and flattens the list.
  285 +Slice context turns the captures into subarrays, so an iteration
  286 +returning a null list does show up as a null subarray when viewed as
  287 +a slice.)
  288 +
  289 +For finer-grained control of which iterations return values, use
  290 +C<gather> and C<take>.
  291 +
  292 +Since the final expression in a subroutine returns its value, it's
  293 +possible to accidentally return a loop's return value when you were
  294 +only evaluating the loop for its side effects. If you do not wish
  295 +to accidentally return a list from the final loop statement in a
  296 +subroutine, place an explicit return statement after it, or declare
  297 +a return type of C<Void>.
  298 +
  299 +=head2 The C<while> and C<until> statements
  300 +
  301 +The C<while> and C<until> statements work as in Perl 5, except that you
  302 +may leave out the parentheses around the conditional:
  303 +
  304 + while $bar < 100 {
  305 + ...
  306 + }
  307 +
  308 +As with conditionals, you may optionally bind the result of the
  309 +conditional expression to a parameter of the block:
  310 +
  311 + while something() -> $thing {
  312 + ...
  313 + }
  314 +
  315 + while something() -> { ... $^thing ... }
  316 +
  317 +Nothing is ever bound implicitly, however, and many conditionals would
  318 +simply bind True or False in an uninteresting fashion. This mechanism
  319 +is really only good for objects that know how to return a boolean
  320 +value and still remain themselves. In general, for most iterated
  321 +solutions you should consider using a C<for> loop instead (see below).
  322 +In particular, we now generally use C<for> to iterate filehandles.
  323 +
  324 +=head2 The C<repeat> statement
  325 +
  326 +Unlike in Perl 5, applying a statement modifier to a C<do> block is
  327 +specifically disallowed:
  328 +
  329 +
  330 + do {
  331 + ...
  332 + } while $x < 10; # ILLEGAL
  333 +
  334 +Instead, you should write the more Pascal-like C<repeat> loop:
  335 +
  336 + repeat {
  337 + ...
  338 + } while $x < 10;
  339 +
  340 +or equivalently:
  341 +
  342 + repeat {
  343 + ...
  344 + } until $x >= 10;
  345 +
  346 +Unlike Perl 5's C<do-while> loop, this is a real loop block now, so
  347 +C<next>, C<last>, and C<redo> work as expected. The loop conditional
  348 +on a repeat block is required, so it will be recognized even if you
  349 +put it on a line by its own:
  350 +
  351 + repeat
  352 + {
  353 + ...
  354 + }
  355 + while $x < 10;
  356 +
  357 +However, that's likely to be visually confused with a following
  358 +C<while> loop at the best of times, so it's also allowed to put the
  359 +loop conditional at the front, with the same meaning. (The C<repeat>
  360 +keyword forces the conditional to be evaluated at the end of the loop,
  361 +so it's still C's do-while semantics.) Therefore, even under GNU style
  362 +rules, the previous example may be rewritten into a very clear:
  363 +
  364 + repeat while $x < 10
  365 + {
  366 + ...
  367 + }
  368 +
  369 +or equivalently:
  370 +
  371 + repeat until $x >= 10
  372 + {
  373 + ...
  374 + }
  375 +
  376 +As with an ordinary C<while>, you may optionally bind the result of
  377 +the conditional expression to a parameter of the block:
  378 +
  379 + repeat -> $thing {
  380 + ...
  381 + } while something();
  382 +
  383 +or
  384 +
  385 + repeat while something() -> $thing {
  386 + ...
  387 + }
  388 +
  389 +Since the loop executes once before evaluating the condition, the
  390 +bound parameter will be undefined that first time through the loop.
  391 +
  392 +=head2 The general loop statement
  393 +
  394 +The C<loop> statement is the C-style C<for> loop in disguise:
  395 +
  396 + loop ($i = 0; $i < 10; $i++) {
  397 + ...
  398 + }
  399 +
  400 +As in C, the parentheses are required if you supply the 3-part spec; however,
  401 +the 3-part loop spec may be entirely omitted to write an infinite loop.
  402 +That is,
  403 +
  404 + loop {...}
  405 +
  406 +is equivalent to the Cish idiom:
  407 +
  408 + loop (;;) {...}
  409 +
  410 +=head2 The C<for> statement
  411 +
  412 +There is no C<foreach> statement any more. It's always spelled C<for>
  413 +in Perl 6, so it always takes a list as an argument:
  414 +
  415 + for @foo { .print }
  416 +
  417 +As mentioned earlier, the loop variable is named by passing a parameter
  418 +to the closure:
  419 +
  420 + for @foo -> $item { print $item }
  421 +
  422 +Multiple parameters may be passed, in which case the list is traversed
  423 +more than one element at a time:
  424 +
  425 + for %hash.kv -> $key, $value { print "$key => $value\n" }
  426 +
  427 +To process two arrays in parallel use the C<zip> function to generate a
  428 +list that can be bound to the corresponding number of parameters:
  429 +
  430 + for zip(@a;@b) -> $a, $b { print "[$a, $b]\n" }
  431 + for @a Z @b -> $a, $b { print "[$a, $b]\n" } # same thing
  432 +
  433 +The list is evaluated lazily by default, so instead of using a C<while>
  434 +to read a file a line at a time as you would in Perl 5:
  435 +
  436 + while (my $line = <STDIN>) {...}
  437 +
  438 +in Perl 6 you should use a C<for> (plus a unary C<=> "iterate the
  439 +iterator" operator) instead:
  440 +
  441 + for =$*IN -> $line {...}
  442 +
  443 +This has the added benefit of limiting the scope of the C<$line>
  444 +parameter to the block it's bound to. (The C<while>'s declaration of
  445 +C<$line> continues to be visible past the end of the block. Remember,
  446 +no implicit block scopes.) It is also possible to write
  447 +
  448 + while =$*IN -> $line {...}
  449 +
  450 +Note also that Perl 5's special rule causing
  451 +
  452 + while (<>) {...}
  453 +
  454 +to automatically assign to C<$_> is not carried over to Perl 6. That
  455 +should now be written:
  456 +
  457 + for =<> {...}
  458 +
  459 +which is short for
  460 +
  461 + for =$*ARGS {...}
  462 +
  463 +Arguments bound to the formal parameters of a pointy block are by
  464 +default readonly within the block. You can declare a parameter
  465 +read/write by including the "C<is rw>" trait. The following treats
  466 +every other value in C<@values> as modifiable:
  467 +
  468 + for @values -> $even is rw, $odd { ... }
  469 +
  470 +In the case where you want all your parameters to default to C<rw>,
  471 +you may use the visually suggestive double-ended arrow to indicate that
  472 +values flow both ways:
  473 +
  474 + for @values <-> $even, $odd { ... }
  475 +
  476 +This is equivalent to
  477 +
  478 + for @values -> $even is rw, $odd is rw { ... }
  479 +
  480 +If you rely on C<$_> as the implicit parameter to a block,
  481 +then C<$_> is considered read/write by default. That is,
  482 +the construct:
  483 +
  484 + for @foo {...}
  485 +
  486 +is actually short for:
  487 +
  488 + for @foo <-> $_ {...}
  489 +
  490 +so you can modify the current list element in that case.
  491 +
  492 +When used as statement modifiers, C<for> and C<given> use a private
  493 +instance of C<$_> for the left side of the statement. The outer C<$_>
  494 +can be referred to as C<$OUTER::_>. (And yes, this implies that the
  495 +compiler may have to retroactively change the binding of <$_> on the
  496 +left side. But it's what people expect of a pronoun like "it".)
  497 +
  498 +=head2 The do-once loop
  499 +
  500 +In Perl 5, a bare block is deemed to be a do-once loop. In Perl 6,
  501 +the bare block is not a do-once. Instead C<do {...}> is the do-once
  502 +loop (which is another reason you can't put a statement
  503 +modifier on it; use C<repeat> for a test-at-the-end loop).
  504 +
  505 +For any statement, prefixing with a C<do> allows you to
  506 +return the value of that statement and use it in an expression:
  507 +
  508 + $x = do if $a { $b } else { $c };
  509 +
  510 +This construct only allows you to attach a single statement to the end
  511 +of an expression. If you want to continue the expression after the
  512 +statement, or if you want to attach multiple statements. you must either
  513 +use the curly form or surround the entire expression in brackets of some sort:
  514 +
  515 + @primes = (do (do $_ if .prime) for 1..100);
  516 +
  517 +Since a bare expression may be used as a statement, you may use C<do>
  518 +on an expression, but its only effect is to function as an unmatched
  519 +left parenthesis, much like the C<$> operator in Haskell. That is,
  520 +precedence decisions do not cross a C<do> boundary, and the missing
  521 +"right paren" is assumed at the next statement terminator or unmatched
  522 +bracket. A C<do> is assumed immediately after any opening bracket,
  523 +so the above can in fact be written:
  524 +
  525 + @primes = (($_ if .prime) for 1..100);
  526 +
  527 +This basically gives us list comprehensions as rvalue expressions:
  528 +
  529 + (for 1..100 { $_ if .prime}).say
  530 +
  531 +Since C<do> is defined as going in front of a statement, it follows
  532 +that it can always be followed by a statement label. This is particularly
  533 +useful for the do-once block, since it is offically a loop and can take
  534 +therefore loop control statements.
  535 +
  536 +Another consequence of this is that any block just inside a
  537 +left parenthesis is immediately called like a bare block, so a
  538 +multidimensional list comprehension may be written using a block with
  539 +multiple parameters fed by a C<for> modifier:
  540 +
  541 + @names = (-> $name, $num { "$name.$num" } for 'a'..'zzz' X 1..100);
  542 +
  543 +or equivalently, using placeholders:
  544 +
  545 + @names = ({ "$^name.$^num" } for 'a'..'zzz' X 1..100);
  546 +
  547 +=head2 Statement-level bare blocks
  548 +
  549 +Although a bare block occuring as a single statement is no longer
  550 +a do-once loop, it still executes immediately as in Perl 5, as if it
  551 +were immediately dereferenced with a C<.()> postfix, so within such a
  552 +block C<CALLER::> refers to the scope surrounding the block.
  553 +
  554 +If you wish to return a closure from a function, you must use an
  555 +explicit prefix such as C<return> or C<sub> or C<< -> >>.
  556 +
  557 +Use of a placeholder parameter in statement-level blocks triggers a
  558 +syntax error, because the parameter is not out front where it can be
  559 +seen. However, it's not an error when prefixed by a C<do>, or when
  560 +followed by a statement modifier:
  561 +
  562 + # Syntax error: Statement-level placeholder block
  563 + { say $^x };
  564 +
  565 + # Not an syntax error, though $x doesn't get the argument it wants
  566 + do { say $^x };
  567 +
  568 + # Not an error: Equivalent to "for 1..10 -> $x { say $x }"
  569 + { say $^x } for 1..10;
  570 +
  571 + # Not an error: Equivalent to "if foo() -> $x { say $x }"
  572 + { say $^x } if foo();
  573 +
  574 +=head2 The gather statement
  575 +
  576 +A variant of C<do> is C<gather>. Like C<do>, it is followed by a
  577 +statement or block, and executes it once. Unlike C<do>, it evaluates
  578 +the statement or block in void context; its return value is instead
  579 +specified by calling the C<take> list prefix operator one or more times
  580 +within the dynamic scope of the C<gather>. The C<take> function's
  581 +signature is like that of C<return>; it merely captures the C<Capture>
  582 +of its argments without imposing any additional constraints (in the
  583 +absence of context propagation by the optimizer). The value returned
  584 +by the C<take> to its own context is that same C<Capture> object (which
  585 +is ignored when the C<take> is in void context). Regardless of the
  586 +C<take>'s context, the C<Capture> object is also added to the list of
  587 +values being gathered, which is returned by the C<gather> in the form
  588 +of a lazy slice, with each slice element corresponding to one C<take>
  589 +capture. (A list of C<Capture>s is lazily flattened in normal list context,
  590 +but you may "unflatten" it again with a C<@@()> contextualizer.)
  591 +
  592 +Because C<gather> evaluates its block or statement in void context,
  593 +this typically causes the C<take> function to be evaluated in void
  594 +context. However, a C<take> function that is not in void context
  595 +gathers its arguments I<en passant> and also returns them unchanged.
  596 +This makes it easy to keep track of what you last "took":
  597 +
  598 + my @uniq = gather for @list {
  599 + state $previous = take $_;
  600 + next if $_ === $previous;
  601 + $previous = take $_;
  602 + }
  603 +
  604 +The C<take> function essentially has two contexts simultaneously, the
  605 +context in which the gather is operating, and the context in which the
  606 +C<take> is operating. These need not be identical contexts, since they
  607 +may bind or coerce the resulting captures differently:
  608 +
  609 + my @y;
  610 + @x = gather for 1..2 { # @() context for list of captures
  611 + my $x = take $_, $_ * 10; # $() context for individual capture
  612 + push @y, $x;
  613 + }
  614 + # @x returns 1,10,2,20
  615 + # @y returns [1,10],[2,20]
  616 +
  617 +Likewise, we can just remember the gather's result by binding and
  618 +later coerce it:
  619 +
  620 + $c := gather for 1..2 {
  621 + take $_, $_ * 10;
  622 + }
  623 + # @$c returns 1,10,2,20
  624 + # @@$c returns [1,10],[2,20]
  625 + # $$c returns [[1,10],[2,20]]
  626 +
  627 +Note that the C<take> itself is in void context in this example because
  628 +the C<for> loop is in void context.
  629 +
  630 +A C<gather> is not considered a loop, but it is easy to combine with a loop
  631 +statement as in the examples above.
  632 +
  633 +If any function called as part of a C<take> list asks what its context
  634 +is, it will be told it was called in list context regardless of the
  635 +eventual binding of the returned C<Capture>. If that is not the
  636 +desired behavior you must coerce the call to an appropriate context.
  637 +In any event, such a function is called only once at the time the
  638 +C<Capture> object is generated, not when it is bound (which could
  639 +happen more than once).
  640 +
  641 +=head2 Other C<do>-like forms
  642 +
  643 +Other similar C<Code>-only forms may also take bare statements,
  644 +including C<try>, C<contend>, C<async>, and C<lazy>. These constructs
  645 +establish a dynamic scope without necessarily establishing a lexical
  646 +scope. (You can always establish a lexical scope explicitly by using
  647 +the block form of argument.) As statement introducers, all these
  648 +keywords must be followed by whitespace. (You can say something
  649 +like C<try({...})>, but then you are calling the C<try()> function
  650 +using function call syntax instead, and since Perl does not supply
  651 +such a function, it will be assumed to be a user-defined function.)
  652 +For purposes of flow control, none of these forms are considered loops,
  653 +but they may easily be applied to a normal loop.
  654 +
  655 +=head1 Switch statements
  656 +
  657 +A switch statement is a means of topicalizing, so the switch keyword
  658 +is the English topicalizer, C<given>. The keyword for individual
  659 +cases is C<when>:
  660 +
  661 + given EXPR {
  662 + when EXPR { ... }
  663 + when EXPR { ... }
  664 + default { ... }
  665 + }
  666 +
  667 +The current topic is always aliased to the special variable C<$_>.
  668 +The C<given> block is just one way to set the current topic, but
  669 +a switch statement can be any block that sets C<$_>, including a
  670 +C<for> loop (assuming one of its loop variables is bound to C<$_>)
  671 +or the body of a method (if you have declared the invocant as C<$_>).
  672 +So switching behavior is actually caused by the C<when> statements in
  673 +the block, not by the nature of the block itself. A C<when> statement
  674 +implicitly does a "smart match" between the current topic (C<$_>) and
  675 +the argument of the C<when>. If the smart match succeeds, C<when>'s
  676 +associated block is executed, and the innermost surrounding block
  677 +that has C<$_> as one of its formal parameters (either explicit
  678 +or implicit) is automatically broken out of. (If that is not the
  679 +block you wish to leave, you must use the C<LABEL.leave> method (or some
  680 +other control exception such as C<return> or C<next>) to
  681 +be more specific, since the compiler may find it difficult to guess
  682 +which surrounding construct was intended as the actual topicalizer.)
  683 +The value of the inner block is returned as the value of the outer
  684 +block.
  685 +
  686 +If the smart match fails, control passes to the next statement
  687 +normally, which may or may not be a C<when> statement. Since C<when>
  688 +statements are presumed to be executed in order like normal statements,
  689 +it's not required that all the statements in a switch block be C<when>
  690 +statements (though it helps the optimizer to have a sequence of
  691 +contiguous C<when> statements, because then it can arrange to jump
  692 +directly to the first appropriate test that might possibly match.)
  693 +
  694 +The default case:
  695 +
  696 + default {...}
  697 +
  698 +is exactly equivalent to
  699 +
  700 + when * {...}
  701 +
  702 +Because C<when> statements are executed in order, the default must
  703 +come last. You don't have to use an explicit default--you can just
  704 +fall off the last C<when> into ordinary code. But use of a C<default>
  705 +block is good documentation.
  706 +
  707 +If you use a C<for> loop with a parameter named C<$_> (either
  708 +explicitly or implicitly), that parameter can function as the topic
  709 +of any C<when> statements within the loop.
  710 +
  711 +You can explicitly break out of a C<when> block (and its surrounding
  712 +topicalizer block) early using the C<break> verb. More precisely,
  713 +it leaves the innermost block outside the C<when> that uses C<$_>
  714 +as one of its formal parameters, either explicitly or implicitly.
  715 +It does this essentially by going to the end of the block and
  716 +returning normally from that block. In other words, a break (either
  717 +implicit or explicit) is assumed to indicate success, not failure.
  718 +
  719 +You can explicitly leave a C<when> block and go to the next statement
  720 +following the C<when> by using C<continue>. (Note that, unlike C's
  721 +idea of "falling through", subsequent C<when> conditions are evaluated.
  722 +To jump into the next C<when> block without testing its condition,
  723 +you must use a C<goto>.)
  724 +
  725 +If you have a switch that is the main block of a C<for> loop, and
  726 +you break out of the switch either implicitly or explicitly (that is,
  727 +the switch "succeeds"), control merely goes to the end of that block,
  728 +and thence on to the next iteration of the loop. You must use C<last>
  729 +(or some more violent control exception such as C<return>) to break
  730 +out of the entire loop early. Of course, an explicit C<next> might
  731 +be clearer than a C<break> if you really want to go directly to the
  732 +next iteration. On the other hand, C<break> can take an optional
  733 +argument giving the value for that iteration of the loop. As with
  734 +the C<.leave> method, there is also a C<.break> method to break from a
  735 +labelled block functioning as a switch:
  736 +
  737 + OUTER.break($retval)
  738 +
  739 +=head1 Exception handlers
  740 +
  741 +Unlike many other languages, Perl 6 specifies exception handlers by
  742 +placing a C<CATCH> block I<within> that block that is having its exceptions
  743 +handled.
  744 +
  745 +The Perl 6 equivalent to Perl 5's C<eval {...}> is C<try {...}>.
  746 +(Perl 6's C<eval> function only evaluates strings, not blocks.)
  747 +A C<try> block by default has a C<CATCH> block that handles all
  748 +exceptions by ignoring them. If you define a C<CATCH> block within
  749 +the C<try>, it replaces the default C<CATCH>. It also makes the C<try>
  750 +keyword redundant, because any block can function as a C<try> block
  751 +if you put a C<CATCH> block within it.
  752 +
  753 +An exception handler is just a switch statement on an implicit topic
  754 +supplied within the C<CATCH> block. That implicit topic is the current
  755 +exception object, also known as C<$!>. Inside the C<CATCH> block, it's
  756 +also bound to C<$_>, since it's the topic. Because of smart matching,
  757 +ordinary C<when> statements are sufficiently powerful to pattern
  758 +match the current exception against classes or patterns or numbers
  759 +without any special syntax for exception handlers. If none of the
  760 +cases in the C<CATCH> handles the exception, the exception is rethrown.
  761 +To ignore all unhandled exceptions, use an empty C<default> case.
  762 +(In other words, there is an implicit C<die $!> just inside the end
  763 +of the C<CATCH> block. Handled exceptions break out past this implicit
  764 +rethrow.)
  765 +
  766 +A C<CATCH> block sees the lexical scope in which it was defined, but
  767 +its caller is the dynamic location that threw the exception. That is,
  768 +the stack is not unwound until some exception handler chooses to
  769 +unwind it by "handling" the exception in question. So logically,
  770 +if the C<CATCH> block throws its own exception, you would expect the
  771 +C<CATCH> block to catch its own exception recursively forever. However,
  772 +a C<CATCH> must not behave that way, so we say that a C<CATCH> block
  773 +never attempts to handle any exception thrown within its own dynamic scope.
  774 +(Otherwise the C<die> in the previous paragraph would never work.)
  775 +
  776 +=head1 Control Exceptions
  777 +
  778 +All abnormal control flow is, in the general case, handled by the
  779 +exception mechanism (which is likely to be optimized away in specific
  780 +cases.) Here "abnormal" means any transfer of control outward that
  781 +is not just falling off the end of a block. A C<return>,
  782 +for example, is considered a form of abnormal control flow, since it
  783 +can jump out of multiple levels of closures to the end of the scope
  784 +of the current subroutine definition. Loop commands like C<next>
  785 +are abnormal, but looping because you hit the end of the block is not.
  786 +The implicit break of a C<when> block is abnormal.
  787 +
  788 +A C<CATCH> block handles only "bad" exceptions, and lets control
  789 +exceptions pass unhindered. Control exceptions may be caught with a
  790 +C<CONTROL> block. Generally you don't need to worry about this unless
  791 +you're defining a control construct. You may have one C<CATCH> block
  792 +and one C<CONTROL> block, since some user-defined constructs may wish to
  793 +supply an implicit C<CONTROL> block to your closure, but let you define
  794 +your own C<CATCH> block.
  795 +
  796 +A C<return> always exits from the lexically surrounding sub
  797 +or method definition (that is, from a function officially declared
  798 +with the C<sub>, C<method>, or C<submethod> keywords). Pointy blocks
  799 +and bare closures are transparent to C<return>. If you pass a closure
  800 +object outside of its official "sub" scope, it is illegal to
  801 +return from it. You may only leave the displaced closure block itself
  802 +by falling off the end of it or by explicitly calling C<leave>.
  803 +
  804 +To return a value from any pointy block or bare closure, you either
  805 +just let the block return the value of its final expression, or you
  806 +can use C<leave>, which comes in both function and method forms.
  807 +The function (or listop) form always exits from the innermost block,
  808 +returning its arguments as the final value of the block exactly as
  809 +return does. The method form will leave any block in the dynamic
  810 +scope that can be named as an object and that responds to the C<.leave>
  811 +method.
  812 +
  813 +Hence, the C<leave> function:
  814 +
  815 + leave(1,2,3)
  816 +
  817 +is really just short for:
  818 +
  819 + &?BLOCK.leave(1,2,3)
  820 +
  821 +To return from your immediate caller, you can say:
  822 +
  823 + caller.leave(1,2,3)
  824 +
  825 +Further contexts up the caller stack may be located by use of the
  826 +C<context> function:
  827 +
  828 + context({ .labels.any eq 'LINE' }).leave(1,2,3);
  829 +
  830 +By default the innermost dynamic scope matching the selection criteria
  831 +will be exited. This can be a bit cumbersome, so in the particular
  832 +case of labels, the label that is already visible in the current lexical
  833 +scope is considered a kind of pseudo object specifying a potential
  834 +dynamic context. If instead of the above you say:
  835 +
  836 + LINE.leave(1,2,3)
  837 +
  838 +it was always exit from your lexically scoped C<LINE> loop, even
  839 +if some inner dynamic scope you can't see happens to also have that
  840 +label. If the C<LINE> label is visible but you aren't actually in
  841 +a dynamic scope controlled by that label, an exception is thrown.
  842 +(If the C<LINE> is not visible, it would have been caught earlier at
  843 +compile time since C<LINE> would likely be a bareword.)
  844 +
  845 +In theory, any user-defined control construct can catch any control
  846 +exception it likes. However, there have to be some culturally enforced
  847 +standards on which constructs capture which exceptions. Much like
  848 +C<return> may only return from an "official" subroutine or method,
  849 +a loop exit like C<next> should be caught by the construct the user
  850 +expects it to be caught by. In particular, if the user labels a loop
  851 +with a specific label, and calls a loop control from within the lexical
  852 +scope of that loop, and if that call mentions the outer loop's label,
  853 +then that outer loop is the one that must be controlled. In other words,
  854 +it first tries this form:
  855 +
  856 + LINE.leave(1,2,3)
  857 +
  858 +If there is no such lexically scoped outer loop in the current subroutine,
  859 +then a fallback search is made outward through the dynamic scopes in
  860 +the same way Perl 5 does. (The difference between Perl 5 and Perl 6
  861 +in this respect arises only because Perl 5 didn't have user-defined
  862 +control structures, hence the sub's lexical scope was I<always>
  863 +the innermost dynamic scope, so the preference to the lexical scope
  864 +in the current sub was implicit. For Perl 6 we have to make this
  865 +preference explicit.) So this fallback is more like the C<context>
  866 +form we saw earlier.
  867 +
  868 +Warnings are produced in Perl 6 by throwing a resumable control
  869 +exception to the outermost scope, which by default prints the
  870 +warning and resumes the exception by extracting a resume continuation
  871 +from the exception, which must be supplied by the warn() function
  872 +(or equivalent). Exceptions are not resumable in Perl 6 unless
  873 +the exception object does the C<Resumable> role. (Note that fatal
  874 +exception types can do the C<Resumable> role even if thrown via
  875 +C<fail()>--when uncaught they just hit the outermost fatal handler
  876 +instead of the outermost warning handler, so some inner scope has to
  877 +explicitly treat them as warnings and resume them.)
  878 +
  879 +Since warnings are processed using the standard control exception
  880 +mechanism, they may be intercepted and either suppressed or fatalized
  881 +anywhere within the dynamic scope by supplying a suitable C<CONTROL>
  882 +block. This dynamic control is orthogonal to any lexically scoped
  883 +warning controls, which merely decide whether to call C<warn()>
  884 +in the first place.
  885 +
  886 +As with calls to C<return>, the warning control exception is an
  887 +abstraction that the compiler is free to optimize away (along with the
  888 +associated continuation) when the compiler or runtime can determine
  889 +that the semantics would be preserved by merely printing out the
  890 +error and going on. Since all exception handlers run in the dynamic
  891 +context of the throw, that reduces to simply returning from the C<warn>
  892 +function most of the time.
  893 +
  894 +=head1 The goto statement
  895 +
  896 +In addition to C<next>, C<last>, and C<redo>, Perl 6 also supports
  897 +C<goto>. As with ordinary loop controls, the label is searched for
  898 +first lexically within the current subroutine, then dynamically outside
  899 +of it. Unlike with loop controls, however, scanning a scope includes
  900 +a scan of any lexical scopes included within the current candidate
  901 +scope. As in Perl 5, it is possible to C<goto> into a lexical scope,
  902 +but only for lexical scopes that require no special initialization
  903 +of parameters. (Initialization of ordinary variables does not
  904 +count--presumably the presence of a label will prevent code-movement
  905 +optimizations past the label.) So, for instance, it's always possible
  906 +to C<goto> into the next case of a C<when> or into either the "then"
  907 +or "else" branch of a conditional. You may not go into a C<given>
  908 +or a C<for>, though, because that would bypass a formal parameter
  909 +binding (not to mention list generation in the case of C<for>).
  910 +(Note: the implicit default binding of an outer $_ to an inner $_
  911 +can be emulated for a bare block, so that doesn't fall under the
  912 +prohibition on bypassing formal binding.)
  913 +
  914 +=head1 Exceptions
  915 +
  916 +As in Perl 5, many built-in functions simply return undef when you ask
  917 +for a value out of range, or the function fails somehow. Perl 6 has
  918 +C<Failure> objects, any of which refers to an unthrown C<Exception> object in
  919 +C<$!> and knows whether it has been handled or not.
  920 +
  921 +If you test a C<Failure> for C<.defined> or C<.true>, it causes C<$!>
  922 +to mark the exception as I<handled>; the exception acts as a relatively harmless
  923 +undefined value thereafter. Any other use of the C<Failure> object to
  924 +extract a normal value will throw its associated exception immediately.
  925 +(The C<Failure> may, however, be stored in any container whose type
  926 +allows the C<Failure> role to be mixed in.) The C<.handled> method
  927 +returns false on failures that have not been handled. It returns true for
  928 +handled exceptions and for all non-C<Failure> objects. (That is,
  929 +it is an C<Object> method, not a C<Failure> method. Only C<Failure> objects
  930 +need to store the actual status however; other types just return C<True>.)
  931 +
  932 +Because the contextual variable C<$!> contains all exceptions collected in the
  933 +current lexical scope, saying C<die $!> will throw all exceptions,
  934 +whether they were handled or not. A bare C<die>/C<fail> takes C<$!> as the
  935 +default argument.
  936 +
  937 +At scope exit, C<$!> discards all handled exceptions from itself, then performs
  938 +a garbage-collection check for all remaining (unhandled) exceptions. If all of
  939 +them are still alive (e.g. by becoming part of the return value), then they are
  940 +appended to C<< CALLER::<$!> >>. Otherwise, it calls C<die> to throw those
  941 +exceptions as a single new exception, which may then be caught with a C<CATCH>
  942 +block in the current (or caller's) scope.
  943 +
  944 +You can cause built-ins to automatically throw exceptions on failure using
  945 +
  946 + use fatal;
  947 +
  948 +The C<fail> function responds to the caller's C<use fatal> state. It
  949 +either returns an unthrown exception, or throws the exception.
  950 +
  951 +=head1 Closure traits
  952 +
  953 +A C<CATCH> block is just a trait of the closure containing it. Other
  954 +blocks can be installed as traits as well. These other blocks are
  955 +called at various times, and some of them respond to various control
  956 +exceptions and exit values:
  957 +
  958 + BEGIN {...}* at compile time, ASAP, only ever runs once
  959 + CHECK {...}* at compile time, ALAP, only ever runs once
  960 + INIT {...}* at run time, ASAP, only ever runs once
  961 + END {...} at run time, ALAP, only ever runs once
  962 +
  963 + START {...}* on first ever execution, once per closure clone
  964 +
  965 + ENTER {...}* at every block entry time, repeats on loop blocks.
  966 + LEAVE {...} at every block exit time
  967 + KEEP {...} at every successful block exit, part of LEAVE queue
  968 + UNDO {...} at every unsuccessful block exit, part of LEAVE queue
  969 +
  970 + FIRST {...}* at loop initialization time, before any ENTER
  971 + NEXT {...} at loop continuation time, before any LEAVE
  972 + LAST {...} at loop termination time, after any LEAVE
  973 +
  974 + PRE {...} assert precondition at every block entry, before ENTER
  975 + POST {...} assert postcondition at every block exit, after LEAVE
  976 +
  977 + CATCH {...} catch exceptions, before LEAVE
  978 + CONTROL {...} catch control exceptions, before LEAVE
  979 +
  980 +Those marked with a C<*> can also be used within an expression:
  981 +
  982 + my $compiletime = BEGIN { localtime };
  983 + our $temphandle = START { maketemp() };
  984 +
  985 +Code that is generated at run time can still fire off C<CHECK>
  986 +and C<INIT> blocks, though of course those blocks can't do things that
  987 +would require travel back in time.
  988 +
  989 +Some of these also have corresponding traits that can be set on variables.
  990 +These have the advantage of passing the variable in question into
  991 +the closure as its topic:
  992 +
  993 + my $r will start { .set_random_seed() };
  994 + our $h will enter { .rememberit() } will undo { .forgetit() };
  995 +
  996 +Apart from C<CATCH> and C<CONTROL>, which can only occur once, most
  997 +of these can occur multiple times within the block. So they aren't
  998 +really traits, exactly--they add themselves onto a list stored in the
  999 +actual trait (except for C<START>, which executes inline). So if you
  1000 +examine the C<ENTER> trait of a block, you'll find that it's really
  1001 +a list of closures rather than a single closure.
  1002 +
  1003 +The semantics of C<INIT> and C<START> are not equivalent to each
  1004 +other in the case of cloned closures. An C<INIT> only runs once for
  1005 +all copies of a cloned closure. A C<START> runs separately for each
  1006 +clone, so separate clones can keep separate state variables:
  1007 +
  1008 + our $i = 0;
  1009 + ...
  1010 + $func = { state $x will start { $x = $i++ }; dostuff($i) };
  1011 +
  1012 +But C<state> automatically applies "start" semantics to any initializer,
  1013 +so this also works:
  1014 +
  1015 + $func = { state $x = $i++; dostuff($i) }
  1016 +
  1017 +Each subsequent clone gets an initial state that is one higher than the
  1018 +previous, and each clone maintains its own state of C<$x>, because that's
  1019 +what C<state> variables do.
  1020 +
  1021 +Even in the absence of closure cloning, C<INIT> runs before the
  1022 +mainline code, while C<START> puts off the initialization till the
  1023 +last possible moment, then runs exactly once, and caches its value
  1024 +for all subsequent calls (assuming it wasn't called in void context,
  1025 +in which case the C<START> is evaluated once only for its side effects).
  1026 +In particular, this means that C<START> can make use of any parameters
  1027 +passed in on the first call, whereas C<INIT> cannot.
  1028 +
  1029 +All of these trait blocks can see any previously declared lexical
  1030 +variables, even if those variables have not been elaborated yet when
  1031 +the closure is invoked (in which case the variables evaluate to an
  1032 +undefined value.)
  1033 +
  1034 +Note: Apocalypse 4 confused the notions of C<PRE>/C<POST> with C<ENTER>/C<LEAVE>.
  1035 +These are now separate notions. C<ENTER> and C<LEAVE> are used only for
  1036 +their side effects. C<PRE> and C<POST> must return boolean values that are
  1037 +evaluated according to the usual Design by Contract (DBC) rules. (Plus,
  1038 +if you use C<ENTER>/C<LEAVE> in a class block, they only execute when the
  1039 +class block is executed, but C<PRE>/C<POST> in a class block are evaluated
  1040 +around every method in the class.) C<KEEP> and C<UNDO> are just variants
  1041 +of C<LEAVE>, and for execution order are treated as part of the queue of
  1042 +C<LEAVE> blocks.
  1043 +
  1044 +C<FIRST>, C<NEXT>, and C<LAST> are meaningful only within the
  1045 +lexical scope of a loop, and may occur only at the top level of such
  1046 +a loop block. A C<NEXT> executes only if the end of the loop block is
  1047 +reached normally, or an explicit C<next> is executed. In distinction
  1048 +to C<LEAVE> blocks, a C<NEXT> block is not executed if the loop block
  1049 +is exited via any exception other than the control exception thrown
  1050 +by C<next>. In particular, a C<last> bypasses evaluation of C<NEXT>
  1051 +blocks.
  1052 +
  1053 +[Note: the name C<FIRST> used to be associated with C<state>
  1054 +declarations. Now it is associated only with loops. See the C<START>
  1055 +above for C<state> semantics.]
  1056 +
  1057 +C<LEAVE> blocks are evaluated after C<CATCH> and C<CONTROL> blocks, including
  1058 +the C<LEAVE> variants, C<KEEP> and C<UNDO>. C<POST> blocks are evaluated after
  1059 +everything else, to guarantee that even C<LEAVE> blocks can't violate DBC.
  1060 +Likewise C<PRE> blocks fire off before any C<ENTER> or C<FIRST> (though not
  1061 +before C<BEGIN>, C<CHECK>, or C<INIT>, since those are done at compile or
  1062 +process initialization time).
  1063 +
  1064 +For blocks such as C<KEEP> and C<POST> that are run when exiting a
  1065 +scope normally, the return value (if any) from that scope is available
  1066 +as the current topic. (It is presented as a C<Capture> object.)
  1067 +The topic of the outer block is still available as C<< OUTER::<$_> >>.
  1068 +Whether the return value is modifiable may be a policy of the block
  1069 +in question. In particular, the return value should not be modified
  1070 +within a C<POST> block, but a C<LEAVE> block could be more liberal.
  1071 +
  1072 +=head1 Statement parsing
  1073 +
  1074 +In this statement:
  1075 +
  1076 + given EXPR {
  1077 + when EXPR { ... }
  1078 + when EXPR { ... }
  1079 + ...
  1080 + }
  1081 +
  1082 +parentheses aren't necessary around C<EXPR> because the whitespace
  1083 +between C<EXPR> and the block forces the block to be considered a block
  1084 +rather than a subscript, provided the block occurs where an infix
  1085 +operator would be expected. This works for all control structures,
  1086 +not just the new ones in Perl 6. A top-level bare block is always
  1087 +considered a statement block if there's a term and a space before it:
  1088 +
  1089 + if $foo { ... }
  1090 + elsif $bar { ... }
  1091 + else { ... }
  1092 + while $more { ... }
  1093 + for 1..10 { ... }
  1094 +
  1095 +You can still parenthesize the expression argument for old times'
  1096 +sake, as long as there's a space between the closing paren and the
  1097 +opening brace. (Otherwise it will be parsed as a hash subscript.)
  1098 +
  1099 +Note that the parser cannot in