develooper Front page | perl.perl6.language | Postings from March 2009

r25685 - docs/Perl6/Spec

Thread Next
From:
pugs-commits
Date:
March 4, 2009 11:21
Subject:
r25685 - docs/Perl6/Spec
Message ID:
20090304192100.14375.qmail@feather.perl6.nl
Author: lwall
Date: 2009-03-04 20:20:59 +0100 (Wed, 04 Mar 2009)
New Revision: 25685

Modified:
   docs/Perl6/Spec/S02-bits.pod
   docs/Perl6/Spec/S03-operators.pod
   docs/Perl6/Spec/S04-control.pod
   docs/Perl6/Spec/S05-regex.pod
   docs/Perl6/Spec/S06-routines.pod
   docs/Perl6/Spec/S09-data.pod
   docs/Perl6/Spec/S12-objects.pod
Log:
Simplify meaning of Capture and Match in item context to preserve sanity
    (an object in item context is always just itself, never a subpart)
Result objects now come though $/{''}, although they may still be created with
    'make' and accessed with $().  (This is already how STD works, btw.)
The invocant (if any) of a Capture is now always considered 1st positional.
Clarify that foo(|$capture) delays choice of dispatcher
ruoso++ for forcing me to rethink all this


Modified: docs/Perl6/Spec/S02-bits.pod
===================================================================
--- docs/Perl6/Spec/S02-bits.pod	2009-03-04 16:27:17 UTC (rev 25684)
+++ docs/Perl6/Spec/S02-bits.pod	2009-03-04 19:20:59 UTC (rev 25685)
@@ -12,9 +12,9 @@
 
   Maintainer: Larry Wall <larry@wall.org>
   Date: 10 Aug 2004
-  Last Modified: 26 Feb 2009
+  Last Modified: 4 Mar 2009
   Number: 2
-  Version: 156
+  Version: 157
 
 This document summarizes Apocalypse 2, which covers small-scale
 lexical items and typological issues.  (These Synopses also contain
@@ -1535,8 +1535,10 @@
 
     $args = \(1,2,3,:mice<blind>)
 
-Values in a C<Capture> object are parsed as ordinary expressions, marked as
-invocant, positional, named, and so on.
+Values in a C<Capture> object are parsed as ordinary expressions, then marked as
+positional or named.  If the first positional is followed by a colon instead of
+a comma, it is marked as the invocant in case it finds itself in a context
+that cares.
 
 Like C<List> objects, C<Capture> objects are immutable in the abstract, but
 evaluate their arguments lazily.  Before everything inside a C<Capture> is
@@ -1552,17 +1554,17 @@
 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 "Array($args)"
+    %$args;         # same as "Hash($args)"
 
 When cast into an array, you can access all the positional arguments; into a
-hash, all named arguments; into a scalar, its invocant.
+hash, all named arguments.
 
 All prefix sigil operators accept one positional argument, evaluated in
 item context as a rvalue.  They can interpolate in strings if called with
-parentheses.  The special syntax form C<$()> translates into C<$( $/ )> 
-to operate on the current match object; the same applies to C<@()> and C<%()>.
+parentheses.  The special syntax form C<$()> translates into C<$( $/{''} // Str($/) )> 
+to operate on the current match object; similarly C<@()> and C<%()> can
+extract positional and named submatches.
 
 C<Capture> objects fill the ecological niche of references in Perl 6.
 You can think of them as "fat" references, that is, references that

Modified: docs/Perl6/Spec/S03-operators.pod
===================================================================
--- docs/Perl6/Spec/S03-operators.pod	2009-03-04 16:27:17 UTC (rev 25684)
+++ docs/Perl6/Spec/S03-operators.pod	2009-03-04 19:20:59 UTC (rev 25685)
@@ -14,7 +14,7 @@
   Date: 8 Mar 2004
   Last Modified: 4 Mar 2009
   Number: 3
-  Version: 156
+  Version: 157
 
 =head1 Overview
 
@@ -649,6 +649,9 @@
 
 Interpolates the contents of the C<Capture> (or C<Capture>-like) value
 into the current argument list as if they had been specified literally.
+If the first argument of the capture is marked as an invocant but is used
+in a context not expecting one, it is treated as an ordinary positional
+argument.
 
 =item *
 
@@ -1797,7 +1800,7 @@
 
 =back
 
-Many of these operators return a list of Captures, which depending on
+Many of these operators return a list of C<Capture>s, which depending on
 context may or may not flatten them all out into one flat list.  The
 default is to flatten, but see the contextualizers below.
 
@@ -1969,8 +1972,8 @@
 
     item foo()
 
-The new name for Perl 5's C<scalar> contextualizer.  Equivalent to C<$()>
-(except that empty C<$()> means C<$($/)>, while empty C<item()> yields C<Failure>).
+The new name for Perl 5's C<scalar> contextualizer.  Equivalent to C<$(...)>
+(except that empty C<$()> means C<$/{''} // Str($/)>, while empty C<item()> yields C<Failure>).
 We still call the values scalars, and talk about "scalar operators", but
 scalar operators are those that put their arguments into item context.
 
@@ -1990,7 +1993,7 @@
 
 Forces the subsequent expression to be evaluated in list context.
 A list of C<Capture>s will be transformed into a flat list.
-Equivalent to C<@()> (except that empty C<@()> means C<@($/)>, while
+Equivalent to C<@(...)> (except that empty C<@()> means C<@($/)>, while
 empty C<list()> means an empty list).
 
 =item *
@@ -2002,7 +2005,7 @@
 Forces the subsequent expression to be evaluated in slice context.
 (Slices are considered to be potentially multidimensional in Perl 6.)
 A list of C<Capture>s will be transformed into a list of lists.
-Equivalent to C<@@()> (except that empty C<@@()> means C<@@($/)>, while
+Equivalent to C<@@(...)> (except that empty C<@@()> means C<@@($/)>, while
 empty C<slice()> means a null slice).
 
 =item *
@@ -2016,7 +2019,7 @@
 then a hash will be created from the list, taken as a list of C<Pair>s.
 (Any element in the list that is not a C<Pair> will pretend to be a key
 and grab the next value in the list as its value.)  Equivalent to
-C<%()> (except that empty C<%()> means C<%($/)>, while
+C<%(...)> (except that empty C<%()> means C<%($/)>, while
 empty C<hash()> means an empty hash).
 
 =back
@@ -4200,22 +4203,25 @@
 signature, but the presence of C<|> defers that test until run time for
 that argument (and for any subsequent arguments):
 
-    my @args := [item @foo, @bar];
-    push |@args;
+    my $args = \(@foo, @bar);
+    push |$args;
 
 is equivalent to:
 
-    push @foo: @bar;
+    push @foo, @bar;
 
-which is just another way to write:
+However,
 
+    my $args = \(@foo: @bar);
+
+is instead equivalent to:
+
     @foo.push(@bar);
 
-Unlike C<[,]>, C<|> does not turn its argument into an C<Array>, but instead directly
+C<|> does not turn its argument into an C<Array>, but instead directly
 converts its argument into a C<Capture>:
 
     my @args = \$x, 1, 2, 3;
-    say [,] @args;  # say([\$x, 1, 2, 3]);
     say |@args;     # say(\$x, 1, 2, 3);
 
 Because of this, C<|%args> always produces named arguments, and
@@ -4248,12 +4254,6 @@
 
     $foo.bar.baz.bletch.whatever.attr[] = 1,2,3;
 
-Otherwise you'd have to write:
-
-    @($foo.bar.baz.bletch.whatever.attr) = 1,2,3;
-
-and remember the C<@> at the front until you get to the C<=>.
-
 The empty C<[]> and C<.[]> postfix operators are interpreted as a
 zero-dimensional slice returning the entire array, not as a one-dimensional
 null slice returning no elements.  Likewise for C<{}> and C<.{}> on hashes,

Modified: docs/Perl6/Spec/S04-control.pod
===================================================================
--- docs/Perl6/Spec/S04-control.pod	2009-03-04 16:27:17 UTC (rev 25684)
+++ docs/Perl6/Spec/S04-control.pod	2009-03-04 19:20:59 UTC (rev 25685)
@@ -12,9 +12,9 @@
 
   Maintainer: Larry Wall <larry@wall.org>
   Date: 19 Aug 2004
-  Last Modified: 27 Feb 2009
+  Last Modified: 4 Mar 2009
   Number: 4
-  Version: 72
+  Version: 73
 
 This document summarizes Apocalypse 4, which covers the block and
 statement syntax of Perl.
@@ -280,7 +280,7 @@
 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
-Captures (a "slice") with dimensional boundaries at each iteration.
+C<Capture>s (a "slice") with dimensional boundaries at each iteration.
 Normal list context ignores these boundaries and flattens the list.
 Slice context turns the captures into subarrays, so an iteration
 returning a null list does show up as a null subarray when viewed as
@@ -1342,9 +1342,9 @@
 called.  [Note: this is currently a potential problem for user-defined
 constructs, since you have to take references to blocks to pass them
 to whatever is managing the control flow.  Perhaps the laziness can
-be deferred through Captures to binding time, so a slurpy of block
+be deferred through C<Capture>s to binding time, so a slurpy of block
 refs doesn't clone them all prematurely.  On the other hand, this
-either means the Capture must be smart enough to keep track of the
+either means the C<Capture> must be smart enough to keep track of the
 lexical scope it came from so that it can pass the info to the cloner,
 or it means that we need some special fat not-cloned-yet references
 that can carry the info lazily.  Neither approach is pretty.]

Modified: docs/Perl6/Spec/S05-regex.pod
===================================================================
--- docs/Perl6/Spec/S05-regex.pod	2009-03-04 16:27:17 UTC (rev 25684)
+++ docs/Perl6/Spec/S05-regex.pod	2009-03-04 19:20:59 UTC (rev 25685)
@@ -14,9 +14,9 @@
    Maintainer: Patrick Michaud <pmichaud@pobox.com> and
                Larry Wall <larry@wall.org>
    Date: 24 Jun 2002
-   Last Modified: 26 Jan 2009
+   Last Modified: 4 Mar 2009
    Number: 5
-   Version: 87
+   Version: 88
 
 This document summarizes Apocalypse 5, which is about the new regex
 syntax.  We now try to call them I<regex> rather than "regular
@@ -2397,8 +2397,14 @@
 
 =item *
 
-When used as a scalar, a C<Match> object evaluates to its underlying
-result object.  Usually this is just the entire match string, but
+When used as a scalar, a C<Match> object evaluates to itself.
+
+However, sometimes you would like an alternate scalar value to ride
+along with the match.  This is called a I<result> object, and it rides
+along in the null named key.
+C<$()> is a shorthand for C<$($/{''} // Str($/))>.
+
+Therefore C<$()> is usually just the entire match string, but
 you can override that by calling C<make> inside a regex:
 
     my $moose = $(m:{
@@ -2407,8 +2413,10 @@
         # match succeeds -- ignore the rest of the regex
     });
 
-C<$()> is a shorthand for C<$($/)>.  The result object may be of any type,
-not just a string.
+This puts the result object into C<$/{''}>.  If a result object is
+returned that way, it may be of any type, not just a string.
+This makes it convenient to build up an abstract syntax tree of
+arbitrary node types.
 
 You may also capture a subset of the match as the result object using
 the C<< <(...)> >> construct:
@@ -3556,7 +3564,7 @@
 choose to process in either of two ways.  If you refer to
 C<@()>, the multidimensionality is ignored and all the matches are returned
 flattened (but still lazily).  If you refer to C<@@()>, you can
-get each individual sublist as a Capture object. (That is, there is a C<@@()>
+get each individual sublist as a C<Capture> object. (That is, there is a C<@@()>
 coercion operator that happens, like C<@()>, to default to C<$/>.)
 As with any multidimensional list, each sublist can be lazy separately.
 

Modified: docs/Perl6/Spec/S06-routines.pod
===================================================================
--- docs/Perl6/Spec/S06-routines.pod	2009-03-04 16:27:17 UTC (rev 25684)
+++ docs/Perl6/Spec/S06-routines.pod	2009-03-04 19:20:59 UTC (rev 25685)
@@ -13,9 +13,9 @@
 
   Maintainer: Larry Wall <larry@wall.org>
   Date: 21 Mar 2003
-  Last Modified: 26 Feb 2009
+  Last Modified: 4 Mar 2009
   Number: 6
-  Version: 104
+  Version: 105
 
 
 This document summarizes Apocalypse 6, which covers subroutines and the
@@ -593,17 +593,12 @@
     print $obj.get_name();
     $obj.set_name("Sam");
 
-For the purpose of matching positional arguments against invocant parameters,
-the invocant argument passed via the method call syntax is considered the
-first positional argument when failover happens from single dispatch to
-multiple dispatch:
+The invocant is actually stored as the first positional argument of a C<Capture>
+object.  It is special only to the dispatcher, otherwise it's just a normal
+positional argument.
 
-    handle_event($w, $e, $m);   # calls the multi sub
-    $w.handle_event($e, $m);    # ditto, but only if there is no
-                                # suitable $w.handle_event method
-
-Invocants may also be passed using the indirect object syntax, with a colon
-after them. The colon is just a special form of the comma, and has the
+Single-dispatch semantics may also be requested by using the indirect object syntax, with a colon
+after the invocant argument. The colon is just a special form of the comma, and has the
 same precedence:
 
     set_name $obj: "Sam";   # try $obj.set_name("Sam") first, then
@@ -615,6 +610,15 @@
 always has the alias C<self>.  Other styles of self can be declared
 with the C<self> pragma.
 
+If you have call of the form:
+
+    foo(|$capture)
+
+the compiler must defer the decision on whether to treat it as a single
+or multiple dispatch based on whether the supplied C<Capture>'s first
+argument is marked as an invocant.  For ordinary calls this can
+always be determined at compile time, however.
+
 =head2 Longname parameters
 
 A routine marked with C<multi> can mark part of its parameters to

Modified: docs/Perl6/Spec/S09-data.pod
===================================================================
--- docs/Perl6/Spec/S09-data.pod	2009-03-04 16:27:17 UTC (rev 25684)
+++ docs/Perl6/Spec/S09-data.pod	2009-03-04 19:20:59 UTC (rev 25685)
@@ -12,9 +12,9 @@
 
   Maintainer: Larry Wall <larry@wall.org>
   Date: 13 Sep 2004
-  Last Modified: 14 Oct 2008
+  Last Modified: 4 Mar 2009
   Number: 9
-  Version: 29
+  Version: 30
 
 =head1 Overview
 
@@ -810,7 +810,7 @@
 Within any kind of bracketing construct, semicolon notionally separates
 the sublists of a multidimensional slice, the interpretation of
 which depends on the context.  Such a semicolon list puts each of its
-sublists into a Capture, deferring the context of the sublist until
+sublists into a C<Capture>, deferring the context of the sublist until
 it is bound somewhere.  The storage of these sublists is hidden in
 the inner workings of the list.  It does not produce a list of lists
 unless the list as a whole is bound into a slice context.

Modified: docs/Perl6/Spec/S12-objects.pod
===================================================================
--- docs/Perl6/Spec/S12-objects.pod	2009-03-04 16:27:17 UTC (rev 25684)
+++ docs/Perl6/Spec/S12-objects.pod	2009-03-04 19:20:59 UTC (rev 25685)
@@ -12,9 +12,9 @@
 
   Maintainer: Larry Wall <larry@wall.org>
   Date: 27 Oct 2004
-  Last Modified: 26 Feb 2009
+  Last Modified: 4 Mar 2009
   Number: 12
-  Version: 71
+  Version: 72
 
 =head1 Overview
 
@@ -833,7 +833,7 @@
     @object»!meth(@args)   # calls private method on each
 
 The return value is a list with exactly the same number of elements
-as C<@object>.  Each such return value is a Capture or List of Captures
+as C<@object>.  Each such return value is a C<Capture> or C<List> of C<Captures>
 as specified above for the non-hyper "dot" variants.
 
 Hyperoperators treat a junction as a scalar value, so saying:


Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About