[svn:perl6-synopsis] r8698 - doc/trunk/design/syn

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 = \@array[0][0]; # $ref is an Arguments object - see S02
+    my $ref = \@array[0][0]; # $ref is an Capture object - see S02
 
     my %hash;
     %hash<foo><bar> = "foo"; # duh

• [svn:perl6-synopsis] r8698 - doc/trunk/design/syn by autrijus
• Re: [svn:perl6-synopsis] r8698 - doc/trunk/design/syn by Dr.Ruud
• Re: [svn:perl6-synopsis] r8698 - doc/trunk/design/syn by Zohar Kelrich