S04-control.pod

=encoding utf8

=head1 TITLE

Synopsis 4: Blocks and Statements

=head1 AUTHORS

    Larry Wall <larry@wall.org>

=head1 VERSION

    Created: 19 Aug 2004

    Last Modified: 16 Sep 2010
    Version: 104

This document summarizes Apocalypse 4, which covers the block and
statement syntax of Perl.

=head1 The Relationship of Lexical and Dynamic Scopes

Control flow is a dynamic feature of all computer programming
languages, but languages differ in the extent to which control flow is
attached to declarative features of the language, which are often known
as "static" or "lexical".  We use the phrase "lexical scoping" in its
industry-standard meaning to indicate those blocks that surround the
current textual location.  More abstractly, any declarations associated
with those textual blocks are also considered to be part of the lexical
scope, and this is where the term earns the "lexical" part of its name,
in the sense that lexical scoping actually does define the "lexicon"
for the current chunk of code, insofar as the definitions of variables
and routines create a local domain-specific language.

We also use the term "dynamic scoping" in the standard fashion to
indicate the nested call frames that are created and destroyed every
time a function or method is called.  In most interesting programs the
dynamic scopes are nested quite differently from the lexical scopes,
so it's important to distinguish carefully which kind of scoping
we're talking about.

Further compounding the difficulty is that every dynamic scope's outer call frame is
associated with a lexical scope somewhere, so you can't just consider
one kind of scoping or the other in isolation.  Many constructs define
a particular interplay of lexical and dynamic features.  For instance,
unlike normal lexically scope variables, dynamic variables search
up the dynamic call stack for a variable of a particular name, but at
each "stop" along the way, they are actually looking in the lexical
"pad" associated with that particular dynamic scope's call frame.

In Perl 6, control flow is designed to do what the user expects most of
the time, but this implies that we must consider the declarative nature
of labels and blocks and combine those with the dynamic nature of the
call stack.  For instance, a C<return> statement always returns from
the lexically scoped subroutine that surrounds it.  But to do that,
it may eventually have to peel back any number of layers of dynamic
call frames internal to the subroutine's current call frame.  The lexical scope supplies the
declared target for the dynamic operation.  There does not seem to
be a prevailing term in the industry for this, so we've coined the
term I<lexotic> to refer to these strange operations that perform a
dynamic operation with a lexical target in mind.  Lexotic operators
in Perl 6 include:

    return
    next
    last
    redo
    goto

Some of these operators also fall back to a purely dynamic interpretation
if the lexotic interpretation doesn't work.  For instance, C<next> with a label
will prefer to exit a loop lexotically, but if there is no loop with
an appropriate label in the lexical context, it will then scan upward
dynamically through the call frames for any loop with the appropriate label, even though that
loop will not be lexically visible.  (C<next> without a label is purely dynamic.)  Lexotic and dynamic control flow
is implemented by a system of control exceptions.  For the lexotic
return of C<next>, the control exception will contain the identity of
the loop scope to be exited (since the label was already "used up" to
discover that identity), but for the dynamic fallback, the exception
will contain only the loop label to be matched dynamically.  See
L</Control Exceptions> below.

=head1 The Relationship of Blocks and Declarations

Every block is a closure.  (That is, in the abstract, they're all
anonymous subroutines that take a snapshot of their lexical environment.)
How a block is invoked and how its results are used are matters of
context, but closures all work the same on the inside.

Blocks are delimited by curlies, or by the beginning and end of the
current compilation unit (either the current file or the current
C<eval> string).  Unlike in Perl 5, there are (by policy) no implicit
blocks around standard control structures.  (You could write a macro
that violates this, but resist the urge.)  Variables that mediate
between an outer statement and an inner block (such as loop variables)
should generally be declared as formal parameters to that block.  There
are three ways to declare formal parameters to a closure.

    $func = sub ($a, $b) { .print if $a eq $b };  # standard sub declaration
    $func = -> $a, $b { .print if $a eq $b };     # a "pointy" block
    $func = { .print if $^a eq $^b }              # placeholder arguments

A bare closure (except the block associated with a conditional statement)
without placeholder arguments that uses C<$_>
(either explicitly or implicitly) is treated as though C<$_> were a
formal parameter:

    $func = { .print if $_ };   # Same as: $func = <-> $_ { .print if $_ };
    $func("printme");

In any case, all formal parameters are the equivalent of C<my> variables
within the block.  See S06 for more on function parameters.

Except for such formal parameter declarations, all lexically scoped
declarations are visible from the point of declaration to the end of
the enclosing block.  Period.  Lexicals may not "leak" from a block to any
other external scope (at least, not without some explicit aliasing
action on the part of the block, such as exportation of a symbol
from a module).  The "point of declaration" is the moment the compiler
sees "C<my $foo>", not the end of the statement as in Perl 5, so

    my $x = $x;

will no longer see the value of the outer C<$x>; you'll need to say
either

    my $x = $OUTER::x;

or

    my $x = OUTER::<$x>;

instead.

If you declare a lexical twice in the same scope, it is the same lexical:

    my $x;
    my $x;

By default the second declaration will get a compiler warning.
You may suppress this by modifying the first declaration
with C<proto>:

    my proto $x;
    ...
    while my $x = @x.shift {...}              # no warning
    while my $x = @x.shift {...}              # no warning

If you've referred to C<$x> prior to the first declaration, and the compiler
tentatively bound it to C<$OUTER::x>, then it's an error to declare it, and
the compiler is required to complain at that point.  If such use can't
be detected because it is hidden in an eval, then it is erroneous, since
the C<eval()> compiler might bind to either C<$OUTER::x> or the subsequently
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
compile-time constant, either a variable or named value, which
may be initialized with a pseudo-assignment:

    constant $pi of Int = 3;
    my Num constant π = atan2(2,2) * 4;

The initializing expression is evaluated at C<BEGIN> time.  Constants
(and enums) default to C<our> scoping so they can be accessed from
outside the package.

There is a new C<state> declarator that introduces a lexically scoped
variable like C<my> does, but with a lifetime that persists for the
life of the closure, so that it keeps its value from the end of one
call to the beginning of the next.  Separate clones of the closure
get separate state variables.  However, recursive calls to the same
clone use the same state variable.

Perl 5's "C<local>" function has been renamed to C<temp> to better
reflect what it does.  There is also a C<let> function that sets a
hypothetical value.  It works exactly like C<temp>, except that the
value will be restored only if the current block exits unsuccessfully.
(See Definition of Success below for more.)  C<temp> and C<let> temporize
or hypotheticalize the value or the variable depending on whether you
do assignment or binding.  One other difference from Perl 5 is that
the default is not to undefine a variable.  So

    temp $x;

causes C<$x> to start with its current value.  Use

    temp undefine $x;

to get the Perl 5 behavior.

Note that temporizations that are undone upon scope exit must be
prepared to be redone if a continuation within that scope is taken.

=head1 The Relationship of Blocks and Statements

In the absence of explicit control flow terminating the block early,
the return value of a block is the value of its final statement.
This is defined as the textually last statement of its top-level
list of statements; any statements embedded within those top-level
statements are in their own lower-level list of statements and,
while they may be a final statement in their subscope, they're not
considered the final statement of the outer block in question.

This is subtly different from Perl 5's behavior, which was to return
the value of the last expression evaluated, even if that expression
was just a conditional.  Unlike in Perl 5, if a final statement in
Perl 6 is a conditional that does not execute any of its branches, it
doesn't matter what the value of the condional is, the value of that
conditional statement is always C<Nil>.  If there are no statements
in the block at all, the result is also C<Nil>.

=head1 Statement-ending blocks

A line ending with a closing brace "C<}>", followed by nothing but
whitespace or comments, will terminate a statement if an end of statement
can occur there.  That is, these two statements are equivalent:

    my $x = sub { 3 }
    my $x = sub { 3 };

Since bracketed expressions consider their insides to be statements,
this works out consistently even where you might expect problems:

    my $x = [
        sub { 3 },  # this comma is not optional
        sub { 3 }   # the statement inside [] terminates here
    ];

    my $hash = {
        1 => { 2 => 3, 4 => 5 },  # OK
        2 => { 6 => 7, 8 => 9 }   # OK, terminates inner statement
    };

