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 <la...@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 <la...@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 <pmich...@pobox.com> and Larry Wall <la...@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 <la...@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 <la...@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 <la...@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: