=encoding utf8

=head1 TITLE

Synopsis 6: Subroutines

=head1 AUTHOR

Damian Conway <damian@conway.org> and
Allison Randal <al@shadowed.net>

=head1 VERSION

  Maintainer: Larry Wall <larry@wall.org>
  Date: 21 Mar 2003
  Last Modified: 29 Jan 2005
  Number: 6
  Version: 7


This document summarizes Apocalypse 6, which covers subroutines and the
new type system.

=head1 Subroutines and other code objects

B<Subroutines> (keyword: C<sub>) are non-inheritable routines with
parameter lists.

B<Methods> (keyword: C<method>) are inheritable routines which always
have an associated object (known as their invocant) and belong to a
particular class.

B<Submethods> (keyword: C<submethod>) are non-inheritable methods, or
subroutines masquerading as methods. They have an invocant and belong to
a particular class.

B<Multimethods> (keyword: C<multi>) are routines that transcend class
boundaries, and can have one or more invocants. 

B<Rules> (keyword: C<rule>) are methods (of a grammar) that perform
pattern matching. Their associated block has a special syntax (see
Synopsis 5).

B<Macros> (keyword: C<macro>) are routines whose calls execute as soon
as they are parsed (i.e. at compile-time). Macros may return another
source code string or a parse-tree.


=head2 Standard subroutines

The general syntax for named subroutines is any of:

     my RETTYPE sub NAME ( PARAMS ) TRAITS {...}
    our RETTYPE sub NAME ( PARAMS ) TRAITS {...}
                sub NAME ( PARAMS ) TRAITS {...}

The general syntax for anonymous subroutines is:

    sub ( PARAMS ) TRAITS {...}

"Trait" is the name for a compile-time (C<is>) property.
See L<"Traits and Properties">


=head2 Perl5ish subroutine declarations

You can still declare a sub without parameter list, as in Perl 5:

    sub foo {...}

Arguments still come in via the C<@_> array, but they are B<constant>
aliases to actual arguments:

    sub say { print qq{"@_"\n}; }   # args appear in @_

    sub cap { $_ = uc $_ for @_ }   # Error: elements of @_ are constant

If you need to modify the elements of C<@_>, declare it explicitly
with the C<is rw> trait:

    sub swap (*@_ is rw) { @_[0,1] = @_[1,0] }


=head2 Blocks

Raw blocks are also executable code structures in Perl 6.

Every block defines an object of type C<Code>, which may either be executed
immediately or passed in as a C<Code> reference argument to some other
subroutine.


=head2 "Pointy subs"

The arrow operator C<< -> >> is almost a synonym for the anonymous
C<sub> keyword, except that the parameter list of a pointy sub does
not require parentheses, it does not require a preceding comma when
included in a list, and a pointy sub may not be given traits.

    $sq = -> $val { $val**2 };  # Same as: $sq = sub ($val) { $val**2 };

    for @list -> $elem {        # Same as: for @list, sub ($elem) {
        print "$elem\n";        #              print "$elem\n";
    }                           #          }

It also behaves like a block with respect to control exceptions.  If you
C<return> from within a pointy sub, it will return from the innermost
enclosing C<sub> or C<method>, not the block itself.  It is referenced
by C<&?BLOCK>, not C<&?SUB>.

=head2 Stub declarations

To predeclare a subroutine without actually defining it, use a "stub block":

    sub foo {...}     # Yes, those three dots are part of the actual syntax

The old Perl 5 form:

    sub foo;

is a compile-time error in Perl 6 (for reasons explained in Apocalypse 6).


=head2 Globally scoped subroutines

Subroutines and variables can be declared in the global namespace, and are
thereafter visible everywhere in a program.

Global subroutines and variables are normally referred to by prefixing
their identifier with C<*>, but it may be omitted if the reference is
unambiguous:

    $*next_id = 0;
    sub *saith($text)  { print "Yea verily, $text" }

    module A {
        my $next_id = 2;    # hides any global or package $next_id
        saith($next_id);    # print the lexical $next_id;
        saith($*next_id);   # print the global $next_id;
    }

    module B {
        saith($next_id);    # Unambiguously the global $next_id
    }


=head2 Lvalue subroutines

Lvalue subroutines return a "proxy" object that can be assigned to.
It's known as a proxy because the object usually represents the
purpose or outcome of the subroutine call.

Subroutines are specified as being lvalue using the C<is rw> trait.

An lvalue subroutine may return a variable:

    my $lastval;
    sub lastval () is rw { return $lastval }
 
or the result of some nested call to an lvalue subroutine:

    sub prevval () is rw { return lastval() }

or a specially tied proxy object, with suitably programmed
C<FETCH> and C<STORE> methods:

    sub checklastval ($passwd) is rw {
        return new Proxy:
                FETCH => sub ($self) {
                            return lastval();
                         },
                STORE => sub ($self, $val) {
                            die unless check($passwd);
                            lastval() = $val;
                         };
    }


=head2 Operator overloading

Operators are just subroutines with special names.  An operator name
consists of a grammatical category name followed by a single colon
followed by an operator name specified as if it were a hash subscript
(but evaluated at compile time).  So any of these indicate the same
binary addition operator:

    infix:<+>
    infix:«+»
    infix:<<+>>
    infix:{'+'}
    infix:{"+"}

Use the C<&> sigil just as you would on ordinary subs.

Unary operators are defined as prefix or postfix:

    sub prefix:<OPNAME>  ($operand) {...}
    sub postfix:<OPNAME> ($operand) {...}

Binary operators are defined as infix:

    sub infix:<OPNAME> ($leftop, $rightop) {...}

Bracketing operators are defined as circumfix.  A two element slice containing
the leading and trailing delimiters is the name of the operator.

    sub circumfix:<LEFTDELIM RIGHTDELIM> ($contents) {...}
    sub circumfix:{'LEFTDELIM','RIGHTDELIM'} ($contents) {...}

(There is no longer any rule about splitting an even number of characters.
You must use a two element slice.)

Operator names can be any sequence of non-whitespace Unicode characters. For example:

    sub infix:<(c)> ($text, $owner) { return $text but Copyright($owner) }
    method prefix:<±> (Num $x) returns Num { return +$x | -$x }
    multi sub postfix:<!> (Int $n) { $n < 2 ?? 1 :: $n*($n-1)! }
    macro circumfix:«<!-- -->» ($text) is parsed / .*? / { "" }

    my $document = $text (c) $me;

    my $tolerance = ±7!;

    <!-- This is now a comment -->

Whitespace may never be part of the name (except as separator
within a C<< <...> >> or C<«...»> slice, as in the example above).

A null operator name does not define a null or whitespace operator, but
a default matching rule for that syntactic category, which is useful when
there is no fixed string that can be recognized, such as tokens beginning
with digits.  Such an operator I<must> supply an C<is parsed> trait.
The Perl grammar uses a default rule for the C<:1st>, C<:2nd>, C<:3rd>,
etc. rule modifiers, something like this:

    sub rxmodexternal:<> ($x) is parsed(rx:p/\d+[st|nd|rd|th]/) {...}

Such default rules are attempted in the order declared.  (They always follow
any rules with a known prefix, by the longest-token-first rule.)

=head1 Parameters and arguments

Perl 6 subroutines may be declared with parameter lists.

By default, all parameters are constant aliases to their corresponding
arguments--the parameter is just another name for the original
argument, but the argument can't be modified through it. To allow
modification, use the C<is rw> trait. To pass-by-copy, use the C<is copy>
trait.

Parameters may be required or optional. They may be passed by position,
or by name. Individual parameters may confer a scalar or list context
on their corresponding arguments.

Arguments destined for required parameters must come before those bound
to optional parameters. Arguments destined for positional parameters
must come before those bound to named parameters.


=head2 Invocant parameters

A method invocant is specified as the first parameter in the parameter
list, with a colon (rather than a comma) immediately after it:

    method get_name ($self:) {...}
    method set_name ($me: $newname) {...}

The corresponding argument (the invocant) is evaluated in scalar context
and is passed as the left operand of the method call operator:

    print $obj.get_name();
    $obj.set_name("Sam");

Multimethod and multisub invocants are specified at the start of the parameter
list, with a colon terminating the list of invocants:

    multi sub handle_event ($window, $event: $mode) {...}    # two invocants

Multi invocant arguments are passed positionally, though the first
invocant can be passed via the method call syntax if the multi happens
to be defined as a multi method within the class of the first invocant.

    # Multimethod calls...
    handle_event($w, $e, $m);
    $w.handle_event($e, $m);

Invocants may also be passed using the indirect object syntax, with a colon
after them. The colon is just a special form of the comma, and has the
same precedence:

    # Indirect method call...
    set_name $obj: "Sam";

    # Indirect multimethod call...
    handle_event $w, $e: $m;

Passing too many or too few invocants is a fatal error.

The first invocant is always the topic of the corresponding method
or multi.


=head2 Required parameters

Required parameters are specified at the start of a subroutine's parameter
list:

    sub numcmp ($x, $y) { return $x <=> $y }

The corresponding arguments are evaluated in scalar context and may be
passed positionally or by name. To pass an argument by name,
specify it as a pair: C<< I<parameter_name> => I<argument_value> >>.

    $comparison = numcmp(2,7);
    $comparison = numcmp(x=>2, y=>7);
    $comparison = numcmp(y=>7, x=>2);

Pairs may also be passed in adverbial pair notation:

    $comparison = numcmp(:x(2), :y(7));
    $comparison = numcmp(:y(7), :x(2));

Passing the wrong number of required arguments is a fatal error.

The number of required parameters a subroutine has can be determined by
calling its C<.arity> method:

    $args_required = &foo.arity;


=head2 Optional parameters

Optional positional parameters are specified after all the required
parameters and each is marked with a C<?> before the parameter:

    sub my_substr ($str, ?$from, ?$len) {...}

The C<=> sign introduces a default value:

    sub my_substr ($str, ?$from = 0, ?$len = Inf) {...}

Default values can be calculated at run-time. They may even use the values of
preceding parameters:

    sub xml_tag ($tag, ?$endtag = matching_tag($tag) ) {...}

Arguments that correspond to optional parameters are evaluated in
scalar context. They can be omitted, passed positionally, or passed by
name:

    my_substr("foobar");            # $from is 0, $len is infinite
    my_substr("foobar",1);          # $from is 1, $len is infinite
    my_substr("foobar",1,3);        # $from is 1, $len is 3
    my_substr("foobar",len=>3);     # $from is 0, $len is 3

Missing optional arguments default to their default value, or to C<undef>
if they have no default.


=head2 Named parameters

Named parameters follow any required or optional parameters in the
signature. They are marked by a C<+> before the parameter.

    sub formalize($text, +$case, +$justify) {...}

Arguments that correspond to named parameters are evaluated in scalar
context. They can only be passed by name, so it doesn't matter what
order you pass them in, so long as they follow any positional arguments:  

    $formal = formalize($title, case=>'upper');
    $formal = formalize($title, justify=>'left');
    $formal = formalize($title, :justify<right>, :case<title>);

Named parameters are optional unless marked with the C<is required>
trait.  (Alternately, we might allow a C<++> prefix for required
name parameters.)  Default values for optional named parameters are
defined in the same way as for positional parameters. Named parameters
default to C<undef> if they have no default.

Again, note the use of adverbial pairs in the argument list.  The following
table shows the correspondence:

    Fat arrow		Adverbial pair
    =========		==============
    a => 1		:a
    a => 0		:a(0)
    a => $x		:a($x)
    a => 'foo'		:a<foo>
    a => <foo bar>	:a<foo bar>
    a => «$foo @bar»	:a«$foo @bar»
    a => {...}		:a{...}
    a => [...]		:a[...]
    "" => {...}		:{...}

=head2 List parameters

List parameters capture a variable length list of data. They're used
in subroutines like C<print>, where the number of arguments needs to be
flexible. They're also called "variadic parameters", because they take a
I<variable> number of arguments.  But generally we call them "slurpy"
parameters because they slurp up arguments.

Slurpy parameters follow any required or optional parameters. They are
marked by a C<*> before the parameter:

    sub duplicate($n, *%flag, *@data) {...}

Named arguments are bound to the slurpy hash (C<*%flag>
in the above example). Such arguments are evaluated in scalar context.
Any remaining variadic arguments at the end of the argument list
are bound to the slurpy array (C<*@data> above) and are evaluated
in list context.

For example:

    duplicate(3, reverse => 1, collate => 0, 2, 3, 5, 7, 11, 14);
    duplicate(3, :reverse, :collate(0), 2, 3, 5, 7, 11, 14);  # same

    # The @data parameter receives [2, 3, 5, 7, 11, 14]
    # The %flag parameter receives { reverse => 1, collate => 0 }

Slurpy scalar parameters capture what would otherwise be the first
elements of the variadic array:

    sub head(*$head, *@tail)         { return $head }
    sub neck(*$head, *$neck, *@tail) { return $neck }
    sub tail(*$head, *@tail)         { return @tail }

    head(1, 2, 3, 4, 5);        # $head parameter receives 1
                                # @tail parameter receives [2, 3, 4, 5]

    neck(1, 2, 3, 4, 5);        # $head parameter receives 1
                                # $neck parameter receives 2
                                # @tail parameter receives [3, 4, 5]

Slurpy scalars still impose list context on their arguments.

Slurpy parameters are treated lazily -- the list is only flattened
into an array when individual elements are actually accessed:

        @fromtwo = tail(1..Inf);        # @fromtwo contains a lazy [2..Inf]

=head2 Slurpy block

It's also possible to declare a slurpy block: C<*&block>.  It slurps
up any nameless block, specified by C<:{...}>.  This will turn out
useful when we discuss adverbs below.

=head2 Flattening argument lists

The unary prefix operator C<*> flattens its operand (which allows the
elements of an array or iterator to be used as an argument list). The
C<*> operator also causes its operand -- and any subsequent arguments
in the argument list -- to be evaluated in list context.

    sub foo($x, $y, $z) {...}    # expects three scalars
    @onetothree = 1..3;          # array stores three scalars

    foo(1,2,3);                  # okay:  three args found
    foo(@onetothree);            # error: only one arg
    foo(*@onetothree);           # okay:  @onetothree flattened to three args

The C<*> operator flattens lazily -- the array is only flattened if
flattening is actually required within the subroutine. To flatten before
the list is even passed into the subroutine, use the unary prefix C<**>
operator:

    foo(**@onetothree);          # array flattened before &foo called


=head2 Pipe operators

The variadic array of a subroutine call can be passed in separately
from the normal argument list, by using either of the "pipe" operators:
C<< <== >> or C<< ==> >>.

Each operator expects to find a call to a variadic subroutine on its
"sharp" end, and a list of values on its "blunt" end:

    grep { $_ % 2 } <== @data;

    @data ==> grep { $_ % 2 };

It binds the (potentially lazy) list from the blunt end to the slurpy
parameter(s) of the subroutine on the sharp end. So both of the calls
above are equivalent to:

    grep { $_ % 2 } @data;

Leftward pipes are a convenient way of explicitly indicating the typical
right-to-left flow of data through a chain of operations:

    @oddsquares = map { $_**2 } sort grep { $_ % 2 } @nums;

    # more clearly written as...

    @oddsquares = map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums;

Rightward pipes are a convenient way of reversing the normal data flow in a
chain of operations, to make it read left-to-right:

    @oddsquares =
            (@nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 });

Note that the parens are necessary there due to precedence.

If the operand on the sharp end of a pipe is not a call to a variadic
operation, it must be a variable, in which case the list value is
assigned to the variable. This special case allows for "pure" processing
chains:

    @oddsquares <== map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums;

    @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 } ==> @oddsquares;


=head2 Closure parameters

Parameters declared with the C<&> sigil take blocks, closures, or
subroutines as their arguments. Closure parameters can be required,
optional, named, or slurpy.

    sub limited_grep (Int $count, &block, *@list) {...}

    # and later...

    @first_three = limited_grep 3 {$_<10} @data;

Within the subroutine, the closure parameter can be used like any other
lexically scoped subroutine:

    sub limited_grep (Int $count, &block, *@list) {
        ...
        if block($nextelem) {...}
        ...
    }

The closure parameter can have its own signature in angles (from which the
parameter names should be omitted):

    sub limited_Dog_grep ($count, &block<Dog>, Dog *@list) {...}

and even a return type:

    sub limited_Dog_grep ($count, &block<Dog> returns Bool, Dog *@list) {...}

When an argument is passed to a closure parameter that has this kind of
signature, the argument must be a C<Code> object with a compatible
parameter list and return type.


=head2 Unpacking array parameters

Instead of specifying an array parameter as an array:

    sub quicksort (@data, ?$reverse, ?$inplace) {
        my $pivot := shift @data;
        ...
    }

it may be broken up into components in the signature, by
specifying the parameter as if it were an anonymous array of
parameters:

    sub quicksort ([$pivot, *@data], ?$reverse, ?$inplace) {
        ...
    }

This subroutine still expects an array as its first argument, just like
the first version.

=head2 Unpacking hash parameters

Likewise, a hash argument can be mapped to a hash of parameters, specified
as named parameters within curlies.  Instead of saying:

    sub register (%guest_data, $room_num) {
        my $name := delete %guest_data<name>;
        my $addr := delete %guest_data<addr>;
        ...
    }
                                                                                
you can get the same effect with:
                                                                                
    sub register ({+$name, +$addr, *%guest_data}, $room_num) {
        ...
    }

=head2 Attributive parameters

If a method's parameter is declared with a C<.> after the sigil (like an
attribute):

    method initialize($.name, $.age) {}

then the argument is assigned directly to the object's attribute of the
same name. This avoids the frequent need to write code like:

    method initialize($name, $age) {
        $.name = $name;
        $.age  = $age;
    }


=head2 Placeholder variables

Even though every bare block is a closure, bare blocks can't have
explicit parameter lists. Instead, they use "placeholder" variables,
marked by a caret (C<^>) after their sigils.

Using placeholders in a block defines an implicit parameter list. The
signature is the list of distinct placeholder names, sorted in Unicode order.
So:

    { $^y < $^z && $^x != 2 }

is a shorthand for:

    sub ($x,$y,$z) { $y < $z && $x != 2 }


=head1 Types

These are the standard type names in Perl 6 (at least this week):

    bit         single native bit
    int         native integer
    str         native string (sequence of integers, no Unicode)
    num         native floating point
    ref         native pointer 
    bool        native boolean
    Bit         Perl single bit (allows traits, aliasing, etc.)
    Int         Perl integer (allows traits, aliasing, etc.)
    Str         Perl string (Unicode semantics)
    Num         Perl number
    Ref         Perl reference
    Bool        Perl boolean
    Array       Perl array
    Hash        Perl hash
    IO          Perl filehandle
    Code        Base class for all executable objects
    Routine     Base class for all nameable executable objects
    Sub         Perl subroutine
    Method      Perl method
    Submethod   Perl subroutine acting like a method
    Macro       Perl compile-time subroutine
    Rule        Perl pattern
    Block       Base class for all unnameable executable objects
    Bare        Basic Perl block
    Parametric  Basic Perl block with placeholder parameters
    Package     Perl 5 compatible namespace
    Module      Perl 6 standard namespace
    Class       Perl 6 standard class namespace
    Object      Perl 6 object
    Grammar     Perl 6 pattern matching namespace
    List        Perl list
    Lazy        Lazily evaluated Perl list
    Eager       Non-lazily evaluated Perl list


=head2 Value types

Explicit types are optional. Perl variables have two associated types:
their "value type" and their "implementation type".  (More generally, any
container has an implementation type, including subroutines and modules.)

The value type specifies what kinds of values may be stored in the
variable. A value type is given as a prefix or with the C<returns> or
C<of> keywords:

    my Dog $spot;
    my $spot returns Dog;
    my $spot of Dog;

    our Animal sub get_pet() {...}
    sub get_pet() returns Animal {...}
    sub get_pet() of Animal {...}

A value type on an array or hash specifies the type stored by each element:

    my Dog @pound;  # each element of the array stores a Dog

    my Rat %ship;   # the value of each entry stores a Rat


=head2 Implementation types

The implementation type specifies how the variable itself is implemented. It is
given as a trait of the variable:

    my $spot is Scalar;             # this is the default
    my $spot is PersistentScalar;
    my $spot is DataBase;

Defining an implementation type is the Perl 6 equivalent to tying
a variable in Perl 5.  But Perl 6 variables are tied directly at
declaration time, and for performance reasons may not be tied with a
run-time C<tie> statement unless the variable is explicitly declared
with an implementation type that does the C<Tieable> role.

=head2 Hierarchical types

A non-scalar type may be qualified, in order to specify what type of
value each of its elements stores:

    my Egg $cup;                       # the value is an Egg
    my Egg @carton;                    # each elem is an Egg
    my Array of Egg @box;              # each elem is an array of Eggs
    my Array of Array of Egg @crate;   # each elem is an array of arrays of Eggs
    my Hash of Array of Recipe %book;  # each value is a hash of arrays of Recipes

Each successive C<of> makes the type on its right a parameter of the
type on its left. Parametric types are named using square brackets, so:

    my Hash of Array of Recipe %book;

actually means:

    my Hash[returns=>Array[returns=>Recipe]] %book; 

Because the actual variable can be hard to find when complex types are
specified, there is a postfix form as well:

    my Hash of Array of Recipe %book;           # HoHoAoRecipe
    my %book of Hash of Array of Recipe;        # same thing
    my %book returns Hash of Array of Recipe;   # same thing

The C<returns> form is more commonly seen in subroutines:

    my Hash of Array of Recipe sub get_book () {...}
    my sub get_book () of Hash of Array of Recipe {...}
    my sub get_book returns Hash of Array of Recipe {...}


=head2 Junctive types

Anywhere you can use a single type you can use a junction of types:

    my Int|Str $error = $val;              # can assign if $val~~Int or $val~~Str

    if $shimmer.isa(Wax & Topping) {...}   # $shimmer must inherit from both


=head2 Parameter types

Parameters may be given types, just like any other variable:

    sub max (int @array is rw) {...}
    sub max (@array of int is rw) {...}


=head2 Return types

On a scoped subroutine, a return type can be specified before or
after the name:

    our Egg sub lay {...}
    our sub lay returns Egg {...}

    my Rabbit sub hat {...}
    my sub hat returns Rabbit {...}

If a subroutine is not explicitly scoped, it belongs to the current
namespace (module, class, grammar, or package). Any return type must go
after the name:

    sub lay returns Egg {...}

On an anonymous subroutine, any return type can only go after the C<sub>
keyword:

    $lay = sub returns Egg {...};

unless you use the "anonymous declarator" (C<a>/C<an>):

    $lay = an Egg sub {...};
    $hat = a Rabbit sub {...};


=head1 Properties and traits

Compile-time properties are called "traits". The 
C<is I<NAME> (I<DATA>)> syntax defines traits on containers and
subroutines, as part of their declaration:

    my $pi is constant = 3;

    my $key is Persistent(:file<.key>);

    sub fib is cached {...}

The C<will I<NAME> I<BLOCK>> syntax is a synonym for C<is I<NAME> (I<BLOCK>)>:

    my $fh will undo { close $fh };    # Same as: my $fh is undo({ close $fh });

The C<but I<NAME> (I<DATA>)> syntax specifies run-time properties on values:

    my $pi = 3 but Approximate("legislated");

    sub system {
        ...
        return $error but false if $error;
        return 0 but true;
    }

Properties are predeclared as roles and implemented as mixins--see A12.

=head2 Subroutine traits

These traits may be declared on the subroutine as a whole (individual
parameters take other traits).

=over 

=item C<is signature>

The signature of a subroutine. Normally declared implicitly, by providing a
parameter list and/or return type.

=item C<returns>/C<is returns>

The type returned by a subroutine.

=item C<will do>

The block of code executed when the subroutine is called. Normally declared
implicitly, by providing a block after the subroutine's signature definition.

=item C<is rw>

Marks a subroutine as returning an lvalue.

=item C<is parsed>

Specifies the rule by which a macro call is parsed.

=item C<is cached>

Marks a subroutine as being memoized.

=item C<is inline>

I<Suggests> to the compiler that the subroutine is a candidate for
optimization via inlining.

=item C<is tighter>/C<is looser>/C<is equiv>

Specifies the precedence of an operator relative to an existing
operator.  C<equiv> also specifies the default associativity to
be the same as the operator to which the new operator is equivalent.
C<tighter> and C<looser> operators default to left associative.

=item C<is assoc>

Specifies the associativity of an operator explicitly.  Valid values are:

    Tag		Examples	Meaning of $a op $b op $c
    ===		========	=========================
    left	+ - * / x	($a op $b) op $c
    right	** =		$a op ($b op $c)
    non		cmp <=> ..	ILLEGAL
    chain	== eq ~~	($a op $b) and ($b op $c)
    list	| & ^ ¥		listop($a, $b, $c)

=item C<PRE>/C<POST>

Mark blocks that are to be unconditionally executed before/after
the subroutine's C<do> block. These blocks must return a true value,
otherwise an exception is thrown.

=item C<FIRST>/C<LAST>/C<NEXT>/C<KEEP>/C<UNDO>/etc.

Mark blocks that are to be conditionally executed before or after
the subroutine's C<do> block. These blocks are generally used only for
their side effects, since most return values will be ignored.

=back


=head2 Parameter traits

The following traits can be applied to many types of parameters.

=over 

=item C<is constant>

Specifies that the parameter cannot be modified (e.g. assigned to,
incremented). It is the default for parameters.

=item C<is rw>

Specifies that the parameter can be modified (assigned to, incremented,
etc). Requires that the corresponding argument is an lvalue or can be
converted to one.

When applied to a variadic parameter, the C<rw> trait applies to each
element of the list:

    sub incr (*@vars is rw) { $_++ for @vars }

(The variadic array as a whole is always modifiable, but such
modifications have no effect on the original argument list.)

=item C<is ref>

Specifies that the parameter is passed by reference. Unlike C<is rw>, the
corresponding argument must already be a suitable lvalue. No attempt at
coercion or autovivification is made, so unsuitable values throw an
exception when you try to modify them.

=item C<is copy>

Specifies that the parameter receives a distinct, read-writeable copy of the
original argument. This is commonly known as "pass-by-value".

    sub reprint ($text, $count is copy) {
        print $text while $count-- > 0;
    }

=item C<is context(I<TYPE>)>

Specifies the context that a parameter applies to its argument. Typically used
to cause a final list parameter to apply a series of scalar contexts:

    # &format may have as many arguments as it likes,
    # each of which is evaluated in scalar context

    sub format(*@data is context(Scalar)) {...}

Note that the compiler may not be able to propagate such a scalar
context to a function call used as a parameter to a method or multisub
whose signature is not visible until dispatch time.  Such function
call parameters are called in list context by default, and must be
coerced to scalar context explicitly if that is desired.

=back


=head1 Advanced subroutine features


=head2 The C<caller> function

The C<caller> function returns an object that describes a particular 
"higher" dynamic scope, from which the current scope was called.

    print "In ",           caller.sub,
          " called from ", caller.file,
          " line ",        caller.line,
          "\n";

C<caller> may be given arguments telling it what kind of higher scope to
look for, and how many such scopes to skip over when looking:

    $caller = caller;                      # immediate caller
    $caller = caller Method;               # nearest caller that is method
    $caller = caller Bare;                 # nearest caller that is bare block
    $caller = caller Sub, :skip(2);        # caller three levels up
    $caller = caller Block, :label<Foo>;   # caller whose label is 'Foo'

=head2 The C<want> function

The C<want> function returns an object that contains information about
the context in which the current block, closure, or subroutine was
called.

The returned context object is typically tested with a smart match (C<~~>)
or a C<when>:

   given want {
        when Scalar {...}           # called in scalar context
        when List   {...}           # called in list context
        when Lvalue {...}           # expected to return an lvalue
        when 2      {...}           # expected to return two values
        ...
    }

or has the corresponding methods called on it:

       if (want.Scalar)    {...}    # called in scalar context
    elsif (want.List)      {...}    # called in list context
    elsif (want.rw)        {...}    # expected to return an lvalue
    elsif (want.count > 2) {...}    # expected to return more than two values


=head2 The C<leave> function

A C<return> statement causes the innermost surrounding subroutine, method,
rule, macro, or multimethod to return.  Only declarations with an explicit
keyword such as "sub" may be returned from.

To return from other types of code structures, the C<leave> function is used:

    leave;                      # return from innermost block of any kind
    leave Method;               # return from innermost calling method
    leave &?SUB <== 1,2,3;      # Return from current sub. Same as: return 1,2,3
    leave &foo <== 1,2,3;       # Return from innermost surrounding call to &foo
    leave Loop, :label<COUNT>;  # Same as: last COUNT;


=head2 Temporization

The C<temp> function temporarily replaces the value of an existing
variable, subroutine, or other object in a given scope:

    {
       temp $*foo = 'foo';      # Temporarily replace global $foo
       temp &bar = sub {...};   # Temporarily replace sub &bar
       ...
    } # Old values of $*foo and &bar reinstated at this point

C<temp> invokes its argument's C<.TEMP> method. The method is expected
to return a reference to a subroutine that can later restore the current
value of the object. At the end of the lexical scope in which the
C<temp> was applied, the subroutine returned by the C<.TEMP> method is
executed.

The default C<.TEMP> method for variables simply creates
a closure that assigns the variable's pre-C<temp> value 
back to the variable.

New kinds of temporization can be created by writing storage classes with
their own C<.TEMP> methods:

    class LoudArray is Array {
        method TEMP {
            print "Replacing $_.id() at $(caller.location)\n";
            my $restorer = .SUPER::TEMP();
            return { 
                print "Restoring $_.id() at $(caller.location)\n";
                $restorer();
            };
        }
    }

You can also modify the behaviour of temporized code structures, by
giving them a C<TEMP> block. As with C<.TEMP> methods, this block is
expected to return a closure, which will be executed at the end of
the temporizing scope to restore the subroutine to its pre-C<temp> state:

    my $next = 0;
    sub next {
        my $curr = $next++;
        TEMP {{ $next = $curr }}  # TEMP block returns the closure { $next = $curr }
        return $curr;
    }

    # and later...
									    
    say next();     # prints 0; $next == 1
    say next();     # prints 1; $next == 2
    say next();     # prints 2; $next == 3
    if ($hiccough) {
	say temp next();  # prints 3; closes $curr at 3; $next == 4
	say next();    	  # prints 4; $next == 5
	say next();       # prints 5; $next == 6
    }                     # $next = 3
    say next();     # prints 3; $next == 4
    say next();     # prints 4; $next == 5

Hypothetical variables use the same mechanism, except that the restoring
closure is called only on failure.

=head2 Wrapping

Every subroutine has a C<.wrap> method. This method expects a single
argument consisting of a block, closure, or subroutine. That argument
must contain a call to the special C<call> function:

    sub thermo ($t) {...}   # set temperature in Celsius, returns old temp

    # Add a wrapper to convert from Fahrenheit...

    $id = &thermo.wrap( { call( ($^t-32)/1.8 ) } );

The call to C<.wrap> replaces the original subroutine with the closure
argument, and arranges that the closure's call to C<call> invokes the
original (unwrapped) version of the subroutine. In other words, the call to
C<.wrap> has more or less the same effect as:

    &old_thermo := &thermo;
    &thermo := sub ($t) { old_thermo( ($t-32)/1.8 ) }

The call to C<.wrap> returns a unique identifier that can later be passed to
the C<.unwrap> method, to undo the wrapping:

    &thermo.unwrap($id);

A wrapping can also be restricted to a particular dynamic scope with
temporization:

    # Add a wrapper to convert from Kelvin
    # wrapper self-unwraps at end of current scope

    temp &thermo.wrap( { call($^t + 273.16) } );

