Author: lwall
Date: 2010-02-17 20:15:34 +0100 (Wed, 17 Feb 2010)
New Revision: 29768
Modified:
docs/Perl6/Spec/S02-bits.pod
docs/Perl6/Spec/S04-control.pod
Log:
[S02,S04] more clarification of when parcels are and aren't used.
Use "argument" as a technical term meaning either a real parcel or an object
that can be used independent of context as an argument (but return chunks
are also arguments in the old "parcel" sense.)
Modified: docs/Perl6/Spec/S02-bits.pod
===================================================================
--- docs/Perl6/Spec/S02-bits.pod 2010-02-17 16:41:32 UTC (rev 29767)
+++ docs/Perl6/Spec/S02-bits.pod 2010-02-17 19:15:34 UTC (rev 29768)
@@ -13,8 +13,8 @@
Created: 10 Aug 2004
- Last Modified: 13 Feb 2009
- Version: 199
+ Last Modified: 17 Feb 2009
+ Version: 200
This document summarizes Apocalypse 2, which covers small-scale
lexical items and typological issues. (These Synopses also contain
@@ -1831,12 +1831,12 @@
=item *
-A list of one or more objects may be grouped together by parentheses
-into a "parenthesis cell", or C<Parcel>. This kind of list should
-not be confused with the flattening list context. Instead, this is
-a raw syntactic list; no interpretation is made of the list without
-knowing what context it will be evaluated in. For example, when
-you say:
+A list of one or more comma-separated objects may be grouped together
+by parentheses into a "parenthesis cell", or C<Parcel>. This kind of
+list should not be confused with the flattening list context. Instead,
+this is a raw syntactic list that has not yet committed to flattening;
+no interpretation is made of the list inside without knowing what
+context it will be evaluated in. For example, when you say:
(1,2,3,:mice<blind>)
@@ -1846,34 +1846,84 @@
rhyme(1,2,3,:mice<blind>)
-the C<Parcel> is translated (at compile time, in this case)
-into a C<Capture> with 3 positionals and one named argument
-in preparation for binding.
+the syntactic C<Parcel> is translated (at compile time, in this case)
+into a C<Capture> object with three positionals and one named argument
+in preparation for binding. More generally, a parcel is transmuted
+to a capture any time it is bound to a complete signature.
-A parcel may be wrapped into an object with backslashed parens:
+You may force immediate conversion to a C<Capture> object by prefixing
+the parcel composer with a backslash:
$args = \(1,2,3,:mice<blind>)
-Values in the C<Parcel> object are parsed as ordinary expressions,
-and any functions mentioned are called, with their results placed
-as either a single item or subparcel within the outer parcel. Whether a
subparcel
-are subsequently flattened will depend on the eventual binding.
+Unlike C<Capture> objects, C<Parcel> objects are ephemeral, insofar as the
+user almost never sees one as a real standalone object, since binding or
+assignment always turns a parcel into something else. A parcel may generally
+only be preserved as a part of an outer parcel or capture object.
+Individual arguments in a parcel or capture composer are parsed as ordinary
+expressions, and any functions mentioned are called immediately, with
+each function's results placed as an argument (often a subparcel, if the
+function returns multiple values) within the outer parcel (or capture).
+Whether any given argument is flattened will depend on its eventual binding,
+and in general cannot be known at parcel/capture composition time.
+
+We use "argument" here to mean anything that would be taken as a single
+argument if bound to a positional or named parameter:
+
+ rhyme(1,2,3,:mice<blind>) # rhyme has 4 arguments
+ rhyme((1,2),3,:mice<blind>) # rhyme has 2 arguments
+ rhyme((1,2,3),:mice<blind>) # rhyme has 2 arguments
+ rhyme((1,2),(3,:mice<blind>)) # rhyme has 2 arguments
+ rhyme((1,2,3,:mice<blind>)) # rhyme has 1 argument
+
+In these examples, the first argument to the function is
+a parcel in all but the first case, where it is simply the
+literal integer 1. An argument is either of:
+
+=over
+
=item *
-If a C<Parcel> is bound to an individual parameter, the behavior
-depends on whether the parameter is "slicey" or "slurpy". Positional
-parameters and slice parameters call C<.getarg> on the internal
-iterator and just return the next syntactic argument (parcel or other object)
without flattening.
-(Such a parcel transmutes to a C<Seq> object.) Slurpy parameters
-call C<.get> on the internal iterator, which flattens any subparcels
-before pulling out the next item. In either case, no bare parcel
-object is seen as a normal parameter. (There is a way to bind the
-underlying parcel using backslash.)
+A parcel that groups together a sublist, or
-In contrast to parameter binding,
-if a C<Parcel> is bound to an entire signature, it will be transformed
-into a C<Capture> objects, which is much like a C<Parcel> but has its
+=item *
+
+Any other object that can function as a single argument.
+
+=back
+
+Looking at it the other way, all arguments that don't actually need to be
+wrapped up in a parcel are considered degenerate parcels in their
+own right when it comes to binding. Note that a capture is not
+considered a kind of parcel, so does not flatten in flat context.
+
+=item *
+
+When a C<Parcel> is bound to a parameter, the behavior depends on whether
+the parameter is "flattening" or "argumentative". Positional parameters
+and slice parameters are argumentative and call C<.getarg> on the internal
+iterator and just return the next syntactic argument (parcel or other object)
+without flattening. (A slice differs from an ordinary positional parameter
+in being "slurpy", that is, it is intended to fetch multiple values from
+the variadic region of the surrounding capture. Slurpy contexts come in
+both flattening (C<*> parameters) and slicing (C<**> parameters) forms.)
+
+The fact that a parameter is being bound implies that there is an outer
+capture being bound to a signature. The capture's iterator provides
+a C<.get> and a C<.getarg> method to tell the iterator what context to
+bind in. For positional/slice parameters, the C<.getarg> method returns
+the entire next argument from the iterator, but transmutes
+any outer C<Parcel> to a C<Seq> object; it returns other objects unchanged.
+In contrast, flat parameters call C<.get> on the capture's iterator, which
+flattens any subparcels before pulling out the next item. In either case,
+no bare parcel object is seen as a normal bound argument. (There is a way to
+bind the underlying parcel using backslash, however. This is how internal
+routines can deal with parcels as real objects.)
+
+In contrast to parameter binding, if a C<Parcel> is bound to an entire
+signature (typically as part of a function or method call), it will be
transformed
+first into a capture object, which is much like a parcel but has its
arguments divvied up into positional and named subsets for faster
binding. (Usually this transformation happens at compile time.)
If the first positional is followed by a colon instead of a comma,
@@ -1881,12 +1931,21 @@
that cares. It's illegal to use the colon in place of the comma
anywhere except after the first argument.
-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.
+Explicit binding to an individual variable is considered a form of signature
+binding, which is to say a declarator puts implicit signature parens
+around the unparenthesized form:
+ my (*...@x) := foo(); # signature binding
+ my *...@x := foo(); # same thing
+
+The parens are, of course, required if there is more than one parameter.
+
+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
@@ -1955,6 +2014,17 @@
=item *
+A C<CaptureCursor> object is a view into another capture with an associated
+start position. Such a cursor is essentially a pattern-matching state.
+Capture cursors are used for operations like C<grep> and C<map> and C<for>
+loops that need to apply a short signature multiple times to a longer list
+of values supplied by the base capture. When we say "capture" we sometimes
+mean either C<Capture> or C<CaptureCursor>. C<CaptureCursors> are also
+immutable. When pattern matching a signature against a cursor, you
+get a new cursor back which tells you the new position in the base capture.
+
+=item *
+
A signature object (C<Signature>) may be created with colon-prefixed parens:
my ::MySig ::= :(Int, Num, Complex, Status)
@@ -1963,9 +2033,13 @@
rather than ordinary expressions. See S06 for more details on the syntax
for parameters.
+Declarators generally make the colon optional:
+
+ my ($a,$b,$c); # parsed as signature
+
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
+When applied to a 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:
@@ -2972,7 +3046,7 @@
$a = \('a', 'b');
-and ends up as a non-flattening object (C<Scalar[Parcel]> or some such).
+and ends up as a non-flattening capture object).
Binding is different from assignment. If bound to a signature, the
C<< <a b> >> parcel will be promoted to a C<Capture> object, but if
@@ -2988,14 +3062,14 @@
$a = ('a');
$a = 'a';
-That is, a C<Parcel> is actually constructed by the comma, not by
+That is, a parcel is actually constructed by the comma, not by
the parens. To force a single value to become a composite object in
item context, either add a comma inside parens, or use an appropriate
constructor or composer for clarity as well as correctness:
$a = (< a >,);
$a = ('a',);
- $a = Parcel.new('a');
+ $a = Seq.new('a');
$a = ['a'];
For any item in the list that appears to be numeric, the literal is
Modified: docs/Perl6/Spec/S04-control.pod
===================================================================
--- docs/Perl6/Spec/S04-control.pod 2010-02-17 16:41:32 UTC (rev 29767)
+++ docs/Perl6/Spec/S04-control.pod 2010-02-17 19:15:34 UTC (rev 29768)
@@ -13,8 +13,8 @@
Created: 19 Aug 2004
- Last Modified: 16 Feb 2010
- Version: 94
+ Last Modified: 17 Feb 2010
+ Version: 95
This document summarizes Apocalypse 4, which covers the block and
statement syntax of Perl.
@@ -349,15 +349,18 @@
within the body of the loop. See below.
The value of a loop statement is the list of values from each
-iteration. Iterations that return a null list (such as by calling
-C<next> with no extra return arguments) interpolate no values in the
-resulting list. (This list is actually a two-dimensional list of
-C<Parcel>s (a "slice") with dimensional boundaries at each iteration.
-Normal list context ignores these boundaries and flattens the list.
-Slice context turns the parcels into sublists, so an iteration
-returning a null list does show up as a null subarray when viewed as
-a slice.)
+iteration. Each iteration's value is returned as a single "argument"
+object. See L<S02> for a long definition of argument, but in short,
+it's either an ordinary object or a parcel containing multiple values.
+Normal flat list context ignores parcel boundaries and flattens the list.
+Slice context turns any parcel objects into C<Seq> objects.
+
+Iterations that return Nil (such as by calling C<next> with no extra return
+arguments) return that Nil as the next value, which will therefore disappear
+when interpolated in flat context, but will interpolate a null Seq into slice
+context.
+
For finer-grained control of which iterations return values, use
C<gather> and C<take>.
@@ -365,8 +368,8 @@
possible to accidentally return a loop's return value when you were
only evaluating the loop for its side effects. If you do not wish
to accidentally return a list from the final loop statement in a
-subroutine, place an explicit return statement after it, or declare
-a return type of C<Void>.
+subroutine, place an explicit return statement after it, use a C<sink>
+statement prefix on the loop itself.
=head2 The C<while> and C<until> statements
X<while>X<until>
@@ -689,29 +692,30 @@
the C<take> list prefix operator one or more times within the dynamic scope of
the C<gather>. The C<take> function's signature is like that of C<return>;
while having the syntax of a list operator, it merely returns a single item
-which if, if you return multiple items in a comma list, be wrapped up in a
-C<Parcel> object. No additional constraints are enforce by context, since
-all context is lazy in Perl 6. The flattening or non-flattening of any such
-returned C<Parcel> will be dependent on how the gather's return iterator is
-iterated (with .get vs .getarg).
+or "argument" (see L<S02> for definition).
-The value returned by the C<take> to the C<take>'s own context is
-that same returned object (which is ignored when the C<take> is in
-sink context). Regardless of the C<take>'s immediate context, the
-object returned is also added to the list of values being gathered,
-which is returned by the C<gather> in the form of a lazy list (that
-is, an iterator, really), with each element of that list corresponding
-to one C<take> object (either a C<Parcel> or any other single object
-serving as a degenerate parcel).
+If you take multiple items in a comma list (since it is, after all, a list
+operator), they will be wrapped up in a C<Parcel> object for return as the
+next argument. No additional context is applied by the C<take> operator,
+since all context is lazy in Perl 6. The flattening or slicing of any such
+returned parcel will be dependent on how the C<gather>'s return iterator is
+iterated (with C<.get> vs C<.getarg>).
-Any C<Parcel>s in the returned list are normally flattened when bound
-into slurpy context. When bound into a slice context, however,
-the C<Parcel> objects become real C<Seq> objects that keep their
+The value returned by the C<take> to the C<take>'s own context is that same
+returned argument (which is ignored when the C<take> is in sink context).
+Regardless of the C<take>'s immediate context, the object returned is also
+added to the list of values being gathered, which is returned by the C<gather>
+as a lazy list (that is, an iterator, really), with each argument element
+of that list corresponding to one C<take>.
+
+Any parcels in the returned list are normally flattened when bound
+into flat context. When bound into a slice context, however,
+the parcel objects become real C<Seq> objects that keep their
identity as discrete sublists. The eventual binding context thus
determines whether to throw away or keep the groupings resulting from
-each individual C<take> call. Since most list contexts are flat
-rather than sliced, the boundaries between individual C<take>
-calls usually disappear.
+each individual C<take> call. Most list contexts are flat
+rather than sliced, so the boundaries between individual C<take>
+calls usually disappear. (FLAT is an acronym meaning Flat Lists Are Typical.
:)
Because C<gather> evaluates its block or statement in sink context,
this typically causes the C<take> function to be evaluated in sink
@@ -1373,7 +1377,12 @@
For phasers such as C<KEEP> and C<POST> that are run when exiting a
scope normally, the return value (if any) from that scope is available
-as the current topic within the phaser. (It is presented as a C<Parcel>
object.)
+as the current topic within the phaser. (It is presented as a argument,
+that is, either as parcel or an object that can stand alone in a list.
+In other words, it's exactly what C<return> is sending to the outside
+world in raw form, so that the phaser doesn't accidentally impose
+context prematurely.)
+
The topic of the outer block is still available as C<< OUTER::<$_> >>.
Whether the return value is modifiable may be a policy of the phaser
in question. In particular, the return value should not be modified