Because subroutine declarations are expressions, not statements,
this is now invalid:

    sub f { 3 } sub g { 3 }     # two terms occur in a row

But these two are valid:

    sub f { 3 }; sub g { 3 };
    sub f { 3 }; sub g { 3 }    # the trailing semicolon is optional

Though certain control statements could conceivably be parsed in a
self-contained way, for visual consistency all statement-terminating
blocks that end in the middle of a line I<must> be terminated by
semicolon unless they are naturally terminated by some other statement
terminator:

    while yin() { yang() }  say "done";      # ILLEGAL
    while yin() { yang() }; say "done";      # okay, explicit semicolon
    @yy := [ while yin() { yang() } ];       # okay within outer [...]
    while yin() { yang() } ==> sort          # okay, ==> separates statements

=head1 Conditional statements
X<if>X<unless>

The C<if> and C<unless> statements work much as they do in
Perl 5.  However, you may omit the parentheses on the conditional:

    if $foo == 123 {
        ...
    }
    elsif $foo == 321 {
        ...
    }
    else {
        ...
    }

The result of a conditional statement is the result of the block
chosen to execute.  If the conditional does not execute any
branch, the return value is C<Nil>.

The C<unless> statement does not allow an C<elsif> or C<else> in Perl 6.

The value of the conditional expression may be optionally bound to
a closure parameter:

    if    testa() -> $a { say $a }
    elsif testb() -> $b { say $b }
    else          -> $b { say $b }

Note that the value being evaluated for truth and subsequently bound is
not necessarily a value of type C<Bool>.  (All normal types in Perl may
be evaluated for truth.  In fact, this construct would be relatively
useless if you could bind only boolean values as parameters, since
within the closure you already know whether it evaluated to true
or false.)  Binding within an C<else> automatically binds the value
tested by the previous C<if> or C<elsif>, which, while known to be
false, might nevertheless be an I<interesting> value of false.  (By similar
reasoning, an C<unless> allows binding of a false parameter.)

An explicit placeholder may also be used:

    if blahblah() { return $^it }

However, use of C<$_> with a conditional statement's block is I<not>
considered sufficiently explicit to turn a 0-ary block into a 1-ary
function, so both these methods use the same invocant:

    if .haste { .waste }

(Contrast with a non-conditional statement such as:

    for .haste { .waste }

where each call to the block would bind a new invocant for the
C<.waste> method, each of which is likely different from the original
invocant to the C<.haste> method.)

Conditional statement modifiers work as in Perl 5.  So do the
implicit conditionals implied by short-circuit operators.  Note though that
the contents of parens or brackets is parsed as a semicolon-separated list of 
I<statements>,
so you can say:

    @x = 41, (42 if $answer), 43;

and that is equivalent to:

    @x = 41, ($answer ?? 42 !! Nil), 43

=head1 Loop statements

Looping statement modifiers are the same as in Perl 5 except that,
for ease of writing list comprehensions, a looping statement modifier
is allowed to contain a single conditional statement modifier:

    @evens = ($_ * 2 if .odd for 0..100);

Loop modifiers C<next>, C<last>, and C<redo> also work much as in
Perl 5.  However, the labeled forms can use method call syntax:
C<LABEL.next>, etc.  The C<.next> and C<.last> methods take an
optional argument giving the final value of that loop iteration.
So the old C<next LINE> syntax is still allowed but really does
something like C<LINE.next(Nil)> underneath.  Any block object can
be used, not just labels, so to return a value from this iteration
of the current block you can say:

    &?BLOCK.next($retval);

[Conjecture: a bare C<next($retval)> function could be taught to do
the same, as long as C<$retval> isn't a loop label.  Presumably multiple
dispatch could sort this out.]

With a target object or label, loop modifiers search lexotically
for the scope to modify.  Without a target, however, they are purely
dynamic, and choose the innermost dynamic loop, which may well be a
C<map> or other implicitly looping function, including user-defined
functions.

There is no longer a C<continue> block.  Instead, use a C<NEXT> block
within the body of the loop.  See below.

The value of a loop statement is the list of values from each
iteration.  Each iteration's value is returned as a single "argument"
object.  See L<S02> for a long definition of argument, but in short,
it's either an ordinary object or a parcel containing multiple values.

Normal flat list context ignores parcel boundaries and flattens the list.
Slice context turns any parcel objects into C<Seq> objects.

Iterations that return C<Nil> (such as by calling C<next> with no extra return
arguments) return that C<Nil> as the next value, which will therefore disappear
when interpolated in flat context, but will interpolate an empty C<Seq> into slice
context.

For finer-grained control of which iterations return values, use
C<gather> and C<take>.

Since the final expression in a subroutine returns its value, it's
possible to accidentally return a loop's return value when you were
only evaluating the loop for its side effects.  If you do not wish
to accidentally return a list from the final loop statement in a
subroutine, place an explicit return statement after it, use a C<sink>
statement prefix on the loop itself.

=head2 The C<while> and C<until> statements
X<while>X<until>

The C<while> and C<until> statements work as in Perl 5, except that you
may leave out the parentheses around the conditional:

    while $bar < 100 {
        ...
    }

As with conditionals, you may optionally bind the result of the
conditional expression to a parameter of the block:

    while something() -> $thing {
        ...
    }

    while something() { ... $^thing ... }

Nothing is ever bound implicitly, however, and many conditionals would
simply bind C<True> or C<False> in an uninteresting fashion.  This mechanism
is really only good for objects that know how to return a boolean
value and still remain themselves.  In general, for most iterated
solutions you should consider using a C<for> loop instead (see below).
In particular, we now generally use C<for> to iterate filehandles.

=head2 The C<repeat> statement
X<repeat>X<while>X<next>X<last>X<redo>

Unlike in Perl 5, applying a statement modifier to a C<do> block is
specifically disallowed:


    do {
        ...
    } while $x < 10;    # ILLEGAL

Instead, you should write the more Pascal-like C<repeat> loop:

    repeat {
        ...
    } while $x < 10;

or equivalently:

    repeat {
        ...
    } until $x >= 10;

Unlike Perl 5's C<do-while> loop, this is a real loop block now, so
C<next>, C<last>, and C<redo> work as expected.  The loop conditional
on a C<repeat> block is required, so it will be recognized even if you
put it on a line by its own:

    repeat
    {
        ...
    }
    while $x < 10;

However, that's likely to be visually confused with a following
C<while> loop at the best of times, so it's also allowed to put the
loop conditional at the front, with the same meaning. (The C<repeat>
keyword forces the conditional to be evaluated at the end of the loop,
so it's still C's C<do-while> semantics.)  Therefore, even under GNU style
rules, the previous example may be rewritten into a very clear:

    repeat while $x < 10
      {
        ...
      }

or equivalently:

    repeat until $x >= 10
      {
        ...
      }

As with an ordinary C<while>, you may optionally bind the result of
the conditional expression to a parameter of the block:

    repeat -> $thing {
        ...
    } while something();

or

    repeat while something() -> $thing {
        ...
    }

Since the loop executes once before evaluating the condition, the
bound parameter will be undefined that first time through the loop.

=head2 The general loop statement
X<loop>

The C<loop> statement is the C-style C<for> loop in disguise:

    loop ($i = 0; $i < 10; $i++) {
        ...
    }

As in C, the parentheses are required if you supply the 3-part spec; however,
the 3-part loop spec may be entirely omitted to write an infinite loop.
That is,

    loop {...}

is equivalent to the Cish idiom:

    loop (;;) {...}

=head2 The C<for> statement
X<for>X<zip>X<Z>X<STDIN>X<$*IN>X<lines>

There is no C<foreach> statement any more. It's always spelled C<for>
in Perl 6, so it always takes a list as an argument:

    for @foo { .print }

As mentioned earlier, the loop variable is named by passing a parameter
to the closure:

    for @foo -> $item { print $item }

Multiple parameters may be passed, in which case the list is traversed
more than one element at a time:

    for %hash.kv -> $key, $value { print "$key => $value\n" }

To process two arrays in parallel use the C<zip> function to generate a
list that can be bound to the corresponding number of parameters:

    for zip(@a;@b) -> $a, $b { print "[$a, $b]\n" }
    for @a Z @b -> $a, $b { print "[$a, $b]\n" }        # same thing

The list is evaluated lazily by default, so instead of using a C<while>
to read a file a line at a time as you would in Perl 5:

    while (my $line = <STDIN>) {...}

in Perl 6 you should use a C<for> instead:

    for $*IN.lines -> $line {...}

This has the added benefit of limiting the scope of the C<$line>
parameter to the block it's bound to.  (The C<while>'s declaration of
C<$line> continues to be visible past the end of the block.  Remember,
no implicit block scopes.)  It is also possible to write

    while $*IN.get -> $line {...}

However, this is likely to fail on autochomped filehandles, so use
the C<for> loop instead.

Note also that Perl 5's special rule causing

    while (<>) {...}

to automatically assign to C<$_> is not carried over to Perl 6.  That
should now be written:

    for lines() {...}

which is short for

    for lines($*ARGFILES) {...}

Arguments bound to the formal parameters of a pointy block are by
default readonly within the block.  You can declare a parameter
read/write by including the "C<is rw>" trait.  The following treats
every other value in C<@values> as modifiable:

    for @values -> $even is rw, $odd { ... }

In the case where you want all your parameters to default to C<rw>,
you may use the visually suggestive double-ended arrow to indicate that
values flow both ways:

    for @values <-> $even, $odd { ... }

This is equivalent to

    for @values -> $even is rw, $odd is rw { ... }

If you rely on C<$_> as the implicit parameter to a block,
then C<$_> is considered read/write by default.  That is,
the construct:

    for @foo {...}

is actually short for:

    for @foo <-> $_ {...}

so you can modify the current list element in that case.

When used as statement modifiers on implicit blocks (thunks), C<for>
and C<given> privately temporize the current value of C<$_> for the
left side of the statement and restore the original value at loop exit:

    $_ = 42;
    .say             # 42
    .say for 1,2,3;  # 1,2,3
    .say;            # 42

The previous value of C<$_> is not available within the loop.  If you
want it to be available, you must rewrite it as an explicit block
using curlies:

    { say OUTER::<$_>, $_ } for 1,2,3;  # 421,422,423

No temporization is necessary with the explicit form since C<$_> is a
formal parameter to the block.  Likewise, temporization is never needed
for C<< statement_control:<for> >> because it always calls a closure.

=head2 The do-once loop

In Perl 5, a bare block is deemed to be a do-once loop.  In Perl 6,
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
return the value of that statement and use it in an expression:

    $x = do if $a { $b } else { $c };

This construct only allows you to attach a single statement to the end
of an expression.  If you want to continue the expression after the
statement, or if you want to attach multiple statements, you must either
use the curly form or surround the entire expression in brackets of some sort:

    @primesquares = (do $_ if prime($_) for 1..100) »**» 2;

Since a bare expression may be used as a statement, you may use C<do>
on an expression, but its only effect is to function as an unmatched
left parenthesis, much like the C<$> operator in Haskell.  That is,
precedence decisions do not cross a C<do> boundary, and the missing
"right paren" is assumed at the next statement terminator or unmatched
bracket.  A C<do> is unnecessary immediately after any opening bracket as
the syntax inside brackets is a semicolon-separated list of statements,
so the above can in fact be written:

    @primesquares = ($_ if prime($_) for 1..100) »**» 2;

This basically gives us list comprehensions as rvalue expressions:

    (for 1..100 { $_ if prime($_)}).say

Another consequence of this is that any block just inside a
left parenthesis is immediately called like a bare block, so a
multidimensional list comprehension may be written using a block with
multiple parameters fed by a C<for> modifier:

    @names = (-> $name, $num { "$name.$num" } for 'a'..'zzz' X 1..100);

or equivalently, using placeholders:

    @names = ({ "$^name.$^num" } for 'a'..'zzz' X 1..100);

Since C<do> is defined as going in front of a statement, it follows
that it can always be followed by a statement label.  This is particularly
useful for the do-once block, since it is officially a loop and can take
therefore loop control statements.

=head2 Statement-level bare blocks

Although a bare block occurring as a single statement is no longer
a do-once loop, it still executes immediately as in Perl 5, as if it
were immediately dereferenced with a C<.()> postfix, so within such a
block C<CALLER::> refers to the dynamic scope associated
with the lexical scope surrounding the block.

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.

Use of a placeholder parameter in statement-level blocks triggers a
syntax error, because the parameter is not out front where it can be
seen.  However, it's not an error when prefixed by a C<do>, or when
followed by a statement modifier:

    # Syntax error: Statement-level placeholder block
    { say $^x };

    # Not a syntax error, though $x doesn't get the argument it wants
    do { say $^x };

    # Not an error: Equivalent to "for 1..10 -> $x { say $x }"
    { say $^x } for 1..10;

    # Not an error: Equivalent to "if foo() -> $x { say $x }"
    { say $^x } if foo();

=head2 The C<gather> statement prefix
X<gather>X<take>

A variant of C<do> is C<gather>.  Like C<do>, it is followed by a statement
or block, and executes it once.  Unlike C<do>, it evaluates the statement or
block in sink (void) context; its return value is instead specified by calling
the C<take> list prefix operator one or more times within the dynamic scope of
the C<gather>.  The C<take> function's signature is like that of C<return>;
while having the syntax of a list operator, it merely returns a single item
or "argument" (see L<S02> for definition).

If you take multiple items in a comma list (since it is, after all, a list
operator), they will be wrapped up in a C<Parcel> object for return as the
next argument.  No additional context is applied by the C<take> operator,
since all context is lazy in Perl 6.  The flattening or slicing of any such
returned parcel will be dependent on how the C<gather>'s return iterator is
iterated (with C<.get> vs C<.getarg>).

The value returned by the C<take> to the C<take>'s own context is that same
returned argument (which is ignored when the C<take> is in sink context).
Regardless of the C<take>'s immediate context, the object returned is also
added to the list of values being gathered, which is returned by the C<gather>
as a lazy list (that is, an iterator, really), with each argument element
of that list corresponding to one C<take>.

Any parcels in the returned list are normally flattened when bound
into flat context.  When bound into a lol context, however,
the parcel objects become real C<List> objects that keep their
identity as discrete sublists.  The eventual binding context thus
determines whether to throw away or keep the groupings resulting from
each individual C<take> call.  Most list contexts are flat
rather than sliced, so the boundaries between individual C<take>
calls usually disappear.  (FLAT is an acronym meaning Flat Lists Are Typical. :)

Because C<gather> evaluates its block or statement in sink context,
this typically causes the C<take> function to be evaluated in sink
context.  However, a C<take> function that is not in sink context
gathers its return objects I<en passant> and also returns them unchanged.
This makes it easy to keep track of what you last "took":

    my @uniq = gather for @list {
        state $previous = take $_;
        next if $_ === $previous;
        $previous = take $_;
    }

The C<take> function essentially has two contexts simultaneously, the
context in which the C<gather> is operating, and the context in which the
C<take> is operating.  These need not be identical contexts, since they
may bind or coerce the resulting parcels differently:

    my @y;
    @x = gather for 1..2 {          # flat context for list of parcels
        my ($y) := take $_, $_ * 10;  # item context promotes parcel to seq
        push @y, $y;
    }
    # @x contains 4 Ints:  1,10,2,20 flattened by list assignment to @x
    # @y contains 2 Seqs: Seq(1,10),Seq(2,20) sliced by binding to positional $y

Likewise, we can just remember the gather's result parcel by binding and
later coercing it:

    my |$c := gather for 1..2 {
        take $_, $_ * 10;
    }
    # $c.flat produces 1,10,2,20 -- flatten fully into a list of Ints.
    # $c.slice produces Seq(1,10),Seq(2,20) -- list of Seqs, a 2-D list.
    # $c.item produces Seq((1,10),(2,20)) -- coerced to Seq of unresolved Parcels

Note that the C<take> itself is in sink context in this example because
the C<for> loop is in the sink context provided inside the gather.

A C<gather> is not considered a loop, but it is easy to combine with a loop
statement as in the examples above.

The C<take> operation may be defined internally using resumable control
exceptions, or dynamic variables, or pigeons carrying clay tablets.
The choice any particular implementation makes is specifically I<not> part
of the definition of Perl 6, and you should not rely on it in portable code.

=head2 The C<lift> statement prefix
X<lift>

When writing generic multi routines you often want to write a bit of
code whose meaning is dependent on the linguistic context of the caller.  It's
somewhat like virtual methods where the actual call depends on the type
of the invocant, but here the "invocant" is really the lexical scope of
the caller, and the virtual calls are name bindings.  Within a lift,
special rules apply to how names are looked up.  Only names defined
in the lexical scope of the immediately surrounding routine are considered concrete.
All other names (including implicit names of operators) are looked up
in the lexical scope of the caller when we actually know who the caller
is at run time.  (Note the caller can vary from call to call!)

This applies to anything that needs to be looked up at compile time, including
names of variables, and named values such as types and subs.

Through this mechanism, a generic multi can redirect execution to
a more specific version, but the candidate list for this redirection
is determined by the caller, not by the lexical scope of the multi,
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 !


Note that in each piece of lifted code there are references to
variables defined in the multi, such as C<$a>, C<$b>, and C<&f>.
These are taken at face value.  Everything else within a lift is
assumed to mean something in the caller's linguistic context.  (This implies
that there are some errors that would ordinarily be found at
compile time that cannot be found until we know what the caller's
lexical scope looks like at run time.  That's okay.)

=head2 Other C<do>-like forms
X<do>

Other similar forms, where a keyword is followed by code to be controlled by it, may also take bare statements,
including C<try>, C<quietly>, C<contend>, C<async>, C<lazy>, and C<sink>.  These constructs
establish a dynamic scope without necessarily establishing a lexical
scope.  (You can always establish a lexical scope explicitly by using
the block form of argument.)  As statement introducers, all these
keywords must be followed by whitespace.  (You can say something
like C<try({...})>, but then you are calling the C<try()> function
using function call syntax instead, and since Perl does not supply
such a function, it will be assumed to be a user-defined function.)
For purposes of flow control, none of these forms are considered loops,
but they may easily be applied to a normal loop.

Note that any construct in the statement_prefix category defines
special syntax.  If followed by a block it does not parse as a
list operator or even as a prefix unary; it will never look for any
additional expression following the block.  In particular,

    foo( try {...}, 2, 3 )

calls the C<foo> function with three arguments.  And

    do {...} + 1

add 1 to the result of the do block.  On the other hand, if a
statement_prefix is followed by a non-block statement, all nested
blockless statement_prefixes will terminate at the same statement
ending:

    do do do foo(); bar 43;

is parsed as:

    do { do { do { foo(); }}}; bar(43);


=head1 Switch statements
X<given>X<when>X<switch>X<case>X<default>

A switch statement is a means of topicalizing, so the switch keyword
is the English topicalizer, C<given>.  The keyword for individual
cases is C<when>:

    given EXPR {
        when EXPR { ... }
        when EXPR { ... }
        default { ... }
    }

The current topic is always aliased to the special variable C<$_>.
The C<given> block is just one way to set the current topic, but
a switch statement can be any block that sets C<$_>, including a
C<for> loop (assuming one of its loop variables is bound to C<$_>)
or the body of a method (if you have declared the invocant as C<$_>).
So switching behavior is actually caused by the C<when> statements in
the block, not by the nature of the block itself.  A C<when> statement
implicitly does a "smart match" between the current topic (C<$_>) and
the argument of the C<when>.  If the smart match succeeds, C<when>'s
associated block is executed, and the innermost surrounding block
that has C<$_> as one of its formal parameters (either explicit
or implicit) is automatically broken out of.  (If that is not the
block you wish to leave, you must use the C<LABEL.leave> method (or some
other control exception such as C<return> or C<next>) to
be more specific, since the compiler may find it difficult to guess
which surrounding construct was intended as the actual topicalizer.)
The value of the inner block is returned as the value of the outer
block.

If the smart match fails, control proceeds the next statement
normally, which may or may not be a C<when> statement.  Since C<when>
statements are presumed to be executed in order like normal statements,
it's not required that all the statements in a switch block be C<when>
statements (though it helps the optimizer to have a sequence of
contiguous C<when> statements, because then it can arrange to jump
directly to the first appropriate test that might possibly match.)

The default case:

    default {...}

is exactly equivalent to

    when * {...}

Because C<when> statements are executed in order, the default must
come last.  You don't have to use an explicit default--you can just
fall off the last C<when> into ordinary code.  But use of a C<default>
block is good documentation.

If you use a C<for> loop with a parameter named C<$_> (either
explicitly or implicitly), that parameter can function as the topic
of any C<when> statements within the loop.

You can explicitly break out of a C<when> block (and its surrounding
topicalizer block) early using the C<succeed> verb.  More precisely,
it first scans outward (lexically) for the innermost containing
C<when> block.  From there it continues to scan outward to find the
innermost block outside the C<when> that uses C<$_> as one of its
formal parameters, either explicitly or implicitly.  (Note that
both of these scans are done at compile time; if the scans fail,
it's a compile-time semantic error.)  Typically, such an outer
block will be the block of a C<given> or a C<for> statement, but any block that
sets the topic in its signature can be broken out of.  At run time,
C<succeed> uses a control exception to scan up the dynamic chain to
find the call frame belonging to that same outer block, and
when it has found that frame, it does a C<.leave> on it to unwind
the call frames.  If any arguments are supplied to the C<succeed> function,
they are passed out via the C<leave> method.  Since leaving a block is
considered a successful return, breaking out of one with C<succeed> is also considered
a successful return for the purposes of C<KEEP> and C<UNDO>.

The implicit break of a normal
C<when> block works the same way, returning the value of the entire
block (normally from its last statement) via an implicit C<succeed>.

You can explicitly leave a C<when> block and go to the next statement
following the C<when> by using C<proceed>.  (Note that, unlike C's
idea of "falling through", subsequent C<when> conditions are evaluated.
To jump into the next C<when> block without testing its condition,
you must use a C<goto>.  But generally that means you should refactor
instead.)

If you have a switch that is the main block of a C<for> loop, and
you break out of the switch either implicitly or explicitly (that is,
the switch "succeeds"), control merely goes to the end of that block,
and thence on to the next iteration of the loop.  You must use C<last>
(or some more violent control exception such as C<return>) to break
out of the entire loop early.  Of course, an explicit C<next> might
be clearer than a C<succeed> if you really want to go directly to the
next iteration.  On the other hand, C<succeed> can take an optional
argument giving the value for that iteration of the loop.  As with
the C<.leave> method, there is also a C<.succeed> method to break from a
labelled block functioning as a switch:

    OUTER.succeed($retval)

There is a C<when> statement modifier, but it does not have any
breakout semantics; it is merely a smartmatch against
the current topic.  That is,

    doit() when 42;

is exactly equivalent to

    doit() if $_ ~~ 42;

This is particularly useful for list comprehensions:

    @lucky = ($_ when /7/ for 1..100);

=head1 Exception handlers
X<CATCH>

Unlike many other languages, Perl 6 specifies exception handlers by
placing a C<CATCH> block I<within> that block that is having its exceptions
handled.

The Perl 6 equivalent to Perl 5's C<eval {...}> is C<try {...}>.
(Perl 6's C<eval> function only evaluates strings, not blocks.)
A C<try> block by default has a C<CATCH> block that handles all fatal
exceptions by ignoring them.  If you define a C<CATCH> block within
the C<try>, it replaces the default C<CATCH>.  It also makes the C<try>
keyword redundant, because any block can function as a C<try> block
if you put a C<CATCH> block within it.

An exception handler is just a switch statement on an implicit topic
supplied within the C<CATCH> block.  That implicit topic is the current
exception object, also known as C<$!>.  Inside the C<CATCH> block, it's
also bound to C<$_>, since it's the topic.  Because of smart matching,
ordinary C<when> statements are sufficiently powerful to pattern
match the current exception against classes or patterns or numbers
without any special syntax for exception handlers.  If none of the
cases in the C<CATCH> handles the exception, the exception is rethrown.
To ignore all unhandled exceptions, use an empty C<default> case.
(In other words, there is an implicit C<die $!> just inside the end
of the C<CATCH> block.  Handled exceptions break out past this implicit
rethrow.)  Hence, C<CATCH> is unlike all other switch statements in that
it treats code inside a C<default> block differently from code that's after
all the C<when> blocks but not in a C<default> block.

More specifically, when you write:

    CATCH {
        when Mumble {...}
        default {...}
    }

you're really calling into a I<catch lambda> that looks like:

    -> $! {
        my $SUCCEEDED = 1;     # assume we will handle it

        given $! {
            when Mumble {...}
            default {...}
            $SUCCEEDED = 0;    # unassume we handled it
        }

        # the user may handle exception either by
        #      1. pattern matching in the given
        #      2. explicitly setting $!.handled = 1
        $!.handled = 1 if $SUCCEEDED;

        # conjecture: this might be enforced by the exception thrower instead
        if $!.handled {
            $!.wrap-die("Pending exceptions not handled") unless all($!.pending».handled);
        }

        $!;
    }

The exception thrower looks up the call stack for a catch lambda
that returns the exception object as handled, and then it is happy,
and unwinds the stack to that point.  If the exception is returned
as not handled. the exception thrower keeps looking for a higher
dynamic scope for a spot to unwind to.  Note that any C<die> in the
catch lambda rethrows outside the lambda as a new exception, wrapping
up the old exception in its new pending list.  In this case the lambda
never finishes executing.  Resumable exceptions may or may not leave
normally depending on the implementation.  If continuations are used,
the C<$!.resume> call will simply goto the continuation in question,
and the lambda's callframe is abandoned.  Resumable exceptions may also
be implemented by simply marking the C<$!> exception as "resumed",
in which case the original exception thrower simply returns to
the code that threw the resumable exception, rather than unwinding
before returning.

A C<CATCH> block sees the lexical scope in which it was defined, but
its caller is the dynamic location that threw the exception.  That is,
the stack is not unwound until some exception handler chooses to
unwind it by "handling" the exception in question.  So logically,
if the C<CATCH> block throws its own exception, you would expect the
C<CATCH> block to catch its own exception recursively forever.  However,
a C<CATCH> must not behave that way, so we say that a C<CATCH> block
never attempts to handle any exception thrown within its own dynamic scope.
(Otherwise any C<die> would cause an infinite loop.)

Any attempt to throw a fatal exception past an already active exception
handler must guarantee to steal the existing fatal exception (plus
any pending exceptions it contains) and add all those to the new
exception's pending list.  (This does not apply to control exceptions
described in the next section.)  When the new exception is handled,
it must also deal with the list of pending exceptions, or the C<wrap-die>
mentioned above will throw a "Pending exceptions not handled" at that point.
Even this does not discard the pending exceptions, so in the final outermost
message, all non-handled exceptions are guaranteed to be listed.

=head1 Control Exceptions

All abnormal control flow is, in the general case, handled by the
exception mechanism (which is likely to be optimized away in specific
cases.)  Here "abnormal" means any transfer of control outward that
is not just falling off the end of a block.  A C<return>,
for example, is considered a form of abnormal control flow, since it
can jump out of multiple levels of closures to the end of the scope
of the current subroutine definition.  Loop commands like C<next>
are abnormal, but looping because you hit the end of the block is not.
The implicit break (what C<succeed> does explicitly) of a C<when> block is abnormal.

A C<CATCH> block handles only "bad" exceptions, and lets control
exceptions pass unhindered.  Control exceptions may be caught with a
C<CONTROL> block.  Generally you don't need to worry about this unless
you're defining a control construct.  You may have one C<CATCH> block
and one C<CONTROL> block, since some user-defined constructs may wish to
supply an implicit C<CONTROL> block to your closure, but let you define
your own C<CATCH> block.

A C<return> always exits from the lexically surrounding sub
or method definition (that is, from a function officially declared
with the C<sub>, C<method>, or C<submethod> keywords).  Pointy blocks
and bare closures are transparent to C<return>, in that the C<return>
statement still means C<&?ROUTINE.leave> from the C<Routine> that existed
in dynamic scope when the closure was cloned.

It is illegal to return from the closure if that C<Routine> no longer owns
a call frame in the current call stack.

To return a value (to the dynamical caller) from any pointy block or bare closure, you either
just let the block return the value of its final expression, or you
can use C<leave>, which comes in both function and method forms.
The function (or listop) form always exits from the innermost block,
returning its arguments as the final value of the block exactly as
C<return> does.  The method form will leave any block in the dynamic
scope that can be named as an object and that responds to the C<.leave>
method.

Hence, the C<leave> function:

    leave(1,2,3)

is really just short for:

    &?BLOCK.leave(1,2,3)

To return from your immediate caller, you can say:

    caller.leave(1,2,3)

Further call frames up the caller stack may be located by use of the
C<callframe> function:

    callframe({ .labels.any eq 'LINE' }).leave(1,2,3);

By default the innermost call frame matching the selection criteria
will be exited.  This can be a bit cumbersome, so in the particular
case of labels, the label that is already visible in the current lexical
scope is considered a kind of pseudo object specifying a potential
dynamic context.  If instead of the above you say:

    LINE.leave(1,2,3)

it was always exit from your lexically scoped C<LINE> loop, even
if some inner dynamic scope you can't see happens to also have that
label.  (In other words, it's lexotic.)  If the C<LINE> label is visible but you aren't actually in
a dynamic scope controlled by that label, an exception is thrown.
(If the C<LINE> is not visible, it would have been caught earlier at
compile time since C<LINE> would likely be a bareword.)

In theory, any user-defined control construct can catch any control
exception it likes.  However, there have to be some culturally enforced
standards on which constructs capture which exceptions.  Much like
C<return> may only return from an "official" subroutine or method,
a loop exit like C<next> should be caught by the construct the user
expects it to be caught by.  (Always assuming the user expects the
right thing, of course...)  In particular, if the user labels a loop
with a specific label, and calls a loop control from within the lexical
scope of that loop, and if that call mentions the outer loop's label,
then that outer loop is the one that must be controlled.  In other words,
it first tries this form:

    LINE.leave(1,2,3)

If there is no such lexically scoped outer loop in the current subroutine,
then a fallback search is made outward through the dynamic scopes in
the same way Perl 5 does.  (The difference between Perl 5 and Perl 6
in this respect arises only because Perl 5 didn't have user-defined
control structures, hence the sub's lexical scope was I<always>
the innermost dynamic scope, so the preference to the lexical scope
in the current sub was implicit.  For Perl 6 we have to make this
preference for lexotic behavior explicit.)

Warnings are produced in Perl 6 by throwing a resumable control
exception to the outermost scope, which by default prints the
warning and resumes the exception by extracting a resume continuation
from the exception, which must be supplied by the C<warn()> function
(or equivalent).  Exceptions are not resumable in Perl 6 unless
the exception object does the C<Resumable> role.  (Note that fatal
exception types can do the C<Resumable> role even if thrown via
C<fail()>--when uncaught they just hit the outermost fatal handler
instead of the outermost warning handler, so some inner scope has to
explicitly treat them as warnings and resume them.)

Since warnings are processed using the standard control exception
mechanism, they may be intercepted and either suppressed or fatalized
anywhere within the dynamic scope by supplying a suitable C<CONTROL>
block.  This dynamic control is orthogonal to any lexically scoped
warning controls, which merely decide whether to call C<warn()>
in the first place.

As with calls to C<return>, the warning control exception is an
abstraction that the compiler is free to optimize away (along with the
associated continuation) when the compiler or runtime can determine
that the semantics would be preserved by merely printing out the
error and going on.  Since all exception handlers run in the dynamic
scope of the throw, that reduces to simply returning from the C<warn>
function most of the time.  See previous section for discussion of
ways to return from catch lambdas.  The control lambda is logically
separate from the catch lambda, though an implementation is allowed
to combine them if it is careful to retain separate semantics for
catch and control exceptions.

=head1 The goto statement
X<goto>

In addition to C<next>, C<last>, and C<redo>, Perl 6 also supports
C<goto>.  As with ordinary loop controls, the label is searched for
first lexically within the current subroutine, then dynamically outside
of it.  Unlike with loop controls, however, scanning a scope includes
a scan of any lexical scopes included within the current candidate
scope.  As in Perl 5, it is possible to C<goto> into a lexical scope,
but only for lexical scopes that require no special initialization
of parameters.  (Initialization of ordinary variables does not
count--presumably the presence of a label will prevent code-movement
optimizations past the label.)  So, for instance, it's always possible
to C<goto> into the next case of a C<when> or into either the "then"
or "else" branch of a conditional.  You may not go into a C<given>
or a C<for>, though, because that would bypass a formal parameter
binding (not to mention list generation in the case of C<for>).
(Note: the implicit default binding of an outer C<$_> to an inner C<$_>
can be emulated for a bare block, so that doesn't fall under the
prohibition on bypassing formal binding.)

=head1 Exceptions

As in Perl 5, many built-in functions simply return an undefined value when you
ask for a value out of range, or the function fails somehow.  Perl 6
has C<Failure> objects, any of which refers to an unthrown C<Exception>
object in C<$!> and knows whether it has been handled or not.  C<$!>
contains one main exception, the most recent, plus an internal list
of unhandled exceptions that may be accessed via the C<.pending> method.
Whenever a new exception is stored in C<$!>, it becomes the new main
exception, and if the old main exception is not marked as handled,
it is pushed onto the internal list of unhandled exceptions.

If you test a C<Failure> for C<.defined> or C<.Bool>, it causes C<$!>
to mark the main exception as I<handled>; the exception acts as a
relatively harmless undefined value thereafter.  Any other use of the
C<Failure> object to extract a normal value will throw its associated
exception immediately.  (The C<Failure> may, however, be stored in
any container whose type allows the C<Failure> role to be mixed in.)
The C<.handled> method returns C<False> on failures that have not
been handled.  It returns C<True> for handled exceptions and for
all non-C<Failure> objects. (That is, it is a C<Mu> method,
not a C<Failure> method.  Only C<Failure> objects need to store the
actual status however; other types just return C<True>.)

The C<.handled> method is C<rw>, so you may mark an exception as handled
by assigning C<True> to it.  Note however that

    $!.handled = 1;

marks only the main exception as handled.  To mark them all as handled
you must access them individually via the C<.pending> method.

A bare C<die>/C<fail> takes C<$!> as the default argument specifying
the exception to be thrown or propagated outward to the caller's C<$!>.

Because the dynamic variable C<$!> contains all exceptions collected
in the current lexical scope, saying C<die $!> will rethrow all those
exceptions as the new thrown exception, keeping the same structure of
main exception and list of unhandled exceptions.  (The C<$!> seen in a
C<CATCH> block is specially bound to this in-flight exception as the
block's initial value for C<$!>, but it may be modified by additional
failures as can any other block's C<$!> value.)  A C<fail> likewise
moves all C<$!> exceptions up into C<< CALLER::<$!> >> before
returning the current exception as normal return of a C<Failure>.

At scope exit, C<$!> discards all handled exceptions from itself,
then if there are any remaining unhandled exceptions, either as the
main exception or as any listed unhandled exception, it calls C<die>
to throw those exceptions as a single new exception, which may then
be caught with a C<CATCH> block in the current (or caller's) scope.
The new main exception is the most recent one, with any older unhandled
exceptions attached as pending.

You can cause built-ins to automatically throw exceptions on failure using

    use fatal;

The C<fail> function responds to the caller's C<use fatal> state.
It either returns an unthrown exception, or throws the exception.
Before you get too happy about this pragma, note that Perl 6 contains
various parallel processing primitives that will tend to get blown
up prematurely by thrown exceptions.  Unthrown exceptions are meant
to provide a failsoft mechanism in which failures can be treated
as data and dealt with one by one, without aborting execution
of what may be perfectly valid parallel computations.  If you
I<don't> deal with the failures as data, then the block exit
semantics will eventually trigger a thrown exception.

In any case, the overriding design principle here is that no
unhandled exception is ever dropped on the floor, but propagated
outward through subsequent C<$!> variables until it is handled.  If
that never happens, the implicit outermost exception handler will
eventually decide to abort and print all unhandled exceptions found
in the C<$!> that it is responsible for.

=head1 Phasers

A C<CATCH> block is just a trait of the closure containing it, and is
automatically called at the appropriate moment.  These auto-called
blocks are known as I<phasers>, since they generally mark the
transition from one phase of computing to another.  For instance,
a C<CHECK> block is called at the end of compiling a compilation
unit.  Other kinds of phasers can be installed as well; these are
automatically called at various times as appropriate, and some of
them respond to various control exceptions and exit values:

      BEGIN {...}*      at compile time, ASAP, only ever runs once
      CHECK {...}*      at compile time, ALAP, only ever runs once
       INIT {...}*      at run time, ASAP, only ever runs once
        END {...}       at run time, ALAP, only ever runs once

      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 (even stack unwinds from exceptions)
       KEEP {...}       at every successful block exit, part of LEAVE queue
       UNDO {...}       at every unsuccessful block exit, part of LEAVE queue

      FIRST {...}*      at loop initialization time, before any ENTER
       NEXT {...}       at loop continuation time, before any LEAVE
       LAST {...}       at loop termination time, after any LEAVE

        PRE {...}       assert precondition at every block entry, before ENTER
       POST {...}       assert postcondition at every block exit, after LEAVE

      CATCH {...}       catch exceptions, before LEAVE
    CONTROL {...}       catch control exceptions, before LEAVE

Those marked with a C<*> can also be used within an expression:

    my $compiletime = BEGIN { now };
    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 now;
    our $temphandle = START maketemp();

In fact, most of these phasers will take either a block or a statement
(known as a I<blast> in the vernacular).  The statement form can be
particularly useful to expose a lexically scoped
declaration to the surrounding lexical scope without "trapping" it inside a block.

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 = now;
    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.)

Most of the non-value-producing phasers may also be so used:

    END say my $accumulator;

Note, however, that

    END say my $accumulator = 0;

sets the variable to 0 at C<END> time, since that is when the "my"
declaration is actually executed.  Only argumentless phasers may
use the statement form.  This means that C<CATCH> and C<CONTROL>
always require a block, since they take an argument that sets C<$_>
to the current topic, so that the innards are able to behave
as a switch statement.  (If bare statements were allowed, the
temporary binding of C<$_> would leak out past the end of the C<CATCH>
or C<CONTROL>, with unpredictable and quite possibly dire consequences.
Exception handlers are supposed to reduce uncertainty, not increase it.)

Code that is generated at run time can still fire off C<CHECK>
and C<INIT> phasers, though of course those phasers can't do things that
would require travel back in time.  You need a wormhole for that.

Some of these phasers also have corresponding traits that can be set on variables.
These have the advantage of passing the variable in question into
the closure as its topic:

    my $r will start { .set_random_seed() };
    our $h will enter { .rememberit() } will undo { .forgetit() };

Apart from C<CATCH> and C<CONTROL>, which can only occur once, most
of these can occur multiple times within the block.  So they aren't
really traits, exactly--they add themselves onto a list stored in the
actual trait (except for C<START>, which executes inline).  So if you
examine the C<ENTER> trait of a block, you'll find that it's really
a list of phasers rather than a single phaser.

The semantics of C<INIT> and C<START> are not equivalent to each
other in the case of cloned closures.  An C<INIT> only runs once for
all copies of a cloned closure.  A C<START> runs separately for each
clone, so separate clones can keep separate state variables:

    our $i = 0;
    ...
    $func = { state $x will start { $x = $i++ }; dostuff($i) };

But C<state> automatically applies "start" semantics to any initializer,
so this also works:

    $func = { state $x = $i++; dostuff($i) }

Each subsequent clone gets an initial state that is one higher than the
previous, and each clone maintains its own state of C<$x>, because that's
what C<state> variables do.

Even in the absence of closure cloning, C<INIT> runs before the
mainline code, while C<START> puts off the initialization till the
last possible moment, then runs exactly once, and caches its value
for all subsequent calls (assuming it wasn't called in sink context,
in which case the C<START> is evaluated once only for its side effects).
In particular, this means that C<START> can make use of any parameters
passed in on the first call, whereas C<INIT> cannot.

All of these phaser blocks can see any previously declared lexical
variables, even if those variables have not been elaborated yet when
the closure is invoked (in which case the variables evaluate to an
undefined value.)

Note: Apocalypse 4 confused the notions of C<PRE>/C<POST> with C<ENTER>/C<LEAVE>.
These are now separate notions.  C<ENTER> and C<LEAVE> are used only for
their side effects.  C<PRE> and C<POST> must return boolean values that are
evaluated according to the usual Design by Contract (DBC) rules.  (Plus,
if you use C<ENTER>/C<LEAVE> in a class block, they only execute when the
class block is executed, but you may declare C<PRE>/C<POST> submethods
in a class block that will be evaluated
around every method in the class.)  C<KEEP> and C<UNDO> are just variants
of C<LEAVE>, and for execution order are treated as part of the queue of
C<LEAVE> phasers.

C<FIRST>, C<NEXT>, and C<LAST> are meaningful only within the
lexical scope of a loop, and may occur only at the top level of such
a loop block.  A C<NEXT> executes only if the end of the loop block is
reached normally, or an explicit C<next> is executed.  In distinction
to C<LEAVE> phasers, a C<NEXT> phaser is not executed if the loop block
is exited via any exception other than the control exception thrown
by C<next>.  In particular, a C<last> bypasses evaluation of C<NEXT>
phasers.

[Note: the name C<FIRST> used to be associated with C<state>
declarations.  Now it is associated only with loops.  See the C<START>
above for C<state> semantics.]

Except for C<CATCH> and C<CONTROL> phasers, which run while an exception
is looking for a place to handle it, all block-leaving phasers wait until
the call stack is actually unwound to run.  Unwinding happens only after
some exception handler decides to handle the exception that way.  That is,
just because an exception is thrown past a stack frame does not mean we have
officially left the block yet, since the exception might be resumable. In
any case, exception handlers are specified to run within the dynamic scope
of the failing code, whether or not the exception is resumable.  The stack
is unwound and the phasers are called only if an exception is not resumed.

So C<LEAVE> phasers for a given block are necessarily evaluated after
any C<CATCH> and C<CONTROL> phasers.  This includes
the C<LEAVE> variants, C<KEEP> and C<UNDO>.  C<POST> phasers are evaluated after
everything else, to guarantee that even C<LEAVE> phasers can't violate DBC.
Likewise C<PRE> phasers fire off before any C<ENTER> or C<FIRST> (though not
before C<BEGIN>, C<CHECK>, or C<INIT>, since those are done at compile or
process initialization time).  Much like C<BUILD> and C<DESTROY> are implicitly
called in the correct order by C<BUILDALL> and C<DESTROYALL>, the C<PRE>/C<POST>
calls are via an implicit C<CALL-VIA-DBC> method that runs
outside the actual call to the method in question.  Class-level C<PRE>/C<POST>
submethods are notionally outside of the method-level C<PRE>/C<POST> blocks.
In the normal course of things, C<CALL-VIA-DBC> follows these steps:

    1. create an empty stack for scheduling postcalls.
    2. call all the appropriate per-class C<PRE> submethods,
        pushing any corresponding C<POST> onto the postcall stack.
    3. call all the appropriate per-method C<PRE> phasers,
        pushing any corresponding C<POST> onto the postcall stack.
    4. enforce DBC logic of C<PRE> calls
    5. call the method call itself, capturing return/unwind status.
    6. pop and call every C<POST> on the postcall stack.
    7. enforce DBC logic of C<POST> calls
    8. continue with the return or unwind.

Note that in steps 2 and 3, the C<POST> block can be defined in
one of two ways.  Either the corresponding C<POST> is defined as a
separate declaration (submethod for 2, phaser for 3), in which case
C<PRE> and C<POST> share no lexical scope.  Alternately, any C<PRE>
(either submethod or phaser) may define its corresponding C<POST>
as an embedded phaser block that closes over the lexical scope of
the C<PRE>.  In either case, the code is pushed onto the postphaser
stack to be run at the appropriate moment.

If exit phasers are running as a result of a stack unwind initiated
by an exception, C<$!> contains the exception that caused it, though
it will be marked as handled by then.  In any case, the information
as to whether the block is being exited successfully or unsuccessfully
needs to be available to decide whether to run C<KEEP> or C<UNDO> blocks.
If there is no stack-unwinding
exception when these phasers are run, C<$!> will be C<Nil>.  The last
exception caught in the outer block is available as C<< OUTER::<$!> >>,
as usual. 

An exception thrown from an C<ENTER> phaser will abort the C<ENTER>
queue, but one thrown from a C<LEAVE> phaser will not.  The exceptions
thrown by failing C<PRE> and C<POST> phasers cannot be caught by a
C<CATCH> in the same block, which implies that C<POST> phaser are not
run if a C<PRE> phaser fails.  If a C<POST> fails while an exception is in
flight the C<POST> failure doesn't replace C<$!> but goes straight into
C<$!.pending>.

For phasers such as C<KEEP> and C<POST> that are run when exiting a
scope normally, the return value (if any) from that scope is available
as the current topic within the phaser.  (It is presented as a argument,
that is, either as parcel or an object that can stand alone in a list.
In other words, it's exactly what C<return> is sending to the outside
world in raw form, so that the phaser doesn't accidentally impose
context prematurely.)

The topic of the block outside a phaser is still available as C<< OUTER::<$_> >>.
Whether the return value is modifiable may be a policy of the phaser
in question.  In particular, the return value should not be modified
within a C<POST> phaser, but a C<LEAVE> phaser could be more liberal.

Class-level C<PRE> and C<POST> submethods are not in the lexical scope
of a method (and are not run in the dynamic scope of the method),
so they cannot see the method's C<$_> at all.  As methods, they
do have access to the current C<self>, of course.  And the C<POST>
submethod gets the return value as the topic, just as exit phasers do.

Any phaser defined in the lexical scope of a method is a closure that
closes over C<self> as well as normal lexicals.  (Or equivalently,
an implementation may simply turn all such phasers into submethods
whose curried invocant is the current object.)

=head1 Statement parsing

In this statement:

    given EXPR {
        when EXPR { ... }
        when EXPR { ... }
        ...
    }

parentheses aren't necessary around C<EXPR> because the whitespace
between C<EXPR> and the block forces the block to be considered a block
rather than a subscript, provided the block occurs where an infix
operator would be expected.  This works for all control structures,
not just the new ones in Perl 6.  A top-level bare block is always
considered a statement block if there's a term and a space before it:

    if $foo { ... }
    elsif $bar { ... }
    else { ... }
    while $more { ... }
    for 1..10 { ... }

You can still parenthesize the expression argument for old times'
sake, as long as there's a space between the closing paren and the
opening brace.  (Otherwise it will be parsed as a hash subscript.)

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

Note that common idioms work as expected though:

    for map { $^a + 1 }, @list { .say }

Unless you are parsing a statement that expects a block argument,
it is illegal to use a bare closure where an operator is expected
because it will be considered to be two terms in row.
(Remove the whitespace if you wish it to be a postcircumfix.)

Anywhere a term is expected, a block is taken to be a closure
definition (an anonymous subroutine).  If a closure has arguments,
it is always taken as a normal closure.  (In addition to standard
formal parameters, placeholder arguments also count, as do the
underscore variables.  Implicit use of C<$_> with C<.method> also
counts as an argument.)

However, if an argumentless closure is empty, or appears to contain
nothing but a comma-separated list starting with a pair or a hash (counting
a single pair or hash as a list of one element), the closure will be
immediately executed as a hash composer, as if called with C<.()>.

    $hash = { };
    $hash = { %stuff };
    $hash = { "a" => 1 };
    $hash = { "a" => 1, $b, $c, %stuff, @nonsense };

    $code = { %_ };                            # use of %_
    $code = { "a" => $_ };                     # use of $_
    $code = { "a" => 1, $b, $c, %stuff, @_ };  # use of @_
    $code = { ; };
    $code = { @stuff };
    $code = { "a", 1 };
    $code = { "a" => 1, $b, $c ==> print };

If you wish to be less ambiguous, the C<hash> list operator will
explicitly evaluate a list and compose a hash of the returned value,
while C<sub> or C<< -> >> introduces an anonymous subroutine:

    $code = -> { "a" => 1 };
    $code = sub { "a" => 1 };
    $hash = hash("a" => 1);
    $hash = hash("a", 1);

Note that the closure in a C<map> will never be interpreted as a hash,
since such a closure always takes arguments, and use of placeholders
(including underscore variables) is taken as evidence of arguments.

If a closure is the right argument of the dot operator, the closure
is interpreted as a hash subscript.

    $code = {$x};       # closure because term expected
    if $term{$x}        # subscript because postfix expected
    if $term {$x}       # expression followed by statement block
    if $term.{$x}       # valid subscript with dot
    if $term\  {$x}     # valid subscript with "unspace"

Similar rules apply to array subscripts:

    $array = [$x];      # array composer because term expected
    if $term[$x]        # subscript because postfix expected
    if $term [$x]       # syntax error (two terms in a row)
    if $term.[$x]       # valid subscript with dot
    if $term\  [$x]     # valid subscript with "unspace"

And to the parentheses delimiting function arguments:

    $scalar = ($x);     # grouping parens because term expected
    if $term($x)        # function call because operator expected
    if $term ($x)       # syntax error (two terms in a row)
    if $term.($x)       # valid function call with explicit dot deref
    if $term\  .($x)    # valid function call with "unspace" and dot

Outside of any kind of expression brackets, a final closing curly
on a line (not counting whitespace or comments) always reverts
to the precedence of semicolon whether or not you put a semicolon
after it.  (In the absence of an explicit semicolon, the current
statement may continue on a subsequent line, but only with valid
statement continuators such as C<else> that cannot be confused with
the beginning of a new statement.  Anything else, such as a statement
modifier (on, say, a C<loop> statement) must continue on the same line,
unless the newline be escaped using the "unspace" construct--see S02.)

Final blocks on statement-level constructs always imply semicolon
precedence afterwards regardless of the position of the closing curly.
Statement-level constructs are distinguished in the grammar by being
declared in the C<statement_control> category:

    macro statement_control:<if> ($expr, &ifblock) {...}
    macro statement_control:<while> ($expr, &whileblock) {...}
    macro statement_control:<BEGIN> (&beginblock) {...}

Statement-level constructs may start only where the parser is expecting
the start of a statement.  To embed a statement in an expression you
must use something like C<do {...}> or C<try {...}>.

    $x =  do { given $foo { when 1 {2} when 3 {4} } } + $bar;
    $x = try { given $foo { when 1 {2} when 3 {4} } } + $bar;

The existence of a C<< statement_control:<BEGIN> >> does not preclude us from
also defining a C<< prefix:<BEGIN> >> that I<can> be used within an expression:

    macro prefix:<BEGIN> (&beginblock) { beginblock().repr }

Then you can say things like:

    $recompile_by = BEGIN { time } + $expiration_time;

But C<< statement_control:<BEGIN> >> hides C<< prefix:<BEGIN> >> at the start of a statement.
You could also conceivably define a C<< prefix:<if> >>, but then you may not
get what you want when you say:

    die if $foo;

since C<< prefix:<if> >> would hide C<< statement_modifier:<if> >>.

Built-in statement-level keywords require whitespace between the
keyword and the first argument, as well as before any terminating loop.
In particular, a syntax error will be reported for C-isms such as these:

    if(...) {...}
    while(...) {...}
    for(...) {...}

=head1 Definition of Success

Hypothetical variables are somewhat transactional--they keep their
new values only on successful exit of the current block, and otherwise
are rolled back to their original values.

It is, of course, a failure to leave the block by propagating an error
exception, though returning a defined value after catching an exception
is okay.

In the absence of error exception propagation, a successful exit is one that
returns a defined value or parcel.  (A defined parcel may contain undefined values.)
So any Perl 6 function can say

    fail "message";

and not care about whether the function is being called in item or list
context.  To return an explicit scalar undef, you can always say

    return Mu;          # like "return undef" in Perl 5

Then in list context, you're returning a list of length 1, which is
defined (much like in Perl 5).  But generally you should be using
C<fail> in such a case to return an exception object.
In any case, returning an unthrown exception is considered failure
from the standpoint of C<let>.  Backtracking over a closure in a regex
is also considered failure of the closure, which is how hypothetical
variables are managed by regexes.  (And on the flip side, use of C<fail>
within a regex closure initiates backtracking of the regex.)

=head1 When is a closure not a closure

Everything is conceptually a closure in Perl 6, but the optimizer
is free to turn unreferenced closures into mere blocks of code.
It is also free to turn referenced closures into mere anonymous
subroutines if the block does not refer to any external lexicals that
should themselves be cloned.  (When we say "clone", we mean the way
the system takes a snapshot of the routine's lexical scope and binds
it to the current instance of the routine so that if you ever use
the current reference to the routine, it gets the current snapshot
of its world in terms of the lexical symbols that are visible to it.)

All remaining blocks are conceptually cloned into closures as soon
as the lexical scope containing them is entered.  (This may be done
lazily as long as consistent semantics are preserved, so a block
that is never executed and never has a reference taken can avoid
cloning altogether.  Execution or reference taking forces cloning
in this case--references are not allowed to be lazily cloned, since
no guarantee can be made that the scope needed for cloning will
remain in existence over the life of the reference.)

In particular, package subroutines are a special problem when embedded in
a changing lexical scope (when they make reference to it).  The binding
of such a definition to a name within a symbol table counts as taking
a reference, so at compile time there is an initial binding
to the symbol table entry in question.  For "global" bindings to
symbol tables visible at compile time, this binds to the compile-time
view of the lexical scopes.  (At run-time, the initial run-time view
of these scopes is copied from the compiler's view of them, so that
initializations carry over, for instance.)  At run time, when such
a subroutine is cloned, an additional binding is done
at clone time to the same symbol table entry that the original
was bound to.  (The binding is not restored on exit from the current
lexical scope; this binding records the I<last> cloning, not
the currently in-use cloning, so any use of the global reference must
take into consideration that it is functioning only as a cache of the
most recent cloning, not as a surrogate for the current lexical scope.)

Matters are more complicated if the package in question is lexically defined.
In such cases, the package must be cloned as if it were a sub on entry to the
corresponding lexical scope.  All runtime instances of a single package
declaration share the same set of compile-time declared functions, however,
the runtime instances can have different lexical environments as described in
the preceding paragraph.  If multiple conflicting definitons of a sub exist
for the same compile-time package, an error condition exists and behavior is
not specified for Perl 6.0.

Methods in classes behave functionally like package subroutines, and have the
same binding behavior if the classes are cloned.  Note that a class declaration,
even an augment, is fundamentally a compile-time operation; composition only
happens once and the results are recorded in the prototype class.  Runtime
typological manipulations are limited to reseating C<OUTER::> scopes of methods.

Lexical names do not share this problem, since the symbol goes out
of scope synchronously with its usage.  Unlike global subs, they
do not need a compile-time binding, but like global subs,
they perform a binding to the lexical symbol at clone time
(again, conceptually at the entry to the outer lexical scope, but
possibly deferred.)

    sub foo {
        # 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
        my $code = &bar;                # this would also force bar to be cloned
        return &baz;
    }

In particular, blocks of inline control flow need not be cloned until
called.  [Note: this is currently a potential problem for user-defined
constructs, since you have to take references to blocks to pass them
to whatever is managing the control flow.  Perhaps the laziness can
be deferred through C<Capture>s to binding time, so a slurpy of block
refs doesn't clone them all prematurely.  On the other hand, this
either means the C<Capture> must be smart enough to keep track of the
lexical scope it came from so that it can pass the info to the cloner,
or it means that we need some special fat not-cloned-yet references
that can carry the info lazily.  Neither approach is pretty.]

Some closures produce C<Block> objects at compile time that cannot be
cloned, because they're not attached to any runtime code that can
actually clone them.  C<BEGIN>, C<CHECK>, C<INIT>, and C<END> blocks
fall into this category.  Therefore you can't reliably refer to
run-time variables from these closures even if they appear to be in the
scope.  (The compile-time closure may, in fact, see some kind of permanent
copy of the variable for some storage classes, but the variable is
likely to be undefined when the closure is run in any case.)  It's
only safe to refer to package variables and file-scoped lexicals from
such a routine.

On the other hand, it is required that C<CATCH> and C<LEAVE> blocks be able
to see transient variables in their current lexical scope, so their
cloning status depends at least on the cloning status of the block
they're in.

=for vim:set expandtab sw=4: