Front page | perl.perl6.language |
Postings from November 2008
r24064 - docs/Perl6/Spec
From:
pugs-commits
Date:
November 26, 2008 15:07
Subject:
r24064 - docs/Perl6/Spec
Message ID:
20081126223346.23683.qmail@feather.perl6.nl
Author: lwall
Date: 2008-11-26 23:33:46 +0100 (Wed, 26 Nov 2008)
New Revision: 24064
Added:
docs/Perl6/Spec/S02.pod
docs/Perl6/Spec/S06.pod
Log:
[Spec] bleah, svn getting confused, and so am I
Added: docs/Perl6/Spec/S02.pod
===================================================================
--- docs/Perl6/Spec/S02.pod (rev 0)
+++ docs/Perl6/Spec/S02.pod 2008-11-26 22:33:46 UTC (rev 24064)
@@ -0,0 +1,3559 @@
+=encoding utf8
+
+=head1 TITLE
+
+Synopsis 2: Bits and Pieces
+
+=head1 AUTHOR
+
+Larry Wall <larry@wall.org>
+
+=head1 VERSION
+
+ Maintainer: Larry Wall <larry@wall.org>
+ Date: 10 Aug 2004
+ Last Modified: 19 Nov 2008
+ Number: 2
+ Version: 143
+
+This document summarizes Apocalypse 2, which covers small-scale
+lexical items and typological issues. (These Synopses also contain
+updates to reflect the evolving design of Perl 6 over time, unlike the
+Apocalypses, which are frozen in time as "historical documents".
+These updates are not marked--if a Synopsis disagrees with its
+Apocalypse, assume the Synopsis is correct.)
+
+=head1 One-pass parsing
+
+To the extent allowed by sublanguages' parsers, Perl is parsed using a
+one-pass, predictive parser. That is, lookahead of more than one
+"longest token" is discouraged. The currently known exceptions to
+this are where the parser must:
+
+=over 4
+
+=item *
+
+Locate the end of interpolated expressions that begin with a sigil
+and might or might not end with brackets.
+
+=item *
+
+Recognize that a reduce operator is not really beginning a C<[...]> composer.
+
+=back
+
+=head1 Lexical Conventions
+
+=over 4
+
+=item *
+
+In the abstract, Perl is written in Unicode, and has consistent Unicode
+semantics regardless of the underlying text representations.
+
+=item *
+
+Perl can count Unicode line and paragraph separators as line markers,
+but that behavior had better be configurable so that Perl's idea of
+line numbers matches what your editor thinks about Unicode lines.
+
+=item *
+
+Unicode horizontal whitespace is counted as whitespace, but it's better
+not to use thin spaces where they will make adjoining tokens look like
+a single token. On the other hand, Perl doesn't use indentation as syntax,
+so you are free to use any whitespace anywhere that whitespace makes sense.
+Comments always count as whitespace.
+
+=item *
+
+For some syntactic purposes, Perl distinguishes bracketing characters
+from non-bracketing. Bracketing characters are defined as any Unicode
+characters with either bidirectional mirrorings or Ps/Pe properties.
+
+In practice, though, you're safest using matching characters with
+Ps/Pe properties, though ASCII angle brackets are a notable exception,
+since they're bidirectional but not in the Ps/Pe set.
+
+Characters with no corresponding closing character do not qualify
+as opening brackets. This includes the second section of the Unicode
+BidiMirroring data table, as well as C<U+201A> and C<U+201E>.
+
+If a character is already used in Ps/Pe mappings, then any entry
+in BidiMirroring is ignored (both forward and backward mappings).
+For any given Ps character, the next Pe codepoint (in numerical
+order) is assumed to be its matching character even if that is not
+what you might guess using left-right symmetry. Therefore C<U+298D>
+maps to C<U+298E>, not C<U+2990>, and C<U+298F> maps to C<U+2990>,
+not C<U+298E>. Neither C<U+298E> nor C<U+2990> are valid bracket
+openers, despite having reverse mappings in the BidiMirroring table.
+
+The C<U+301D> codepoint has two closing alternatives, C<U+301E> and C<U+301F>;
+Perl 6 only recognizes the one with lower code point number, C<U+301E>,
+as the closing brace. This policy also applies to new one-to-many
+mappings introduced in the future.
+
+=back
+
+=head1 Whitespace and Comments
+
+=over 4
+
+=item *
+
+POD sections may be used reliably as multiline comments in Perl 6.
+Unlike in Perl 5, POD syntax now requires that C<=begin comment>
+and C<=end comment> delimit a POD block correctly without the need
+for C<=cut>. (In fact, C<=cut> is now gone.) The format name does
+not have to be C<comment> -- any unrecognized format name will do
+to make it a comment. (However, bare C<=begin> and C<=end> probably
+aren't good enough, because all comments in them will show up in the
+formatted output.)
+
+We have single paragraph comments with C<=for comment> as well.
+That lets C<=for> keep its meaning as the equivalent of a C<=begin>
+and C<=end> combined. As with C<=begin> and C<=end>, a comment started
+in code reverts to code afterwards.
+
+Since there is a newline before the first C<=>, the POD form of comment
+counts as whitespace equivalent to a newline.
+
+=item *
+
+Except within a string literal, a C<#> character always introduces a comment in
+Perl 6. There are two forms of comment based on C<#>. Embedded
+comments require the C<#> to be followed by one
+or more opening bracketing characters.
+
+All other uses of C<#> are interpreted as single-line comments that
+work just as in Perl 5, starting with a C<#> character and
+ending at the subsequent newline. They count as whitespace equivalent
+to newline for purposes of separation. Unlike in Perl 5, C<#>
+may not be used as the delimiter in quoting constructs.
+
+=item *
+
+Embedded comments are supported as a variant on quoting syntax, introduced
+by C<#> plus any user-selected bracket characters (as defined in
+L</Lexical Conventions> above):
+
+ say #( embedded comment ) "hello, world!";
+
+ $object\#{ embedded comments }.say;
+
+ $object\ #「
+ embedded comments
+ 」.say;
+
+Brackets may be nested, following the same policy as ordinary quote brackets.
+
+There must be no space between the C<#> and the opening bracket character.
+(There may be the I<visual appearance> of space for some double-wide
+characters, however, such as the corner quotes above.)
+
+An embedded comment is not allowed as the first thing on the line.
+
+ #sub foo # line-end comment
+ #{ # ILLEGAL, syntax error
+ # ...
+ #}
+
+If you wish to have a comment there, you must disambiguate it to
+either an embedded comment or a line-end comment. You can put a
+space in front of it to make it an embedded comment:
+
+ #sub foo # line end comment
+ #{ # okay, comment
+ ... # extends
+ } # to here
+
+Or you can put something other than a single C<#>
+to make it a line-end comment. Therefore, if you are commenting out a
+block of code using the line-comment form, we recommend that you use
+C<##>, or C<#> followed by some whitespace, preferably a tab to keep
+any tab formatting consistent:
+
+ ##sub foo
+ ##{ # okay
+ ## ...
+ ##}
+
+ # sub foo
+ # { # okay
+ # ...
+ # }
+
+
+ # sub foo
+ # { # okay
+ # ...
+ # }
+
+However, it's often better to use pod comments because they are
+implicitly line-oriented. And if you have an intelligent syntax
+highlighter that will mark pod comments in a different color, there's
+less visual need for a C<#> on every line.
+
+=item *
+
+For all quoting constructs that use user-selected brackets, you can open
+with multiple identical bracket characters, which must be closed by the
+same number of closing brackets. Counting of nested brackets applies only
+to pairs of brackets of the same length as the opening brackets:
+
+ say #{{
+ This comment contains unmatched } and { { { { (ignored)
+ Plus a nested {{ ... }} pair (counted)
+ }} q<< <<woot>> >> # says " <<woot>> "
+
+Note however that bare circumfix or postcircumfix C<<< <<...>> >>> is
+not a user-selected bracket, but the ASCII variant of the C<< «...» >>
+interpolating word list. Only C<#> and the C<q>-style quoters (including
+C<m>, C<s>, C<tr>, and C<rx>) enable subsequent user-selected brackets.
+
+=item *
+
+Some languages such as C allow you to escape newline characters
+to combine lines. Other languages (such as regexes) allow you to
+backslash a space character for various reasons. Perl 6 generalizes
+this notion to any kind of whitespace. Any contiguous whitespace
+(including comments) may be hidden from the parser by prefixing it
+with C<\>. This is known as the "unspace". An unspace can suppress
+any of several whitespace dependencies in Perl. For example, since
+Perl requires an absence of whitespace between a noun and a postfix
+operator, using unspace lets you line up postfix operators:
+
+ %hash\ {$key}
+ @array\ [$ix]
+ $subref\($arg)
+
+As a special case to support the use above, a backslash where
+a postfix is expected is considered a degenerate form of unspace.
+Note that whitespace is not allowed before that, hence
+
+ $subref \($arg)
+
+is a syntax error (two terms in a row). And
+
+ foo \($arg)
+
+will be parsed as a list operator with a C<Capture> argument:
+
+ foo(\($arg))
+
+However, other forms of unspace may usefully be preceded by whitespace.
+(Unary uses of backslash may therefore never be followed by whitespace
+or they would be taken as an unspace.)
+
+Other postfix operators may also make use of unspace:
+
+ $number\ ++;
+ $number\ --;
+ 1+3\ i;
+ $object\ .say();
+ $object\#{ your ad here }.say
+
+Another normal use of a you-don't-see-this-space is typically to put
+a dotted postfix on the next line:
+
+ $object\ # comment
+ .say
+
+ $object\#[ comment
+ ].say
+
+ $object\
+ .say
+
+But unspace is mainly about language extensibility: it lets you continue
+the line in any situation where a newline might confuse the parser,
+regardless of your currently installed parser. (Unless, of course,
+you override the unspace rule itself...)
+
+Although we say that the unspace hides the whitespace from the parser,
+it does not hide whitespace from the lexer. As a result, unspace is not
+allowed within a token. Additionally, line numbers are still
+counted if the unspace contains one or more newlines. A C<#> following
+such a newline is always an end-of-line comment, as described above.
+Since Pod chunks count as whitespace to the language, they are also
+swallowed up by unspace. Heredoc boundaries are suppressed, however,
+so you can split excessively long heredoc intro lines like this:
+
+ ok(q:to'CODE', q:to'OUTPUT', \
+ "Here is a long description", \ # --more--
+ todo(:parrøt<0.42>, :dötnet<1.2>));
+ ...
+ CODE
+ ...
+ OUTPUT
+
+To the heredoc parser that just looks like:
+
+ ok(q:to'CODE', q:to'OUTPUT', "Here is a long description", todo(:parrøt<0.42>, :dötnet<1.2>));
+ ...
+ CODE
+ ...
+ OUTPUT
+
+Note that this is one of those cases in which it is fine to have
+whitespace before the unspace, since we're only trying to suppress
+the newline transition, not all whitespace as in the case of postfix
+parsing. (Note also that the example above is not meant to spec how
+the test suite works. :)
+
+=item *
+
+An unspace may contain a comment, but a comment may not contain an unspace.
+In particular, end-of-line comments do not treat backslash as significant.
+If you say:
+
+ #\ (...
+
+it is an end-of-line comment, not an embedded comment. Write:
+
+ \ #(
+ ...
+ )
+
+to mean the other thing.
+
+=item *
+
+In general, whitespace is optional in Perl 6 except where it is needed
+to separate constructs that would be misconstrued as a single token or
+other syntactic unit. (In other words, Perl 6 follows the standard
+I<longest-token> principle, or in the cases of large constructs, a
+I<prefer shifting to reducing> principle. See L</Grammatical Categories>
+below for more on how a Perl program is analyzed into tokens.)
+
+This is an unchanging deep rule, but the surface ramifications of it
+change as various operators and macros are added to or removed from
+the language, which we expect to happen because Perl 6 is designed to
+be a mutable language. In particular, there is a natural conflict
+between postfix operators and infix operators, either of which
+may occur after a term. If a given token may be interpreted as
+either a postfix operator or an infix operator, the infix operator
+requires space before it. Postfix operators may never have intervening
+space, though they may have an intervening dot. If further separation
+is desired, an embedded comment may be used as described above, as long
+as no whitespace occurs outside the embedded comment.
+
+For instance, if you were to add your own C<< infix:<++> >> operator,
+then it must have space before it. The normal autoincrementing
+C<< postfix:<++> >> operator may never have space before it, but may
+be written in any of these forms:
+
+ $x++
+
+ $x.++
+
+ $x\ ++
+
+ $x\ .++
+
+ $x\#( comment ).++
+ $x\#((( comment ))).++
+
+ $x\
+ .++
+
+ $x\ # comment
+ # inside unspace
+ .++
+
+ $x\ # comment
+ # inside unspace
+ ++ # (but without the optional postfix dot)
+
+ $x\#『 comment
+ more comment
+ 』.++
+
+ $x\#[ comment 1
+ comment 2
+ =begin podstuff
+ whatever (pod comments ignore current parser state)
+ =end podstuff
+ comment 3
+ ].++
+
+A consequence of the postfix rule is that (except when delimiting a
+quote or terminating an unspace) a dot with whitespace in front
+of it is always considered a method call on C<$_> where a term is
+expected. If a term is not expected at this point, it is a syntax
+error. (Unless, of course, there is an infix operator of that name
+beginning with dot. You could, for instance, define a Fortranly
+C<< infix:<.EQ.> >> if the fit took you. But you'll have to be sure to
+always put whitespace in front of it, or it would be interpreted as
+a postfix method call instead.)
+
+For example,
+
+ foo .method
+
+and
+
+ foo
+ .method
+
+will always be interpreted as
+
+ foo $_.method
+
+but never as
+
+ foo.method
+
+Use some variant of
+
+ foo\
+ .method
+
+if you mean the postfix method call.
+
+One consequence of all this is that you may no longer write a Num as
+C<42.> with just a trailing dot. You must instead say either C<42>
+or C<42.0>. In other words, a dot following a number can only be a
+decimal point if the following character is a digit. Otherwise the
+postfix dot will be taken to be the start of some kind of method call
+syntax, whether long-dotty or not. (The C<.123> form with a leading
+dot is still allowed however when a term is expected, and is equivalent
+to C<0.123> rather than C<$_.123>.)
+
+=back
+
+=head1 Built-In Data Types
+
+=over 4
+
+=item *
+
+In support of OO encapsulation, there is a new fundamental datatype:
+B<P6opaque>. External access to opaque objects is always through method
+calls, even for attributes.
+
+=item *
+
+Perl 6 has an optional type system that helps you write safer
+code that performs better. The compiler is free to infer what type
+information it can from the types you supply, but will not complain
+about missing type information unless you ask it to.
+
+=item *
+
+Types are officially compared using name equivalence rather than
+structural equivalence. However, we're rather liberal in what we
+consider a name. For example, the name includes the version and
+authority associated with the module defining the type (even if
+the type itself is "anonymous"). Beyond that, when you instantiate
+a parametric type, the arguments are considered part of the "long
+name" of the resulting type, so one C<Array of Int> is equivalent to
+another C<Array of Int>. (Another way to look at it is that the type
+instantiation "factory" is memoized.) Typename aliases are considered
+equivalent to the original type.
+
+This name equivalence of parametric types extends only to parameters
+that can be considered immutable (or that at least can have an
+immutable snapshot taken of them). Two distinct classes are never
+considered equivalent even if they have the same attributes because
+classes are not considered immutable.
+
+=item *
+
+Perl 6 supports the notion of B<properties> on various kinds of
+objects. Properties are like object attributes, except that they're
+managed by the individual object rather than by the object's class.
+
+According to S12, properties are actually implemented by a
+kind of mixin mechanism, and such mixins are accomplished by the
+generation of an individual anonymous class for the object (unless
+an identical anonymous class already exists and can safely be shared).
+
+=item *
+
+Properties applied to objects constructed at compile-time, such as
+variables and classes, are also called B<traits>. Traits cannot be
+changed at run-time. Changes to run-time properties are done via
+mixin instead, so that the compiler can optimize based on declared traits.
+
+=item *
+
+Perl 6 is an OO engine, but you're not generally required to think
+in OO when that's inconvenient. However, some built-in concepts such
+as filehandles will be more object-oriented in a user-visible way
+than in Perl 5.
+
+=item *
+
+A variable's type is a constraint indicating what sorts of values the
+variable may contain. More precisely, it's a promise that the object
+or objects contained in the variable are capable of responding to the
+methods of the indicated "role". See S12 for more about roles.
+
+ # $x can contain only Int objects
+ my Int $x;
+
+A variable may itself be bound to a container type that specifies how
+the container works, without specifying what kinds of things it contains.
+
+ # $x is implemented by the MyScalar class
+ my $x is MyScalar;
+
+Constraints and container types can be used together:
+
+ # $x can contain only Int objects,
+ # and is implemented by the MyScalar class
+ my Int $x is MyScalar;
+
+Note that C<$x> is also initialized to C<::Int>. See below for more on this.
+
+=item *
+
+C<my Dog $spot> by itself does not automatically call a C<Dog> constructor.
+It merely assigns an undefined C<Dog> prototype object to C<$spot>:
+
+ my Dog $spot; # $spot is initialized with ::Dog
+ my Dog $spot = Dog; # same thing
+
+ $spot.defined; # False
+ say $spot; # "Dog"
+
+Any class name used as a value by itself is an undefined instance of
+that class's prototype, or I<protoobject>. See S12 for more on that.
+(Any type name in rvalue context is parsed as a list operator
+indicating a typecast, but an argumentless one of these degenerates
+to a typecast of undef, producing the protoobject.)
+
+To get a real C<Dog> object, call a constructor method such as C<new>:
+
+ my Dog $spot .= new;
+ my Dog $spot = $spot.new; # .= is rewritten into this
+
+You can pass in arguments to the constructor as well:
+
+ my Dog $cerberus .= new(heads => 3);
+ my Dog $cerberus = $cerberus.new(heads => 3); # same thing
+
+=item *
+
+If you say
+
+ my int @array is MyArray;
+
+you are declaring that the elements of C<@array> are native integers,
+but that the array itself is implemented by the C<MyArray> class.
+Untyped arrays and hashes are still perfectly acceptable, but have
+the same performance issues they have in Perl 5.
+
+=item *
+
+To get the number of elements in an array, use the C<.elems> method. You can
+also ask for the total string length of an array's elements, in bytes,
+codepoints or graphemes, using these methods C<.bytes>, C<.codes> or C<.graphs>
+respectively on the array. The same methods apply to strings as well.
+(Note that C<.bytes> is not guaranteed to be well-defined when the encoding
+is unknown. Similarly, C<.codes> is not well-defined unless you know which
+canonicalization is in effect. Hence, both methods allow an optional argument
+to specify the meaning exactly if it cannot be known from context.)
+
+There is no C<.length> method for either arrays or strings, because C<length>
+does not specify a unit.
+
+=item *
+
+Built-in object types start with an uppercase letter. This includes
+immutable types (e.g. C<Int>, C<Num>, C<Complex>, C<Rat>, C<Str>,
+C<Bit>, C<Regex>, C<Set>, C<Junction>, C<Code>, C<Block>, C<List>,
+C<Seq>), as well as mutable (container) types, such as C<Scalar>,
+C<Array>, C<Hash>, C<Buf>, C<Routine>, C<Module>, etc.
+
+Non-object (native) types are lowercase: C<int>, C<num>, C<complex>,
+C<rat>, C<buf>, C<bit>. Native types are primarily intended for
+declaring compact array storage. However, Perl will try to make those
+look like their corresponding uppercase types if you treat them that way.
+(In other words, it does autoboxing. Note, however, that sometimes
+repeated autoboxing can slow your program more than the native type
+can speed it up.)
+
+Some object types can behave as value types. Every object can produce
+a "WHICH" value that uniquely identifies the
+object for hashing and other value-based comparisons. Normal objects
+just use their address in memory, but if a class wishes to behave as a
+value type, it can define a C<.WHICH> method that makes different objects
+look like the same object if they happen to have the same contents.
+
+=item *
+
+Variables with non-native types can always contain I<undefined> values,
+such as C<Object>, C<Whatever> and C<Failure> objects. See S04 for more
+about failures (i.e. unthrown exceptions):
+
+ my Int $x = undef; # works
+
+Variables with native types do not support undefinedness: it is an error
+to assign an undefined value to them:
+
+ my int $y = undef; # dies
+
+Conjecture: num might support the autoconversion of undef to NaN, since
+the floating-point form can represent this concept. Might be better
+to make that conversion optional though, so that the rocket designer
+can decide whether to self-destruct immediately or shortly thereafter.
+
+Variables of non-native types start out containing an undefined value
+unless explicitly initialized to a defined value.
+
+=item *
+
+Every object supports a C<HOW> function/method that returns the
+metaclass instance managing it, regardless of whether the object
+is defined:
+
+ 'x'.HOW.methods; # get available methods for strings
+ Str.HOW.methods; # same thing with the prototype object Str
+ HOW(Str).methods; # same thing as function call
+
+ 'x'.methods; # this is likely an error - not a meta object
+ Str.methods; # same thing
+
+(For a prototype system (a non-class-based object system), all objects are merely managed by the same meta object.)
+
+=item *
+
+Perl 6 intrinsically supports big integers and rationals through its
+system of type declarations. C<Int> automatically supports promotion
+to arbitrary precision, as well as holding C<Inf> and C<NaN> values.
+Note that C<Int> assumes 2's complement arithmetic, so C<+^1 == -2>
+is guaranteed. (Native C<int> operations need not support this on
+machines that are not natively 2's complement. You must convert to
+and from C<Int> to do portable bitops on such ancient hardware.)
+
+(C<Num> may support arbitrary-precision floating-point arithmetic, but
+is not required to unless we can do so portably and efficiently. C<Num>
+must support the largest native floating point format that runs at full speed.)
+
+C<Rat> supports arbitrary precision rational arithmetic. However,
+dividing two C<Int> objects using C<< infix:</> >> produces a
+fraction of C<Num> type, not a ratio. You can produce a ratio by
+using C<< infix:<div> >> on two integers instead.
+
+Lower-case types like C<int> and C<num> imply the native
+machine representation for integers and floating-point numbers,
+respectively, and do not promote to arbitrary precision, though
+larger representations are always allowed for temporary values.
+Unless qualified with a number of bits, C<int> and C<num> types represent
+the largest native integer and floating-point types that run at full speed.
+
+Numeric values in untyped variables use C<Int> and C<Num> semantics
+rather than C<int> and C<num>.
+
+=item *
+
+Perl 6 should by default make standard IEEE floating point concepts
+visible, such as C<Inf> (infinity) and C<NaN> (not a number). Within a
+lexical scope, pragmas may specify the nature of temporary values,
+and how floating point is to behave under various circumstances.
+All IEEE modes must be lexically available via pragma except in cases
+where that would entail heroic efforts to bypass a braindead platform.
+
+The default floating-point modes do not throw exceptions but rather
+propagate Inf and NaN. The boxed object types may carry more detailed
+information on where overflow or underflow occurred. Numerics in Perl
+are not designed to give the identical answer everywhere. They are
+designed to give the typical programmer the tools to achieve a good
+enough answer most of the time. (Really good programmers may occasionally
+do even better.) Mostly this just involves using enough bits that the
+stupidities of the algorithm don't matter much.
+
+=item *
+
+A C<Str> is a Unicode string object. There is no corresponding native
+C<str> type. However, since a C<Str> object may fill multiple roles,
+we say that a C<Str> keeps track of its minimum and maximum Unicode
+abstraction levels, and plays along nicely with the current lexical
+scope's idea of the ideal character, whether that is bytes, codepoints,
+graphemes, or characters in some language. For all builtin operations,
+all C<Str> positions are reported as position objects, not integers.
+These C<StrPos> objects point into a particular string at a particular
+location independent of abstraction level, either by tracking the
+string and position directly, or by generating an abstraction-level
+independent representation of the offset from the beginning of the
+string that will give the same results if applied to the same string
+in any context. This is assuming the string isn't modified in the
+meanwhile; a C<StrPos> is not a "marker" and is not required to follow
+changes to a mutable string. For instance, if you ask for the positions
+of matches done by a substitution, the answers are reported in terms of the
+original string (which may now be inaccessible!), not as positions within
+the modified string. (However, if you use C<.pos> on the modified string,
+it will report the position of the end of the substitution in terms
+of the new string.)
+
+The subtraction of two C<StrPos> objects gives a C<StrLen> object,
+which is also not an integer, because the string between two positions
+also has multiple integer interpretations depending on the units.
+A given C<StrLen> may know that it represents 18 bytes, 7 codepoints,
+3 graphemes, and 1 letter in Malayalam, but it might only know this
+lazily because it actually just hangs onto the two C<StrPos> endpoints
+within the string that in turn may or may not just lazily point into
+the string. (The lazy implementation of C<StrLen> is much like a
+C<Range> object in that respect.)
+
+If you use integers as arguments where position objects are expected,
+it will be assumed that you mean the units of the current lexically
+scoped Unicode abstraction level. (Which defaults to graphemes.)
+Otherwise you'll need to coerce to the proper units:
+
+ substr($string, 42.as(Bytes), 1.as(ArabicChars))
+
+Of course, such a dimensional number will fail if used on a string
+that doesn't provide the appropriate abstraction level.
+
+If a C<StrPos> or C<StrLen> is forced into a numeric context, it will
+assume the units of the current Unicode abstraction level. It is
+erroneous to pass such a non-dimensional number to a routine that
+would interpret it with the wrong units.
+
+Implementation note: since Perl 6 mandates that the default Unicode
+processing level must view graphemes as the fundamental unit rather
+than codepoints, this has some implications regarding efficient
+implementation. It is suggested that all graphemes be translated on
+input to a unique grapheme numbers and represented as integers within
+some kind of uniform array for fast substr access. For those graphemes
+that have a precomposed form, use of that codepoint is suggested.
+(Note that this means Latin-1 can still be represented internally
+with 8-bit integers.)
+
+For graphemes that have no precomposed form, a temporary private
+id should be assigned that uniquely identifies the grapheme.
+If such ids are assigned consistently thoughout the process,
+comparison of two graphemes is no more difficult than the comparison
+of two integers, and comparison of base characters no more difficult
+than a direct lookup into the id-to-NFD table.
+
+Obviously, any temporary grapheme ids must be translated back to
+some universal form (such as NFD) on output, and normal precomposed
+graphemes may turn into either NFC or NFD forms depending on the
+desired output. Maintaining a particular grapheme/id mapping over the
+life of the process may have some GC implications for long-running
+processes, but most processes will likely see a limited number of
+non-precomposed graphemes.
+
+If the program has a scope that wants a codepoint view rather than
+a grapheme view, the string visible to that lexical scope must also
+be translated to universal form, just as with output translation.
+Alternately, the temporary grapheme ids may be hidden behind an
+abstraction layer. In any case, codepoint scope should never see
+any temporary grapheme ids. (The lexical codepoint declaration
+should probably specify which normalization form it prefers to
+view strings under. Such a declaration could be applied to input
+translation as well.)
+
+=item *
+
+A C<Buf> is a stringish view of an array of
+integers, and has no Unicode or character properties without explicit
+conversion to some kind of C<Str>. (A C<buf> is the native counterpart.)
+Typically it's an array of bytes serving as a buffer. Bitwise
+operations on a C<Buf> treat the entire buffer as a single large
+integer. Bitwise operations on a C<Str> generally fail unless the
+C<Str> in question can provide an abstract C<Buf> interface somehow.
+Coercion to C<Buf> should generally invalidate the C<Str> interface.
+As a generic type C<Buf> may be instantiated as (or bound to) any
+of C<buf8>, C<buf16>, or C<buf32> (or to any type that provides the
+appropriate C<Buf> interface), but when used to create a buffer C<Buf>
+defaults to C<buf8>.
+
+Unlike C<Str> types, C<Buf> types prefer to deal with integer string
+positions, and map these directly to the underlying compact array
+as indices. That is, these are not necessarily byte positions--an
+integer position just counts over the number of underlying positions,
+where one position means one cell of the underlying integer type.
+Builtin string operations on C<Buf> types return integers and expect
+integers when dealing with positions. As a limiting case, C<buf8> is
+just an old-school byte string, and the positions are byte positions.
+Note, though, that if you remap a section of C<buf32> memory to be
+C<buf8>, you'll have to multiply all your positions by 4.
+
+=item *
+
+Ordinarily a term beginning with C<*> indicates a global function
+or type name, but by itself, the C<*> term captures the notion of
+"Whatever", which is applied lazily by whatever operator it is an
+argument to. Generally it can just be thought of as a "glob" that
+gives you everything it can in that argument position. For instance:
+
+ if $x ~~ 1..* {...} # if 1 <= $x <= +Inf
+ my ($a,$b,$c) = "foo" xx *; # an arbitrary long list of "foo"
+ if /foo/ ff * {...} # a latching flipflop
+ @slice = @x[*;0;*]; # any Int
+ @slice = %x{*;'foo'}; # any keys in domain of 1st dimension
+ @array[*] # flattens, unlike @array[]
+ (*, *, $x) = (1, 2, 3); # skip first two elements
+ # (same as lvalue "undef" in Perl 5)
+
+C<Whatever> is an undefined prototype object derived from C<Any>. As a
+type it is abstract, and may not be instantiated as a defined object.
+If for a particular MMD dispatch, nothing in the MMD system claims it,
+it dispatches to as an C<Any> with an undefined value, and usually
+blows up constructively. If you say
+
+ say 1 + *;
+
+you should probably not expect it to yield a reasonable answer, unless
+you think an exception is reasonable. Since the C<Whatever> object
+is effectively immutable, the optimizer is free to recognize C<*>
+and optimize in the context of what operator it is being passed to.
+
+A variant of C<*> is the C<**> term. It is generally understood to
+be a multidimension form of C<*> when that makes sense.
+
+Other uses for C<*> will doubtless suggest themselves over time. These
+can be given meaning via the MMD system, if not the compiler. In general
+a C<Whatever> should be interpreted as maximizing the degrees of freedom
+in a dwimmey way, not as a nihilistic "don't care anymore--just shoot me".
+
+=back
+
+=head2 Native types
+
+Values with these types autobox to their uppercase counterparts when
+you treat them as objects:
+
+ bit single native bit
+ int native signed integer
+ uint native unsigned integer (autoboxes to Int)
+ buf native buffer (finite seq of native ints or uints, no Unicode)
+ num native floating point
+ complex native complex number
+ bool native boolean
+
+Since native types cannot represent Perl's concept of undefined values,
+in the absence of explicit initialization, native floating-point types
+default to NaN, while integer types (including C<bit>) default to 0.
+The complex type defaults to NaN + NaN.i. A buf type of known size
+defaults to a sequence of 0 values. If any native type is explicitly
+initialized to C<*> (the C<Whatever> type), no initialization is attempted
+and you'll get whatever was already there when the memory was allocated.
+
+If a buf type is initialized with a Unicode string value, the string
+is decomposed into Unicode codepoints, and each codepoint shoved into
+an integer element. If the size of the buf type is not specified,
+it takes its length from the initializing string. If the size
+is specified, the initializing string is truncated or 0-padded as
+necessary. If a codepoint doesn't fit into a buf's integer type,
+a parse error is issued if this can be detected at compile time;
+otherwise a warning is issued at run time and the overflowed buffer
+element is filled with an appropriate replacement character, either
+C<U+FFFD> (REPLACEMENT CHARACTER) if the element's integer type is at
+least 16 bits, or C<U+007f> (DELETE) if the larger value would not fit.
+If any other conversion is desired, it must be specified explicitly.
+In particular, no conversion to UTF-8 or UTF-16 is attempted; that
+must be specified explicitly. (As it happens, conversion to a buf
+type based on 32-bit integers produces valid UTF-32 in the native
+endianness.)
+
+=head2 Undefined types
+
+These can behave as values or objects of any class, except that
+C<defined> always returns false. One can create them with the
+built-in C<undef> and C<fail> functions. (See S04 for how failures
+are handled.)
+
+ Nil Empty list viewed as an item
+ Object Uninitialized (derivatives serve as protoobjects of classes)
+ Whatever Wildcard (like undef, but subject to do-what-I-mean via MMD)
+ Failure Failure (lazy exceptions, thrown if not handled properly)
+
+Whenever you declare any kind of type, class, module, or package, you're
+automatically declaring a undefined prototype value with the same name.
+
+Whenever a C<Failure> value is put into a typed container, it takes
+on the type specified by the container but continues to carry the
+C<Failure> role. (The C<undef> function merely returns the most
+generic C<Failure> object. Use C<fail> to return more specific failures. Use
+C<Object> for the most generic non-failure undefined value. The C<Any>
+type is also undefined, but excludes C<Junctions> so that autothreading
+may be dispatched using normal multiple dispatch rules.)
+
+The C<Nil> type is officially undefined as an item but interpolates
+as a null list into list context, and an empty capture into slice
+context. A C<Nil> object may also carry failure information,
+but if so, the object behaves as a failure only in item context.
+Use C<Failure>/C<undef> when you want to return a hard failure that
+will not evaporate in list context.
+
+=head2 Immutable types
+
+Objects with these types behave like values, i.e. C<$x === $y> is true
+if and only if their types and contents are identical (that is, if
+C<$x.WHICH> eqv C<$y.WHICH>).
+
+ Bit Perl single bit (allows traits, aliasing, undef, etc.)
+ Int Perl integer (allows Inf/NaN, arbitrary precision, etc.)
+ Str Perl string (finite sequence of Unicode characters)
+ Num Perl number
+ Rat Perl rational
+ Complex Perl complex number
+ Bool Perl boolean
+ Exception Perl exception
+ Code Base class for all executable objects
+ Block Executable objects that have lexical scopes
+ List Lazy Perl list (composed of immutables and iterators)
+ Seq Completely evaluated (hence immutable) sequence
+ Range A pair of Ordered endpoints; gens immutables when iterated
+ Set Unordered collection of values that allows no duplicates
+ Bag Unordered collection of values that allows duplicates
+ Junction Set with additional behaviors
+ Pair A single key-to-value association
+ Mapping Set of Pairs with no duplicate keys
+ Signature Function parameters (left-hand side of a binding)
+ Capture Function call arguments (right-hand side of a binding)
+ Blob An undifferentiated mass of bits
+
+Insofar as Lists are lazy, they're really only partially immutable, in
+the sense that the past is fixed but the future is not. The portion of
+a List yet to be determined by iterators may depend on mutable values.
+When an iterator is called upon to iterate and extend the known part
+of the list, some number of immutable values (which includes immutable
+references to mutable objects) are decided and locked in at that point.
+Iterators may have several different ways of iterating depending on
+the degree of laziness/eagerness desired in context. The iterator
+API is described in S07.
+
+=head2 Mutable types
+
+Objects with these types have distinct C<.WHICH> values that do not change
+even if the object's contents change. (Routines are considered mutable
+because they can be wrapped in place.)
+
+ Scalar Perl scalar
+ Array Perl array
+ Hash Perl hash
+ KeyHash Perl hash that autodeletes values matching default
+ KeySet KeyHash of Bool (does Set in list/array context)
+ KeyBag KeyHash of UInt (does Bag in list/array context)
+ Buf Perl buffer (a stringish array of memory locations)
+ IO Perl filehandle
+ Routine Base class for all wrappable executable objects
+ Sub Perl subroutine
+ Method Perl method
+ Submethod Perl subroutine acting like a method
+ Macro Perl compile-time subroutine
+ Regex Perl pattern
+ Match Perl match, usually produced by applying a pattern
+ Package Perl 5 compatible namespace
+ Module Perl 6 standard namespace
+ Class Perl 6 standard class namespace
+ Role Perl 6 standard generic interface/implementation
+ Grammar Perl 6 pattern matching namespace
+ Any Perl 6 object (default parameter type, excludes Junction)
+ Object Perl 6 object (either Any or Junction)
+
+A C<KeyHash> differs from a normal C<Hash> in how it handles default
+values. If the value of a C<KeyHash> element is set to the default
+value for the C<KeyHash>, the element is deleted. If undeclared,
+the default default for a C<KeyHash> is 0 for numeric types, C<False>
+for boolean types, and the null string for string and buffer types.
+A C<KeyHash> of a C<Object> type defaults to the undefined prototype
+for that type. More generally, the default default is whatever defined
+value an C<undef> would convert to for that value type. A C<KeyHash>
+of C<Scalar> deletes elements that go to either 0 or the null string.
+A C<KeyHash> also autodeletes keys for normal undef values (that is,
+those undefined values that do not contain an unthrown exception).
+
+A C<KeySet> is a C<KeyHash> of booleans with a default of C<False>.
+If you use the C<Hash> interface and increment an element of a
+C<KeySet> its value becomes true (creating the element if it doesn't
+exist already). If you decrement the element it becomes false and
+is automatically deleted. Decrementing a non-existing value results
+in a C<False> value. Incrementing an existing value results in C<True>.
+When not used as a C<Hash> (that is,
+when used as an C<Array> or list or C<Set> object) a C<KeySet>
+behaves as a C<Set> of its keys. (Since the only possible value of
+a C<KeySet> is the C<True> value, it need not be represented in
+the actual implementation with any bits at all.)
+
+A C<KeyBag> is a C<KeyHash> of C<UInt> with default of 0. If you
+use the C<Hash> interface and increment an element of a C<KeyBag>
+its value is increased by one (creating the element if it doesn't exist
+already). If you decrement the element the value is decreased by one;
+if the value goes to 0 the element is automatically deleted. An attempt
+to decrement a non-existing value results in a C<Failure> value. When not
+used as a C<Hash> (that is, when used as an C<Array> or list or C<Bag>
+object) a C<KeyBag> behaves as a C<Bag> of its keys, with each key
+replicated the number of times specified by its corresponding value.
+(Use C<.kv> or C<.pairs> to suppress this behavior in list context.)
+
+=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 is stored as its C<of> property, while the implementation
+type of the container is just the object type of the container itself.
+The word C<returns> is allowed as an alias for C<of>.
+
+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<of> keyword:
+
+ my Dog $spot;
+ my $spot of Dog;
+
+In either case this sets the C<of> property of the container to C<Dog>.
+
+Subroutines have a variant of the C<of> property, C<as>, that sets
+the C<as> property instead. The C<as> property specifies a
+constraint (or perhaps coercion) to be enforced on the return value (either
+by explicit call to C<return> or by implicit fall-off-the-end return).
+This constraint, unlike the C<of> property, is not advertised as the
+type of the routine. You can think of it as the implicit type signature of
+the (possibly implicit) return statement. It's therefore available for
+type inferencing within the routine but not outside it. If no C<as> type
+is declared, it is assumed to be the same as the C<of> type, if declared.
+
+ sub get_pet() of Animal {...} # of type, obviously
+ sub get_pet() returns Animal {...} # of type
+ our Animal sub get_pet() {...} # of type
+ sub get_pet() as Animal {...} # as type
+
+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
+
+The key type of a hash may be specified as a shape trait--see S09.
+
+=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.
+
+However, package variables are always considered C<Tieable> by default.
+As a consequence, all named packages are also C<Tieable> by default.
+Classes and modules may be viewed as differently tied packages.
+Looking at it from the other direction, classes and modules that
+wish to be bound to a global package name must be able to do the
+C<Package> 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[of => Array[of => Recipe]] %book;
+
+Because the actual variable can be hard to find when complex types are
+specified, there is a postfix form as well:
+
+ my Hash of Array of Recipe %book; # HoHoAoRecipe
+ my %book of Hash of Array of Recipe; # same thing
+
+The C<as> form may be used in subroutines:
+
+ my sub get_book ($key) as Hash of Array of Recipe {...}
+
+Alternately, the return type may be specified within the signature:
+
+ my sub get_book ($key --> Hash of Array of Recipe) {...}
+
+There is a slight difference, insofar as the type inferencer will
+ignore a C<as> but pay attention to C<< --> >> or prefix type
+declarations, also known as the C<of> type. Only the inside of the
+subroutine pays attention to C<as>, and essentially coerces the return
+value to the indicated type, just as if you'd coerced each return expression.
+
+You may also specify the C<of> type as the C<of> trait (with C<returns>
+allowed as a synonym):
+
+ my Hash of Array of Recipe sub get_book ($key) {...}
+ my sub get_book ($key) of Hash of Array of Recipe {...}
+ my sub get_book ($key) returns Hash of Array of Recipe {...}
+
+=head2 Polymorphic types
+
+Anywhere you can use a single type you can use a set of types, for convenience
+specifiable as if it were an "or" junction:
+
+ my Int|Str $error = $val; # can assign if $val~~Int or $val~~Str
+
+Fancier type constraints may be expressed through a subtype:
+
+ subset Shinola of Any where {.does(DessertWax) and .does(FloorTopping)};
+ if $shimmer ~~ Shinola {...} # $shimmer must do both interfaces
+
+Since the terms in a parameter could be viewed as a set of
+constraints that are implicitly "anded" together (the variable itself
+supplies type constraints, and C<where> clauses or tree matching just
+add more constraints), we relax this to allow juxtaposition of
+types to act like an "and" junction:
+
+ # Anything assigned to the variable $mitsy must conform
+ # to the type Fish and either the Cat or Dog type...
+ my Cat|Dog Fish $mitsy = new Fish but { Bool.pick ?? .does Cat
+ !! .does Dog };
+
+=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 Generic types
+
+Within a declaration, a class variable (either by itself or
+following an existing type name) declares a new type name and takes
+its parametric value from the actual type of the parameter it is
+associated with. It declares the new type name in the same scope
+as the associated declaration.
+
+ sub max (Num ::X @array) {
+ push @array, X.new();
+ }
+
+The new type name is introduced immediately, so two such types in
+the same signature must unify compatibly if they have the same name:
+
+ sub compare (Any ::T $x, T $y) {
+ return $x eqv $y;
+ }
+
+=head2 Return types
+
+On a scoped subroutine, a return type can be specified before or after
+the name. We call all return types "return types", but distinguish
+two kinds of return types, the C<as> type and the C<of> type,
+because the C<of> type is normally an "official" named type and
+declares the official interface to the routine, while the C<as>
+type is merely a constraint on what may be returned by the routine
+from the routine's point of view.
+
+ our sub lay as Egg {...} # as type
+ our Egg sub lay {...} # of type
+ our sub lay of Egg {...} # of type
+ our sub lay (--> Egg) {...} # of type
+
+ my sub hat as Rabbit {...} # as type
+ my Rabbit sub hat {...} # of type
+ my sub hat of Rabbit {...} # of type
+ my sub hat (--> Rabbit) {...} # of type
+
+If a subroutine is not explicitly scoped, it belongs to the current
+namespace (module, class, grammar, or package), as if it's scoped with
+the C<our> scope modifier. Any return type must go after the name:
+
+ sub lay as Egg {...} # as type
+ sub lay of Egg {...} # of type
+ sub lay (--> Egg) {...} # of type
+
+On an anonymous subroutine, any return type can only go after the C<sub>
+keyword:
+
+ $lay = sub as Egg {...}; # as type
+ $lay = sub of Egg {...}; # of type
+ $lay = sub (--> Egg) {...}; # of type
+
+but you can use a scope modifier to introduce an C<of> prefix type:
+
+ $lay = my Egg sub {...}; # of type
+ $hat = my Rabbit sub {...}; # of type
+
+Because they are anonymous, you can change the C<my> modifier to C<our>
+without affecting the meaning.
+
+The return type may also be specified after a C<< --> >> token within
+the signature. This doesn't mean exactly the same thing as C<as>.
+The C<of> type is the "official" return type, and may therefore be
+used to do type inferencing outside the sub. The C<as> type only
+makes the return type available to the internals of the sub so that
+the C<return> statement can know its context, but outside the sub we
+don't know anything about the return value, as if no return type had
+been declared. The prefix form specifies the C<of> type rather than
+the C<as> type, so the return type of
+
+ my Fish sub wanda ($x) { ... }
+
+is known to return an object of type Fish, as if you'd said:
+
+ my sub wanda ($x --> Fish) { ... }
+
+I<not> as if you'd said
+
+ my sub wanda ($x) as Fish { ... }
+
+It is possible for the C<of> type to disagree with the C<as> type:
+
+ my Squid sub wanda ($x) as Fish { ... }
+
+or equivalently,
+
+ my sub wanda ($x --> Squid) as Fish { ... }
+
+This is not lying to yourself--it's lying to the world. Having a
+different inner type is useful if you wish to hold your routine to
+a stricter standard than you let on to the outside world, for instance.
+
+=head1 Names and Variables
+
+=over 4
+
+=item *
+
+The C<$Package'var> syntax is gone. Use C<$Package::var> instead.
+
+=item *
+
+Perl 6 includes a system of B<sigils> to mark the fundamental
+structural type of a variable:
+
+ $ scalar (object)
+ @ ordered array
+ % unordered hash (associative array)
+ & code/rule/token/regex
+ :: package/module/class/role/subset/enum/type/grammar
+ @@ slice view of @
+
+Within a declaration, the C<&> sigil also declares the visibility of the
+subroutine name without the sigil within the scope of the declaration:
+
+ my &func := sub { say "Hi" };
+ func; # calls &func
+
+Within a signature or other declaration, the C<::> sigil followed by an
+identifier marks a type variable that also declares the visibility
+of a package/type name without the sigil within the scope of the
+declaration. The first such declaration within a scope is assumed
+to be an unbound type, and takes the actual type of its associated
+argument. With subsequent declarations in the same scope the use of
+the sigil is optional, since the bare type name is also declared.
+
+A declaration nested within must not use the sigil if it wishes to
+refer to the same type, since the inner declaration would rebind
+the type. (Note that the signature of a pointy block counts as part
+of the inner block, not the outer block.)
+
+=item *
+
+Sigils indicate overall interface, not the exact type of the bound
+object. Different sigils imply different minimal abilities.
+
+C<$x> may be bound to any object, including any object that can be
+bound to any other sigil. Such a scalar variable is always treated as
+a singular item in any kind of list context, regardless of whether the
+object is essentially composite or unitary. It will not automatically
+dereference to its contents unless placed explicitly in some kind of
+dereferencing context. In particular, when interpolating into list
+context, C<$x> never expands its object to anything other than the
+object itself as a single item, even if the object is a container
+object containing multiple items.
+
+C<@x> may be bound to an object of the C<Array> class, but it may also
+be bound to any object that does the C<Positional> role, such as a
+C<List>, C<Seq>, C<Range>, C<Buf>, or C<Capture>. The C<Positional>
+role implies the ability to support C<< postcircumfix:<[ ]> >>.
+
+Likewise, C<%x> may be bound to any object that does the C<Associative>
+role, such as C<Pair>, C<Mapping>, C<Set>, C<Bag>, C<KeyHash>, or
+C<Capture>. The C<Associative> role implies the ability to support
+C<< postcircumfix:<{ }> >>.
+
+C<&x> may be bound to any object that does the C<Callable> role, such
+as any C<Block> or C<Routine>. The C<Callable> role implies the ability
+to support C<< postcircumfix:<( )> >>.
+
+C<::x> may be bound to any object that does the C<Abstraction> role,
+such as a typename, package, module, class, role, grammar, or any other
+protoobject with C<.HOW> hooks. This C<Abstraction> role implies the
+ability to do various symbol table and/or typological manipulations which
+may or may not be supported by any given abstraction. Mostly though it
+just means that you want to give some abstraction an official name that
+you can then use later in the compilation without any sigil.
+
+In any case, the minimal container role implied by the sigil is
+checked at binding time at the latest, and may fail earlier (such
+as at compile time) if a semantic error can be detected sooner.
+If you wish to bind an object that doesn't yet do the appropriate
+role, you must either stick with the generic C<$> sigil, or mix in
+the appropriate role before binding to a more specific sigil.
+
+An object is allowed to support both C<Positional> and C<Associative>.
+An object that does not support C<Positional> may not be bound directly
+to C<@x>. However, any construct such as C<%x> that can interpolate
+the contents of such an object into list context can automatically
+construct a list value that may then be bound to an array variable.
+Subscripting such a list does not imply subscripting back into the
+original object.
+
+=item *
+
+Unlike in Perl 5, you may no longer put whitespace between a sigil
+and its following name or construct.
+
+=item *
+
+Ordinary sigils indicate normally scoped variables, either lexical
+or package scoped. Oddly scoped variables include a secondary sigil
+(a B<twigil>) that indicates what kind of strange scoping the variable
+is subject to:
+
+ $foo ordinary scoping
+ $.foo object attribute accessor
+ $^foo self-declared formal positional parameter
+ $:foo self-declared formal named parameter
+ $*foo global variable
+ $+foo contextual variable
+ $?foo compiler hint variable
+ $=foo pod variable
+ $<foo> match variable, short for $/{'foo'}
+ $!foo explicitly private attribute (mapped to $foo though)
+
+Most variables with twigils are implicitly declared or assumed to
+be declared in some other scope, and don't need a "my" or "our".
+Attribute variables are declared with C<has>, though.
+
+=item *
+
+Sigils are now invariant. C<$> always means a scalar variable, C<@>
+an array variable, and C<%> a hash variable, even when subscripting.
+In item context, variables such as C<@array> and C<%hash> simply
+return themselves as C<Array> and C<Hash> objects. (Item context was
+formerly known as scalar context, but we now reserve the "scalar"
+notion for talking about variables rather than contexts, much as
+arrays are disassociated from list context.)
+
+=item *
+
+In string contexts, container objects automatically stringify to
+appropriate (white-space separated) string values. In numeric
+contexts, the number of elements in the container is returned.
+In boolean contexts, a true value is returned if and only if there
+are any elements in the container.
+
+=item *
+
+To get a Perlish representation of any object, use the C<.perl> method.
+Like the C<Data::Dumper> module in Perl 5, the C<.perl> method will put
+quotes around strings, square brackets around list values, curlies around
+hash values, constructors around objects, etc., so that Perl can evaluate
+the result back to the same object.
+
+=item *
+
+To get a formatted representation of any scalar value, use the
+C<.fmt('%03d')> method to do an implicit C<sprintf> on the value.
+
+To format an array value separated by commas, supply a second argument:
+C<.fmt('%03d', ', ')>. To format a hash value or list of pairs, include
+formats for both key and value in the first string: C<< .fmt('%s: %s', "\n") >>.
+
+=item *
+
+Subscripts now consistently dereference the container produced by
+whatever was to their left. Whitespace is not allowed between a
+variable name and its subscript. However, there are two ways to
+stretch the construct out visually. Since a subscript is a kind
+of postfix operator, there is a corresponding B<dot> form of each
+subscript (C<@foo.[1]> and C<%bar.{'a'}>) that makes the dereference
+a little more explicit. Constant string subscripts may be placed
+in angles, so C<%bar.{'a'}> may also be written as C<< %bar<a> >>
+or C<< %bar.<a> >>. Additionally, you may insert extra whitespace
+using the unspace.
+
+=item *
+
+Slicing is specified by the nature of the subscript, not by
+the sigil.
+
+=item *
+
+The context in which a subscript is evaluated is no longer controlled
+by the sigil either. Subscripts are always evaluated in list context.
+(More specifically, they are evaluated in a variant of list context
+known as I<slice> context, which preserves dimensional information
+so that you can do multi-dimensional slices using semicolons. However,
+each slice dimension evaluates its sublist in normal list context,
+so functions called as part of a subscript don't see a slice context.
+See S09 for more on slice context.)
+
+If you need to force inner context to item (scalar), we now have convenient
+single-character context specifiers such as + for numbers and ~ for strings:
+
+ $x = g(); # item context for g()
+ @x[f()] = g(); # list context for f() and g()
+ @x[f()] = +g(); # list context for f(), numeric item context for g()
+ @x[+f()] = g(); # numeric item context for f(), list context for g()
+
+ @x[f()] = @y[g()]; # list context for f() and g()
+ @x[f()] = +@y[g()]; # list context for f() and g()
+ @x[+f()] = @y[g()]; # numeric item context for f(), list context for g()
+ @x[f()] = @y[+g()]; # list context for f(), numeric item context for g()
+
+ %x{~f()} = %y{g()}; # string item context for f(), list context for g()
+ %x{f()} = %y{~g()}; # list context for f(), string item context for g()
+
+Sigils used either as functions or as list prefix operators also
+force context, so these also work:
+
+ @x[$(g())] # item context for g()
+ @x[$ g()] # item context for g()
+ %x{$(g())} # item context for g()
+ %x{$ g()} # item context for g()
+
+But note that these don't do the same thing:
+
+ @x[$g()] # call function in $g
+ %x{$g()} # call function in $g
+
+=item *
+
+There is a need to distinguish list assignment from list binding.
+List assignment works much like it does in Perl 5, copying the
+values. There's a new C<:=> binding operator that lets you bind
+names to C<Array> and C<Hash> objects without copying, in the same way
+as subroutine arguments are bound to formal parameters. See S06
+for more about binding.
+
+=item *
+
+An argument list may be captured into an object with backslashed parens:
+
+ $args = \(1,2,3,:mice<blind>)
+
+Values in a C<Capture> object are parsed as ordinary expressions, marked as
+invocant, positional, named, and so on.
+
+Like C<List> objects, C<Capture> objects are immutable in the abstract, but
+evaluate their arguments lazily. Before everything inside a C<Capture> is
+fully evaluated (which happens at compile time when all the arguments are
+constants), the eventual value may well be unknown. All we know is
+that we have the promise to make the bits of it immutable as they become known.
+
+C<Capture> objects may contain multiple unresolved iterators such as feeds
+or slices. How these are resolved depends on what they are eventually
+bound to. Some bindings are sensitive to multiple dimensions while
+others are not.
+
+You may retrieve parts from a C<Capture> object with a prefix sigil operator:
+
+ $args = \3; # same as "$args = \(3)"
+ $$args; # same as "$args as Scalar" or "Scalar($args)"
+ @$args; # same as "$args as Array" or "Array($args)"
+ %$args; # same as "$args as Hash" or "Hash($args)"
+
+When cast into an array, you can access all the positional arguments; into a
+hash, all named arguments; into a scalar, its invocant.
+
+All prefix sigil operators accept one positional argument, evaluated in
+item context as a rvalue. They can interpolate in strings if called with
+parentheses. The special syntax form C<$()> translates into C<$( $/ )>
+to operate on the current match object; the same applies to C<@()> and C<%()>.
+
+C<Capture> objects fill the ecological niche of references in Perl 6.
+You can think of them as "fat" references, that is, references that
+can capture not only the current identity of a single object, but
+also the relative identities of several related objects. Conversely,
+you can think of Perl 5 references as a degenerate form of C<Capture>
+when you want to refer only to a single item.
+
+=item *
+
+A signature object (C<Signature>) may be created with colon-prefixed parens:
+
+ my ::MySig ::= :(Int, Num, Complex, Status)
+
+Expressions inside the signature are parsed as parameter declarations
+rather than ordinary expressions. See S06 for more details on the syntax
+for parameters.
+
+Signature objects bound to type variables (as in the example above) may
+be used within other signatures to apply additional type constraints.
+When applied to a C<Capture> argument, the signature allows you to
+take the types of the capture's arguments from C<MySig>, but declare
+the (untyped) variable names yourself via an additional signature
+in parentheses:
+
+ sub foo (Num Dog|Cat $numdog, MySig $a ($i,$j,$k,$mousestatus)) {...}
+ foo($mynumdog, \(1, 2.7182818, 1.0i, statmouse());
+
+=item *
+
+Unlike in Perl 5, the notation C<&foo> merely stands for the C<foo>
+function as a Code object without calling it. You may call any Code
+object with parens after it (which may, of course, contain arguments):
+
+ &foo($arg1, $arg2);
+
+Whitespace is not allowed before the parens because it is parsed as
+a postfix. As with any postfix, there is also a corresponding C<.()>
+operator, and you may use the "unspace" form to insert optional
+whitespace and comments between the backslash and either of the
+postfix forms:
+
+ &foo\ ($arg1, $arg2);
+ &foo\ .($arg1, $arg2);
+ &foo\#[
+ embedded comment
+ ].($arg1, $arg2);
+
+=item *
+
+With multiple dispatch, C<&foo> may actually be the name of a set
+of candidate functions (which you can use as if it were an ordinary function).
+However, in that case C<&foo> by itself is not be sufficient to uniquely
+name a specific function. To do that, the type may be refined by
+using a signature literal as a postfix operator:
+
+ &foo:(Int,Num)
+
+It still just returns a C<Code> object. A call may also be partially
+applied by using the C<.assuming> method:
+
+ &foo.assuming(1,2,3,:mice<blind>)
+
+
+=item *
+
+Slicing syntax is covered in S09. A multidimensional
+slice will be done with semicolons between individual slice sublists.
+Each such slice sublist is evaluated lazily.
+
+=item *
+
+To make a slice subscript return something other than values, append an
+appropriate adverb to the subscript.
+
+ @array = <A B>;
+ @array[0,1,2]; # returns 'A', 'B', undef
+ @array[0,1,2] :p; # returns 0 => 'A', 1 => 'B'
+ @array[0,1,2] :kv; # returns 0, 'A', 1, 'B'
+ @array[0,1,2] :k; # returns 0, 1
+ @array[0,1,2] :v; # returns 'A', 'B'
+
+ %hash = (:a<A>, :b<B>);
+ %hash<a b c>; # returns 'A', 'B', undef
+ %hash<a b c> :p; # returns a => 'A', b => 'B'
+ %hash<a b c> :kv; # returns 'a', 'A', 'b', 'B'
+ %hash<a b c> :k; # returns 'a', 'b'
+ %hash<a b c> :v; # returns 'A', 'B'
+
+These adverbial forms all weed out non-existing entries. You may also
+perform an existence test, which will return true if all the elements
+of the slice exist:
+
+ if %hash<a b c> :exists {...}
+
+likewise,
+
+ my ($a,$b,$c) = %hash<a b c> :delete;
+
+deletes the entries "en passant" while returning them. (Of course,
+any of these forms also work in the degenerate case of a slice
+containing a single index.) Note that these forms work by virtue
+of the fact that the subscript is the topmost previous operator.
+You may have to parenthesize or force list context if some other
+operator that is tighter than comma would appear to be topmost:
+
+ 1 + (%hash{$x} :delete);
+ $x = (%hash{$x} :delete);
+ ($x) = %hash{$x} :delete;
+
+(The situation does not often arise for the slice modifiers above
+because they are usually used in list context, which operates
+at comma precedence.)
+
+=item *
+
+In numeric context (i.e. when cast into C<Int> or C<Num>), a C<Hash> object
+becomes the number of pairs contained in the hash. In a boolean context, a
+Hash object is true if there are any pairs in the hash. In either case,
+any intrinsic iterator would be reset. (If hashes do carry an intrinsic
+iterator (as they do in Perl 5), there will be a C<.reset> method on the
+hash object to reset the iterator explicitly.)
+
+=item *
+
+Sorting a list of pairs should sort on their keys by default, then
+on their values. Sorting a list of lists should sort on the first
+elements, then the second elements, etc. For more on C<sort> see S29.
+
+=item *
+
+Many of the special variables of Perl 5 are going away. Those that
+apply to some object such as a filehandle will instead be attributes
+of the appropriate object. Those that are truly global will have
+global alphabetic names, such as C<$*PID> or C<@*ARGS>.
+
+=item *
+
+Any remaining special variables will be lexically scoped.
+This includes C<$_> and C<@_>, as well as the new C<$/>, which
+is the return value of the last regex match. C<$0>, C<$1>, C<$2>, etc.,
+are aliases into the C<$/> object.
+
+=item *
+
+The C<$#foo> notation is dead. Use C<@foo.end> or C<@foo[*-1]> instead.
+(Or C<@foo.shape[$dimension]> for multidimensional arrays.)
+
+=back
+
+=head1 Names
+
+=over 4
+
+=item *
+
+An I<identifier> is composed of an alphabetic character followed by
+any sequence of alphanumeric characters. The definitions of alphabetic
+and numeric include appropriate Unicode characters. Underscore is
+always considered alphabetic. An identifier may also contain isolated
+apostrophes or hyphens provided the next character is alphabetic.
+
+A I<name> is anything that is a legal part of a variable name (not counting
+the sigil). This includes
+
+ $foo # simple identifiers
+ $Foo::Bar::baz # compound identifiers separated by ::
+ $Foo::($bar)::baz # compound identifiers that perform interpolations
+ $42 # numeric names
+ $! # certain punctuational variables
+
+When not used as a sigil, the semantic function of C<::> within a
+name is to force the preceding portion of the name to be considered
+a package through which the subsequent portion of the name is to
+be located. If the preceding portion is null, it means the package
+is unspecified and must be searched for according to the nature of
+what follows. Generally this means that an initial C<::> following the
+main sigil is a no-op on names that are known at compile time, though
+C<::> can also be used to introduce an interpolation (see below).
+Also, in the absence of another sigil, C<::> can serve as its own
+sigil indicating intentional use of a not-yet-declared package name.
+
+Unlike in Perl 5, if a sigil is followed by comma, semicolon, colon,
+or any kind of bracket or whitespace (including Unicode brackets and
+whitespace), it will be taken to be a sigil without a name rather
+than a punctuational variable. This allows you to use sigils as coercion
+operators:
+
+ print $( foo() ) # foo called in item context
+ print @@( foo() ) # foo called in slice context
+
+The bare sigil is parsed as a list operator in rvalue context, so
+these mean the same thing:
+
+ print $ foo() # foo called in item context
+ print @@ foo() # foo called in slice context
+
+In declarative contexts bare sigils may be used as placeholders for
+anonymous variables:
+
+ my ($a, $, $c) = 1..3;
+ print unless (state $)++;
+
+Outside of declarative contexts you may use C<*> for a placeholder:
+
+ ($a, *, $c) = 1..3;
+
+=item *
+
+Ordinary package-qualified names look like in Perl 5:
+
+ $Foo::Bar::baz # the $baz variable in package Foo::Bar
+
+Sometimes it's clearer to keep the sigil with the variable name, so an
+alternate way to write this is:
+
+ Foo::Bar::<$baz>
+
+This is resolved at compile time because the variable name is a constant.
+
+=item *
+
+The following pseudo-package names are reserved in the first position:
+
+ MY # Lexical variables declared in the current scope
+ OUR # Package variables declared in the current package
+ GLOBAL # Builtin variables and functions
+ PROCESS # process-related globals
+ OUTER # Lexical variables declared in the outer scope
+ CALLER # Contextual variables in the immediate caller's scope
+ CONTEXT # Contextual variables in any context's scope
+ SUPER # Package variables declared in inherited classes
+ COMPILING # Lexical variables in the scope being compiled
+
+Other all-caps names are semi-reserved. We may add more of them in
+the future, so you can protect yourself from future collisions by using
+mixed case on your top-level packages. (We promise not to break
+any existing top-level CPAN package, of course. Except maybe ACME,
+and then only for coyotes.)
+
+=item *
+
+You may interpolate a string into a package or variable name using
+C<::($expr)> where you'd ordinarily put a package or variable name.
+The string is allowed to contain additional instances of C<::>, which
+will be interpreted as package nesting. You may only interpolate
+entire names, since the construct starts with C<::>, and either ends
+immediately or is continued with another C<::> outside the parens.
+Most symbolic references are done with this notation:
+
+ $foo = "Bar";
+ $foobar = "Foo::Bar";
+ $::($foo) # package-scoped $Bar
+ $::("MY::$foo") # lexically-scoped $Bar
+ $::("*::$foo") # global $Bar
+ $::($foobar) # $Foo::Bar
+ $::($foobar)::baz # $Foo::Bar::baz
+ $::($foo)::Bar::baz # $Bar::Bar::baz
+ $::($foobar)baz # ILLEGAL at compile time (no operator baz)
+
+Note that unlike in Perl 5, initial C<::> doesn't imply global.
+Package names are searched for from inner lexical scopes to outer,
+then from inner packages to outer. Variable names are searched
+for from inner lexical scopes to outer, but unlike package names
+are looked for in only the current package and the global package.
+
+The global namespace is the last place it looks in either case.
+You must use the C<*> (or C<GLOBAL>) package on the front of the
+string argument to force the search to start in the global namespace.
+
+Use the C<MY> pseudopackage to limit the lookup to the current lexical
+scope, and C<OUR> to limit the scopes to the current package scope.
+
+=item *
+
+When "strict" is in effect (which is the default except for one-liners),
+non-qualified variables (such as C<$x> and C<@y>) are only looked up from
+lexical scopes, but never from package scopes.
+
+To bind package variables into a lexical scope, simply say C<our ($x, @y)>.
+To bind global variables into a lexical scope, predeclare them with C<use>:
+
+ use GLOBAL <$IN $OUT>;
+
+Or just refer to them as C<$*IN> and C<$*OUT>.
+
+=item *
+
+To do direct lookup in a package's symbol table without scanning, treat
+the package name as a hash:
+
+ Foo::Bar::{'&baz'} # same as &Foo::Bar::baz
+ GLOBAL::<$IN> # Same as $*IN
+ Foo::<::Bar><::Baz> # same as Foo::Bar::Baz
+
+The C<::> before the subscript is required here, because the C<Foo::Bar{...}>
+syntax is reserved for defining an autovivifiable protoobject along with
+its initialization closure (see S12).
+
+Unlike C<::()> symbolic references, this does not parse the argument
+for C<::>, nor does it initiate a namespace scan from that initial
+point. In addition, for constant subscripts, it is guaranteed to
+resolve the symbol at compile time.
+
+The null pseudo-package is reserved to mean the same search list as an ordinary
+name search. That is, the following are all identical in meaning:
+
+ $foo
+ $::{'foo'}
+ ::{'$foo'}
+ $::<foo>
+ ::<$foo>
+
+That is, each of them scans lexical scopes outward, and then the current package scope
+(though the package scope is then disallowed when "strict" is in effect).
+
+As a result of these rules, you can write any arbitrary variable name as either of:
+
+ $::{'!@#$#@'}
+ ::{'$!@#$#@'}
+
+You can also use the C<< ::<> >> form as long as there are no spaces in the name.
+
+=item *
+
+The current lexical symbol table is now accessible through the
+pseudo-package C<MY>. The current package symbol table is visible as
+pseudo-package C<OUR>. The C<OUTER> name refers to the C<MY> symbol table
+immediately surrounding the current C<MY>, and C<OUTER::OUTER> is the one
+surrounding that one.
+
+ our $foo = 41;
+ say $::foo; # prints 41, :: is no-op
+ {
+ my $foo = 42;
+ say MY::<$foo>; # prints "42"
+ say $MY::foo; # same thing
+ say $::foo; # same thing, :: is no-op here
+
+ say OUR::<$foo>; # prints "41"
+ say $OUR::foo; # same thing
+
+ say OUTER::<$foo>; # prints "41" (our $foo is also lexical)
+ say $OUTER::foo; # same thing
+ }
+
+You may not use any lexically scoped symbol table, either by name or
+by reference, to add symbols to a lexical scope that is done compiling.
+(We reserve the right to relax this if it turns out to be useful though.)
+
+=item *
+
+The C<CALLER> package refers to the lexical scope of the (dynamically
+scoped) caller. The caller's lexical scope is allowed to hide any
+variable except C<$_> from you. In fact, that's the default, and a
+lexical variable must have the trait "C<is context>" to be
+visible via C<CALLER>. (C<$_>, C<$!> and C<$/> are always
+contextual.) If the variable is not visible in the caller, it returns
+failure. Variables whose names are visible at the point of the call but that
+come from outside that lexical scope are controlled by the scope
+in which they were originally declared.
+Hence the visibility of C<< CALLER::<$+foo> >> is determined where
+C<$+foo> is actually declared, not by the caller's scope. Likewise
+C<< CALLER::CALLER::<$x> >> depends only on the declaration of C<$x>
+visible in your caller's caller.
+
+Any lexical declared with the C<is context> trait is by default
+considered readonly outside the current lexical scope. You may
+add a trait argument of C<< <rw> >> to allow called routines to
+modify your value. C<$_>, C<$!>, and C<$/> are C<< context<rw> >>
+by default. In any event, your lexical scope can always access the
+variable as if it were an ordinary C<my>; the restriction on writing
+applies only to called subroutines.
+
+=item *
+
+The C<CONTEXT> pseudo-package is just like C<CALLER> except that
+it starts in the current dynamic scope and from there
+scans outward through all dynamic scopes until it finds a
+contextual variable of that name in that context's lexical scope.
+(Use of C<$+FOO> is equivalent to C<< CONTEXT::<$FOO> >> or C<< $CONTEXT::FOO >>.)
+If after scanning all the lexical scopes of each dynamic scope,
+there is no variable of that name, it looks in the C<*> package.
+If there is no variable in the C<*> package and the variable is
+a scalar, it then looks in C<%*ENV> for the identifier of the variable,
+that is, in the environment variables passed to program. If the
+value is not found there, it returns failure. Unlike C<CALLER>,
+C<CONTEXT> will see a contextual variable that is declared in
+the current scope, however it will not be writeable via C<CONTEXT> unless
+declared "C<< is context<rw> >>", even if the variable itself is
+modifiable in that scope. (If it is, you should just use the bare
+variable itself to modify it.) Note that C<$+_> will always see
+the C<$_> in the current scope, not the caller's scope. You may
+use C<< CALLER::<$+foo> >> to bypass a contextual definition of C<$foo>
+in your current context, such as to initialize it with the outer
+contextual value:
+
+ my $foo is context = CALLER::<$+foo>;
+
+The C<CONTEXT> package is only for internal overriding of contextual
+information, modelled on how environmental variables work among
+processes. Despite the fact that the C<CONTEXT> package reflects the
+current process's environment variables, at least where those are not
+hidden by lower-level declarations, the C<CONTEXT> package should not
+be considered isomorphic to the current set of environment variables.
+Subprocesses are passed only the global C<%*ENV> values. They do
+not see any lexical variables or their values, unless you copy those
+values into C<%*ENV> to change what subprocesses see:
+
+ temp %*ENV{LANG} = $+LANG; # may be modified by parent
+ system "greet";
+
+=item *
+
+There is no longer any special package hash such as C<%Foo::>. Just
+subscript the package object itself as a hash object, the key of which
+is the variable name, including any sigil. The package object can
+be derived from a type name by use of the C<::> postfix operator:
+
+ MyType::<$foo>
+ MyType.::.{'$foo'} # same thing with dots
+ MyType\ ::\ {'$foo'} # same thing with unspaces
+
+(Directly subscripting the type with either square brackets or curlies
+is reserved for various generic type-theoretic operations. In most other
+matters type names and package names are interchangeable.)
+
+Typeglobs are gone. Use binding (C<:=> or C<::=>) to do aliasing.
+Individual variable objects are still accessible through the
+hash representing each symbol table, but you have to include the
+sigil in the variable name now: C<MyPackage::{'$foo'}> or the
+equivalent C<< MyPackage::<$foo> >>.
+
+=item *
+
+Truly global variables live in the C<*> package: C<$*UID>, C<%*ENV>.
+(The C<*> may be omitted if you import the name from the C<GLOBAL>
+package.) C<$*foo> is short for C<$*::foo>, suggesting that the
+variable is "wild carded" into every package.
+
+=item *
+
+For an ordinary Perl program running by itself, the C<GLOBAL> and
+C<PROCESS> namespaces are considered synonymous. However, in certain
+situations (such as shared hosting under a webserver), the actual
+process may contain multiple virtual processes, each running its own
+"main" code. In this case, the C<GLOBAL> namespace holds variables
+that properly belong to the individual virtual process, while the
+C<PROCESS> namespace holds variables that properly belong to the actual
+process as a whole. From the viewpoint of the C<GLOBAL> namespace
+there is little difference, since process variables that normally
+appear in C<GLOBAL> are automatically imported from C<PROCESS>.
+However, the process as a whole may place restrictions on the
+mutability of process variables as seen by the individual subprocesses.
+Also, individual subprocesses may not create new process variables.
+If the process wishes to grant subprocesses the ability to communicate
+via the C<PROCESS> namespace, it must supply a writeable variable
+to all the subprocesses granted that privilege.
+
+When these namespaces are so distinguished, the C<*> shortcut always refers
+to C<GLOBAL>. There is no twigil shortcut for C<PROCESS>.
+
+=item *
+
+Standard input is C<$*IN>, standard output is C<$*OUT>, and standard error
+is C<$*ERR>. The magic command-line input handle is C<$*ARGS>.
+The arguments themselves come in C<@*ARGS>. See also "Declaring a MAIN
+subroutine" in S06.
+
+=item *
+
+Magical file-scoped values live in variables with a C<=> secondary
+sigil. C<$=DATA> is the name of your C<DATA> filehandle, for instance.
+All pod structures are available through C<%=POD> (or some such).
+As with C<*>, the C<=> may also be used as a package name: C<$=::DATA>.
+
+=item *
+
+Magical lexically scoped values live in variables with a C<?> secondary
+sigil. These are all values that are known to the compiler, and may
+in fact be dynamically scoped within the compiler itself, and only
+appear to be lexically scoped because dynamic scopes of the compiler
+resolve to lexical scopes of the program. All C<$?> variables are considered
+constants, and may not be modified after being compiled in. The user
+is also allowed to define or (redefine) such constants:
+
+ constant $?TABSTOP = 4; # assume heredoc tabs mean 4 spaces
+
+(Note that the constant declarator always evaluates its initialization
+expression at compile time.)
+
+C<$?FILE> and C<$?LINE> are your current file and line number, for
+instance. C<?> is not a shortcut for a package name like C<*> is.
+Instead of C<$?OUTER::SUB> you probably want to write C<< OUTER::<$?SUB> >>.
+Within code that is being run during the compile, such as C<BEGIN> blocks, or
+macro bodies, or constant initializers, the compiler variables must be referred
+to as (for instance) C<< COMPILING::<$?LINE> >> if the bare C<$?LINE> would
+be taken to be the value during the compilation of the currently running
+code rather than the eventual code of the user's compilation unit. For
+instance, within a macro body C<$?LINE> is the line within the macro
+body, but C<< COMPILING::<$?LINE> >> is the line where the macro was invoked.
+See below for more about the C<COMPILING> pseudo package.
+
+Here are some possibilities:
+
+ $?FILE Which file am I in?
+ $?LINE Which line am I at?
+ $?PARSER Which Perl grammar was used to parse this statement?
+ $?LANG Which Perl parser should embedded closures parse with?
+ &?ROUTINE Which routine am I in?
+ @?ROUTINE Which nested routines am I in?
+ &?BLOCK Which block am I in?
+ @?BLOCK Which nested blocks am I in?
+ $?LABEL Which innermost block label am I in?
+ @?LABEL Which nested block labels am I in?
+
+All the nested C<@?> variables are ordered from the innermost to the
+outermost, so C<@?BLOCK[0]> is always the same as C<&?BLOCK>.
+
+The following return objects that contain all pertinent info:
+
+ $?OS Which operating system am I compiled for?
+ $?DISTRO Which OS distribution am I compiling under
+ $?VM Which virtual machine am I compiling under
+ $?XVM Which virtual machine am I cross-compiling for
+ $?PERL Which Perl am I compiled for?
+ $?PACKAGE Which package am I in?
+ @?PACKAGE Which nested packages am I in?
+ $?MODULE Which module am I in?
+ @?MODULE Which nested modules am I in?
+ $?CLASS Which class am I in? (as variable)
+ @?CLASS Which nested classes am I in?
+ $?ROLE Which role am I in? (as variable)
+ @?ROLE Which nested roles am I in?
+ $?GRAMMAR Which grammar am I in?
+ @?GRAMMAR Which nested grammars am I in?
+
+It is relatively easy to smartmatch these constant objects
+against pairs to check various attributes such as name,
+version, or authority:
+
+ given $?VM {
+ when :name<Parrot> :ver(v2) { ... }
+ when :name<CLOS> { ... }
+ when :name<SpiderMonkey> { ... }
+ when :name<JVM> :ver(v6.*) { ... }
+ }
+
+Matches of constant pairs on constant objects may all be resolved at
+compile time, so dead code can be eliminated by the optimizer.
+
+Note that some of these things have parallels in the C<*> space at run time:
+
+ $*OS Which OS I'm running under
+ $*DISTRO Which OS distribution I'm running under
+ $*VM Which VM I'm running under
+ $*PERL Which Perl I'm running under
+
+You should not assume that these will have the same value as their
+compile-time cousins.
+
+=item *
+
+While C<$?> variables are constant to the run time, the compiler
+has to have a way of changing these values at compile time without
+getting confused about its own C<$?> variables (which were frozen in
+when the compile-time code was itself compiled). The compiler can
+talk about these compiler-dynamic values using the C<COMPILING> pseudopackage.
+
+References to C<COMPILING> variables are automatically hoisted into the
+context currently being compiled. Setting or temporizing a C<COMPILING>
+variable sets or temporizes the incipient C<$?> variable in the
+surrounding lexical context that is being compiled. If nothing in
+the context is being compiled, an exception is thrown.
+
+ $?FOO // say "undefined"; # probably says undefined
+ BEGIN { COMPILING::<$?FOO> = 42 }
+ say $?FOO; # prints 42
+ {
+ say $?FOO; # prints 42
+ BEGIN { temp COMPILING::<$?FOO> = 43 } # temporizes to *compiling* block
+ say $?FOO; # prints 43
+ BEGIN { COMPILING::<$?FOO> = 44 }
+ say $?FOO; # prints 44
+ BEGIN { say COMPILING::<$?FOO> } # prints 44, but $?FOO probably undefined
+ }
+ say $?FOO; # prints 42 (left scope of temp above)
+ $?FOO = 45; # always an error
+ COMPILING::<$?FOO> = 45; # an error unless we are compiling something
+
+Note that C<< CALLER::<$?FOO> >> might discover the same variable
+as C<COMPILING::<$?FOO>>, but only if the compiling context is the
+immediate caller. Likewise C<< OUTER::<$?FOO> >> might or might not
+get you to the right place. In the abstract, C<COMPILING::<$?FOO>>
+goes outwards dynamically until it finds a compiling scope, and so is
+guaranteed to find the "right" C<$?FOO>. (In practice, the compiler
+hopefully keeps track of its current compiling scope anyway, so no
+scan is needed.)
+
+Perceptive readers will note that this subsumes various "compiler hints"
+proposals. Crazy readers will wonder whether this means you could
+set an initial value for other lexicals in the compiling scope. The
+answer is yes. In fact, this mechanism is probably used by the
+exporter to bind names into the importer's namespace.
+
+=item *
+
+The currently compiling Perl parser is switched by modifying
+C<< COMPILING::<$?PARSER> >>. Lexically scoped parser changes
+should temporize the modification. Changes from here to
+end-of-compilation unit can just assign or bind it. In general,
+most parser changes involve deriving a new grammar and then pointing
+C<< COMPILING::<$?PARSER> >> at that new grammar. Alternately, the
+tables driving the current parser can be modified without derivation,
+but at least one level of anonymous derivation must intervene from
+the standard Perl grammar, or you might be messing up someone else's
+grammar. Basically, the current grammar has to belong only to the
+current compiling scope. It may not be shared, at least not without
+explicit consent of all parties. No magical syntax at a distance.
+Consent of the governed, and all that.
+
+=item *
+
+It is often convenient to have names that contain arbitrary characters
+or other data structures. Typically these uses involve situations
+where a set of entities shares a common "short" name, but still needs
+for each of its elements to be identifiable individually. For
+example, you might use a module whose short name is C<ThatModule>,
+but the complete long name of a module includes its version, naming
+authority, and perhaps even its source language. Similarly,
+sets of operators work together in various syntactic categories
+with names like C<prefix>, C<infix>, C<postfix>, etc. The long
+names of these operators, however, often contain characters that
+are excluded from ordinary identifiers.
+
+For all such uses, an identifier followed by a subscript-like adverbial
+form (see below) is considered an I<extended identifier>:
+
+ infix:<+> # the official name of the operator in $a + $b
+ infix:<*> # the official name of the operator in $a * $b
+ infix:«<=» # the official name of the operator in $a <= $b
+ prefix:<+> # the official name of the operator in +$a
+ postfix:<--> # the official name of the operator in $a--
+
+This name is to be thought of semantically, not syntactically. That is,
+the bracketing characters used do not count as part of the name; only
+the quoted data matters. These are all the same name:
+
+ infix:<+>
+ infix:<<+>>
+ infix:«+»
+ infix:['+']
+
+Despite the appearance as a subscripting form, these names are resolved
+not at run time but at compile time. The pseudo-subscripts need not
+be simple scalars. These are extended with the same two-element list:
+
+ infix:<?? !!>
+ infix:['??','!!']
+
+An identifier may be extended with multiple named identifier
+extensions, in which case the names matter but their order does not.
+These name the same module:
+
+ use ThatModule:ver<2.7.18.28.18>:auth<Somebody>
+ use ThatModule:auth<Somebody>:ver<2.7.18.28.18>
+
+Adverbial syntax will be described more fully later.
+
+=back
+
+=head1 Literals
+
+=over 4
+
+=item *
+
+A single underscore is allowed only between any two digits in a
+literal number, where the definition of digit depends on the radix.
+Underscores are not allowed anywhere else in any numeric literal,
+including next to the radix point or exponentiator, or at the beginning
+or end.
+
+=item *
+
+Initial C<0> no longer indicates octal numbers by itself. You must use
+an explicit radix marker for that. Pre-defined radix prefixes include:
+
+ 0b base 2, digits 0..1
+ 0o base 8, digits 0..7
+ 0d base 10, digits 0..9
+ 0x base 16, digits 0..9,a..f (case insensitive)
+
+=item *
+
+The general radix form of a number involves prefixing with the radix
+in adverbial form:
+
+ :10<42> same as 0d42 or 42
+ :16<DEAD_BEEF> same as 0xDEADBEEF
+ :8<177777> same as 0o177777 (65535)
+ :2<1.1> same as 0b1.1 (0d1.5)
+
+Extra digits are assumed to be represented by C<a>..C<z> and C<A>..C<Z>, so you
+can go up to base 36. (Use C<A> and C<B> for base twelve, not C<T> and C<E>.)
+Alternately you can use a list of digits in decimal:
+
+ :60[12,34,56] # 12 * 3600 + 34 * 60 + 56
+ :100[3,'.',14,16] # pi
+
+Any radix may include a fractional part. A dot is never ambiguous
+because you have to tell it where the number ends:
+
+ :16<dead_beef.face> # fraction
+ :16<dead_beef>.face # method call
+
+=item *
+
+Only base 10 (in any form) allows an additional exponentiator starting
+with 'e' or 'E'. All other radixes must either rely on the constant folding
+properties of ordinary multiplication and exponentiation, or supply the
+equivalent two numbers as part of the string, which will be interpreted
+as they would outside the string, that is, as decimal numbers by default:
+
+ :16<dead_beef> * 16**8
+ :16<dead_beef*16**8>
+
+It's true that only radixes that define C<e> as a digit are ambiguous that
+way, but with any radix it's not clear whether the exponentiator should
+be 10 or the radix, and this makes it explicit:
+
+ 0b1.1e10 ILLEGAL, could be read as any of:
+
+ :2<1.1> * 2 ** 10 1536
+ :2<1.1> * 10 ** 10 15,000,000,000
+ :2<1.1> * :2<10> ** :2<10> 6
+
+So we write those as
+
+ :2<1.1*2**10> 1536
+ :2<1.1*10**10> 15,000,000,000
+ :2«1.1*:2<10>**:2<10>» 6
+
+The generic string-to-number converter will recognize all of these
+forms (including the * form, since constant folding is not available
+to the run time). Also allowed in strings are leading plus or minus,
+and maybe a trailing Units type for an implied scaling. Leading and
+trailing whitespace is ignored. Note also that leading C<0> by itself
+I<never> implies octal in Perl 6.
+
+Any of the adverbial forms may be used as a function:
+
+ :2($x) # "bin2num"
+ :8($x) # "oct2num"
+ :10($x) # "dec2num"
+ :16($x) # "hex2num"
+
+Think of these as setting the default radix, not forcing it. Like Perl
+5's old C<oct()> function, any of these will recognize a number starting
+with a different radix marker and switch to the other radix. However,
+note that the C<:16()> converter function will interpret leading C<0b>
+or C<0d> as hex digits, not radix switchers.
+
+=item *
+
+Characters indexed by hex numbers can be interpolated into strings
+by introducing with C<"\x">, followed by either a bare hex number
+(C<"\x263a">) or a hex number in square brackets (C<"\x[263a]">).
+Similarly, C<"\o12"> and C<"\o[12]"> interpolate octals--but generally
+you should be using hex in the world of Unicode. Multiple characters
+may be specified within any of the bracketed forms by separating the
+numbers with comma: C<"\x[41,42,43]">. You must use the bracketed
+form to disambiguate if the unbracketed form would "eat" too many
+characters, because all of the unbracketed forms eat as many characters
+as they think look like digits in the radix specified. None of these
+notations work in normal Perl code. They work only in interpolations
+and regexes and the like.
+
+The old C<\123> form is now illegal, as is the C<\0123> form.
+Only C<\0> remains, and then only if the next character is not in
+the range C<'0'..'7'>. Octal characters must use C<\o> notation.
+Note also that backreferences are no longer represented by C<\1>
+and the like--see S05.
+
+=item *
+
+The C<qw/foo bar/> quote operator now has a bracketed form: C<< <foo bar> >>.
+When used as a subscript it performs a slice equivalent to C<{'foo','bar'}>.
+Elsewhere it is equivalent to a parenthesisized list of strings:
+C<< ('foo','bar') >>. Since parentheses are generally reserved just for
+precedence grouping, they merely autointerpolate in list context. Therefore
+
+ @a = 1, < x y >, 2;
+
+is equivalent to:
+
+ @a = 1, ('x', 'y'), 2;
+
+which is the same as:
+
+ @a = 1, 'x', 'y', 2;
+
+In item context, though, the implied parentheses are not removed, so
+
+ $a = < a b >;
+
+is equivalent to:
+
+ $a = ('a', 'b');
+
+which, because the list is assigned to a scalar, is autopromoted into
+an Array object:
+
+ $a = ['a', 'b'];
+
+Likewise, if bound to a scalar parameter, C<< <a b> >> will be
+treated as a single list object, but if bound to a slurpy parameter,
+it will auto-flatten.
+
+But note that under the parenthesis-rewrite rule, a single value will
+still act like a scalar value. These are all the same:
+
+ $a = < a >;
+ $a = ('a');
+ $a = 'a';
+
+And if bound to a scalar parameter, no list is constructed.
+To force a single value to become a list object in item context,
+you should use C<< ['a'] >> for clarity as well as correctness.
+
+Much like the relationship between single quotes and double quotes, single
+angles do not interpolate while double angles do. The double angles may
+be written either with French quotes, C<«$foo @bar[]»>, or
+with "Texas" quotes, C<<< <<$foo @bar[]>> >>>, as the ASCII workaround.
+The implicit split is done after interpolation, but respects quotes
+in a shell-like fashion, so that C<«'$foo' "@bar[]"»> is guaranteed to
+produce a list of two "words" equivalent to C<< ('$foo', "@bar[]") >>.
+C<Pair> notation is also recognized inside C<«...»> and such "words" are
+returned as C<Pair> objects.
+
+Colon pairs (but not arrow pairs) are recognized within double angles.
+In addition, the double angles allow for comments beginning with C<#>.
+These comments work exactly like ordinary comments in Perl code.
+That is, C<#> at beginning of line is always a line-end comment,
+otherwise a following bracket sequence implies an inline comment;
+also, unlike in the shells, any literal C<#> must be quoted, even
+ones without whitespace in front of them, but note that this comes
+more or less for free with a colon pair like C<< :char<#x263a> >>.
+
+=item *
+
+There is now a generalized adverbial form of Pair notation. The
+following table shows the correspondence to the "fatarrow" notation:
+
+ Fat arrow Adverbial pair Paren form
+ ========= ============== ==========
+ a => 1 :a
+ a => 0 :!a
+ a => 0 :a(0)
+ a => $x :a($x)
+ a => 'foo' :a<foo> :a(<foo>)
+ a => <foo bar> :a<foo bar> :a(<foo bar>)
+ a => «$foo @bar» :a«$foo @bar» :a(«$foo @bar»)
+ a => {...} :a{...} :a({...})
+ a => [...] :a[...] :a([...])
+ a => $a :$a
+ a => @a :@a
+ a => %a :%a
+ a => $$a :$$a
+ a => @$$a :@$$a (etc.)
+ a => %foo<a> %foo<a>:p
+
+The fatarrow construct may be used only where a term is expected
+because it's considered an expression in its own right, since the
+fatarrow itself is parsed as a normal infix operator (even when
+autoquoting an identifier on its left). Because the left side is a
+general expression, the fatarrow form may be used to create a Pair
+with I<any> value as the key. On the other hand, when used as above
+to generate C<Pair> objects, the adverbial forms are restricted to
+the use of identifiers as keys. You must use the fatarrow form to
+generate a C<Pair> where the key is not an identifier.
+
+Despite that restriction, it's possible for other things to
+come between a colon and its brackets; however, all of the possible
+non-identifier adverbial keys are reserved for special syntactical
+forms. Perl 6 currently recognizes decimal numbers and the null key.
+In the following table the first and second columns do I<not> mean
+the same thing:
+
+ Simple pair DIFFERS from which means
+ =========== ============ ===========
+ 2 => <101010> :2<101010> radix literal 0b101010
+ 8 => <123> :8<123> radix literal 0o123
+ 16 => <deadbeef> :16<deadbeef> radix literal 0xdeadbeef
+ 16 => $somevalue :16($somevalue) radix conversion function
+ '' => $x :($x) arglist or signature literal
+ '' => ($x,$y) :($x,$y) arglist or signature literal
+ '' => <x> :<x> identifier extension
+ '' => «x» :«x» identifier extension
+ '' => [$x,$y] :[$x,$y] identifier extension
+ '' => { .say } :{ .say } adverbial block
+
+All of the adverbial forms (including the normal ones with
+identifier keys) are considered special tokens and are recognized
+in various positions in addition to term position. In particular,
+when used where an infix would be expected they modify the previous
+topmost operator that is tighter in precedence than "loose unary"
+(see S03):
+
+ 1 .. 100 :by(3) # count to 100 by threes
+
+Within declarations the adverbial form is used to rename parameter declarations:
+
+ sub foo ( :externalname($myname) ) {...}
+
+Adverbs modify the meaning of various quoting forms:
+
+ q:x 'cat /etc/passwd'
+
+When appended to an identifier (that is, in postfix position),
+the adverbial syntax is used to generate unique variants of that
+identifier; this syntax is used for naming operators such as C<<
+infix:<+> >> and multiply-dispatched grammatical rules such as
+C<statement_control:if>. When so used, the adverb is considered an
+integral part of the name, so C<< infix:<+> >> and C<< infix:<-> >>
+are two different operators. Likewise C<< prefix:<+> >> is different
+from C<< infix:<+> >>. (The notation also has the benefit of grouping
+distinct identifiers into easily accessible sets; this is how the
+standard Perl 6 grammar knows the current set of infix operators,
+for instance.)
+
+Either fatarrow or adverbial pair notation may be used to pass
+named arguments as terms to a function or method. After a call with
+parenthesized arguments, only the adverbial syntax may be used to pass
+additional arguments. This is typically used to pass an extra block:
+
+ find($directory) :{ when not /^\./ }
+
+This just naturally falls out from the preceding rules because the
+adverbial block is in operator position, so it modifies the "find
+operator". (Parens aren't considered an operator.)
+
+Note that (as usual) the C<{...}> form (either identifier-based
+or special) can indicate either a closure or a hash depending on
+the contents. It does I<not> always indicate a subscript despite
+being parsed as one. (The function to which it is passed can I<use>
+the value as a subscript if it chooses, however.)
+
+Note also that the C<< <a b> >> form is not a subscript and is
+therefore equivalent not to C<.{'a','b'}> but rather to C<('a','b')>.
+Bare C<< <a> >> turns into C<('a')> rather than C<('a',)>. (However,
+as with the other bracketed forms, the value may end up being used
+as a subscript depending on context.)
+
+Two or more adverbs can always be strung together without intervening
+punctuation anywhere a single adverb is acceptable. When used as
+named arguments in an argument list, you I<may> put comma between,
+because they're just ordinary named arguments to the function, and
+a fatarrow pair would work the same. However, this comma is allowed
+only when the first pair occurs where a term is expected. Where an
+infix operator is expected, the adverb is always taken as modifying
+the nearest preceding operator that is not hidden within parentheses,
+and if you string together multiple such pairs, you may not put commas
+between, since that would cause subsequent pairs to look like terms.
+(The fatarrow form is not allowed at all in operator position.)
+See S06 for the use of adverbs as named arguments.
+
+The negated form (C<:!a>) and the sigiled forms (C<:$a>, C<:@a>,
+C<:%a>) never take an argument and don't care what the next character
+is. They are considered complete. These forms require an identifier
+to serve as the key.
+
+For identifiers that take a numeric argument, it is allowed to
+abbreviate, for example, C<:sweet(16)> to C<:16sweet>. (This is
+distinguishable from the :16<deadbeef> form, which never has an
+alphabetic character following the number.) Only literal decimal
+numbers may be swapped this way.
+
+The other forms of adverb (including the bare C<:a> form) I<always>
+look for an immediate bracketed argument, and will slurp it up.
+If that's not intended, you must use whitespace between the adverb and
+the opening bracket. The syntax of individual adverbs is the same
+everywhere in Perl 6. There are no exceptions based on whether an
+argument is wanted or not. (There is a minor exception for quote and
+regex adverbs, which accept I<only> parentheses as their bracketing
+operator, and ignore other brackets, which must be placed in parens
+if desired. See "Paren form" in the table above.)
+
+Except as noted above, the parser always
+looks for the brackets. Despite not indicating a true subscript,
+the brackets are similarly parsed as postfix operators. As postfixes
+the brackets may be separated from their initial C<:foo> with either
+unspace or dot (or both), but nothing else.
+
+Regardless of syntax, adverbs used as named arguments (in either term
+or infix position) generally show up as optional named parameters to
+the function in question--even if the function is an operator or macro.
+The function in question neither knows nor cares how weird the original
+syntax was.
+
+=item *
+
+In addition to C<q> and C<qq>, there is now the base form C<Q> which does
+I<no> interpolation unless explicitly modified to do so. So C<q> is really
+short for C<Q:q> and C<qq> is short for C<Q:qq>. In fact, all quote-like
+forms derive from C<Q> with adverbs:
+
+ q// Q :q //
+ qq// Q :qq //
+ rx// Q :regex //
+ s/// Q :subst ///
+ tr/// Q :trans ///
+
+Adverbs such as C<:regex> change the language to be parsed by switching
+to a different parser. This can completely change the interpretation
+of any subsequent adverbs as well as the quoted material itself.
+
+ q:s// Q :q :scalar //
+ rx:s// Q :regex :sigspace //
+
+=item *
+
+Generalized quotes may now take adverbs:
+
+ Short Long Meaning
+ ===== ==== =======
+ :x :exec Execute as command and return results
+ :w :words Split result on words (no quote protection)
+ :ww :quotewords Split result on words (with quote protection)
+ :q :single Interpolate \\, \q and \' (or whatever)
+ :qq :double Interpolate with :s, :a, :h, :f, :c, :b
+ :s :scalar Interpolate $ vars
+ :a :array Interpolate @ vars
+ :h :hash Interpolate % vars
+ :f :function Interpolate & calls
+ :c :closure Interpolate {...} expressions
+ :b :backslash Interpolate \n, \t, etc. (implies :q at least)
+ :to :heredoc Parse result as heredoc terminator
+ :regex Parse as regex
+ :subst Parse as substitution
+ :trans Parse as transliteration
+ :code Quasiquoting
+
+You may omit the first colon by joining an initial C<Q>, C<q>, or C<qq> with
+a single short form adverb, which produces forms like:
+
+ qw /a b c/; # P5-esque qw// meaning q:w
+ Qc '...{$x}...'; # Q:c//, interpolate only closures
+ qqx/$cmd @args[]/ # equivalent to P5's qx//
+
+(Note that C<qx//> doesn't interpolate.)
+
+If you want to abbreviate further, just define a macro:
+
+ macro qx { 'qq:x ' } # equivalent to P5's qx//
+ macro qTO { 'qq:x:w:to ' } # qq:x:w:to//
+ macro quote:<❰ ❱> ($text) { quasi { $text.quoteharder } }
+
+All the uppercase adverbs are reserved for user-defined quotes.
+All Unicode delimiters above Latin-1 are reserved for user-defined quotes.
+
+=item *
+
+A consequence of the previous item is that we can now say:
+
+ %hash = qw:c/a b c d {@array} {%hash}/;
+
+or
+
+ %hash = qq:w/a b c d {@array} {%hash}/;
+
+to interpolate items into a C<qw>. Conveniently, arrays and hashes
+interpolate with only whitespace separators by default, so the subsequent
+split on whitespace still works out. (But the built-in C<«...»> quoter
+automatically does interpolation equivalent to C<qq:ww/.../>. The
+built-in C<< <...> >> is equivalent to C<q:w/.../>.)
+
+=item *
+
+Whitespace is allowed between the "q" and its adverb: C<q :w /.../>.
+
+=item *
+
+For these "q" forms the choice of delimiters has no influence on the
+semantics. That is, C<''>, C<"">, C<< <> >>, C<«»>, C<``>, C<()>,
+C<[]>, and C<{}> have no special significance when used in place of
+C<//> as delimiters. There may be whitespace before the
+opening delimiter. (Which is mandatory for parens because C<q()> is
+a subroutine call and C<q:w(0)> is an adverb with arguments). Other
+brackets may also require whitespace when they would be understood as
+an argument to an adverb in something like C<< q:z<foo>// >>.
+A colon may never be used as the delimiter since it will always be
+taken to mean another adverb regardless of what's in front of it.
+Nor may a C<#> character be used as the delimiter since it is always
+taken as whitespace (specifically, as a comment).
+
+=item *
+
+New quoting constructs may be declared as macros:
+
+ macro quote:<qX> (*%adverbs) {...}
+
+Note: macro adverbs are automatically evaluated at macro call time if
+the adverbs are included in the parse. If an adverb needs to affect
+the parsing of the quoted text of the macro, then an explicit named
+parameter may be passed on as a parameter to the C<is parsed> subrule,
+or used to select which subrule to invoke.
+
+=item *
+
+You may interpolate double-quotish text into a single-quoted string
+using the C<\qq[...]> construct. Other "q" forms also work, including
+user-defined ones, as long as they start with "q". Otherwise you'll
+just have to embed your construct inside a C<\qq[...]>.
+
+=item *
+
+Bare scalar variables always interpolate in double-quotish
+strings. Bare array, hash, and subroutine variables may I<never> be
+interpolated. However, any scalar, array, hash or subroutine variable may
+start an interpolation if it is followed by a sequence of one or more bracketed
+dereferencers: that is, any of:
+
+=over 4
+
+=item 1. An array subscript
+
+=item 2. A hash subscript
+
+=item 3. A set of parentheses indicating a function call
+
+=item 4. Any of 1 through 3 in their B<dot> form
+
+=item 5. A method call that includes argument parentheses
+
+=item 6. A sequence of one or more unparenthesized method call, followed by any of 1 through 5
+
+=back
+
+In other words, this is legal:
+
+ "Val = $a.ord.fmt('%x')\n"
+
+and is equivalent to
+
+ "Val = { $a.ord.fmt('%x') }\n"
+
+
+=item *
+
+In order to interpolate an entire array, it's necessary now to subscript
+with empty brackets:
+
+ print "The answers are @foo[]\n"
+
+Note that this fixes the spurious "C<@>" problem in double-quoted email addresses.
+
+As with Perl 5 array interpolation, the elements are separated by a space.
+(Except that a space is not added if the element already ends in some kind
+of whitespace. In particular, a list of pairs will interpolate with a
+tab between the key and value, and a newline after the pair.)
+
+=item *
+
+In order to interpolate an entire hash, it's necessary to subscript
+with empty braces or angles:
+
+ print "The associations are:\n%bar{}"
+ print "The associations are:\n%bar<>"
+
+Note that this avoids the spurious "C<%>" problem in double-quoted printf formats.
+
+By default, keys and values are separated by tab characters, and pairs
+are terminated by newlines. (This is almost never what you want, but
+if you want something polished, you can be more specific.)
+
+=item *
+
+In order to interpolate the result of a sub call, it's necessary to include
+both the sigil and parentheses:
+
+ print "The results are &baz().\n"
+
+The function is called in item context. (If it returns a list anyway,
+that list is interpolated as if it were an array in string context.)
+
+=item *
+
+In order to interpolate the result of a method call without arguments,
+it's necessary to include parentheses or extend the call with something
+ending in brackets:
+
+ print "The attribute is $obj.attr().\n"
+ print "The attribute is $obj.attr<Jan>.\n"
+
+The method is called in item context. (If it returns a list,
+that list is interpolated as if it were an array.)
+
+It is allowed to have a cascade of argumentless methods as long as
+the last one ends with parens:
+
+ print "The attribute is %obj.keys.sort.reverse().\n"
+
+(The cascade is basically counted as a single method call for the
+end-bracket rule.)
+
+=item *
+
+Multiple dereferencers may be stacked as long as each one ends in
+some kind of bracket:
+
+ print "The attribute is @baz[3](1,2,3){$xyz}<blurfl>.attr().\n"
+
+Note that the final period above is not taken as part of the expression since
+it doesn't introduce a bracketed dereferencer.
+
+=item *
+
+A bare closure also interpolates in double-quotish context. It may
+not be followed by any dereferencers, since you can always put them
+inside the closure. The expression inside is evaluated in string item
+context. You can force list context on the expression using
+the C<list> operator if necessary.
+
+The following means the same as the previous example.
+
+ print "The attribute is { @baz[3](1,2,3){$xyz}<blurfl>.attr }.\n"
+
+The final parens are unnecessary since we're providing "real" code in
+the curlies. If you need to have double quotes that don't interpolate
+curlies, you can explicitly remove the capability:
+
+ qq:c(0) "Here are { $two uninterpolated } curlies";
+
+or equivalently:
+
+ qq:!c "Here are { $two uninterpolated } curlies";
+
+Alternately, you can build up capabilities from single quote to tell
+it exactly what you I<do> want to interpolate:
+
+ q:s 'Here are { $two uninterpolated } curlies';
+
+=item *
+
+Secondary sigils (twigils) have no influence over whether the primary sigil
+interpolates. That is, if C<$a> interpolates, so do C<$^a>, C<$*a>,
+C<$=a>, C<$?a>, C<$.a>, etc. It only depends on the C<$>.
+
+=item *
+
+No other expressions interpolate. Use curlies.
+
+=item *
+
+A class method may not be directly interpolated. Use curlies:
+
+ print "The dog bark is {Dog.bark}.\n"
+
+=item *
+
+The old disambiguation syntax:
+
+ ${foo[$bar]}
+ ${foo}[$bar]
+
+is dead. Use closure curlies instead:
+
+ {$foo[$bar]}
+ {$foo}[$bar]
+
+(You may be detecting a trend here...)
+
+=item *
+
+To interpolate a topical method, use curlies: C<"{.bark}">.
+
+=item *
+
+To interpolate a function call without a sigil, use curlies: C<"{abs $var}">.
+
+=item *
+
+And so on.
+
+=item *
+
+Backslash sequences still interpolate, but there's no longer any C<\v>
+to mean I<vertical tab>, whatever that is... (C<\v> now matches vertical
+whitespace in a regex.) Literal character representations are:
+
+ \a BELL
+ \b BACKSPACE
+ \t TAB
+ \n LINE FEED
+ \f FORM FEED
+ \r CARRIAGE RETURN
+ \e ESCAPE
+
+=item *
+
+There's also no longer any C<\L>, C<\U>, C<\l>, C<\u>, or C<\Q>.
+Use curlies with the appropriate function instead: C<"{ucfirst $word}">.
+
+=item *
+
+You may interpolate any Unicode codepoint by name using C<\c> and
+square brackets:
+
+ "\c[NEGATED DOUBLE VERTICAL BAR DOUBLE RIGHT TURNSTILE]"
+
+Multiple codepoints constituting a single character may be interpolated
+with a single C<\c> by separating the names with comma:
+
+ "\c[LATIN CAPITAL LETTER A, COMBINING RING ABOVE]"
+
+Whether that is regarded as one character or two depends on the
+Unicode support level of the current lexical scope. It is also
+possible to interpolate multiple codepoints that do not resolve to
+a single character:
+
+ "\c[LATIN CAPITAL LETTER A, LATIN CAPITAL LETTER B]"
+
+[Note: none of the official Unicode character names contains comma.]
+
+You may also put one or more decimal numbers inside the square brackets:
+
+ "\c[13,10]" # CRLF
+
+Any single decimal number may omit the brackets:
+
+ "\c8" # backspace
+
+(Within a regex you may also use C<\C> to match a character that is
+not the specified character.)
+
+If the character following C<\c> or C<\C> is neither a left square bracket
+nor a decimal digit,
+the single following character is turned into a control character by
+the usual trick of XORing the 64 bit. This allows C<\c@> for NULL
+and C<\c?> for DELETE, but note that the ESCAPE character may not be
+represented that way; it must be represented something like:
+
+ \e
+ \c[ESCAPE]
+ \c27
+ \x1B
+ \o33
+
+Obviously C<\e> is preferred when brevity is needed.
+
+=item *
+
+Any character that I<would> start an interpolation in the current
+quote context may be protected from such interpolation by prefixing with
+backslash. The backslash is always removed in this case.
+
+The treatment of backslashed characters that would I<not> have
+introduced an interpolation varies depending on the type of quote:
+
+=over 4
+
+=item 1.
+
+Any quoting form that includes C<qq> or C<:qq> in its semantic
+derivation (including the normal double quote form) assumes that all
+backslashes are to be considered meaningful. The meaning depends
+on whether the following character is alphanumeric; if it is, the
+non-interpolating sequence produces a compile-time error. If the
+character is non-alphanumeric, the backslash is silently removed, on
+the assumption that the string was backslashed using C<quotemeta()>
+or some such.
+
+=item 2.
+
+All other quoting forms (including standard single quotes)
+assume that non-interpolating sequences are to be left unaltered
+because they are probably intended to pass through to the result.
+Backslashes are removed I<only> for the terminating quote or for
+characters that would interpolate if unbackslashed. (In either case,
+a special exception is made for brackets; if the left bracket would
+interpolate, the right bracket may optionally also be backslashed,
+and if so, the backslash will be removed. If brackets are used as
+the delimiters, both left and right C<must> be backslashed the same,
+since they would otherwise be counted wrong in the bracket count.)
+
+=back
+
+As a consequence, these all produce the same literal string:
+
+ " \{ this is not a closure } "
+ " \{ this is not a closure \} "
+ q:c / \{ this is not a closure } /
+ q:c / \{ this is not a closure \} /
+ q:c { \{ this is not a closure \} }
+ q { { this is not a closure } }
+ q { \{ this is not a closure \} }
+
+(Of course, matching backslashes is likely to make your syntax
+highlighter a bit happier, along with any other naïve bracket
+counting algorithms...)
+
+=item *
+
+There are no barewords in Perl 6. An undeclared bare identifier will
+always be taken to mean a subroutine name. (Class names
+(and other type names) are predeclared, or prefixed with the C<::>
+type sigil when you're declaring a new one.) A consequence of this
+is that there's no longer any "C<use strict 'subs'>". Since the syntax
+for method calls is distinguished from sub calls, it is only unrecognized
+sub calls that must be treated specially.
+
+You still must declare your subroutines, but a bareword with an unrecognized
+name is provisionally compiled as a subroutine call, on that assumption that
+such a declaration will occur by the end of the current compilation unit:
+
+ foo; # provisional call if neither &foo nor ::foo is defined so far
+ foo(); # provisional call if &foo is not defined so far
+ foo($x); # provisional call if &foo is not defined so far
+ foo($x, $y); # provisional call if &foo is not defined so far
+
+ $x.foo; # not a provisional call; it's a method call on $x
+ foo $x:; # not a provisional call; it's a method call on $x
+ foo $x: $y; # not a provisional call; it's a method call on $x
+
+If a postdeclaration is not seen, the compile fails at C<CHECK> time.
+(You are still free to predeclare subroutines explicitly, of course.)
+The postdeclaration may be in any lexical or package scope that
+could have made the declaration visible to the provisional call had the
+declaration occurred before rather than after the provisional
+call.
+
+This fixup is done only for provisional calls. If there
+is I<any> real predeclaration visible, it always takes precedence.
+In case of multiple ambiguous postdeclarations, either they must all
+be multis, or a compile-time error is declared and you must predeclare,
+even if one postdeclaration is obviously "closer". A single
+C<proto> predeclaration may make all postdeclared C<multi> work fine,
+since that's a run-time dispatch, and all multis are effectively
+visible at the point of the controlling C<proto> declaration.
+
+Parsing of a bareword function as a provisional call is always done
+the same way list operators are treated. If a postdeclaration
+bends the syntax to be inconsistent with that, it is an error of
+the inconsistent signature variety.
+
+If the unrecognized subroutine name is followed by C<< postcircumfix:<( )> >>,
+it is compiled as a provisional function call of the parenthesized form.
+If it is not, it is compiled as a provisional function call of
+the list operator form, which may or may not have an argument list.
+When in doubt, the attempt is made to parse an argument list. As with
+any list operator, an immediate postfix operator is illegal unless it is a
+form of parentheses, whereas anything following whitespace will be interpreted
+as an argument list if possible.
+
+Based on the signature of the subroutine declaration, there are only
+four ways that an argument list can be parsed:
+
+ Signature # of expected args
+ () 0
+ ($x) 1
+ ($x?) 0..1
+ (anything else) 0..Inf
+
+That is, a standard subroutine call may be parsed only as a 0-arg term
+(or function call), a 1-mandatory-arg prefix operator (or function
+call), a 1-optional-arg term or prefix operator (or function call), or
+an "infinite-arg" list operator (or function call). A given signature
+might only accept 2 arguments, but the only number distinctions the
+parser is allowed to make is between void, singular and plural;
+checking that number of arguments supplied matches some number
+larger than one must be done as a separate semantic constraint, not
+as a syntactic constraint. Perl functions never take N arguments
+off of a list and leave the rest for someone else, except for small
+values of N, where small is defined as not more than 1. You can get
+fancier using macros, but macros I<always> require predeclaration.
+Since the non-infinite-list forms are essentially behaving as macros,
+those forms also require predeclaration. Only the infinite-list form
+may be postdeclared (and hence used provisionally).
+
+It is illegal for a provisional subroutine call to be followed by a
+colon postfix, since such a colon is allowed only on an indirect object,
+or a method call in dot form. (It is also allowed on a label when a
+statement is expected.) So for any undeclared identifier "C<foo>":
+
+ foo.bar # ILLEGAL -- postfix must use foo().bar
+ foo .bar # foo($_.bar) -- no postfix starts with whitespace
+ foo\ .bar # ILLEGAL -- must use foo()\ .bar
+ foo++ # ILLEGAL -- postfix must use foo()++
+ foo 1,2,3 # foo(1,2,3) -- args always expected after listop
+ foo + 1 # foo(+1) -- term always expected after listop
+ foo; # foo(); -- no postfix, but no args either
+ foo: # label -- must be label at statement boundary.
+ -- ILLEGAL otherwise
+ foo: bar: # two labels in a row, okay
+ .foo: # $_.foo: 1 -- must be "dot" method with : args
+ .foo(1) # $_.foo(1) -- must be "dot" method with () args
+ .foo # $_.foo() -- must be "dot" method with no args
+ .$foo: # $_.$foo: 1 -- indirect "dot" method with : args
+ foo bar: 1 # bar.foo(1) -- bar must be predecl as class
+ -- sub bar allowed here only if 0-ary
+ -- otherwise you must say (bar):
+ foo bar 1 # foo(bar(1)) -- both subject to postdeclaration
+ -- never taken as indirect object
+ foo $bar: 1 # $bar.foo(1) -- indirect object even if declared sub
+ -- $bar considered one token
+ foo (bar()): # bar().foo(1) -- even if foo declared sub
+ foo bar(): # ILLEGAL -- bar() is two tokens.
+ foo .bar: # foo(.bar:) -- colon chooses .bar to listopify
+ foo bar baz: 1 # foo(baz.bar(1)) -- colon controls "bar", not foo.
+ foo (bar baz): 1 # bar(baz()).foo(1) -- colon controls "foo"
+ $foo $bar # ILLEGAL -- two terms in a row
+ $foo $bar: # ILLEGAL -- use $bar.$foo for indirection
+ (foo bar) baz: 1 # ILLEGAL -- use $baz.$(foo bar) for indirection
+
+The indirect object colon only ever dominates a simple term, where
+"simple" includes classes and variables and parenthesized expressions,
+but explicitly not method calls, because the colon will bind to a
+trailing method call in preference. An indirect object that parses as
+more than one token must be placed in parentheses, followed by the colon.
+
+In short, only an identifier followed by a simple term followed by a
+postfix colon is C<ever> parsed as an indirect object, but that form
+will C<always> be parsed as an indirect object regardless of whether
+the identifier is otherwise declared.
+
+=item *
+
+There's also no "C<use strict 'refs'>" because symbolic dereferences
+are now syntactically distinguished from hard dereferences.
+C<@($arrayref)> must now provide an actual array object, while
+C<@::($string)> is explicitly a symbolic reference. (Yes, this may
+give fits to the P5-to-P6 translator, but I think it's worth it to
+separate the concepts. Perhaps the symbolic ref form will admit real
+objects in a pinch.)
+
+=item *
+
+There is no hash subscript autoquoting in Perl 6. Use C<< %x<foo> >>
+for constant hash subscripts, or the old standby C<< %x{'foo'} >>. (It
+also works to say C<%x«foo»> as long as you realized it's subject to
+interpolation.)
+
+But C<< => >> still autoquotes any bare identifier to its immediate
+left (horizontal whitespace allowed but not comments). The identifier is not
+subject to keyword or even macro interpretation. If you say
+
+ $x = do {
+ call_something();
+ if => 1;
+ }
+
+then C<$x> ends up containing the pair C<< ("if" => 1) >>. Always.
+(Unlike in Perl 5, where version numbers didn't autoquote.)
+
+You can also use the :key($value) form to quote the keys of option
+pairs. To align values of option pairs, you may use the
+"unspace" postfix forms:
+
+ :longkey\ ($value)
+ :shortkey\ <string>
+ :fookey\ { $^a <=> $^b }
+
+These will be interpreted as
+
+ :longkey($value)
+ :shortkey<string>
+ :fookey{ $^a <=> $^b }
+
+=item *
+
+The double-underscore forms are going away:
+
+ Old New
+ --- ---
+ __LINE__ $?LINE
+ __FILE__ $?FILE
+ __PACKAGE__ $?PACKAGE
+ __END__ =begin END
+ __DATA__ =begin DATA
+
+The C<=begin END> pod stream is special in that it assumes there's
+no corresponding C<=end END> before end of file. The C<DATA>
+stream is no longer special--any POD stream in the current file
+can be accessed via a filehandle, named as C<< %=POD{'DATA'} >> and such.
+Alternately, you can treat a pod stream as a scalar via C<$=DATA>
+or as an array via C<@=DATA>. Presumably a module could read all
+its COMMENT blocks from C<@=COMMENT>, for instance. Each chunk of
+pod comes as a separate array element. You have to split it into lines
+yourself. Each chunk has a C<.range> property that indicates its
+line number range within the source file.
+
+The lexical routine itself is C<&?ROUTINE>; you can get its name with
+C<&?ROUTINE.name>. The current block is C<&?BLOCK>. If the block has any
+labels, those shows up in C<&?BLOCK.labels>. Within the lexical scope of
+a statement with a label, the label is a pseudo-object representing
+the dynamic context of that statement. (If inside multiple dynamic
+instances of that statement, the label represents the innermost one.)
+When you say:
+
+ next LINE;
+
+it is really a method on this pseudo-object, and
+
+ LINE.next;
+
+would work just as well. You can exit any labeled block early by saying
+
+ MyLabel.leave(@results);
+
+=item *
+
+Heredocs are no longer written with C<<< << >>>, but with an adverb on
+any other quote construct:
+
+ print qq:to/END/;
+ Give $amount to the man behind curtain number $curtain.
+ END
+
+Other adverbs are also allowed, as are multiple heredocs within the same
+expression:
+
+ print q:c:to/END/, q:to/END/;
+ Give $100 to the man behind curtain number {$curtain}.
+ END
+ Here is a $non-interpolated string
+ END
+
+=item *
+
+Heredocs allow optional whitespace both before and after terminating
+delimiter. Leading whitespace equivalent to the indentation of the
+delimiter will be removed from all preceding lines. If a line is
+deemed to have less whitespace than the terminator, only whitespace
+is removed, and a warning may be issued. (Hard tabs will be assumed
+to be C<< ($?TABSTOP // 8) >> spaces, but as long as tabs and spaces are used consistently
+that doesn't matter.) A null terminating delimiter terminates on
+the next line consisting only of whitespace, but such a terminator
+will be assumed to have no indentation. (That is, it's assumed to
+match at the beginning of any whitespace.)
+
+=item *
+
+There are two possible ways to parse heredocs. One is to look ahead
+for the newline and grab the lines corresponding to the heredoc, and
+then parse the rest of the original line. This is how Perl 5 does it.
+Unfortunately this suffers from the problem pervasive in Perl 5 of
+multi-pass parsing, which is masked somewhat because there's no way
+to hide a newline in Perl 5. In Perl 6, however, we can use "unspace"
+to hide a newline, which means that an algorithm looking ahead to find
+the newline must do a full parse (with possible untoward side effects)
+in order to locate the newline.
+
+Instead, Perl 6 takes the one-pass approach, and just lazily queues
+up the heredocs it finds in a line, and waits until it sees a "real"
+newline to look for the text and attach it to the appropriate heredoc.
+The downside of this approach is a slight restriction--you may not use
+the actual text of the heredoc in code that must run before the line
+finishes parsing. Mostly that just means you can't write:
+
+ BEGIN { say q:to/END/ }
+ Say me!
+ END
+
+You must instead put the entire heredoc into the C<BEGIN>:
+
+ BEGIN {
+ say q:to/END/;
+ Say me!
+ END
+ }
+
+=item *
+
+A version literal is written with a 'v' followed by the version
+number in dotted form. This always constructs a C<Version> object,
+not a string. Only integers and certain wildcards are allowed;
+for anything fancier you must coerce a string to a C<Version>:
+
+ v1.2.3 # okay
+ v1.2.* # okay, wildcard version
+ v1.2.3+ # okay, wildcard version
+ v1.2.3beta # illegal
+ Version('1.2.3beta') # okay
+
+Note though that most places that take a version number in Perl accept
+it as a named argument, in which case saying C<< :ver<1.2.3beta> >> is fine.
+See S11 for more on using versioned modules.
+
+Version objects have a predefined sort order that follows most people's
+intuition about versioning: each sorting position sorts numerically
+between numbers, alphabetically between alphas, and alphabetics in a
+position before numerics. Missing final positions are assumed to be '.0'.
+Except for '0' itself, numbers ignore leading zeros. For splitting
+into sort positions, if any alphabetics (including underscore) are
+immediately adjacent to a number, a dot is assumed between them.
+Likewise any non-alphanumeric character is assumed to be equivalent
+to a dot. So these are all equivalent:
+
+ 1.2.1alpha1.0
+ 1.2.1alpha1
+ 1.2.1.alpha1
+ 1.2.1alpha.1
+ 1.2.1.alpha.1
+ 1.2-1+alpha/1
+
+And these are also equivalent:
+
+ 1.2.1_01
+ 1.2.1_1
+ 1.2.1._1
+ 1.2.1_1
+ 1.2.1._.1
+ 001.0002.0000000001._.00000000001
+ 1.2.1._.1.0.0.0.0.0
+
+So these are in sorted version order:
+
+ 1.2.0.999
+ 1.2.1_01
+ 1.2.1_2
+ 1.2.1_003
+ 1.2.1a1
+ 1.2.1.alpha1
+ 1.2.1b1
+ 1.2.1.beta1
+ 1.2.1.gamma
+ 1.2.1α1
+ 1.2.1β1
+ 1.2.1γ
+ 1.2.1
+
+Note how the last pair assume that an implicit .0 sorts after anything
+alphabetic, and that alphabetic is defined according to Unicode, not just
+according to ASCII. The intent of all this is to make sure that prereleases
+sort before releases. Note also that this is still a subset of the
+versioning schemes seen in the real world. Modules with such strange
+versions can still be used by Perl since by default Perl imports
+external modules by exact version number. (See S11.) Only range
+operations will be compromised by an unknown foreign collation order,
+such as a system that sorts "delta" after "gamma".
+
+=back
+
+=head1 Context
+
+=over 4
+
+=item *
+
+Perl still has the three main contexts: void, item (scalar), and list.
+
+=item *
+
+In addition to undifferentiated items, we also have these item contexts:
+
+ Context Type OOtype Operator
+ ------- ---- ------ --------
+ boolean bit Bit ?
+ integer int Int int
+ numeric num Num +
+ string buf Str ~
+
+There are also various container contexts that require particular kinds of
+containers (such as slice and hash context; see S03 for details).
+
+=item *
+
+Unlike in Perl 5, objects are no longer always considered true.
+It depends on the state of their C<.true> property. Classes get to decide
+which of their values are true and which are false. Individual objects
+can override the class definition:
+
+ return 0 but True;
+
+=item *
+
+The definition of C<.true> for the most ancestral type (that is, the
+C<Object> type) is equivalent to C<.defined>. Since protoobjects are
+considered undefined, all protoobjects (including C<Object> itself)
+are false unless the type overrides the definition of C<.true>
+to include undefined values. Instantiated objects default to true
+unless the class overrides the definition. Note that if you could
+instantiate an C<Object> it would be considered defined, and thus true.
+(It is not clear that this is allowed, however.)
+
+=item *
+
+In general any container types should return false if they are empty,
+and true otherwise. This is true of all the standard container types
+except Scalar, which always defers the definition of truth to its
+contents. Non-container types define truthiness much as Perl 5 does.
+
+Just as with the standard types, user-defined types should feel free
+to partition their defined values into true and false values if such
+a partition makes sense in control flow using boolean contexts, since
+the separate C<.defined> method is always there if you need it.
+
+=back
+
+=head1 Lists
+
+=over 4
+
+=item *
+
+List context in Perl 6 is by default lazy. This means a list can
+contain infinite generators without blowing up. No flattening happens
+to a lazy list until it is bound to the signature of a function or
+method at call time (and maybe not even then). We say that such
+an argument list is "lazily flattened", meaning that we promise to
+flatten the list on demand, but not before.
+
+=item *
+
+There is a "C<list>" operator which imposes a list context on
+its arguments even if C<list> itself occurs in a item context.
+In list context, it flattens lazily. In an item context, it returns
+the resulting list as a single C<List> object. (So the C<list> operator
+really does exactly the same thing as putting a list in parentheses with
+at least one comma. But it's more readable in some situations.)
+
+To force a non-flattening item context, use the "C<item>" operator.
+
+=item *
+
+When evaluating chained operators, if an C<each()> occurs anywhere in that
+chain, the chain will be transformed first into a C<grep>. That is,
+
+ for 0 <= each(@x) < all(@y) {...}
+
+becomes
+
+ for @x.grep:{ 0 <= $_ < all(@y) } {...}
+
+Because of this, the original ordering C<@x> is guaranteed to be
+preserved in the returned list, and duplicate elements in C<@x> are
+preserved as well. In particular,
+
+ @result = each(@x) ~~ {...};
+
+is equivalent to
+
+ @result = @x.grep:{...};
+
+However, this I<each() comprehension> is strictly a syntactic transformation,
+so a list computed any other way will not trigger the rewrite:
+
+ @result = (@x = each(@y)) ~~ {...}; # not a comprehension
+
+=item *
+
+The C<|> prefix operator may be used to force "capture" context on its
+argument and I<also> defeat any scalar argument checking imposed by
+subroutine signature declarations. Any resulting list arguments are
+then evaluated lazily.
+
+=item *
+
+To force non-lazy list flattening, use the C<eager> list operator.
+Don't use it on an infinite list unless you have a machine with
+infinite memory, and are willing to wait a long time. To expand an
+iterator object to completion, iterate it with C<< prefix:<=> >>
+inside an eager list:
+
+ @lines = eager =$filehandle; # read all remaining lines
+
+By contrast,
+
+ @lines = =$filehandle;
+
+makes no guarantee about how many lines ahead the iterator has read.
+Iterators appending to a list are allowed to process in batches, even
+when stored within an array. The array knows that it is extensible,
+and calls the iterator as it needs more elements. (Counting the elements
+in the array will also force eager completion.)
+
+=item *
+
+A variant of C<eager> is the C<hyper> list operator, which declares
+not only that you want all the values generated now, but that you want
+them badly enough that you don't care what order they're generated in.
+That is, C<eager> requires sequential evaluation of the list, while
+C<hyper> requests (but does not require) parallel evaluation. In any
+case, it declares that you don't care about the evaluation order.
+(Conjecture: populating a hash from a hyper list of pairs could be done
+as the results come in, such that some keys can be seen even before
+the hyper is done. Thinking about Map-Reduce algorithms here...)
+
+=item *
+
+Signatures on non-multi subs can be checked at compile time, whereas
+multi sub and method call signatures can only be checked at run time
+(in the absence of special instructions to the optimizer).
+
+This is not a problem for arguments that are arrays or hashes,
+since they don't have to care about their context, but just return
+themselves in any event, which may or may not be lazily flattened.
+
+However, function calls in the argument list can't know their eventual
+context because the method hasn't been dispatched yet, so we don't
+know which signature to check against. As in Perl 5, list context
+is assumed unless you explicitly qualify the argument with an item
+context operator.
+
+=item *
+
+The C<< => >> operator now constructs C<Pair> objects rather than merely
+functioning as a comma. Both sides are in item context.
+
+=item *
+
+The C<< .. >> operator now constructs C<Range> objects rather than merely
+functioning as an operator. Both sides are in item context.
+
+=item *
+
+There is no such thing as a hash list context. Assignment to a hash
+produces an ordinary list context. You may assign alternating keys
+and values just as in Perl 5. You may also assign lists of C<Pair> objects, in
+which case each pair provides a key and a value. You may, in fact,
+mix the two forms, as long as the pairs come when a key is expected.
+If you wish to supply a C<Pair> as a key, you must compose an outer C<Pair>
+in which the key is the inner C<Pair>:
+
+ %hash = (($keykey => $keyval) => $value);
+
+=item *
+
+The anonymous C<enum> function takes a list of keys or pairs, and adds
+values to any keys that are not already part of a key. The value added
+is one more than the previous key or pair's value. This works nicely with
+the new C<qq:ww> form:
+
+ %hash = enum <<:Mon(1) Tue Wed Thu Fri Sat Sun>>;
+ %hash = enum « :Mon(1) Tue Wed Thu Fri Sat Sun »;
+
+are the same as:
+
+ %hash = ();
+ %hash<Mon Tue Wed Thu Fri Sat Sun> = 1..7;
+
+=item *
+
+In contrast to assignment, binding to a hash requires a C<Hash> (or
+C<Pair>) object. Binding to a "splat" hash requires a list of pairs
+or hashes, and stops processing the argument list when it runs out
+of pairs or hashes. See S06 for much more about parameter binding.
+
+=back
+
+=head1 Files
+
+=over 4
+
+=item *
+
+Filename globs are no longer done with angle brackets. Use the C<glob>
+function.
+
+=item *
+
+Input from a filehandle is no longer done with angle brackets. Instead
+of
+
+ while (<HANDLE>) {...}
+
+you now write
+
+ for =$handle {...}
+
+As a unary prefix operator, you may also apply adverbs to C<=>:
+
+ for =$handle :prompt('$ ') { say $_ + 1 }
+
+or
+
+ for =($handle):prompt('$ ') { say $_ + 1 }
+
+or you may even write it in its functional form, passing the adverbs
+as ordinary named arguments.
+
+ for prefix:<=>($handle, :prompt('$ ')) { say $_ + 1 }
+
+=back
+
+=head1 Properties
+
+=over 4
+
+=item *
+
+Properties work as detailed in S12. They're actually object
+attributes provided by role mixins. Compile-time properties applied
+to containers and such still use the C<is> keyword, but are now called
+"traits". On the other hand, run-time properties are attached to
+individual objects using the C<but> keyword instead, but are still
+called "properties".
+
+=item *
+
+Properties are accessed just like attributes because they are in fact
+attributes of some class or other, even if it's an anonymous singleton
+class generated on the fly for that purpose. Since "C<rw>" attributes
+behave in all respects as variables, properties may therefore also
+be temporized with C<temp>, or hypotheticalized with C<let>.
+
+=back
+
+=head1 Grammatical Categories
+
+Lexing in Perl 6 is controlled by a system of grammatical categories.
+At each point in the parse, the lexer knows which subset of the
+grammatical categories are possible at that point, and follows the
+longest-token rule across all the active grammatical categories.
+The grammatical categories that are active at any point are specified
+using a regex construct involving a set of magical hashes. For example,
+the matcher for the beginning of a statement might look like:
+
+ <%statement_control
+ | %scope_declarator
+ | %prefix
+ | %prefix_circumfix_meta_operator
+ | %circumfix
+ | %quote
+ | %term
+ >
+
+(Ordering of grammatical categories within such a construct matters
+only in case of a "tie", in which case the grammatical category that
+is notionally "first" wins. For instance, given the example above, a
+statement_control is always going to win out over a prefix operator of
+the same name. And the reason you can't call a function named "if"
+directly as a list operator is because it would be hidden either by
+the statement_control category at the beginning of a statement or by
+the statement_modifier category elsewhere in the statement. Only the
+C<if(...)> form unambiguously calls an "if" function, and even that
+works only because statement controls and statement modifiers require
+subsequent whitespace, as do list operators.)
+
+Here are the current grammatical categories:
+
+ category:<prefix> prefix:<+>
+ circumfix:<[ ]> [ @x ]
+ dotty:<.=> $obj.=method
+ infix_circumfix_meta_operator:{'»','«'} @a »+« @b
+ infix_postfix_meta_operator:<=> $x += 2;
+ infix_prefix_meta_operator:<!> $x !~~ 2;
+ infix:<+> $x + $y
+ package_declarator:<role> role Foo;
+ postcircumfix:<[ ]> $x[$y] or $x.[$y]
+ postfix_prefix_meta_operator:{'»'} @array »++
+ postfix:<++> $x++
+ prefix_circumfix_meta_operator:{'[',']'} [*]
+ prefix_postfix_meta_operator:{'«'} -« @magnitudes
+ prefix:<!> !$x (and $x.'!')
+ q_backslash:<\\> '\\'
+ qq_backslash:<n> "\n"
+ quote_mod:<x> q:x/ ls /
+ quote:<qq> qq/foo/
+ regex_assertion:<!> /<!before \h>/
+ regex_backslash:<w> /\w/ and /\W/
+ regex_metachar:<.> /.*/
+ regex_mod_internal:<P5> m:/ ... :P5 ... /
+ routine_declarator:<sub> sub foo {...}
+ scope_declarator:<has> has $.x;
+ sigil:<%> %hash
+ special_variable:<$!> $!
+ statement_control:<if> if $condition { 1 } else { 2 }
+ statement_mod_cond:<if> .say if $condition
+ statement_mod_loop:<for> .say for 1..10
+ statement_prefix:<gather> gather for @foo { .take }
+ term:<!!!> $x = { !!! }
+ trait_auxiliary:<does> my $x does Freezable
+ trait_verb:<handles> has $.tail handles <wag>
+ twigil:<?> $?LINE
+ type_declarator:<subset> subset Nybble of Int where ^16
+ version:<v> v4.3.*
+
+Any category containing "circumfix" requires two token arguments, supplied
+in slice notation. Note that many of these names do not represent real
+operators, and you wouldn't be able to call them even though you can name
+them.
+
+=for vim:set expandtab sw=4:
Added: docs/Perl6/Spec/S06.pod
===================================================================
--- docs/Perl6/Spec/S06.pod (rev 0)
+++ docs/Perl6/Spec/S06.pod 2008-11-26 22:33:46 UTC (rev 24064)
@@ -0,0 +1,2863 @@
+=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: 21 Nov 2008
+ Number: 6
+ Version: 97
+
+
+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 kind or class.
+
+B<Submethods> (keyword: C<submethod>) are non-inheritable methods, or
+subroutines masquerading as methods. They have an invocant and belong to
+a particular kind or class.
+
+B<Regexes> (keyword: C<regex>) are methods (of a grammar) that perform
+pattern matching. Their associated block has a special syntax (see
+Synopsis 5). (We also use the term "regex" for anonymous patterns
+of the traditional form.)
+
+B<Tokens> (keyword: C<token>) are regexes that perform low-level
+non-backtracking (by default) pattern matching.
+
+B<Rules> (keyword: C<rule>) are regexes that perform non-backtracking
+(by default) pattern matching (and also enable rules to do whitespace
+dwimmery).
+
+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.
+
+=head1 Routine modifiers
+
+B<Multis> (keyword: C<multi>) are routines that can have multiple
+variants that share the same name, selected by arity, types, or some
+other constraints.
+
+B<Prototypes> (keyword: C<proto>) specify the commonalities (such
+as parameter names, fixity, and associativity) shared by all multis
+of that name in the scope of the C<proto> declaration. A C<proto>
+also adds an implicit C<multi> to all routines of the same short
+name within its scope, unless they have an explicit modifier.
+(This is particularly useful when adding to rule sets or when attempting
+to compose conflicting methods from roles.)
+
+B<Only> (keyword: C<only>) routines do not share their short names
+with other routines. This is the default modifier for all routines,
+unless a C<proto> of the same name was already in scope.
+
+A modifier keyword may occur before the routine keyword in a named routine:
+
+ only sub foo {...}
+ proto sub foo {...}
+ multi sub foo {...}
+
+ only method bar {...}
+ proto method bar {...}
+ multi method bar {...}
+
+If the routine keyword is omitted, it defaults to C<sub>.
+
+Modifier keywords cannot apply to anonymous routines.
+
+=head2 Named subroutines
+
+The general syntax for named subroutines is any of:
+
+ my RETTYPE sub NAME ( PARAMS ) TRAITS {...} # lexical only
+ our RETTYPE sub NAME ( PARAMS ) TRAITS {...} # also package-scoped
+ sub NAME ( PARAMS ) TRAITS {...} # same as "our"
+
+The return type may also be put inside the parentheses:
+
+ sub NAME (PARAMS --> RETTYPE) {...}
+
+Unlike in Perl 5, named subroutines are considered expressions,
+so this is valid Perl 6:
+
+ my @subs = (sub foo { ... }, sub bar { ... });
+
+=head2 Anonymous subroutines
+
+The general syntax for anonymous subroutines is:
+
+ sub ( PARAMS ) TRAITS {...}
+
+But one can also use a scope modifier to introduce the return type first:
+
+ my RETTYPE sub ( PARAMS ) TRAITS {...}
+ our RETTYPE sub ( PARAMS ) TRAITS {...}
+
+In this case there is no effective difference, since the distinction between
+C<my> and C<our> is only in the handling of the name, and in the case of
+an anonymous sub, there's isn't one.
+
+B<Trait> is the name for a compile-time (C<is>) property.
+See L<"Properties and traits">.
+
+
+=head2 Perl5ish subroutine declarations
+
+You can declare a sub without parameter list, as in Perl 5:
+
+ sub foo {...}
+
+This is equivalent to
+
+ sub foo (*@_, *%_) {...}
+
+Positional arguments implicitly come in via the C<@_> array, but
+unlike in Perl 5 they are C<readonly> aliases to actual arguments:
+
+ sub say { print qq{"@_[]"\n}; } # args appear in @_
+
+ sub cap { $_ = uc $_ for @_ } # Error: elements of @_ are read-only
+
+Also unlike in Perl 5, Perl 6 has true named arguments, which come in
+via C<%_> instead of C<@_>. (To construct pseudo-named arguments that
+come in via C<@_> as in Perl 5, the p5-to-p6 translator will use the ugly
+C<< p5=> >> operator instead of Perl 6's C<< => >> Pair constructor.)
+
+If you need to modify the elements of C<@_> or C<%_>, declare the
+array or hash explicitly with the C<is rw> trait:
+
+ sub swap (*@_ is rw, *%_ is rw) { @_[0,1] = @_[1,0]; %_<status> = "Q:S"; }
+
+Note: the "rw" container trait is automatically distributed to the
+individual elements by the the slurpy star even though there's no
+actual array or hash passed in. More precisely, the slurpy star
+means the declared formal parameter is I<not> considered readonly; only
+its elements are. See L</Parameters and arguments> below.
+
+Note also that if the sub's block contains placeholder variables
+(such as C<$^foo> or C<$:bar>), those are considered to be formal
+parameters already, so in that case C<@_> or C<%_> fill the role of
+sopping up unmatched arguments. That is, if those containers are
+explicitly mentioned within the body, they are added as slurpy
+parameters. This allows you to easily customize your error message
+on unrecognized parameters. If they are not mentioned in the body,
+they are not added to the signature, and normal dispatch rules will
+simply fail if the signature cannot be bound.
+
+=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 on as a C<Code> object. How a block is
+parsed is context dependent.
+
+A bare block where an operator is expected terminates the current
+expression and will presumably be parsed as a block by the current
+statement-level construct, such as an C<if> or C<while>. (If no
+statement construct is looking for a block there, it's a syntax error.)
+This form of bare block requires leading whitespace because a bare
+block where a postfix is expected is treated as a hash subscript.
+
+
+A bare block where a term is expected merely produces a C<Code> object.
+If the term bare block occurs in a list, it is considered the final
+element of that list unless followed immediately by a comma or colon
+(intervening C<\h*> or "unspace" is allowed).
+
+=head2 "Pointy blocks"
+
+Semantically the arrow operator C<< -> >> is almost a synonym for the
+C<sub> keyword as used to declare an anonymous subroutine, insofar as
+it allows you to declare a signature for a block of code. However,
+the parameter list of a pointy block does not require parentheses,
+and a pointy block may not be given traits. In most respects,
+though, a pointy block is treated more like a bare block than like
+an official subroutine. Syntactically, a pointy block may be used
+anywhere a bare block could be used:
+
+ my $sq = -> $val { $val**2 };
+ say $sq(10); # 100
+
+ my @list = 1..3;
+ for @list -> $elem {
+ say $elem; # prints "1\n2\n3\n"
+ }
+
+It also behaves like a block with respect to control exceptions.
+If you C<return> from within a pointy block, the block is transparent
+to the return; it will return from the innermost enclosing C<sub> or
+C<method>, not from the block itself. It is referenced by C<&?BLOCK>,
+not C<&?ROUTINE>.
+
+A normal pointy block's parameters default to C<readonly>, just like
+parameters to a normal sub declaration. However, the double-pointy variant
+defaults parameters to C<rw>:
+
+ for @list <-> $elem {
+ $elem++;
+ }
+
+This form applies C<rw> to all the arguments:
+
+ for @kv <-> $key, $value {
+ $key ~= ".jpg";
+ $value *= 2 if $key ~~ :e;
+ }
+
+=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 (because it would imply that the body of the
+subroutine extends from that statement to the end of the file, as C<class> and
+C<module> declarations do). The only allowed use of the semicolon form is to
+declare a C<MAIN> sub--see L</Declaring a MAIN subroutine> below.
+
+Redefining a stub subroutine does not produce an error, but redefining
+an already-defined subroutine does. If you wish to redefine a defined sub,
+you must explicitly use the "C<is instead>" trait.
+
+The C<...> is the "yadayadayada" operator, which is executable but returns
+a failure. You can also use C<???> to produce a warning, or C<!!!> to
+always die. These also officially define stub blocks if used as the
+only expression in the block.
+
+It has been argued that C<...> as literal syntax is confusing when
+you might also want to use it for metasyntax within a document.
+Generally this is not an issue in context; it's never an issue in the
+program itself, and the few places where it could be an issue in the
+documentation, a comment will serve to clarify the intent, as above.
+The rest of the time, it doesn't really matter whether the reader
+takes C<...> as literal or not, since the purpose of C<...> is to
+indicate that something is missing whichever way you take it.
+
+
+=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 identifiers with C<*> (short for "C<GLOBAL::>"). The C<*>
+is required on the declaration unless the C<GLOBAL> namespace can be
+inferred some other way, but the C<*> may be omitted on use 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
+ }
+
+However, under stricture (the default for most code), the C<*> is required
+on variable references. It's never required on sub calls, and in fact,
+the syntax
+
+ $x = *saith($y);
+
+is illegal, because a C<*> where a term is expected is always parsed
+as the "whatever" token. If you really want to use a C<*>, you must
+also use the sigil along with the twigil:
+
+ $x = &*saith($y);
+
+Only the name is installed into the C<GLOBAL> package by C<*>. To define
+subs completely within the scope of the C<GLOBAL> namespace you should
+use "C<package GLOBAL {...}>" around the declaration.
+
+=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 => method {
+ return lastval();
+ },
+ STORE => method ($val) {
+ die unless check($passwd);
+ lastval() = $val;
+ };
+ }
+
+Other methods may be defined for specialized purposes such as temporizing
+the value of the proxy.
+
+=head2 Operator overloading
+
+Operators are just subroutines with special names and scoping.
+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
+indicates 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 C<prefix> or C<postfix>:
+
+ sub prefix:<OPNAME> ($operand) {...}
+ sub postfix:<OPNAME> ($operand) {...}
+
+Binary operators are defined as C<infix>:
+
+ sub infix:<OPNAME> ($leftop, $rightop) {...}
+
+Bracketing operators are defined as C<circumfix> where a term is expected
+or C<postcircumfix> where a postfix is expected. 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) {...}
+
+Contrary to Apocalypse 6, there is no longer any rule about splitting an even
+number of characters. You must use a two-element slice. Such names
+are canonicalized to a single form within the symbol table, so you
+must use the canonical name if you wish to subscript the symbol table
+directly (as in C<< PKG::{'infix:<+>'} >>). Otherwise any form will
+do. (Symbolic references do not count as direct subscripts since they
+go through a parsing process.) The canonical form always uses angle
+brackets and a single space between slice elements. The elements
+are not escaped, so C<< PKG::circumfix:{'<','>'} >> is canonicalized
+to C<<< PKG::{'circumfix:<< >>'} >>>, and decanonicalizing always
+involves stripping the outer angles and splitting on space, if any.
+This works because a hash key knows how long it is, so there's no
+ambiguity about where the final angle is. And space works because
+operators are not allowed to contain spaces.
+
+Operator names can be any sequence of non-whitespace characters
+including Unicode characters. For example:
+
+ sub infix:<(c)> ($text, $owner) { return $text but Copyright($owner) }
+ method prefix:<±> (Num $x --> 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 subscript, as in the example above).
+
+A null operator name does not define a null or whitespace operator, but
+a default matching subrule 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 subrule for the C<:1st>, C<:2nd>, C<:3rd>,
+etc. regex modifiers, something like this:
+
+ sub regex_mod_external:<> ($x) is parsed(token { \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.)
+
+Although the name of an operator can be installed into any package or
+lexical namespace, the syntactic effects of an operator declaration are
+always lexically scoped. Operators other than the standard ones should
+not be installed into the C<*> namespace. Always use exportation to make
+non-standard syntax available to other scopes.
+
+=head1 Parameters and arguments
+
+Perl 6 subroutines may be declared with parameter lists.
+
+By default, all parameters are readonly aliases to their corresponding
+arguments--the parameter is just another name for the original
+argument, but the argument can't be modified through it. This is
+vacuously true for value arguments, since they may not be modified in
+any case. However, the default forces any container argument to also
+be treated as an immutable value. This extends down only one level;
+an immutable container may always return an element that is mutable if
+it so chooses. (For this purpose a scalar variable is not considered
+a container of its singular object, though, so the top-level object
+within a scalar variable is considered immutable by default. Perl 6
+does not have references in the same sense that Perl 5 does.)
+
+To allow modification, use the C<is rw> trait. This requires a mutable
+object or container as an argument (or some kind of protoobject that
+can be converted to a mutable object, such as might be returned
+by an array or hash that knows how to autovivify new elements).
+Otherwise the signature fails to bind, and this candidate routine
+cannot be considered for servicing this particular call. (Other multi
+candidates, if any, may succeed if the don't require C<rw> for this
+parameter.) In any case, failure to bind does not by itself cause
+an exception to be thrown; that is completely up to the dispatcher.
+
+To pass-by-copy, use the C<is copy> trait. An object container will
+be cloned whether or not the original is mutable, while an (immutable)
+value will be copied into a suitably mutable container. The parameter
+may bind to any argument that meets the other typological constraints
+of the parameter.
+
+If you have a readonly parameter C<$ro>, it may never be passed on to
+a C<rw> parameter of a subcall, whether or not C<$ro> is currently
+bound to a mutable object. It may only be rebound to readonly or
+copy parameters. It may also be rebound to a C<ref> parameter (see
+"C<is ref>" below), but modification will fail as in the case where
+an immutable value is bound to a C<ref> parameter.
+
+Aliases of C<$ro> are also readonly, whether generated explicitly with C<:=>
+or implicitly within a C<Capture> object (which are themselves immutable).
+
+Also, C<$ro> may not be returned from an lvalue subroutine or method.
+
+Parameters may be required or optional. They may be passed by position,
+or by name. Individual parameters may confer an item or list context
+on their corresponding arguments, but unlike in Perl 5, this is decided
+lazily at parameter binding time.
+
+Arguments destined for required positional parameters must come before
+those bound to optional positional parameters. Arguments destined
+for named parameters may come before and/or after the positional
+parameters. (To avoid confusion it is highly recommended that all
+positional parameters be kept contiguous in the call syntax, but
+this is not enforced, and custom arg list processors are certainly
+possible on those arguments that are bound to a final slurpy or
+arglist variable.)
+
+=head2 Named arguments
+
+Named arguments are recognized syntactically at the "comma" level.
+Since parameters are identified using identifiers, the recognized
+syntaxes are those where the identifier in question is obvious.
+You may use either the adverbial form, C<:name($value)>, or the
+autoquoted arrow form, C<< name => $value >>. These must occur at
+the top "comma" level, and no other forms are taken as named pairs
+by default. Pairs intended as positional arguments rather than named
+arguments may be indicated by extra parens or by explicitly quoting
+the key to suppress autoquoting:
+
+ doit :when<now>,1,2,3; # always a named arg
+ doit (:when<now>),1,2,3; # always a positional arg
+
+ doit when => 'now',1,2,3; # always a named arg
+ doit (when => 'now'),1,2,3; # always a positional arg
+ doit 'when' => 'now',1,2,3; # always a positional arg
+
+Only bare keys with valid identifier names are recognized as named arguments:
+
+ doit when => 'now'; # always a named arg
+ doit 'when' => 'now'; # always a positional arg
+ doit 123 => 'now'; # always a positional arg
+ doit :123<now>; # always a positional arg
+
+Going the other way, pairs intended as named arguments that don't look
+like pairs must be introduced with the C<|> prefix operator:
+
+ $pair = :when<now>;
+ doit $pair,1,2,3; # always a positional arg
+ doit |$pair,1,2,3; # always a named arg
+ doit |get_pair(),1,2,3; # always a named arg
+ doit |('when' => 'now'),1,2,3; # always a named arg
+
+Note the parens are necessary on the last one due to precedence.
+
+Likewise, if you wish to pass a hash and have its entries treated as
+named arguments, you must dereference it with a C<|>:
+
+ %pairs = (:when<now>, :what<any>);
+ doit %pairs,1,2,3; # always a positional arg
+ doit |%pairs,1,2,3; # always named args
+ doit |%(get_pair()),1,2,3; # always a named arg
+ doit |%('when' => 'now'),1,2,3; # always a named arg
+
+Variables with a C<:> prefix in rvalue context autogenerate pairs, so you
+can also say this:
+
+ $when = 'now';
+ doit $when,1,2,3; # always a positional arg of 'now'
+ doit :$when,1,2,3; # always a named arg of :when<now>
+
+In other words C<:$when> is shorthand for C<:when($when)>. This works
+for any sigil:
+
+ :$what :what($what)
+ :@what :what(@what)
+ :%what :what(%what)
+ :&what :what(&what)
+
+Ordinary hash notation will just pass the value of the hash entry as a
+positional argument regardless of whether it is a pair or not.
+To pass both key and value out of hash as a positional pair, use C<:p>
+instead:
+
+ doit %hash<a>:p,1,2,3;
+ doit %hash{'b'}:p,1,2,3;
+
+The C<:p> stands for "pairs", not "positional"--the C<:p> adverb may be
+placed on any Hash access to make it mean "pairs" instead of "values".
+If you want the pair (or pairs) to be interpreted a named argument,
+you may do so by prefixing with the C<< prefix:<|> >> operator:
+
+ doit |%hash<a>:p,1,2,3;
+ doit |%hash{'b'}:p,1,2,3;
+
+Pair constructors are recognized syntactically at the call level and
+put into the named slot of the C<Capture> structure. Hence they may be
+bound to positionals only by name, not as ordinary positional C<Pair>
+objects. Leftover named arguments can be slurped into a slurpy hash.
+
+Because named and positional arguments can be freely mixed, the
+programmer always needs to disambiguate pairs literals from named
+arguments with parentheses or quotes:
+
+ # Named argument "a"
+ push @array, 1, 2, :a<b>;
+
+ # Pair object (a=>'b')
+ push @array, 1, 2, (:a<b>);
+ push @array, 1, 2, 'a' => 'b';
+
+Perl 6 allows multiple same-named arguments, and records the relative
+order of arguments with the same name. When there are more than one
+argument, the C<@> sigil in the parameter list causes the arguments
+to be concatenated:
+
+ sub fun (Int @x) { ... }
+ fun( x => 1, x => 2 ); # @x := (1, 2)
+ fun( x => (1, 2), x => (3, 4) ); # @x := (1, 2, 3, 4)
+
+Other sigils bind only to the I<last> argument with that name:
+
+ sub fun (Int $x) { ... }
+ f( x => 1, x => 2 ); # $x := 2
+ fun( x => (1, 2), x => (3, 4) ); # $x := (3, 4)
+
+This means a hash holding default values must come I<before> known named
+parameters, similar to how hash constructors work:
+
+ # Allow "x" and "y" in %defaults to be overridden
+ f( |%defaults, x => 1, y => 2 );
+
+=head2 Invocant parameters
+
+A method invocant may be 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 ($_: $newname) {...}
+
+The corresponding argument (the invocant) is evaluated in item context
+and is passed as the left operand of the method call operator:
+
+ print $obj.get_name();
+ $obj.set_name("Sam");
+
+For the purpose of matching positional arguments against invocant parameters,
+the invocant argument passed via the method call syntax is considered the
+first positional argument when failover happens from single dispatch to
+multiple dispatch:
+
+ handle_event($w, $e, $m); # calls the multi sub
+ $w.handle_event($e, $m); # ditto, but only if there is no
+ # suitable $w.handle_event method
+
+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:
+
+ set_name $obj: "Sam"; # try $obj.set_name("Sam") first, then
+ # fall-back to set_name($obj, "Sam")
+ $obj.set_name("Sam"); # same as the above
+
+An invocant is the topic of the corresponding method if that formal
+parameter is declared with the name C<$_>. A method's invocant
+always has the alias C<self>. Other styles of self can be declared
+with the C<self> pragma.
+
+=head2 Longname parameters
+
+A routine marked with C<multi> can mark part of its parameters to
+be considered in the multi dispatch. These are called I<longnames>;
+see S12 for more about the semantics of multiple dispatch.
+
+You can choose part of a C<multi>'s parameters to be its longname,
+by putting a double semicolon after the last one:
+
+ multi sub handle_event ($window, $event;; $mode) {...}
+ multi method set_name ($self: $name;; $nick) {...}
+
+A parameter list may have at most one double semicolon; parameters
+after it are never considered for multiple dispatch (except of course
+that they can still "veto" if their number or types mismatch).
+
+[Conjecture: It might be possible for a routine to advertise multiple
+long names, delimited by single semicolons. See S12 for details.]
+
+If the parameter list for a C<multi> contains no semicolons to delimit
+the list of important parameters, then all positional parameters are
+considered important. If it's a C<multi method> or C<multi submethod>,
+an additional implicit unnamed C<self> invocant is added to the
+signature list unless the first parameter is explicitly marked with a colon.
+
+
+=head2 Required parameters
+
+Required parameters are specified at the start of a subroutine's parameter
+list:
+
+ sub numcmp ($x, $y) { return $x <=> $y }
+
+Required parameters may optionally be declared with a trailing C<!>,
+though that's already the default for positional parameters:
+
+ sub numcmp ($x!, $y!) { return $x <=> $y }
+
+The corresponding arguments are evaluated in item 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 to a normal subroutine
+is a fatal error. Passing a named argument that cannot be bound to a normal
+subroutine is also a fatal error. (Methods are different.)
+
+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<?> after the parameter:
+
+ sub my_substr ($str, $from?, $len?) {...}
+
+Alternately, optional fields may be marked by supplying a default value.
+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
+item 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 values, or to
+an undefined value if they have no default. (A supplied argument that is
+undefined is not considered to be missing, and hence does not trigger
+the default. Use C<//=> within the body for that.)
+
+You may check whether an optional parameter was bound to anything
+by calling C<VAR($param).defined>.
+
+=head2 Named parameters
+
+Named-only parameters follow any required or optional parameters in the
+signature. They are marked by a prefix C<:>:
+
+ sub formalize($text, :$case, :$justify) {...}
+
+This is actually shorthand for:
+
+ sub formalize($text, :case($case), :justify($justify)) {...}
+
+If the longhand form is used, the label name and variable name can be
+different:
+
+ sub formalize($text, :case($required_case), :justify($justification)) {...}
+
+so that you can use more descriptive internal parameter names without
+imposing inconveniently long external labels on named arguments.
+Multiple name wrappings may be given; this allows you to give both a
+short and a long external name:
+
+ sub globalize (:g(:global($gl))) {...}
+
+Or equivalently:
+
+ sub globalize (:g(:$global)) {...}
+
+Arguments that correspond to named parameters are evaluated in item
+context. They can only be passed by name, so it doesn't matter what
+order you pass them in:
+
+ $formal = formalize($title, case=>'upper');
+ $formal = formalize($title, justify=>'left');
+ $formal = formalize($title, :justify<right>, :case<title>);
+
+See S02 for the correspondence between adverbial form and arrow notation.
+
+While named and position arguments may be intermixed, it is suggested
+that you keep all the positionals in one place for clarity unless you
+have a good reason not to. This is likely bad style:
+
+ $formal = formalize(:justify<right>, $title, :case<title>, $date);
+
+Named parameters are optional unless marked with a following C<!>.
+Default values for optional named parameters are defined in the same
+way as for positional parameters, but may depend only on existing
+values, including the values of parameters that have already been
+bound. Named optional parameters default to C<undef> if they have
+no default. Named required parameters fail unless an argument pair
+of that name is supplied.
+
+Bindings happen in declaration order, not call order, so any default
+may reliably depend on formal parameters to its left in the signature.
+In other words, if the first parameter is C<$a>, it will bind to
+a C<:a()> argument in preference to the first positional argument.
+It might seem that performance of binding would suffer by requiring
+a named lookup before a positional lookup, but the compiler is able
+to guarantee that subs with known fixed signatures (both onlys and
+multis with protos) translate named arguments to positional in the
+first N positions. Also, purely positional calls may obviously omit any
+named lookups, as may bindings that have already used up all the named
+arguments. The compiler is also free to intuit proto signatures for
+a given sub or method name as long as the candidate list is stable..
+
+=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 item 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, 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]
+
+You can't bind to the name of a slurpy parameter: the name is just there
+so you can refer to it within the body.
+
+ sub foo(*%flag, *@data) {...}
+
+ foo(:flag{ a => 1 }, :data[ 1, 2, 3 ]);
+ # %flag has elements (flag => (a => 1)) and (data => [1,2,3])
+ # @data has nothing
+
+=head2 Slurpy block
+
+It's also possible to declare a slurpy block: C<*&block>. It slurps
+up any nameless block, specified by C<{...}>, at either the current positional
+location or the end of the syntactic list. Put it first if you want the
+option of putting a block either first or last in the arguments. Put it
+last if you want to force it to come in as the last argument.
+
+=head2 Argument list binding
+
+The underlying C<Capture> object may be bound to a single scalar
+parameter marked with a C<|>.
+
+ sub bar ($a,$b,$c,:$mice) { say $mice }
+ sub foo (|$args) { say $args.perl; &bar.callwith(|$args); }
+
+This prints:
+
+ foo 1,2,3,:mice<blind>; # says "\(1,2,3,:mice<blind>)" then "blind"
+
+As demonstrated above, the capture may be interpolated into another
+call's arguments. (The C<|> prefix is described in the next section.)
+Use of C<callwith> allows the routine to be called without introducing
+an official C<CALLER> frame. For more see "Wrapping" below.
+
+It is allowed to rebind the parameters within the signature, but
+only as a subsignature of the capture argument:
+
+ sub compare (|$args (Num $x, Num $y --> Bool)) { ... }
+
+For all normal declarative purposes (invocants and multiple dispatch
+types, for instance), the inner signature is treated as the entire
+signature:
+
+ method addto (|$args ($self: @x)) { trace($args); $self += [+] @x }
+
+The inner signature is not required for non-multis since there can
+only be one candidate, but for multiple dispatch the inner signature
+is required at least for its types, or the declaration would not know
+what signature to match against.
+
+ multi foo (|$args (Int, Bool?, *@, *%)) { reallyintfoo($args) }
+ multi foo (|$args (Str, Bool?, *@, *%)) { reallystrfoo($args) }
+
+=head2 Flattening argument lists
+
+The unary C<|> operator casts its argument to a C<Capture>
+object, then splices that capture into the argument list
+it occurs in. To get the same effect on multiple arguments you
+can use the C<< |« >> hyperoperator.
+
+C<Pair> and C<Hash> become named arguments:
+
+ |(x=>1); # Pair, becomes \(x=>1)
+ |{x=>1, y=>2}; # Hash, becomes \(x=>1, y=>2)
+
+C<List> (also C<Seq>, C<Range>, etc.) are simply turned into
+positional arguments:
+
+ |(1,2,3); # Seq, becomes \(1,2,3)
+ |(1..3); # Range, becomes \(1,2,3)
+ |(1..2, 3); # List, becomes \(1,2,3)
+ |([x=>1, x=>2]); # List (from an Array), becomes \((x=>1), (x=>2))
+
+For example:
+
+ 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 flattened only if
+flattening is actually required within the subroutine. To flatten before
+the list is even passed into the subroutine, use the C<eager> list
+operator:
+
+ foo(|eager @onetothree); # array flattened before &foo called
+
+
+=head2 Multidimensional argument list binding
+
+Some functions take more than one list of positional and/or named arguments,
+that they wish not to be flattened into one list. For instance, C<zip()> wants
+to iterate several lists in parallel, while array and hash subscripts want to
+process a multidimensional slice. The set of underlying argument lists may be
+bound to a single array parameter declared with a double C<@@> sigil:
+
+ sub foo (*@@slice) { ... }
+
+Note that this is different from
+
+ sub foo (\$slice) { ... }
+
+insofar as C<\$slice> is bound to a single argument-list object that
+makes no commitment to processing its structure (and maybe doesn't
+even know its own structure yet), while C<*@@slice> has to create
+an array that binds the incoming dimensional lists to the array's
+dimensions, and make that commitment visible to the rest of the scope
+via the sigil so that constructs expecting multidimensional lists
+know that multidimensionality is the intention.
+
+It is allowed to specify a return type:
+
+ sub foo (*@@slice --> Num) { ... }
+
+The invocant does not participate in multi-dimensional argument lists,
+so C<self> is not present in the C<@@slice> below:
+
+ method foo (*@@slice) { ... }
+
+The C<@@> sigil is just a variant of the C<@> sigil, so C<@@slice>
+and C<@slice> are really the same array. In particular, C<@@_> is
+really the good old C<@_> array viewed as multidimensional.
+
+=head2 Zero-dimensional argument list
+
+If you call a function without parens and supply no arguments, the
+argument list becomes a zero-dimensional slice. It differs from
+C<\()> in several ways:
+
+ sub foo (*@@slice) {...}
+ foo; # +@@slice == 0
+ foo(); # +@@slice == 1
+
+ sub bar (\$args = \(1,2,3)) {...}
+ bar; # $args === \(1,2,3)
+ bar(); # $args === \()
+
+=head2 Feed operators
+
+The variadic list of a subroutine call can be passed in separately from
+the normal argument list, by using either of the I<feed> operators:
+C<< <== >> or C<< ==> >>. Syntactically, feed operators expect to find a
+statement on either end. Any statement can occur on the source end;
+however not all statements are suitable for use on the sink end of a feed.
+
+Each operator expects to find a call to a variadic receiver 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 receiver on the sharp end. In the case of a receiver
+that is a variadic function, the feed is received as part of its slurpy list.
+So both of the calls above are equivalent to:
+
+ grep { $_ % 2 }, @data;
+
+Note that all such feeds (and indeed all lazy argument lists) supply
+an implicit promise that the code producing the lists may execute
+in parallel with the code receiving the lists. (Feeds, hyperops,
+and junctions all have this promise of parallelizability in common,
+but differ in interface. Code which violates these promises is
+erroneous, and will produce undefined results when parallelized.)
+
+However, feeds go a bit further than ordinary lazy lists in enforcing
+the parallel discipline: they explicitly treat the blunt end as a
+cloned closure that starts a subthread (presumably cooperative). The only variables shared
+by the inner scope with the outer scope are those lexical variables
+declared in the outer scope that are visible at the time the closure is
+cloned and the subthread spawned. Use of such shared variables will
+automatically be subject to transactional protection (and associated
+overhead). Package variables are not cloned unless predeclared
+as lexical names with C<our>. Variables declared within the blunt
+end are not visible outside, and in fact it is illegal to declare a
+lexical on the blunt end that is not enclosed in curlies somehow.
+
+Because feeds are defined as lazy pipes, a chain of feeds may not begin
+and end with the same array without some kind of eager sequence point.
+That is, this isn't guaranteed to work:
+
+ @data <== grep { $_ % 2 } <== @data;
+
+either of these do:
+
+ @data <== grep { $_ % 2 } <== eager @data;
+ @data <== eager grep { $_ % 2 } <== @data;
+
+Conjecture: if the cloning process eagerly duplicates C<@data>, it could
+be forced to work. Not clear if this is desirable, since ordinary clones
+just clone the container, not the value.
+
+Leftward feeds 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;
+
+ # perhaps more clearly written as...
+
+ @oddsquares = do {
+ map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums;
+ }
+
+Rightward feeds are a convenient way of reversing the normal data flow in a
+chain of operations, to make it read left-to-right:
+
+ @oddsquares = do {
+ @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 };
+ }
+
+Note that something like the C<do> is necessary because feeds operate
+at the statement level. Parens would also work, since a statement is
+expected inside:
+
+ @oddsquares = (
+ @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 };
+ );
+
+But as described below, you can also just write:
+
+ @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 } ==> @oddsquares;
+
+If the operand on the sharp end of a feed is not a call to a variadic
+operation, it must be something else that can be interpreted as a list
+receiver, or a scalar expression that can be evaluated to produce an
+object that does the C<KitchenSink> role, such as an C<IO> object.
+Such an object provides C<.clear> and C<.push> methods that will
+be called as appropriate to send data. (Note that an C<IO> object
+used as a sink will force eager evaluation on its pipeline, so the
+next statement is guaranteed not to run till the file is closed.
+In contrast, an C<Array> object used as a sink turns into a lazy
+array.)
+
+Any non-variadic object (such as an C<Array> or C<IO> object) used as a filter
+between two feeds is treated specially as a I<tap> that merely captures
+data I<en passant>. You can safely install such a tap in an extended pipeline
+without changing the semantics. An C<IO> object used as a tap does not
+force eager evaluation since the eagerness is controlled instead by the
+downstream feed.
+
+Any prefix list operator is considered a variadic operation, so ordinarily
+a list operator adds any feed input to the end of its list.
+But sometimes you want to interpolate elsewhere, so any contextualizer
+with C<*> as an argument may be used to indicate the target of a
+feed without the use of a temporary array:
+
+ foo() ==> say @(*), " is what I meant";
+ bar() ==> @@(*).baz();
+
+Likewise, an C<Array> used as a tap may be distinguished from an C<Array> used
+as a translation function:
+
+ numbers() ==> @array ==> bar() # tap
+ numbers() ==> @array[@(*)] ==> bar() # translation
+
+Feeding into the C<*> "whatever" term sets the source for the next sink.
+To append multiple sources to the next sink, double the angle:
+
+ 0..* ==> *;
+ 'a'..* ==>> *;
+ pidigits() ==>> *;
+
+ # outputs "(0, 'a', 3)\n"...
+ for zip(@@(*)) { .perl.say }
+
+You may use a variable (or variable declaration) as a receiver, in
+which case the list value is bound as the "todo" of the variable.
+(The append form binds addition todos to the receiver's todo list.)
+Do not think of it as an assignment, nor as an ordinary binding.
+Think of it as iterator creation. In the case of a scalar variable,
+that variable contains the newly created iterator itself. In the case
+of an array, the new iterator is installed as the method for extending
+the array. As with assignment, the old todo list is clobbered; use the
+append form to avoid that and get push semantics.
+
+In general you can simply think of a receiver array as representing
+the results of the chain, so you can equivalently write any of:
+
+ my @oddsquares <== map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums;
+
+ my @oddsquares
+ <== map { $_**2 }
+ <== sort
+ <== grep { $_ % 2 }
+ <== @nums;
+
+ @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 } ==> my @oddsquares;
+
+ @nums
+ ==> grep { $_ % 2 }
+ ==> sort
+ ==> map { $_**2 }
+ ==> my @oddsquares;
+
+Since the feed iterator is bound into the final variable, the variable
+can be just as lazy as the feed that is producing the values.
+
+When feeds are bound to arrays with "push" semantics, you can have
+a receiver for multiple feeds:
+
+ my @foo;
+ 0..2 ==> @foo;
+ 'a'..'c' ==>> @foo;
+ say @foo; # 0,1,2,'a','b','c'
+
+Note how the feeds are concatenated in C<@foo> so that C<@foo>
+is a list of 6 elements. This is the default behavior. However,
+sometimes you want to capture the outputs as a list of two iterators,
+namely the two iterators that represent the two input feeds. You can
+get at those two iterators by using the name C<@@foo> instead, where
+the "slice" sigil marks a multidimensional array, that is, an
+array of lists, each of which may be treated independently.
+
+ 0..* ==> @@foo;
+ 'a'..* ==>> @@foo;
+ pidigits() ==>> @@foo;
+
+ for zip(@@foo) { .say }
+
+ [0,'a',3]
+ [1,'b',1]
+ [2,'c',4]
+ [3,'d',1]
+ [4,'e',5]
+ [5,'f',9]
+ ...
+
+Here C<@@foo> is an array of three iterators, so
+
+ zip(@@foo)
+
+is equivalent to
+
+ zip(@@foo[0]; @@foo[1]; @@foo[2])
+
+A semicolon inside brackets is equivalent to stacked feeds. The code above
+could be rewritten as:
+
+ (0..*; 'a'..*; pidigits()) ==> my @@foo;
+ for @@foo.zip { .say }
+
+which is in turn equivalent to
+
+ for zip(0..*; 'a'..*; pidigits()) { .say }
+
+A named receiver array is useful when you wish to feed into an
+expression that is not an ordinary list operator, and you wish to be
+clear where the feed's destination is supposed to be:
+
+ picklist() ==> my @baz;
+ my @foo = @bar[@baz];
+
+Various contexts may or may not be expecting multi-dimensional slices
+or feeds. By default, ordinary arrays are flattened, that is, they
+have "list" semantics. If you say
+
+ (0..2; 'a'..'c') ==> my @tmp;
+ for @tmp { .say }
+
+then you get 0,1,2,'a','b','c'. If you have a multidim array, you
+can ask for list semantics explicitly with list():
+
+ (0..2; 'a'..'c') ==> my @@tmp;
+ for @@tmp.list { .say }
+
+As we saw earlier, "zip" produces an interleaved result by taking one element
+from each list in turn, so
+
+ (0..2; 'a'..'c') ==> my @@tmp;
+ for @@tmp.zip { .say }
+
+produces 0,'a',1,'b',2,'c'.
+
+If you want the result as a list of subarrays, then you need to put
+the zip into a "chunky" context instead:
+
+ (0..2; 'a'..'c') ==> my @@tmp;
+ for @@tmp.zip.@@() { .say }
+
+This produces [0,'a'],[1,'b'],[2,'c']. But usually you want the flat
+form so you can just bind it directly to a signature:
+
+ for @@tmp.zip -> $i, $a { say "$i: $a" }
+
+Otherwise you'd have to say this:
+
+ for @@tmp.zip.@@() -> [$i, $a] { say "$i: $a" }
+
+In list context the C<@@foo> notation is really a shorthand for C<[;](@@foo)>.
+In particular, you can use C<@@foo> to interpolate a multidimensional slice
+in an array or hash subscript.
+
+If C<@@foo> is currently empty, then C<for zip(@@foo) {...}> acts on a
+zero-dimensional slice (i.e. C<for (zip) {...}>), and outputs nothing
+at all.
+
+Note that with the current definition, the order of feeds is preserved
+left to right in general regardless of the position of the receiver.
+
+So
+
+ ('a'..*; 0..*) ==> *;
+ for zip(@@() <== @foo) -> $a, $i, $x { ... }
+
+is the same as
+
+ 'a'..* ==> *;
+ 0..* ==> *;
+ for zip(@@ <== @foo) -> $a, $i, $x { ... }
+
+which is the same as
+
+ for zip('a'..*; 0..*; @foo) -> $a, $i, $x { ... }
+
+Also note that these come out to be identical for ordinary arrays:
+
+ @foo.zip
+ @foo.cat
+
+The C<@@($foo)> coercer can be used to pull a multidim out of some
+object that contains one, such as a C<Capture> or C<Match> object. Like
+C<@()>, C<@@()> defaults to C<@@($/)>, and returns a multidimensional
+view of any match that repeatedly applies itself with C<:g> and
+the like. In contrast, C<@()> would flatten those into one list.
+
+=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;
+
+(The comma is required after the closure.)
+
+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 a type specification written
+with C<:(...)>:
+
+ sub limited_Dog_grep ($count, &block:(Dog), Dog *@list) {...}
+
+and even a return type:
+
+ sub limited_Dog_grep ($count, &block:(Dog --> 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 Type parameters
+
+Unlike normal parameters, type parameters often come in piggybacked
+on the actual value as "kind", and you'd like a way to capture both
+the value and its kind at once. (A "kind" is a class or type that
+an object is allowed to be. An object is not officially allowed
+to take on a constrained or contravariant type.) A type variable
+can be used anywhere a type name can, but instead of asserting that
+the value must conform to a particular type, it captures the
+actual "kind" of the object and also declares a package/type name
+by which you can refer to that kind later in the signature or body.
+For instance, if you wanted to match any two Dogs as long as they
+were of the same kind, you can say:
+
+ sub matchedset (Dog ::T $fido, T $spot) {...}
+
+(Note that C<::T> is not required to contain C<Dog>, only
+a type that is compatible with C<Dog>.)
+
+The C<::> sigil is short for "subset" in much the same way that C<&> is
+short for "sub". Just as C<&> can be used to name any kind of code,
+so too C<::> can be used to name any kind of type. Both of them insert
+a bare identifier into the symbol table, though they fill different syntactic
+spots.
+
+Note that it is not required to capture the object associated with the
+class unless you want it. The sub above could be written as
+
+ sub matchedset (Dog ::T, T) {...}
+
+if we're not interested in C<$fido> or C<$spot>. Or just
+
+ sub matchedset (::T, T) {...}
+
+if we don't care about anything but the matching.
+
+=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 a single list argument
+
+To match the first element of the slurpy list, use a "slurpy" scalar:
+
+ sub quicksort (:$reverse, :$inplace, *$pivot, *@data)
+
+=head2 Unpacking tree node parameters
+
+You can unpack hash values and tree nodes in various dwimmy ways by enclosing the bindings
+of child nodes and attributes in parentheses following the declaration of
+the node itself:
+
+ sub traverse ( BinTree $top ( $left, $right ) ) {
+ traverse($left);
+ traverse($right);
+ }
+
+In this, C<$left> and C<$right> are automatically bound to the left
+and right nodes of the tree. If $top is an ordinary object, it binds
+the C<$top.left> and C<$top.right> attributes. If it's a hash,
+it binds C<< $top<left> >> and C<< $top<right> >>. If C<BinTree> is a
+signature type and $top is a List (argument list) object, the child types
+of the signature are applied to the actual arguments in the argument
+list object. (Signature types have the benefit that you can view
+them inside-out as constructors with positional arguments, such that
+the transformations can be reversible.)
+
+However, the full power of signatures can be applied to pattern match
+just about any argument or set of arguments, even though in some cases
+the reverse transformation is not derivable. For instance, to bind to
+an array of children named C<.kids> or C<< .<kids> >>, use something
+like:
+
+ multi traverse ( NAry $top ( :kids [$eldest, *@siblings] ) ) {
+ traverse($eldest);
+ traverse(:kids(@siblings)); # (binds @siblings to $top)
+ }
+ multi traverse ( $leaf ) {...}
+
+The second candidate is called only if the parameter cannot be bound to
+both $top and to the "kids" parsing subparameter.
+
+Likewise, to bind to a hash element of the node and then bind to
+keys in that hash by name:
+
+ sub traverse ( AttrNode $top ( :%attr{ :$vocalic, :$tense } ) ) {
+ say "Has {+%attr} attributes, of which";
+ say "vocalic = $vocalic";
+ say "tense = $tense";
+ }
+
+You may omit the top variable if you prefix the parentheses with a colon
+to indicate a signature. Otherwise you must at least put the sigil of
+the variable, or we can't correctly differentiate:
+
+ my Dog ($fido, $spot) := twodogs(); # list of two dogs
+ my Dog $ ($fido, $spot) := twodogs(); # one twodog object
+ my Dog :($fido, $spot) := twodogs(); # one twodog object
+
+Sub signatures can be matched directly within regexes by using C<:(...)>
+notation.
+
+ push @a, "foo";
+ push @a, \(1,2,3);
+ push @a, "bar";
+ ...
+ my ($i, $j, $k);
+ @a ~~ rx/
+ <,> # match initial elem boundary
+ :(Int $i,Int $j,Int? $k) # match lists with 2 or 3 ints
+ <,> # match final elem boundary
+ /;
+ say "i = $<i>";
+ say "j = $<j>";
+ say "k = $<k>" if defined $<k>;
+
+If you want a parameter bound into C<$/>, you have to say C<< $<i> >>
+within the signature. Otherwise it will try to bind an external C<$i>
+instead, and fail if no such variable is declared.
+
+Note that unlike a sub declaration, a regex-embedded signature has no
+associated "returns" syntactic slot, so you have to use C<< --> >>
+within the signature to specify the C<of> type of the signature, or match as
+an arglist:
+
+ :(Num, Num --> Coord)
+ :(\Coord(Num, Num))
+
+A consequence of the latter form is that you can match the type of
+an object with C<:(\Dog)> without actually breaking it into its components.
+Note, however, that it's not equivalent to say
+
+ :(--> Dog)
+
+which would be equivalent to
+
+ :(\Dog())
+
+that is, match a nullary function of type C<Dog>. Nor is it equivalent to
+
+ :(Dog)
+
+which would be equivalent to
+
+ :(\Any(Dog))
+
+and match a function taking a single parameter of type Dog.
+
+Note also that bare C<\(1,2,3)> is never legal in a regex since the
+first (escaped) paren would try to match literally.
+
+=head2 Attributive parameters
+
+If a submethod's parameter is declared with a C<.> or C<!> after the
+sigil (like an attribute):
+
+ submethod 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:
+
+ submethod initialize($name, $age) {
+ $.name = $name;
+ $!age = $age;
+ }
+
+To rename an attribute parameter you can use the explicit pair form:
+
+ submethod initialize(:moniker($.name), :youth($!age)) {}
+
+The C<:$name> shortcut may be combined with the C<$.name> shortcut,
+but the twigil is ignored for the parameter name, so
+
+ submethod initialize(:$.name, :$!age) {}
+
+is the same as:
+
+ submethod initialize(:name($.name), :age($!age)) {}
+
+Note that C<$!age> actually refers to the private "C<has>" variable that
+can be referred to as either C<$age> or C<$!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<^>) or a colon (C<:>) after their sigils.
+The caret marks positional placeholders, while the colon marks named
+placeholders.
+
+Using placeholders in a block defines an implicit parameter list. The
+signature is the list of distinct positional placeholder names,
+sorted in Unicode order, following by the named placeholder names in
+any order. So:
+
+ { say "woof" if $:dog; $^y < $^z && $^x != 2 }
+
+is a shorthand for:
+
+ -> $x,$y,$z,:$dog { say "woof" if $dog; $y < $z && $x != 2 }
+
+Note that placeholder variables syntactically cannot have type constraints.
+Also, it is illegal to use placeholder variables in a block that already
+has a signature, because the autogenerated signature would conflict with that.
+Positional placeholder names consisting of a single uppercase letter are disallowed,
+not because we're mean, but because it helps us catch references to
+obsolete Perl 5 variables such as $^O.
+
+A function containing placeholders may also refer to either C<@_>
+or C<%_> or both, each of which (if so used) will be added to the
+signature as a normal readonly slurpy pararmeter:
+
+ { say $:what; warn "bad option: $_\n" for keys %_; }
+
+turns into
+
+ -> :$what, *%_ { say $what; warn "bad option: $_\n" for keys %_; }
+
+If not used, they are not added, and a dispatch with mispatched parameters will fail.
+
+Placeholders may also be used in method bodies that have no formal signature.
+
+Since the placeholder declares a parameter variable without the twigil,
+the twigil is needed only on the first occurrence of the variable within
+the block. Subsequent mentions of that variable may omit the twigil.
+Within an internal nested block the twigil I<must> be omitted, since
+it would wrongly attach to the inner block.
+
+=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:
+
+ constant $pi is Approximated = 3; # variable $pi has Approximated trait
+
+ 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:
+
+ constant $pi = 3 but Inexact; # value 3 has Inexact property
+
+ sub system {
+ ...
+ return $error but False if $error;
+ return 0 but True;
+ }
+
+Properties are predeclared as roles and implemented as mixins--see S12.
+
+=head2 Subroutine traits
+
+These traits may be declared on the subroutine as a whole (individual
+parameters take other traits). Trait syntax depends on the particular
+auxiliary you use, but for C<is>, the subsequent syntax is identical to
+adverbial syntax, except that that colon may be omitted or doubled depending
+on the degree of ambiguity desired:
+
+ is ::Foo[...] # definitely a parameterized typename
+ is :Foo[...] # definitely a pair with a list
+ is Foo[...] # depends on whether Foo is predeclared as type
+
+=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 C<inner> type constraint that a routine imposes on its return value.
+
+=item C<of>/C<is of>
+
+The C<of> type that is the official return type of the routine. Or you
+can think of "of" as outer/formal. If there is no inner type, the outer
+type also serves as the inner type to constrain the return value.
+
+=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 subrule by which a macro call is parsed. The parse
+always starts after the macro's initial token. If the operator has
+two parts (circumfix or postcircumfix), the final token is also automatically
+matched, and should not be matched by the supplied regex.
+
+=item C<is reparsed>
+
+Also specifies the subrule by which a macro call is parsed, but restarts
+the parse before the macro's initial token, usually because you want
+to parse using an existing rule that expects to traverse the initial
+token. If the operator has two parts (circumfix or postcircumfix), the
+final token must also be explicitly matched by the supplied regex.
+
+=item C<is cached>
+
+Marks a subroutine as being memoized, or at least memoizable.
+In the abstract, this cache is just a hash where incoming argument
+C<Capture>s are mapped to return values. If the C<Capture> is found in
+the hash, the return value need not be recalculated. If you use
+this trait, the compiler will assume two things:
+
+=over
+
+=item *
+
+A given C<Capture> would always calculate the same return value. That is,
+there is no state hidden within the dynamic scope of the call.
+
+=item *
+
+The cache lookup is likely to be more efficient than recalculating
+the value in at least some cases, because either most uncached calls
+would be slower (and reduce throughput), or you're trying to avoid a
+significant number of pathological cases that are unacceptably slow
+(and increase latency).
+
+=back
+
+This trait is a suggestion to the compiler that caching is okay. The
+compiler is free to choose any kind of caching algorithm (including
+non-expiring, random, lru, pseudo-lru, or adaptive algoritms, or
+even no caching algorithm at all). The run-time system is free to
+choose any kind of maximum cache size depending on the availability
+of memory and trends in usage patterns. You may suggest a particular
+cache size by passing a numeric argument (representing the maximum number
+of unique C<Capture> values allowed), and some of the possible
+algorithms may pay attention to it. You may also pass C<*> for the
+size to request a non-expiring cache (complete memoization). The
+compiler is free to ignore this too.
+
+The intent of this trait is to specify performance hints without
+mandating any exact behavior. Proper use of this trait should not
+change semantics of the program; it functions as a kind of "pragma".
+This trait will not be extended to reinvent other existing ways of
+achieving the same effect. To gain more control, write your own
+trait handler to allow the use of a more specific trait, such as
+"C<is lru(42)>". Alternately, just use a state hash keyed on the
+sub's argument capture to write your own memoization with complete
+control from within the subroutine itself, or from within a wrapper
+around your subroutine.
+
+=item C<is inline>
+
+I<Suggests> to the compiler that the subroutine is a candidate for
+optimization via inlining. Basically promises that nobody is going
+to try to wrap this subroutine (or that if they do, you don't care).
+
+=item C<is tighter>/C<is looser>/C<is equiv>
+
+Specifies the precedence of an operator relative to an existing
+operator. C<tighter> and C<looser> operators default to being left
+associative.
+
+C<equiv> on the other hand also clones other traits, so it specifies
+the default associativity to be the same as the operator to which
+the new operator is equivalent. The following are the default
+equivalents for various syntactic categories if neither C<equiv> nor
+C<assoc> is specified. (Many of these have no need of precedence
+or associativity because they are parsed specially. Nevertheless,
+C<equiv> may be useful for cloning other traits of these operators.)
+
+ category:<prefix>
+ circumfix:<( )>
+ dotty:<.>
+ infix:<+>
+ infix_circumfix_meta_operator:{'»','«'}
+ infix_postfix_meta_operator:<=>
+ infix_prefix_meta_operator:<!>
+ package_declarator:<class>
+ postcircumfix:<( )>
+ postfix:<++>
+ postfix_prefix_meta_operator:{'»'}
+ prefix:<++>
+ prefix_circumfix_meta_operator:{'[',']'}
+ prefix_postfix_meta_operator:{'«'}
+ q_backslash:<\\>
+ qq_backslash:<n>
+ quote_mod:<c>
+ quote:<q>
+ regex_assertion:<?>
+ regex_backslash:<w>
+ regex_metachar:<.>
+ regex_mod_internal:<i>
+ routine_declarator:<sub>
+ scope_declarator:<my>
+ sigil:<$>
+ special_variable:<$!>
+ statement_control:<if>
+ statement_mod_cond:<if>
+ statement_mod_loop:<while>
+ statement_prefix:<do>
+ term:<*>
+ trait_auxiliary:<is>
+ trait_verb:<of>
+ twigil:<?>
+ type_declarator:<subset>
+ version:<v>
+
+The existing operator may be specified either as a function object
+or as a string argument equivalent to the one that would be used in
+the complete function name. In string form the syntactic
+category will be assumed to be the same as the new declaration.
+Therefore these all have the same effect:
+
+ sub postfix:<!> ($x) is equiv(&postfix:<++>) {...}
+ sub postfix:<!> ($x) is equiv<++> {...}
+ sub postfix:<!> ($x) {...} # since equiv<++> is the default
+
+Prefix operators that are identifiers are handled specially. Both of
+
+ sub foo ($) {...}
+ sub prefix:<foo> ($) {...}
+
+default to named unary precedence despite declaring a prefix operator.
+Likewise postfix operators that look like method calls are forced to
+default to the precedence of method calls. Any prefix operator that
+requires multiple arguments defaults to listop precedence, even if it
+is not an identifier.
+
+=item C<is assoc>
+
+Specifies the associativity of an operator explicitly. Valid values are:
+
+ Tag Examples Meaning of $a op $b op $c Default equiv
+ === ======== ========================= =============
+ left + - * / x ($a op $b) op $c +
+ right ** = $a op ($b op $c) **
+ non cmp <=> .. ILLEGAL cmp
+ chain == eq ~~ ($a op $b) and ($b op $c) eqv
+ list | & ^ Z op($a; $b; $c) |
+
+Note that operators "C<equiv>" to relationals are automatically considered
+chaining operators. When creating a new precedence level, the chaining
+is determined by the presence or absence of "C<< is assoc<chain> >>",
+and other operators defined at that level are required to be the same.
+
+Specifying an C<assoc> without an explicit C<equiv> substitutes a default
+C<equiv> consistent with the associativity, as shown in the final column above.
+
+=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.
+
+When applied to a method, the semantics provide support for the
+"Design by Contract" style of OO programming: a precondition of
+a particular method is met if all the C<PRE> blocks associated
+with that method return true. Otherwise, the precondition is met
+if C<all> of the parent classes' preconditions are met (which may
+include the preconditions of I<their> parent classes if they fail,
+and so on recursively.)
+
+In contrast, a method's postcondition is met if all the method's C<POST> blocks
+return true I<and> all its parents' postconditions are also met recursively.
+
+C<POST> blocks (and "C<will post>" block traits) declared within a C<PRE>
+or C<ENTER> block are automatically hoisted outward to be called at the
+same time as other C<POST> blocks. This conveniently gives "circum"
+semantics by virtue of wrapping the post lexical scope within the pre
+lexical scope.
+
+ method push ($new_item) {
+ ENTER {
+ my $old_height = self.height;
+ POST { self.height == $old_height + 1 }
+ }
+
+ $new_item ==> push @.items;
+ }
+
+ method pop () {
+ ENTER {
+ my $old_height = self.height;
+ POST { self.height == $old_height - 1 }
+ }
+
+ return pop @.items;
+ }
+
+[Conjecture: class and module invariants can similarly be supplied
+by embedding C<POST>/C<post> declarations in a C<FOREIGN> block that
+only runs when any routine of this module is called from "outside"
+the current module or type, however that's defined. The C<FOREIGN> block
+itself could perhaps refine the concept of what is foreign, much like
+an exception handler.]
+
+=item C<ENTER>/C<LEAVE>/C<KEEP>/C<UNDO>/etc.
+
+These supply closures that are to be conditionally executed before or
+after the subroutine's C<do> block (only if used at the outermost level
+within the subroutine; technically, these are block traits on the C<do>
+block, not subroutine traits). 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 readonly>
+
+Specifies that the parameter cannot be modified (e.g. assigned to,
+incremented). It is the default for parameters. On arguments which
+are already immutable values it is a no-op at run time; on mutable
+containers it may need to create an immutable alias to the mutable object
+if the constraint cannot be enforced entirely at compile time. Binding
+to a readonly parameter never triggers autovivification.
+
+=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 if you try to modify them within the body of the routine.
+
+=item C<is copy>
+
+Specifies that the parameter receives a distinct, read-writable copy of the
+original argument. This is commonly known as "pass-by-value".
+
+ sub reprint ($text, $count is copy) {
+ print $text while $count-- > 0;
+ }
+
+Binding to a copy parameter never triggers autovivification.
+
+=item C<is context(I<ACCESS>)>
+
+Specifies that the parameter is to be treated as an "environmental"
+variable, that is, a lexical that is accessible from the dynamic
+scope (see S02). If I<ACCESS> is omitted, defaults to readonly in
+any portions of the dynamic scope outside the current lexical scope.
+
+=back
+
+
+=head1 Advanced subroutine features
+
+=head2 The C<return> function
+
+The C<return> function notionally throws a control exception that is
+caught by the current lexically enclosing C<Routine> to force a return
+through the control logic code of any intermediate block constructs.
+(That is, it must unwind the stack of dynamic scopes to the proper
+lexical scope belonging to this routine.) With normal blocks
+(those that are autoexecuted in place because they're known to the
+compiler) this unwinding can likely be optimized away to a "goto".
+All C<Routine> declarations have an explicit declarator such as C<sub>
+or C<method>; bare blocks and "pointy" blocks are never considered
+to be routines in that sense. To return from a block, use C<leave>
+instead--see below.
+
+The C<return> function preserves its argument list as a C<Capture> object, and
+responds to the left-hand C<Signature> in a binding. This allows named return
+values if the caller expects one:
+
+ sub f () { return :x<1> }
+ sub g ($x) { print $x }
+
+ my $x := |(f); # binds 1 to $x, via a named argument
+ g(|(f)); # prints 1, via a named argument
+
+To return a literal C<Pair> object, always put it in an additional set of
+parentheses:
+
+ return( (:x<1>), (:y<2>) ); # two positional Pair objects
+
+Note that the postfix parentheses on the function call don't count as
+being "additional". However, as with any function, whitespace after the
+C<return> keyword prevents that interpretation and turns it instead
+into a list operator:
+
+ return :x<1>, :y<2>; # two named arguments (if caller uses |)
+ return ( :x<1>, :y<2> ); # two positional Pair objects
+
+If the function ends with an expression without an explicit C<return>,
+that expression is also taken to be a C<Capture>, just as if the expression
+were the argument to a C<return> list operator (with whitespace):
+
+ sub f { :x<1> } # named-argument binding (if caller uses |)
+ sub f { (:x<1>) } # always just one positional Pair object
+
+On the caller's end, the C<Capture> is interpolated into any new argument list
+much like an array would be, that is, as an item in item context, and as a
+list in list context. This is the default behavior, but the
+caller may use C<< prefix:<|> >> to inline the returned values as part of the
+new argument list. The caller may also bind the returned C<Capture> directly.
+
+If any function called as part of a return list asks what its context
+is, it will be told it was called in list context regardless of the
+eventual binding of the returned C<Capture>. (This is quite
+different from Perl 5, where a C<return> statement always propagates its
+caller's context to its own argument(s).) If that is not the
+desired behavior you must coerce the call to an appropriate context,
+(or declare the return type of the function to perform such a coercion).
+In any event, such a function is called only once at the time the
+C<Capture> object is generated, not when it is later bound (which
+could happen more than once).
+
+=head2 The C<context> and C<caller> functions
+
+The C<context> function takes a list of matchers and interprets them
+as a navigation path from the current context to a location in the
+dynamic scope, either the current context itself or some context
+from which the current context was called. It returns an object
+that describes that particular dynamic scope, or a false value if
+there is no such scope. Numeric arguments are interpreted as number
+of contexts to skip, while non-numeric arguments scan outward for a
+context matching the argument as a smartmatch.
+
+The current context is accessed with a null argument list.
+
+ say " file ", context().file,
+ " line ", context().line;
+
+which is equivalent to:
+
+ say " file ", CONTEXT::<$?FILE>,
+ " line ", CONTEXT::<$?LINE>;
+
+The immediate caller of this context is accessed by skipping one level:
+
+ say " file ", context(1).file,
+ " line ", context(1).line;
+
+You might think that that must be the current function's caller,
+but that's not necessarily so. This might return an outer block in
+our own routine, or even some function elsewhere that implements a
+control operator on behalf of our block. To get outside your current
+routine, see C<caller> below.
+
+The C<context> function may be given arguments
+telling it which higher scope to look for. Each argument is processed
+in order, left to right. Note that C<Any> and C<0> are no-ops:
+
+ $ctx = context(); # currently running context for &?BLOCK
+ $ctx = context(Any); # currently running context for &?BLOCK
+ $ctx = context(Any,Any); # currently running context for &?BLOCK
+ $ctx = context(1); # my context's context
+ $ctx = context(2); # my context's context's context
+ $ctx = context(3); # my context's context's context's context
+ $ctx = context(1,0,1,1); # my context's context's context's context
+ $ctx = context($i); # $i'th context
+
+Note also that negative numbers are allowed as long as you stay within
+the existing context stack:
+
+ $ctx = context(4,-1); # my context's context's context's context
+
+Repeating any smartmatch just matches the same context again unless you
+intersperse a 1 to skip the current level:
+
+ $ctx = context(Method); # nearest context that is method
+ $ctx = context(Method,Method); # nearest context that is method
+ $ctx = context(Method,1,Method); # 2nd nearest method context
+ $ctx = context(Method,1,Method,1) # caller of that 2nd nearest method
+ $ctx = context(1,Block); # nearest outer context that is block
+ $ctx = context(Sub,1,Sub,1,Sub); # 3rd nearest sub context
+ $ctx = context({ .labels.any eq 'Foo' }); # nearest context labeled 'Foo'
+
+Note that this last potentially differs from the answer returned by
+
+ Foo.context
+
+which returns the context of the innermost C<Foo> block in the lexical scope
+rather than the dynamic scope. A context also responds to the C<.context>
+method, so a given context may be used as the basis for further navigation:
+
+ $ctx = context(Method,1,Method);
+ $ctx = context(Method).context(1).context(Method); # same
+
+You must supply args to get anywhere else, since C<.context> is
+the identity operator when called on something that is already
+a C<Context>:
+
+ $ctx = context;
+ $ctx = context.context.context.context; # same
+
+The C<caller> function is special-cased to go outward just far enough
+to escape from the current routine scope, after first ignoring any
+inner blocks that are embedded, or are otherwise pretending to be "inline":
+
+ &caller ::= &context.assuming({ !.inline }, 1);
+
+Note that this is usually the same as C<context(&?ROUTINE,1)>,
+but not always. A call to a returned closure might not even have
+C<&?ROUTINE> in its dynamic scope anymore, but it still has a caller.
+
+So to find where the current routine was called you can say:
+
+ say " file ", caller.file,
+ " line ", caller.line;
+
+which is equivalent to:
+
+ say " file ", CALLER::<$?FILE>,
+ " line ", CALLER::<$?LINE>;
+
+Additional arguments to C<caller> are treated as navigational from the
+calling context. One context out from your current routine is I<not>
+guaranteed to be a C<Routine> context. You must say C<caller(Routine)>
+to get to the next-most-inner routine.
+
+Note that C<caller(Routine).line> is not necessarily going to give you the
+line number that your current routine was called from; you're rather
+likely to get the line number of the topmost block that is executing
+within that outer routine, where that block contains the call to
+your routine.
+
+For either C<context> or C<caller>,
+the returned context object supports at least the following methods:
+
+ .context
+ .caller
+ .leave
+ .want
+ .inline
+ .package
+ .file
+ .line
+ .my
+ .hints
+
+The C<.context> and C<.caller> methods work the same as the functions
+except that they are relative to the context supplied as invocant.
+The C<.leave> method can force an immediate return from the
+specified context. The C<.want> method returns known smart-matchable
+characteristics of the specified context.
+
+The C<.inline> method says whether this block was entered implicitly
+by some surrounding control structure. Any time you invoke a block or
+routine explicitly with C<.()> this is false. However, it is defined
+to be true for any block entered using dispatcher-level primitives
+such as C<.callwith>, C<.callsame>, C<.nextwith>, or C<.nextsame>.
+
+The C<.my> method provides access to the lexical namespace in effect at
+the given dynamic context's current position. It may be used to look
+up ordinary lexical variables in that lexical scope. It must not be
+used to change any lexical variable that is not marked as C<< context<rw> >>.
+
+The C<.hints> method gives access to a snapshot of compiler symbols in
+effect at the point of the call when the call was originally compiled.
+(For instance, C<caller.hints('&?ROUTINE')> will give you the caller's
+routine object.) Such values are always read-only, though in the
+case of some (like the caller's routine above) may return a fixed
+object that is nevertheless mutable.
+
+=head2 The C<want> function
+
+The C<want> function returns a C<Signature> object that contains
+information about the context in which the current block, closure,
+or subroutine was called. The C<want> function is really just
+short for C<caller.want>. (Note that this is what your current
+routine's caller wants from your routine, not necessarily the same as
+C<context.want> when you are embedded in a block within a subroutine.
+Use C<context.want> if that's what you want.)
+
+As with normal function signatures, you can test the result of C<want> with a
+smart match (C<~~>) or a C<when>:
+
+ given want {
+ when :($) {...} # called in item context
+ when :(*@) {...} # called in list context
+ when :($ is rw) {...} # expected to return an lvalue
+ when :($,$) {...} # expected to return two values
+ ...
+ }
+
+Or use its shorthand methods to reduce line noise:
+
+ if want.item {...} # called in non-lvalue item context
+ elsif want.list {...} # called in list context
+ elsif want.void {...} # called in void context
+ elsif want.rw {...} # expected to return an lvalue
+
+The C<.arity> and C<.count> methods also work here:
+
+ if want.arity > 2 {...} # must return more than two values
+ if want.count > 2 {...} # can return more than two values
+
+Their difference is that C<.arity> considers only mandatory parts,
+while C<.count> considers also optional ones, including C<*$>:
+
+ ($x, $y) = f(); # Within &f, want === :(*$?, *$?, *@)
+ # want.arity === 0
+ # want.count === 2
+
+=head2 The C<leave> function
+
+As mentioned above, a C<return> call causes the innermost surrounding
+subroutine, method, rule, token, regex (as a keyword) or macro
+to return. Only declarations with an explicit declarator keyword
+(C<sub>, C<submethod>, C<method>, C<macro>, C<regex>, C<token>, and
+C<rule>) may be returned from. Statement prefixes such a C<do> and
+C<try> do not fall into that category.
+You cannot use C<return> to escape directly into the surrounding
+context from loops, bare blocks, pointy blocks, or quotelike operators
+such as C<rx//>; a C<return> within one of those constructs will
+continue searching outward for a "proper" routine to return from.
+Nor may you return from property blocks such as C<BEGIN> or C<CATCH>
+(though blocks executing within the lexical and dynamic scope of a
+routine can of course return from that outer routine, which means
+you can always return from a C<CATCH> or a C<FIRST>, but never from
+a C<BEGIN> or C<INIT>.)
+
+To return from blocks that aren't routines, the C<leave> method is used
+instead. (It can be taken to mean either "go away from" or "bequeath
+to your successor" as appropriate.) The object specifies the scope to exit,
+and the method's arguments specify the return value. If the object
+is omitted (by use of the function or listop forms), the innermost
+block is exited. Otherwise you must use something like C<context>
+or C<&?BLOCK> or a contextual variable to specify the scope you
+want to exit. A label (such as a loop label) previously seen in
+the lexical scope also works as a kind of singleton context object:
+it names a statement that is serving both as an outer lexical scope
+and as a context in the current dynamic scope.
+
+As with C<return>, the arguments are taken to be a C<Capture> holding the
+return values.
+
+ leave; # return from innermost block of any kind
+ context(Method).leave; # return from innermost calling method
+ &?ROUTINE.leave(1,2,3); # Return from current sub. Same as: return 1,2,3
+ &?ROUTINE.leave <== 1,2,3; # same thing, force return as feed
+ OUTER.leave; # Return from OUTER label in lexical scope
+ &foo.leave: 1,2,3; # Return from innermost surrounding call to &foo
+
+Note that these are equivalent in terms of control flow:
+
+ COUNT.leave;
+ last COUNT;
+
+However, the first form explicitly sets the return value for the
+entire loop, while the second implicitly returns all the previous
+successful loop iteration values as a list comprehension. (It may,
+in fact, be too late to set a return value for the loop if it is
+being evaluated lazily!) A C<leave>
+from the inner loop block, however, merely specifies the return value for
+that iteration:
+
+ for 1..10 { leave $_ * 2 } # 2..20
+
+Note that this:
+
+ leave COUNT;
+
+will always be taken as the function, not the method, so it returns
+the C<COUNT> object from the innermost block. The indirect object form
+of the method always requires a colon:
+
+ leave COUNT: ;
+
+=head2 Temporization
+
+The C<temp> macro temporarily replaces the value of an existing
+variable, subroutine, context of a function call, 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 C<Code> object 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 $.WHICH() at {caller.location}\n";
+ my $restorer = $.SUPER::TEMP();
+ return {
+ print "Restoring $.WHICH() 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
+
+Note that C<temp> must be a macro rather than a function because the
+temporization must be arranged before the function causes any state
+changes, and if it were a normal argument to a normal function, the state
+change would be happen before C<temp> got control.
+
+Hypothetical variables use the same mechanism, except that the restoring
+closure is called only on failure.
+
+Note that contextual variables may be a better solution than temporized
+globals in the face of multithreading.
+
+=head2 Wrapping
+
+Every C<Routine> object has a C<.wrap> method. This method expects a
+single C<Code> argument. Within the code, the special C<callsame>,
+C<callwith>, C<nextsame> and C<nextwith> functions will invoke the
+original routine, but do not introduce an official C<CALLER> frame:
+
+ sub thermo ($t) {...} # set temperature in Celsius, returns old value
+
+ # Add a wrapper to convert from Fahrenheit...
+ $handle = &thermo.wrap( { callwith( ($^t-32)/1.8 ) } );
+
+The C<callwith> function lets you pass your own arguments to the wrapped
+function. The C<callsame> function takes no argument; it
+implicitly passes the original argument list through unchanged.
+
+The call to C<.wrap> replaces the original C<Routine> with the C<Code>
+argument, and arranges that any call to C<callsame>, C<callwith>,
+C<nextsame> or C<nextwith> invokes the previous version of the
+routine. 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 ) }
+
+except that C<&thermo> is mutated in-place, so C<&thermo.WHICH> stays the same
+after the C<.wrap>.
+
+The call to C<.wrap> returns a unique handle that can later be passed to
+the C<.unwrap> method, to undo the wrapping:
+
+ &thermo.unwrap($handle);
+
+This does not affect any other wrappings placed to the routine.
+
+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( { callwith($^t + 273.16) } );
+
+The entire argument list may be captured by binding to a C<Capture> parameter.
+It can then be passed to C<callwith> using that name:
+
+ # Double the return value for &thermo
+ &thermo.wrap( -> |$args { callwith(|$args) * 2 } );
+
+In this case only the return value is changed.
+
+The wrapper is not required to call the original routine; it can call another
+C<Code> object by passing the C<Capture> to its C<callwith> method:
+
+ # Transparently redirect all calls to &thermo to &other_thermo
+ &thermo.wrap( sub (|$args) { &other_thermo.callwith(|$args) } );
+
+or more briefly:
+
+ &thermo.wrap( { &other_thermo.callsame } );
+
+Since the method versions of C<callsame>, C<callwith>, C<nextsame>,
+and C<nextwith> specify an explicit destination, their semantics do
+not change outside of wrappers. However, the corresponding functions
+have no explicit destination, so instead they implicitly call the
+next-most-likely method or multi-sub; see S12 for details.
+
+As with any return value, you may capture the returned C<Capture> of C<call>
+by binding:
+
+ my |$retval := callwith(|$args);
+ ... # postprocessing
+ return |$retval;
+
+Alternately, you may prevent any return at all by using the variants
+C<nextsame> and C<nextwith>. Arguments are passed just as with
+C<callsame> and C<callwith>, but a tail call is explicitly enforced;
+any code following the call will be unreached, as if a return had
+been executed there before calling into the destination routine.
+
+Within an ordinary method dispatch these functions treat the rest
+of the dispatcher's candidate list as the wrapped function, which
+generally works out to calling the same method in one of our parent
+(or older sibling) classes. Likewise within a multiple dispatch the
+current routine may defer to candidates further down the candidate
+list. Although not necessarily related by a class hierarchy, such
+later candidates are considered more generic and hence likelier
+to be able to handle various unforeseen conditions (perhaps).
+
+=head2 The C<&?ROUTINE> object
+
+C<&?ROUTINE> is always an alias for the lexically innermost C<Routine>
+(which may be a C<Sub>, C<Method>, or C<Submethod>), so you can specify
+tail-recursion on an anonymous sub:
+
+ my $anonfactorial = sub (Int $n) {
+ return 1 if $n<2;
+ return $n * &?ROUTINE($n-1);
+ };
+
+You can get the current routine name by calling C<&?ROUTINE.name>.
+(The outermost routine at a file-scoped compilation unit is always
+named C<&MAIN> in the file's package.)
+
+Note that C<&?ROUTINE> refers to the current single sub, even if it is
+declared "multi". To redispatch to the entire suite under a given short
+name, just use the named form, since there are no anonymous multis.
+
+=head2 The C<&?BLOCK> object
+
+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<&?BLOCK.labels> contains a list of all labels of the current block.
+This is typically matched by saying
+
+ if &?BLOCK.labels.any eq 'Foo' {...}
+
+If the innermost lexical block happens to be the main block of a C<Routine>,
+then C<&?BLOCK> just returns the C<Block> object, not the C<Routine> object
+that contains it.
+
+[Note: to refer to any C<$?> or C<&?> variable at the time the sub or
+block is being compiled, use the C<< COMPILING:: >> pseudopackage.]
+
+=head2 Currying
+
+Every C<Code> object has a C<.assuming> method. This method does a partial
+binding of a set of arguments to a signature and returns a new function
+that takes only the remaining arguments.
+
+ &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 C<Code> object 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
+a C<.assuming> method, allowing the user to bind parameters in all the
+module's subroutines/methods/etc. simultaneously:
+
+ (use IO::Logging).assuming(logfile => ".log");
+
+This special form should generally be restricted to named parameters.
+
+To curry a particular multi variant, it may be necessary to specify the type
+for one or more of its parameters:
+
+ &woof ::= &bark:(Dog).assuming :pitch<low>;
+ &pine ::= &bark:(Tree).assuming :pitch<yes>;
+
+=head2 Macros
+
+Macros are functions or operators that are called by the compiler as
+soon as their arguments are parsed (if not sooner). The syntactic
+effect of a macro declaration or importation is always lexically
+scoped, even if the name of the macro is visible elsewhere. As with
+ordinary operators, macros may be classified by their grammatical
+category. For a given grammatical category, a default parsing rule or
+set of rules is used, but those rules that have not yet been "used"
+by the time the macro keyword or token is seen can be replaced by
+use of "is parsed" trait. (This means, for instance, that an infix
+operator can change the parse rules for its right operand but not
+its left operand.)
+
+In the absence of a signature to the contrary, a macro is called as
+if it were a method on the current match object returned from the
+grammar rule being reduced; that is, all the current parse information
+is available by treating C<self> as if it were a C<$/> object.
+[Conjecture: alternate representations may be available if arguments
+are declared with particular AST types.]
+
+Macros may return either a string to be reparsed, or a syntax tree
+that needs no further parsing. The textual form is handy, but the
+syntax tree form is generally preferred because it allows the parser
+and debugger to give better error messages. Textual substitution
+on the other hand tends to yield error messages that are opaque to
+the user. Syntax trees are also better in general because they are
+reversible, so things like syntax highlighters can get back to the
+original language and know which parts of the derived program come
+from which parts of the user's view of the program. Nevertheless,
+it's difficult to return a syntax tree for an unbalanced construct,
+and in such cases a textual macro may be a clearer expression of the
+evil thing you're trying to do.
+
+If you call a macro at runtime, the result of the macro is automatically
+evaluated again, so the two calls below print the same thing:
+
+ macro f { '1 + 1' }
+ say f(); # compile-time call to &f
+ say &f(); # runtime call to &f
+
+=head2 Quasiquoting
+
+In aid of returning syntax tree, Perl provides a "quasiquoting"
+mechanism using the quote C<quasi>, followed by a block intended to
+represent an AST:
+
+ return quasi { say "foo" };
+
+Modifiers to the C<:code> adverb can modify the operation:
+
+ :ast(MyAst) # Default :ast(AST)
+ :lang(Ruby) # Default :lang($?PARSER)
+ :unquote<[: :]> # Default "triple rule"
+
+Within a quasiquote, variable and function names resolve according
+to the lexical scope of the macro definition. Unrecognized symbols raise
+errors when the macro is being compiled, I<not> when it's being used.
+
+To make a symbol resolve to the (partially compiled) scope of the macro
+call, use the C<COMPILING::> pseudo-package:
+
+ macro moose () { quasi { $COMPILING::x } }
+
+ moose(); # macro-call-time error
+ my $x;
+ moose(); # resolves to 'my $x'
+
+If you want to mention symbols from the scope of the macro call, use the
+import syntax as modifiers to C<:code>:
+
+ :COMPILING<$x> # $x always refers to $x in caller's scope
+ :COMPILING # All free variables fallback to caller's scope
+
+If those symbols do not exist in the scope of the compiling scope, a
+compile-time exception is thrown at macro call time.
+
+Similarly, in the macro body you may either refer to the C<$x> declared in the
+scope of the macro call as C<$COMPILING::x>, or bind to them explicitly:
+
+ my $x := $COMPILING::x;
+
+You may also use an import list to bind multiple symbols into the
+macro's lexical scope:
+
+ require COMPILING <$x $y $z>;
+
+Note that you need to use the run-time C<:=> and C<require> forms, not C<::=>
+and C<use>, because the macro caller's compile-time is the macro's runtime.
+
+=head2 Splicing
+
+Bare AST variables (such as the arguments to the macro) may not be
+spliced directly into a quasiquote because they would be taken as
+normal bindings. Likewise, program text strings to be inserted need
+to be specially marked or they will be bound normally. To insert a
+"unquoted" expression of either type within a quasiquote, use the
+quasiquote delimiter tripled, typically a bracketing quote of some sort:
+
+ return quasi { say $a + {{{ $ast }}} }
+ return quasi [ say $a + [[[ $ast ]]] ]
+ return quasi < say $a + <<< $ast >>> >
+ return quasi ( say $a + ((( $ast ))) )
+
+The delimiters don't have to be bracketing quotes, but the following
+is probably to be construed as Bad Style:
+
+ return quasi / say $a + /// $ast /// /
+
+(Note to implementors: this must not be implemented by finding
+the final closing delimiter and preprocessing, or we'll violate our
+one-pass parsing rule. Perl 6 parsing rules are parameterized to know
+their closing delimiter, so adding the opening delimiter should not
+be a hardship. Alternately the opening delimiter can be deduced from
+the closing delimiter. Writing a rule that looks for three opening
+delimiters in a row should not be a problem. It has to be a special
+grammar rule, though, not a fixed token, since we need to be able to
+nest code blocks with different delimiters. Likewise when parsing the
+inner expression, the inner parser subrule is parameterized to know that
+C<}}}> or whatever is its closing delimiter.)
+
+Unquoted expressions are inserted appropriately depending on the
+type of the variable, which may be either a syntax tree or a string.
+(Again, syntax tree is preferred.) The case is similar to that of a
+macro called from within the quasiquote, insofar as reparsing only
+happens with the string version of interpolation, except that such
+a reparse happens at macro call time rather than macro definition
+time, so its result cannot change the parser's expectations about
+what follows the interpolated variable.
+
+Hence, while the quasiquote itself is being parsed, the syntactic
+interpolation of a unquoted expression into the quasiquote always
+results in the expectation of an operator following the variable.
+(You must use a call to a submacro if you want to expect something
+else.) Of course, the macro definition as a whole can expect
+whatever it likes afterwards, according to its syntactic category.
+(Generally, a term expects a following postfix or infix operator,
+and an operator expects a following term or prefix operator. This
+does not matter for textual macros, however, since the reparse of
+the text determines subsequent expectations.)
+
+Quasiquotes default to hygienic lexical scoping, just like closures.
+The visibility of lexical variables is limited to the quasi expression
+by default. A variable declaration can be made externally visible using
+the C<COMPILING::> pseudo-package. Individual variables can be made visible,
+or all top-level variable declarations can be exposed using the
+C<quasi :COMPILING> form.
+
+Both examples below will add C<$new_variable> to the lexical scope of
+the macro call:
+
+ quasi { my $COMPILING::new_variable; my $private_var; ... }
+ quasi :COMPILING { my $new_variable; { my $private_var; ... } }
+
+(Note that C<:COMPILING> has additional effects described in L<Macros>.)
+
+=head1 Other matters
+
+
+=head2 Anonymous hashes vs blocks
+
+C<{...}> is always a block. However, if it is completely empty or
+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 object.
+
+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:
+
+ $obj = sub { 1, 2, 3, 4, 5, 6 }; # Anonymous sub returning list
+ $obj = { 1, 2, 3, 4, 5, 6 }; # Anonymous sub returning list
+ $obj = { 1=>2, 3=>4, 5=>6 }; # Anonymous hash
+ $obj = { 1=>2, 3, 4, 5, 6 }; # Anonymous hash
+ $obj = hash( 1, 2, 3, 4, 5, 6 ); # Anonymous hash
+ $obj = hash 1, 2, 3, 4, 5, 6 ; # Anonymous hash
+ $obj = { pair 1, 2, 3, 4, 5, 6 }; # Anonymous hash
+
+
+=head2 Pairs as lvalues
+
+Since they are immutable, Pair objects may not be directly assigned:
+
+ (key => $var) = "value"; # ERROR
+
+However, when binding pairs, names can be used to "match up" lvalues
+and rvalues, provided you write the left side as a signature using
+C<:(...)> notation:
+
+ :(:who($name), :why($reason)) := (why => $because, who => "me");
+
+(Otherwise the parser doesn't know it should parse the insides as a
+signature and not as an ordinary expression until it gets to the C<:=>,
+and that would be bad. Alternately, the C<my> declarator can also
+force treatment of its argument as a signature.)
+
+=head2 Out-of-scope names
+
+C<< GLOBAL::<$varname> >> specifies the C<$varname> declared in the C<*>
+namespace. Or maybe it's the other way around...
+
+C<< CALLER::<$varname> >> specifies the C<$varname> visible in
+the dynamic scope from which the current block/closure/subroutine
+was called, provided that variable is declared with the "C<is context>"
+trait. (Implicit lexicals such as C<$_> are automatically
+assumed to be contextual.)
+
+C<< CONTEXT::<$varname> >> specifies the C<$varname> visible in the
+innermost dynamic scope that declares the variable with the "C<is context>"
+trait.
+
+C<< MY::<$varname> >> specifies the lexical C<$varname> declared in the current
+lexical scope.
+
+C<< OUR::<$varname> >> specifies the C<$varname> declared in the current
+package's namespace.
+
+C<< COMPILING::<$varname> >> specifies the C<$varname> declared (or about
+to be declared) in the lexical scope currently being compiled.
+
+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).
+
+=head2 Declaring a C<MAIN> subroutine
+
+Ordinarily a top-level Perl "script" just evaluates its anonymous
+mainline code and exits. During the mainline code, the program's
+arguments are available in raw form from the C<@*ARGS> array. At the end of
+the mainline code, however, a C<MAIN> subroutine will be called with
+whatever command-line arguments remain in C<@*ARGS>. This call is
+performed if and only if:
+
+=over
+
+=item a)
+
+the compilation unit was directly invoked rather than
+by being required by another compilation unit, and
+
+=item b)
+
+the compilation unit declares a C<Routine> named "C<MAIN>", and
+
+=item c)
+
+the mainline code is not terminated prematurely, such as with an explicit call
+to C<exit>, or an uncaught exception.
+
+=back
+
+The command line arguments (or what's left of them after mainline
+processing) is magically converted into a C<Capture> and passed to
+C<MAIN> as its arguments, so switches may be bound as named args and
+other arguments to the program may be bound to positional parameters
+or the slurpy array:
+
+ sub MAIN ($directory, :$verbose, *%other, *@filenames) {
+ for @filenames { ... }
+ }
+
+If C<MAIN> is declared as a set of multi subs, MMD dispatch is performed.
+
+As with module and class declarations, a sub declaration
+ending in semicolon is allowed at the outermost file scope if it is the
+first such declaration, in which case the rest of the file is the body:
+
+ sub MAIN ($directory, :$verbose, *%other, *@filenames);
+ for @filenames { ... }
+
+This form is allowed only for simple subs named C<MAIN> that are intended
+to be run from the command line.
+Proto or multi definitions may not be written in semicolon form,
+nor may C<MAIN> subs within a module or class. (A C<MAIN> routine
+is allowed in a module or class, but is not usually invoked unless
+the file is run directly (see a above). This corresponds to the
+"unless caller" idiom of Perl 5.) In general, you may have only one
+semicolon-style declaration that controls the whole file.
+
+If an attempted dispatch to C<MAIN> fails, the C<USAGE> routine is called.
+If there is no C<USAGE> routine, a default message is printed. This
+usage message is automatically generated from the signature (or
+signatures) of C<MAIN>. This message is generated at compile time,
+and hence is available at any later time as C<$?USAGE>.
+
+Common Unix command-line conventions are mapped onto the capture
+as follows:
+
+ On command line... $*ARGS capture gets...
+
+ -name :name
+ -name=value :name<value>
+ -name="spacy value" :name«'spacy value'»
+ -name='spacy value' :name«'spacy value'»
+ -name=val1,'val 2', etc :name«val1 'val 2' etc»
+
+ --name :name # only if declared Bool
+ --name=value :name<value> # don't care
+ --name value :name<value> # only if not declared Bool
+
+ --name="spacy value" :name«'spacy value'»
+ --name "spacy value" :name«'spacy value'»
+ --name='spacy value' :name«'spacy value'»
+ --name 'spacy value' :name«'spacy value'»
+ --name=val1,'val 2', etc :name«val1 'val 2' etc»
+ --name val1 'val 2' etc :name«val1 'val 2' etc» # only if declared @
+ -- # end named argument processing
+
+ +name :!name
+ +name=value :name<value> but False
+ +name="spacy value" :name«'spacy value'» but False
+ +name='spacy value' :name«'spacy value'» but False
+ +name=val1,'val 2', etc :name«val1 'val 2' etc» but False
+
+ :name :name
+ :!name :!name # potential conflict with ! histchar
+ :/name :!name # potential workaround?
+ :name=value :name<value>
+ :name="spacy value" :name«'spacy value'»
+ :name='spacy value' :name«'spacy value'»
+ :name=val1,'val 2', etc :name«val1 'val 2' etc»
+
+Exact Perl 6 forms are okay if quoted from shell processing:
+
+ ':name<value>' :name<value>
+ ':name(42)' :name(42)
+
+For security reasons, only constants are allowed as arguments, however.
+
+The default C<Capture> mapper pays attention to declaration of C<MAIN>'s
+parameters to resolve certain ambiguities. A C<--foo> switch needs to
+know whether to treat the next word from the command line as an argument.
+(Allowing the spacey form gives the shell room to do various things to
+the argument.) The short C<-foo> form never assumes a separate argument,
+and you must use C<=>. For the C<--foo> form, if there is a named parameter
+corresponding to the switch name, and it is of type C<Bool>, then no argument
+is expected. Otherwise an argument is expected. If the parameter is of
+a non-slurpy array type, all subsequent words up to the next command-line
+switch (or the end of the list) are bound to that parameter.
+
+As usual, switches are assumed to be first, and everything after
+the first non-switch, or any switches after a C<-->, are treated
+as positionals or go into the slurpy array (even if they look like
+switches). Other policies may easily be introduced by calling C<MAIN>
+explicitly. For instance, you can parse your arguments with a grammar
+and pass the resulting C<Match> object as a C<Capture> to C<MAIN>:
+
+ @*ARGS ~~ /<MyGrammar::top>/;
+ MAIN(|$/);
+ exit;
+
+ sub MAIN ($frompart, $topart, *@rest) {
+ if $frompart<foo> { ... }
+ if $topart<bar><baz> { ... }
+ }
+
+This will conveniently bind top-level named matches to named
+parameters, but still give you access to nested matches through those
+parameters, just as any C<Match> object would. Of course, in this example,
+there's no particular reason the sub has to be named C<MAIN>.
+
+To give both a long and a short switch name, you may use the pair
+notation. The key will be considered the short switch name, while
+the variable name will be considered the long switch name. So if
+the previous declaration had been:
+
+ sub MAIN (:f($frompart), :t($topart), *@rest)
+
+then you could invoke the program with either C<-f> or C<--frompart>
+to specify the first parameter. Likewise you could use either C<-t>
+or C<--topart> for the second parameter.
+
+If a switch of the form C<-abc> cannot be matched against any
+particular parameter, an attempt will be made to match it as if it
+had been written C<-a -b -c>.
+
+=head2 Implementation note on autothreading of only subs
+
+The natural way to implement autothreading for multi subs is to
+simply have the junctional signatures (the ones that can accept
+Objects/Junctions as well as Any parameters) match more loosely than
+the non-autothreading versions, and let multiple dispatch find the
+appropriate sub based on the signature. Those generic routines
+then end up redispatching to the more specific ones.
+
+On the other hand, the natural implementation of only subs is to
+call the sub in question directly for efficiency (and maybe even
+inline it in some cases). That efficiency is, after all, the main
+reason for not just making all subs multi. However, this direct
+call conflicts with the desire to allow autothreading. It might
+be tempting to simply make everything multi dispatch underneath,
+and then say that the "only" declaration merely means that you get
+an error if you redeclare. And maybe that is a valid approach if
+the multiple dispatch mechanism is fast enough.
+
+However, a direct call still needs to bind its arguments to its
+parameters correctly, and it has to handle the case of failure to
+bind somehow. So it is also possible to implement autothreading
+of only subs based on failover from the binding failure. This could
+either be a one-shot failover followed by a conversion to a multi call,
+or it could failover every time you try to autothread. If we assume
+that junctional processing is likely to be fairly heavyweight most of
+the time compared to the cost of failing to bind, that tends to argue
+for failing over every time. This is also more conducive to inlining,
+since it's difficult to rewrite inlined calls.
+
+=for vim:set expandtab sw=4:
-
r24064 - docs/Perl6/Spec
by pugs-commits