Author: larry
Date: Mon Jan 29 14:06:49 2007
New Revision: 13545
Modified:
doc/trunk/design/syn/S04.pod
Log:
Clarifications requested by gaal++.
Modified: doc/trunk/design/syn/S04.pod
==
--- doc/trunk/design/syn/S04.pod(original)
+++ doc/trunk/design/syn/S04.podMon Jan 29 14:06:49 2007
@@ -438,12 +438,19 @@
=head2 The gather statement
A variant of Cdo is Cgather. Like Cdo, it is followed by a
-statement or block, and executes it once. Unlike Cdo, it evaluates the
-statement or block in void context; its return
-value is instead specified by calling the Ctake function one or more times
-within the dynamic scope of the Cgather. The returned values are in the
-form of a lazy multislice, with each slice corresponding to one
-Ctake capture. (A multislice is lazily flattened in normal list context,
+statement or block, and executes it once. Unlike Cdo, it evaluates
+the statement or block in void context; its return value is instead
+specified by calling the Ctake list prefix operator one or more times
+within the dynamic scope of the Cgather. The Ctake function's
+signature is like that of Creturn; it merely captures the CCapture
+of its argments without imposing any additional constraints (in the
+absense of context propagation by the optimizer). The value returned
+by the Ctake to its own context is that same CCapture object (which
+is ignored when the Ctake is in void context). Regardless of the
+Ctake's context, the CCapture object is also added to the list of
+values being gathered, which is returned by the Cgather in the form
+of a lazy multislice, with each slice corresponding to one Ctake
+capture. (A multislice is lazily flattened in normal list context,
but you may unflatten it again with a C@@() contextualizer.)
Because Cgather evaluates its block or statement in void context,
@@ -458,8 +465,34 @@
$previous = take $_;
}
+The Ctake function essentially has two contexts simultaneously, the
+context in which the gather is operating, and the context in which the
+Ctake is operating. These need not be identical contexts, since they
+may bind or coerce the resulting captures differently:
+
+my @y;
+@x = gather for 1..2 { # @() context for list of captures
+my $x = take $_, $_ * 10; # $() context for individual capture
+push @y, $x;
+}
+# @x returns 1,10,2,20
+# @y returns [1,10],[2,20]
+
+Likewise, we can just remember the gather's result by binding and
+later coerce it:
+
+$c := gather for 1..2 {
+take $_, $_ * 10;
+}
+# @$c returns 1,10,2,20
+# @@$c returns [1,10],[2,20]
+# $$c returns [[1,10],[2,20]]
+
+Note that the Ctake itself is in void context in this example because
+the Cfor loop is in void context.
+
A Cgather is not considered a loop, but it is easy to combine with a loop
-as in the example above.
+statement as in the examples above.
=head2 Other Cdo-like forms
