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.pod Mon Jan 29 14:06:49 2007
@@ -438,12 +438,19 @@
=head2 The gather statement
A variant of C<do> is C<gather>. Like C<do>, it is followed by a
-statement or block, and executes it once. Unlike C<do>, it evaluates the
-statement or block in void context; its return
-value is instead specified by calling the C<take> function one or more times
-within the dynamic scope of the C<gather>. The returned values are in the
-form of a lazy multislice, with each slice corresponding to one
-C<take> capture. (A multislice is lazily flattened in normal list context,
+statement or block, and executes it once. Unlike C<do>, it evaluates
+the statement or block in void context; its return value is instead
+specified by calling 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>; it merely captures the C<Capture>
+of its argments without imposing any additional constraints (in the
+absense of context propagation by the optimizer). The value returned
+by the C<take> to its own context is that same C<Capture> object (which
+is ignored when the C<take> is in void context). Regardless of the
+C<take>'s context, the C<Capture> object is also added to the list of
+values being gathered, which is returned by the C<gather> in the form
+of a lazy multislice, with each slice corresponding to one C<take>
+capture. (A multislice is lazily flattened in normal list context,
but you may "unflatten" it again with a C<@@()> contextualizer.)
Because C<gather> evaluates its block or statement in void context,
@@ -458,8 +465,34 @@
$previous = take $_;
}
+The C<take> function essentially has two contexts simultaneously, the
+context in which the gather is operating, and the context in which the
+C<take> 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 C<take> itself is in void context in this example because
+the C<for> loop is in void context.
+
A C<gather> 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 C<do>-like forms
XXX = gather {
YYY
take f();
ZZZ
}
sub f () {
return want.Scalar ?? 42 !! 54;
}
Which of XXX, YYY, and ZZZ influence whether the taken value is 42 or
54? Please confirm there's *no way* that &f is entered twice here :-)
(If I'm following correctly, then take's args are basically evaluated
in list context. If YYY is something like "$scalar = " that list gets
Captured, but there's still a list there.)
--
Gaal Yahas <ga...@forum2.org>
http://gaal.livejournal.com/
> +absense of context propagation by the optimizer). The value returned
Minor spelling nit: "absence"
--
brandon s. allbery [linux,solaris,freebsd,perl] all...@kf8nh.com
system administrator [openafs,heimdal,too many hats] all...@ece.cmu.edu
electrical and computer engineering, carnegie mellon university KF8NH