Author: autrijus
Date: Sat Apr 15 06:17:49 2006
New Revision: 8698
Modified:
doc/trunk/design/syn/S02.pod
doc/trunk/design/syn/S03.pod
doc/trunk/design/syn/S06.pod
doc/trunk/design/syn/S09.pod
Log:
* Synopses: Change "Arguments" to "Capture" to avoid using a
plural word as a class name. (Also it makes it easier later
to say that "Match" is a subclass of "Capture".)
Modified: doc/trunk/design/syn/S02.pod
==============================================================================
--- doc/trunk/design/syn/S02.pod (original)
+++ doc/trunk/design/syn/S02.pod Sat Apr 15 06:17:49 2006
@@ -525,35 +525,33 @@
=item *
-An argument list object (C<Arguments>) may be created with backslashed parens:
+An argument list object (C<Capture>) may be created with backslashed parens:
$args = \(1,2,3,:mice<blind>)
-Values in C<Arguments> values are parsed as ordinary expressions, marked as
-positional, named, to-be-flattened, and so on.
+Values in C<Capture> are parsed as ordinary expressions, marked as invocant,
+positional, named, and so on.
-Like C<List> objects, C<Arguments> are immutable in the abstract, but
-evaluates its arguments lazily. Before everything inside a C<Arguments> are
+Like C<List> objects, C<Capture> objects are immutable in the abstract, but
+evaluates its arguments lazily. Before everything inside a C<Capture> are
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 is
that we have the promise to make the bits of it immutable as they become known.
-C<Arguments> objects may contain multiple unresolved iterators such as pipes
+C<Capture> objects may contain multiple unresolved iterators such as pipes
or slices. How these are resolved depends on what they are eventually
bound to. Some bindings are sensitive to multiple dimensions while
others are not.
-You may cast C<Arguments> to other types with a prefix sigil operator:
+You may retrieve parts from a C<Capture> object with a prefix sigil operator:
$args = \3; # same as "$args = \(3)"
$$args; # same as "$args as Scalar" or "Scalar($args)"
@$args; # same as '$args as Array" or "Array($args)"
%$args; # same as '$args as Hash" or "Hash($args)"
- &$args; # same as '$args as Code" or "Code($args)"
When cast into an array, you can access all the positional arguments; into a
-hash, all named arguments; into a scalar, the invocant; into code, its slurpy
-nameless block.
+hash, all named arguments; into a scalar, its invocant.
All prefix sigil operators accept one positional argument, evaluated in
scalar context as a rvalue. They can interpolate in strings if called with
Modified: doc/trunk/design/syn/S03.pod
==============================================================================
--- doc/trunk/design/syn/S03.pod (original)
+++ doc/trunk/design/syn/S03.pod Sat Apr 15 06:17:49 2006
@@ -61,7 +61,7 @@
=item * The backslash operator captures its arguments, and returns an
object representing those arguments. You can I<dereference> this object
in several ways to retrieve different parts of the arguments; see the
-definition of C<Arguments> S02 for details.
+definition of C<Capture> in S02 for details.
=item * The old scalar C<..> flipflop operator is now done with
C<ff> operator. (C<..> now always produces a Range object
@@ -456,7 +456,7 @@
as is this:
- my $args = \(@foo, @bar); # construct Arguments object
+ my $args = \(@foo, @bar); # construct a Capture object
push *$args;
In list context, a Scalar holding an Array object does not flatten. Hence
Modified: doc/trunk/design/syn/S06.pod
==============================================================================
--- doc/trunk/design/syn/S06.pod (original)
+++ doc/trunk/design/syn/S06.pod Sat Apr 15 06:17:49 2006
@@ -403,7 +403,7 @@
"pairs" instead of "values".)
Pair constructors are recognized syntactically at the call level and
-put into the named slot of the C<Arguments> structure. Hence they may be
+put into the named slot of the C<Capture> structure. Hence they may be
bound to positionals only by name, not as ordinary positional C<Pair>
objects. Leftover named arguments can be slurped into a slurpy hash.
@@ -579,7 +579,7 @@
so that you can use more descriptive internal parameter names without
imposing inconveniently long external labels on named arguments.
-Arguments that correspond to named parameters are evaluated in scalar
+Capture that correspond to named parameters are evaluated in scalar
context. They can only be passed by name, so it doesn't matter what
order you pass them in, so long as they don't intermingle with any
positional arguments:
@@ -681,13 +681,13 @@
=head2 Argument list binding
-The underlying C<Arguments> object may be bound to a single scalar
+The underlying C<Capture> object may be bound to a single scalar
parameter marked with a C<\>.
sub bar ($a,$b,$c,:$mice) { say $mice }
sub foo (\$args) { say $args.perl; &bar.call($args); }
-The C<.call> method of C<Code> objects accepts a single C<Arguments>
+The C<.call> method of C<Code> objects accepts a single C<Capture>
object, and calls it without introducing a C<CALLER> frame.
foo 1,2,3,:mice<blind>; # says "\(1,2,3,:mice<blind>)" then "blind"
@@ -705,12 +705,12 @@
=head2 Flattening argument lists
-The unary prefix operator C<*> casts a value to an C<Arguments>
+The unary prefix operator C<*> casts a value to an C<Capture>
object, then splices it into the argument list it occurs in.
-Casting C<Arguments> to C<Arguments> is a no-op:
+Casting C<Capture> to C<Capture> is a no-op:
- *(\(1, x=>2)); # Arguments, becomes \(1, x=>2)
+ *(\(1, x=>2)); # Capture, becomes \(1, x=>2)
C<Pair> and C<Hash> become named arguments:
@@ -744,11 +744,11 @@
=head2 Multidimensional argument list binding
-Some functions take multiple C<Arguments> that they wish not to be flattened
-into one list. For instance, C<zip()> wants to iterate several lists in
-parallel, while array and hash subscripts want to process multidimensional
-slices. The set of underlying argument list (List) objects may be bound to a
-single array parameter declared with a C<;> twigil:
+Some functions take more than one C<Capture> as their argument list, that they
+wish not to be flattened into one list. For instance, C<zip()> wants to
+iterate several lists in parallel, while array and hash subscripts want to
+process multidimensional slices. The set of underlying argument list (Capture)
+objects may be bound to a single array parameter declared with a C<;> twigil:
sub foo (*@;slices) { ... }
@@ -1340,7 +1340,7 @@
Pair Tuple of two elements that serves as an one-element Mapping
Mapping Pairs with no duplicate keys
Signature Function parameters (left-hand side of a binding)
- Arguments Function call arguments (right-hand side of a binding)
+ Capture Function call arguments (right-hand side of a binding)
=head2 Mutable types
@@ -1739,15 +1739,21 @@
=head2 The C<return> function
-The C<return> function accepts C<Arguments> just like any other function.
-This allows named return values if the caller expects one:
+The C<return> function preserves its argument list as a C<Capture> object, and
+responds to the left-hand C<Signature> in a binding. This allows named return
+values if the caller expects one:
- sub f { return x => 1 }
+ sub f { return :x<1> }
sub g ($x) { print $x }
my $x := *f(); # binds 1 to $x, via a named argument
g(*f()); # prints 1, via a named argument
+To return a literal C<Pair> object, always put it in an additional set of
+parentheses:
+
+ return( (:x<1>), (:y<2>) ); # two positional Pair objects
+
=head2 The C<caller> function
The C<caller> function returns an object that describes a particular
@@ -1918,7 +1924,7 @@
&thermo.wrap( -> \$args { call(*$args) * 2 } );
The wrapper is not required to call the original routine; it can call another
-C<Code> object by passing the C<Arguments> to its C<call> method:
+C<Code> object by passing the C<Capture> to its C<call> method:
# Transparently redirect all calls to &thermo to &other_thermo
&thermo.wrap( -> \$args { &other_thermo.call(*$args) } );
Modified: doc/trunk/design/syn/S09.pod
==============================================================================
--- doc/trunk/design/syn/S09.pod (original)
+++ doc/trunk/design/syn/S09.pod Sat Apr 15 06:17:49 2006
@@ -697,7 +697,7 @@
my $val := %hash<foo><bar>;
my @array;
- my $ref = [EMAIL PROTECTED]; # $ref is an Arguments object - see S02
+ my $ref = [EMAIL PROTECTED]; # $ref is an Capture object - see S02
my %hash;
%hash<foo><bar> = "foo"; # duh
