Merge branch 'master' of github.com:perl6/specs

S02-bits.pod

@@ -777,7 +777,7 @@ return values are allowed, e.g. C<use native 'int';> and such.
 (The optimizer is also allowed to substitute such variants when it
 can determine that the final destination would store natively in
 any case, or that the variant could not possibly malfunction given
-the arguments.)  [Conjecture: we could allow an 'N' metoperator to
+the arguments.)  [Conjecture: we could allow an 'N' metaoperator to
 select the native variant on a case by case basis.]
 
 Numeric values in untyped variables use C<Int> and C<Num> semantics
@@ -1693,16 +1693,19 @@ behaves as a C<Set> of its keys.  (Since the only possible value of
 a C<SetHash> is the C<True> value, it need not be represented in
 the actual implementation with any bits at all.)
 
-A C<BagHash> is a C<QuantHash> of C<UInt> with default of 0.  If you
+A C<BagHash> is a C<QuantHash> of C<UInt> with a default of 0.  If you
 use the C<Hash> interface and increment an element of a C<BagHash>
 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 returns an undefined value.  When not
 used as a C<Hash> (that is, when used as an C<Array> or list or C<Bag>
-object) a C<BagHash> 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.)
+object) a C<BagHash> behaves as a C<Bag> of its pairs.
+
+A C<MixHash> is a C<QuantHash> of C<Real> with a default of 0.0.  If the
+value goes to 0 the element is automatically deleted.  When not used as a
+C<Hash> (that is, when used as an C<Array> or list or C<Mix> object) a
+C<MixHash> behaves as a C<Mix> of its pairs.
 
 As with C<Hash> types, C<Pair> and C<PairSeq> are mutable in their
 values but not in their keys.  (A key can be a reference to a mutable
@@ -1955,9 +1958,8 @@ C<Range>, C<Buf>, C<Parcel>, 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<PairSet>, C<Set>, C<Bag>, C<Mix>, or
-C<Capture>.  The C<Associative> role implies the ability to support
-C<< postcircumfix:<{ }> >>.
+role, such as C<Pair>, C<Set>, C<Bag>, C<Mix>, 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
@@ -2025,14 +2027,12 @@ The C<anon> declarator allows a declaration to provide a name that
 can be used in error messages, but that isn't put into any external symbol table:
 
     my $secret = anon sub marine () {...}
-    $secret(42)  # too many arguments to sub marine
+    $secret(42);  # too many arguments to sub marine
 
 However, the name is introduced into the scope of the declaration itself, so it
 may be used to call itself recursively:
 
-    my $secret =
-        anon sub tract($n) { say $n; tract($n-1) if $n }
-
+    my $secret = anon sub tract($n) { say $n; tract($n-1) if $n };
     $secret(5); # 5 4 3 2 1 0
 
 =head2 Invariant sigils
@@ -2058,7 +2058,8 @@ are any elements in the container.
 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
+hash values, constructors around objects, properly handle circular
+references etc., so that Perl can evaluate
 the result back to the same object.  The C<.perl> method will return
 a representation of the object on the assumption that, if the code is
 reparsed at some point, it will be used to regenerate the object as a
@@ -2477,7 +2478,6 @@ side effects, then returns the value of the final statement.  In order
 to do that in Perl 6, you need to use one of these constructs:
 
     do { my $x = 42; $x }
-    SEQ( my $x = 42; $x )
     $( my $x = 42; $x )
     @( my @x = 42,43; @x )
     %( my %x = a => 42; %x )
@@ -2675,23 +2675,19 @@ operators:
     print $( foo() )    # foo called in item context
     print %( foo() )   # foo called in hash context
 
-In declarative constructs bare sigils may be used as placeholders for
-anonymous variables:
+Bare sigils may be used as placeholders for anonymous variables:
 
     my ($a, $, $c) = 1..3;
     print unless (state $)++;
 
-Outside of declarative constructs you may use C<*> for a placeholder:
+Outside of declarative constructs you may also use C<*> for a placeholder:
 
     ($a, *, $c) = 1..3;
 
-Attempts to say something like:
+Which would be the same as:
 
     ($a, $, $c) = 1..3;
 
-will result in the message, "Anonymous variable requires declarator".
-
-
 =head2 Package-qualified names
 
 Ordinary package-qualified names look like they do in Perl 5:
@@ -3322,7 +3318,7 @@ These name the same module:
     use ThatModule:auth<Somebody>:ver<2.7.18.28.18>
     use ThatModule:ver<2.7.18.28.18>:auth<Somebody>
 
-Adverbial syntax will be described more fully later.
+Adverbial syntax is described in L</Adverbial Pair forms>.
 
 =head1 Literals
 
@@ -4433,7 +4429,7 @@ chunk has a C<.range> property that indicates its line number range
 within the source file.
 
 [Speculative]
-It may also be possible to treat a Pod object as an IO, to read the Pod
+It may also be possible to treat a Pod object as an IO::Handle, to read the Pod
 information line-by-line (like the C<DATA> filehandle in Perl 5, but
 for I<any> Pod block).
 

S03-operators.pod

@@ -9,13 +9,14 @@ Synopsis 3: Operators
     Luke Palmer <luke@luqui.org>
     Larry Wall <larry@wall.org>
     Darren Duncan <darren@darrenduncan.net>
+    Elizabeth Mattijsen <liz@dijkmat.nl>
 
 =head1 VERSION
 
     Created: 8 Mar 2004
 
-    Last Modified: 30 Aug 2014
-    Version: 281
+    Last Modified: 7 Oct 2014
+    Version: 282
 
 =head1 Overview
 
@@ -361,7 +362,7 @@ Meta-method call
     $obj.^meth
 
 The C<.^> operator calls a class metamethod;
-C<foo.^bar> is short for C<foo.HOW.bar>.
+C<foo.^bar> is short for C<foo.HOW.bar(foo)>.
 
 =item *
 
@@ -2443,7 +2444,7 @@ is processed as a bare C<Parcel> object, not a flattening list:
 
      $(1,2 Z 3,4)      # Scalar((1,3),(2,4))
      @(1,2 Z 3,4)      # ((1,3),(2,4))
-     %(1,2 Z 3,4)      # PairSeq(1 => 3, 2 => 4)
+     %(1,2 Z 3,4)      # (1 => 3, 2 => 4)
 
      $(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))
@@ -2465,7 +2466,7 @@ 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<Seq> object from it.  The function
+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
 decisions will be deferred until subsequent use of the contents.
 
@@ -2761,7 +2762,7 @@ you can test anything for definedness or undefinedness:
 
 Using the pattern form, multiple tests may be combined via junctions:
 
-    given $handle {
+    given $path {
         when :r & :w & :x {...}
         when :!w | :!x    {...}
         when *            {...}
@@ -2781,29 +2782,29 @@ The pair forms are useful only for boolean tests because the method's
 value is evaluated as a Bool, so the
 method form must be used for any numeric-based tests:
 
-    if stat($filename).s > 1024 {...}
+    if $filename.IO.s > 1024 {...}
 
 However, these still work:
 
-    given $fh {
+    given $io {
         when :s  {...} # file has size > 0
         when :!s {...} # file size == 0
     }
 
 One advantage of the method form is that it can be used in places that
 require tighter precedence than C<~~> provides:
 
-    sort { $^a.M <=> $^b.M }, @files».IO
+    sort { $^a.modified <=> $^b.modified }, @files».IO
 
 though that's a silly example since you could just write:
 
-    sort { .M }, @files».IO
+    sort { .modified }, @files».IO
 
 But that demonstrates the other advantage of the method form, which is
 that it allows the "unary dot" syntax to test the current topic.
 
 Unlike in earlier versions of Perl 6, these filetest methods do not return
-stat buffers, but simple scalars of type C<Bool>, C<Int>, or C<Num>.
+stat buffers, but simple scalars of type C<Bool>, C<Int>, or C<Instant>.
 
 In general, the user need not worry about caching the stat buffer
 when a filename is queried.  The stat buffer will automatically be
@@ -2906,8 +2907,8 @@ written: C<<< << ... >> >>>.
 
 =item *
 
-Comma C<,> now constructs a C<Parcel> object from its
-operands.  In item context this turns into a C<Seq> object.  You have to use a C<[*-1]> subscript to get the last one.
+Comma C<,> now constructs a C<Parcel> 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
 object known at compile time not to have negative subscripts.)
@@ -3845,9 +3846,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   Seq    array begins with seq  X,*
-    Array   Seq    array contains seq     *,X,*
-    Array   Seq    array ends with seq    *,X
+    Array   Parcel array begins /w Parcel X,*
+    Array   Parcel array contains Parcel  *,X,*
+    Array   Parcel array ends with Parcel *,X
     Hash    Str    hash element truth     .{X}
     Hash    Str    hash key existence     .{X}:exists
     Hash    Num    hash element truth     .{X}
@@ -4412,8 +4413,8 @@ More generally, a dwimmy hyper operator works recursively for any object
 matching the C<Iterable> role even if the object itself doesn't support
 the operator in question:
 
-    Bag(3,8,[2,Seq(9,3)],8) >>->> 1;         # Bag(2,7,[1,Seq(8,2)],7)
-    Seq(3,8,[2,Seq(9,3)],8) >>->> (1,1,2,1); # Seq(2,7,[0,Seq(7,1)],7)
+    Bag(3,8,[2,(9,3)],8) >>->> 1;      # Bag(2,7,[1,(8,2)],7)
+    (3,8,[2,(9,3)],8) >>->> (1,1,2,1); # (2,7,[0,(7,1)],7)
 
 In particular, tree node types with C<Iterable> semantics enable visitation:
 
@@ -5293,7 +5294,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<Seq> objects from the
+has a C<zip> function that builds a list of C<Parcel> objects from the
 elements of two or more arrays.  In ordinary list context this behaves
 as a list of C<Captures> and automatically flattens.
 

S04-control.pod

@@ -377,7 +377,6 @@ object.  See L<S02> for a long definition of argument, but in short,
 it's either an ordinary object or a parcel containing multiple values.
 
 Normal flat list context ignores parcel boundaries and flattens the list.
-Slice context turns any parcel objects into C<Seq> objects.
 
 Iterations that return C<()> (such as by calling C<next> with no extra return
 arguments) return that C<()> as the next value, which will therefore disappear

S06-routines.pod

@@ -1298,7 +1298,7 @@ C<Pair> and C<Hash> become named arguments:
 Anything else that is C<Iterable> is simply turned into
 positional arguments:
 
-    |(1,2,3);         # Seq, becomes \(1,2,3)
+    |(1,2,3);         # Parcel, becomes \(1,2,3)
     |(1..3);          # Range, becomes \(1,2,3)
     |(1..2, 3);       # Parcel, becomes \(1,2,3)
     |([x=>1, x=>2]);  # List (from an Array), becomes \((x=>1), (x=>2))