Within a wrapper, the C<&_> variable is implicitly declared as a
lexical by the wrapper, and refers to the function that C<call>
implicitly calls.  Thus, for non-wrappers, you may also declare
your own C<&_> lexical variable (or parameter) and then use C<call>
to call whatever is referenced by C<&_>.  (In the absence of such
a declaration, C<call> magically steals the dispatch list from the
current dispatcher, and redispatches to the next-most-likely method
or multi-sub.)

=head2 The C<&?SUB> routine

C<&?SUB> is always an alias for the current subroutine, so you can
specify tail-recursion on an anonymous sub:

    my $anonfactorial = sub (Int $n) {
                            return 1 if $n<2;
                            return $n * &?SUB($n-1);
                        };

C<$?SUBNAME> contains the name of the current subroutine, if any.

=head2 The C<&?BLOCK> routine

C<&?BLOCK> is always an alias for the current block, so you can
specify tail-recursion on an anonymous block:

    my $anonfactorial = -> Int $n { $n < 2
    					?? 1
					:: $n * &?BLOCK($n-1)
				  };

C<$?BLOCKLABEL> contains the label of the current block, if any.

=head2 Currying

Every subroutine has an C<.assuming> method. This method takes a series
of named arguments, whose names must match parameters of the subroutine
itself:

    &textfrom := &substr.assuming(str=>$text, len=>Inf);

or equivalently:

    &textfrom := &substr.assuming(:str($text) :len(Inf));

or even:

    &textfrom := &substr.assuming:str($text):len(Inf);

It returns a reference to a subroutine that implements the same behaviour
as the original subroutine, but has the values passed to C<.assuming>
already bound to the corresponding parameters:

    $all  = $textfrom(0);   # same as: $all  = substr($text,0,Inf);
    $some = $textfrom(50);  # same as: $some = substr($text,50,Inf);
    $last = $textfrom(-1);  # same as: $last = substr($text,-1,Inf);

The result of a C<use> statement is a (compile-time) object that also has
an C<.assuming> method, allowing the user to bind parameters in all the
module's subroutines/methods/etc. simultaneously:

    (use IO::Logging).assuming(logfile => ".log");

To curry a particular multimethod it may be necessary to specify the type
of one or more of its invocants:

    &woof ::= &bark<Dog>.assuming :pitch<low>;
    &pine ::= &bark<Tree>.assuming :pitch<yes>;


=head1 Other matters


=head2 Anonymous hashes vs blocks

C<{...}> is always a block.  However, if it consists of a single list, the
first element of which is either a hash or a pair, it is executed immediately
to compose a hash reference.

The standard C<pair> list operator is equivalent to:

    sub pair (*@LIST) {
        my @pairs;
        for @LIST -> $key, $val {
            push @pairs, $key => $val;
        }
        return @pairs;
    }

or more succinctly (and lazily):

    sub pair (*@LIST) {
        gather {
	    for @LIST -> $key, $val {
		take $key => $val;
	    }
	}
    }

The standard C<hash> list operator is equivalent to:

    sub hash (*@LIST) {
	return { pair @LIST };
    }

So you may use C<sub> or C<hash> or C<pair> to disambiguate:

    $ref =  sub { 1, 2, 3, 4, 5, 6 };   # Anonymous sub returning list
    $ref =      { 1, 2, 3, 4, 5, 6 };   # Anonymous sub returning list
    $ref =      { 1=>2, 3=>4, 5=>6 };   # Anonymous hash
    $ref =      { 1=>2, 3, 4, 5, 6 };   # Anonymous hash
    $ref =  hash( 1, 2, 3, 4, 5, 6 );   # Anonymous hash
    $ref =  hash  1, 2, 3, 4, 5, 6  ;   # Anonymous hash
    $ref = { pair 1, 2, 3, 4, 5, 6 };   # Anonymous hash


=head2 Pairs as lvalues

Pairs can be used as lvalues. The value of the pair is the recipient of
the assignment:

    (key => $var) = "value";

When binding pairs, names can be used to "match up" lvalues and rvalues:

    (who => $name, why => $reason) := (why => $because, who => "me");


=head2 Out-of-scope names

C<$CALLER::varname> specifies the C<$varname> visible in the dynamic
scope from which the current block/closure/subroutine was called.

C<$MY::varname> specifies the lexical C<$varname> declared in the current
lexical scope.  C<%MY::> is the hash representing that scope.

C<$OUTER::varname> specifies the C<$varname> declared in the lexical
scope surrounding the current lexical scope (i.e. the scope in which
the current block was defined).
