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 <[email protected]>
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 <[email protected]>
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 <[email protected]> and
Larry Wall <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 <[email protected]>
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:
