Merge branch 'master' into newio

Conflicts:
	S16-io.pod

Not bothering to fix the conflicts

S03-operators.pod

@@ -8,8 +8,8 @@ Synopsis 3: Operators
 
     Created: 8 Mar 2004
 
-    Last Modified: 8 Apr 2015
-    Version: 287
+    Last Modified: 16 Oct 2015
+    Version: 288
 
 =head1 Overview
 
@@ -25,7 +25,7 @@ each level.  (Column 'A' is for "associativity", see following table.)
     A  Level             Examples
     =  =====             ========
     O  Terms             42 3.14 "eek" qq["foo"] $x :!verbose @$array
-    L  Method postfix    .meth .+ .? .* .() .[] .{} .<> .«» .:: .= .^ .:
+    L  Method postfix    .meth .+ .? .* .() .[] .{} .<> .«» .:: .= .^ .: i
     N  Autoincrement     ++ --
     R  Exponentiation    **
     L  Symbolic unary    ! + - ~ ? | || +^ ~^ ?^ ^
@@ -46,7 +46,7 @@ each level.  (Column 'A' is for "associativity", see following table.)
     X  Comma operator    , :
     X  List infix        Z minmax X X~ X* Xeqv ...
     R  List prefix       print push say die map substr ... [+] [*] any Z=
-    X  Loose and         and andthen
+    X  Loose and         and andthen notandthen
     X  Loose or          or xor orelse
     X  Sequencer         <== ==> <<== ==>>
     O  Terminator        ; {...} unless extra ) ] }
@@ -257,7 +257,7 @@ Subexpressions circumfixed by parentheses
 
 Parentheses are parsed on the inside as a semicolon-separated list
 of statements, which (unlike the statements in a block) returns the results
-of all the statements concatenated together as a C<List> of C<Parcel>.
+of all the statements concatenated together as a C<List> of C<List>.
 How that is subsequently treated depends on its eventual binding.
 
 =item *
@@ -315,10 +315,10 @@ comma on the right--see List prefix precedence below.
 
 =head2 Method postfix precedence
 
-All method postfixes start with a dot, though the dot is optional
-for subscripts.  Since these are the tightest standard operator,
-you can often think of a series of method calls as a single term that
-merely expresses a complicated name.
+All method postfixes (except for C<i>) start with a dot, though the dot is
+optional for subscripts. Since these are the tightest standard operator, you can
+often think of a series of method calls as a single term that merely expresses a
+complicated name.
 
 See L<S12> for more discussion of single dispatch method calls.
 
@@ -395,6 +395,17 @@ Dotted postfix form of any other prefix operator
 
 =item *
 
+Imaginary number postfix
+
+    42i
+    $foo\i
+
+The only operator on this level that does not start with a dot. Turns a number
+into a purely-imaginary number (a C<Complex> with a zero real part). Must be
+backslashed if after a name, including C<Inf> and C<NaN>.
+
+=item *
+
 There is specifically no C<< infix:<.> >> operator, so
 
     $foo . $bar
@@ -689,9 +700,9 @@ argument.
 
 C<< prefix:<||> >>, flatten object into semicolon list
 
-    || $parcel
+    || $list
 
-Interpolates the elements of the C<Parcel> (or any other ordered value)
+Interpolates the elements of the C<List> (or any other ordered or iterable value)
 into the current argument list as if they had been specified literally,
 separated by semicolons, that is, at the multi-dimensional level.
 It is an error to use this operator outside of a lol context; in
@@ -1072,8 +1083,8 @@ C<< infix:<xx> >>, expression repetition operator
     @list xx $count
 
 Evaluates the left argument the number of times specified by the right
-argument.  Each evaluation is in list context, and returns a C<Parcel>.
-The result of all these evaluations is returned as a list of C<Parcels>
+argument.  Each evaluation is in list context, and returns a C<Seq>.
+The result of all these evaluations is returned as a list of arrays
 (which will behave differently depending on whether it's bound into
 a flat context or a lol context).
 
@@ -1926,7 +1937,7 @@ if they do match you may interleave unrelated sequences:
 
     1,1,{ $^a + 1, $^b * 2 }...*   # 1,1,2,2,3,4,4,8,5,16,6,32...
 
-Note in this case that the any limit test is applied to the entire parcel
+Note in this case that the any limit test is applied to the entire list
 returned from the function, which contains two values.
 
 A sequence generated from an explicit function places no type
@@ -2264,7 +2275,7 @@ the actual produced length, not C<Inf>.
 
 =back
 
-Many of these operators return a list of C<Parcel>s, which depending on
+Many of these operators return a list of C<List>s or C<Seq>s, which depending on
 context may or may not flatten them all out into one flat list.  The
 default is to flatten, but see the contextualizers below.
 
@@ -2483,7 +2494,7 @@ to return any actual type that does the role in question.
 
 Unless applied directly to a scalar variable, as in C<@$a>, these
 may only be applied with explicit parens around an argument that
-is processed as a bare C<Parcel> object, not a flattening list:
+is processed as a bare C<List> object, not a flattening list:
 
      $(1,2 Z 3,4)      # Scalar((1,3),(2,4))
      @(1,2 Z 3,4)      # ((1,3),(2,4))
@@ -2492,10 +2503,10 @@ is processed as a bare C<Parcel> object, not a flattening list:
      $(1,2 X 3,4)      # Scalar((1,3),(1,4),(2,3),(2,4))
      @(1,2 X 3,4)      # ((1,3),(1,4),(2,3),(2,4))
 
-(Note, internal parens indicate nested C<Parcel> structure here,
+(Note, internal parens indicate nested C<List> structure here,
 since there is no flattening.)
 
-Since a C<Parcel> with one argument is transparent, there can be no
+Since a C<List> with one argument is transparent, there can be no
 difference between the meaning of C<@($a)> and C<@$a>.
 
 =item *
@@ -2509,8 +2520,8 @@ The new name for Perl 5's C<scalar> contextualizer.  Equivalent to C<$(...)>
 We still call the values scalars, and talk about "scalar operators", but
 scalar operators are those that put their arguments into item context.
 
-If given a list, this function makes a C<Parcel> object from it.  The function
-is agnostic about any C<Parcel> embedded in such a sequence, and any contextual
+If given a list, this function makes a C<List> object from it.  The function
+is agnostic about any C<List> embedded in such a sequence, and any contextual
 decisions will be deferred until subsequent use of the contents.
 
 Note that this parses as a list operator, not a unary prefix operator,
@@ -2537,18 +2548,7 @@ The C<flat> contextualizer
 
 Forces the subsequent expression to be evaluated in a flattening
 list context.  The result will be recursively flattened, i.e.,
-contain no embedded C<Parcel> objects.
-
-=item *
-
-The C<lol> contextualizer
-
-    lol foo()
-
-Forces the subsequent expression to be evaluated in list-of-lists
-context.  This is typically used to form a multidimensional slice.
-A parcel potentially containing subparcels will be transformed into
-a list of lists, specifically of type C<LoL>.
+contain no embedded C<List>, C<Seq> or C<Range> objects.
 
 =item *
 
@@ -2557,7 +2557,8 @@ The C<hash> contextualizer
     hash foo()
 
 Forces the subsequent expression to be evaluated in hash context.
-The expression is evaluated in list context (flattening any C<Parcel>s),
+The expression is evaluated in list context (flattening any C<List>s or
+C<Seq>s),
 then a hash will be created from the list, taken as a list of C<Pair>s.
 (Any element in the list that is not a C<Pair> will pretend to be a key
 and grab the next value in the list as its value.)  Equivalent to
@@ -2605,6 +2606,8 @@ is equivalent to
 
 There is no corresponding high-precedence version.
 
+If you wish to have the same semantics in the opposite order, use the C<with> statement modifier.
+
 =back
 
 =head2 Loose or precedence
@@ -2646,18 +2649,20 @@ right argument.
 If the right side is a block or pointy block, the result of the left
 side is bound to any arguments of the block.  If the right side is
 not a block, a block scope is assumed around the right side, and the
-result of the left side is implicitly bound to C<$!> for the scope
+result of the left side is implicitly bound to C<$_> for the scope
 of the right side.  That is,
 
     test1() orelse test2()
 
 is equivalent to
 
-    test1() orelse -> $! { test2() }
+    test1() orelse -> $_ { test2() }
 
-(The high-precedence C<//> operator is similar, but does not set C<$!> or
+(The high-precedence C<//> operator is similar, but does not set C<$_> or
 treat blocks specially.)
 
+If you wish to have the same semantics in the opposite order, use the C<without> statement modifier.
+
 =back
 
 =head2 Terminator precedence
@@ -2681,7 +2686,7 @@ Semicolon: C<;>
 
 The context determines how the expressions terminated by semicolon
 are interpreted.  At statement level they are statements.  Within a
-bracketing construct they are interpreted as lists of C<Parcel>s,
+bracketing construct they are interpreted as lists of C<List>s,
 which in lol context will be treated as the multiple dimensions of a
 multidimensional slice.  (Other contexts may have other interpretations
 or disallow semicolons entirely.)
@@ -2886,7 +2891,7 @@ Unary C<~> now imposes a string (C<Stringy>) context on its
 argument, and C<+> imposes a numeric (C<Numeric>) context (as opposed
 to being a no-op in Perl 5).  Along the same lines, C<?> imposes
 a boolean (C<Bool>) context, and the C<|> unary operator imposes
-a function-arguments (C<Parcel> or C<Capture>) context on its argument.
+a function-arguments (C<List> or C<Capture>) context on its argument.
 Unary sigils are allowed when followed by a C<$> sigil on a scalar variable;
 they impose the container context implied by their sigil.
 As with Perl 5, however, C<$$foo[bar]> parses as C<( $($foo) )[bar]>,
@@ -2950,7 +2955,7 @@ written: C<<< << ... >> >>>.
 
 =item *
 
-Comma C<,> now constructs a C<Parcel> object from its operands.  You have to
+Comma C<,> now constructs a C<List> object from its operands.  You have to
 use a C<[*-1]> subscript to get the last one.
 (Note the C<*>.  Negative subscripts no longer implicitly count from
 the end; in fact, the compiler may complain if you use C<[-1]> on an
@@ -3717,7 +3722,7 @@ as a default because the more specific types listed above it didn't match.
     Any         Callable:($)  item sub truth          X($_)
     Any         Callable:()   simple closure truth    X() (ignoring $_)
     Any         Bool      simple truth            X (treats Bool value as success/failure)
-    Any         List      list truth              X (treats list size as success/failure)
+    Positional  List      lists are comparable    $_ »~~« X (but dwims ** wildcards!)
     Any         Match     match success           X (treats Match value as success)
     Any         Nil       benign failure          X (treats Nil value as failure)
     Any         Failure   malign failure          X (passes Failure object through)
@@ -3737,7 +3742,6 @@ as a default because the more specific types listed above it didn't match.
     Mix         Mix       identical bags          $_ === X
     Any         Mixy      force mix comparison    $_.Mix === X.Mix
 
-    Positional  Array     arrays are comparable   $_ «===» X (dwims * wildcards!)
     Associative Array     keys/list are comparable +X == +$_ and $_{X.all}:exists
     Callable    Positional list vs predicate      so $_(X)
     Any         Positional lists are comparable   $_[] «===» X[]
@@ -3889,9 +3893,9 @@ Various proposed-but-deprecated smartmatch behaviors may be easily
     Array   Num    array element truth    .[X]
     Array   Num    array contains number  *,X,*
     Array   Str    array contains string  *,X,*
-    Array   Parcel array begins /w Parcel X,*
-    Array   Parcel array contains Parcel  *,X,*
-    Array   Parcel array ends with Parcel *,X
+    Array   List   array begins /w List   X,*
+    Array   List   array contains List    *,X,*
+    Array   List   array ends with List   *,X
     Hash    Str    hash element truth     .{X}
     Hash    Str    hash key existence     .{X}:exists
     Hash    Num    hash element truth     .{X}
@@ -3979,7 +3983,7 @@ of values encompassed by the intervals involved, for any orderable
 type such as real numbers, strings, or versions.  The result is
 defined as true if and only if all potential elements that would
 be matched by the left range are also matched by the right range.
-Hence it does not matter to what extent the bounds of a empty range
+Hence it does not matter to what extent the bounds of an empty range
 are "overspecified".  If the left range is empty, it always matches,
 because there exists no value to falsify it.  If the right range is
 empty, it can match only if the left range is also empty.
@@ -4606,7 +4610,7 @@ together, just as if you had written it out explicitly:
     [<] 1, 3, 5;      # 1 < 3 < 5
 
 For list infix operators, flattening is not done on the input list, so
-that multiple parcels may be passed in as comma-separated arguments:
+that multiple lists may be passed in as comma-separated arguments:
 
     [X~] (1,2), <a b>;  # 1,2 X~ <a b>
 
@@ -5334,7 +5338,7 @@ its bits at once using the C<< prefix:<|> >> operator:
 =head1 Traversing arrays in parallel
 
 In order to support parallel iteration over multiple arrays, Perl 6
-has a C<zip> function that builds a list of C<Parcel> objects from the
+has a C<zip> function that builds a list of C<List> objects from the
 elements of two or more arrays.  In ordinary list context this behaves
 as a list of C<Captures> and automatically flattens.