Author: larry
Date: Wed Sep 20 22:07:47 2006
New Revision: 12284
Modified:
doc/trunk/design/syn/S02.pod
doc/trunk/design/syn/S03.pod
doc/trunk/design/syn/S06.pod
doc/trunk/design/syn/S12.pod
Log:
The | sigil and operator.
Modified: doc/trunk/design/syn/S02.pod
==============================================================================
--- doc/trunk/design/syn/S02.pod (original)
+++ doc/trunk/design/syn/S02.pod Wed Sep 20 22:07:47 2006
@@ -12,9 +12,9 @@
Maintainer: Larry Wall <[EMAIL PROTECTED]>
Date: 10 Aug 2004
- Last Modified: 18 Sept 2006
+ Last Modified: 20 Sept 2006
Number: 2
- Version: 69
+ Version: 70
This document summarizes Apocalypse 2, which covers small-scale
lexical items and typological issues. (These Synopses also contain
@@ -670,6 +670,7 @@
@ ordered array
% unordered hash (associative array)
& code/rule/token/regex
+ | capture/arguments/match
:: package/module/class/role/subset/enum/type/grammar
@@ multislice view of @
@@ -817,15 +818,22 @@
$$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; # all of the above
When cast into an array, you can access all the positional arguments; into a
hash, all named arguments; into a scalar, its invocant.
+When stored in a variable using the C<|> sigil, the capture autointerpolates
+into argument lists much like C<@> autoflattens into lists:
+
+ |args := \($a, @b, :option($c));
+ somefunc(|args); # same as somefunc($a, @b, :option($c))
+
All prefix sigil operators accept one positional argument, evaluated in
scalar 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<@()>, C<%()> and
-C<*()> forms.
+C<|()> forms.
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: doc/trunk/design/syn/S03.pod
==============================================================================
--- doc/trunk/design/syn/S03.pod (original)
+++ doc/trunk/design/syn/S03.pod Wed Sep 20 22:07:47 2006
@@ -12,9 +12,9 @@
Maintainer: Larry Wall <[EMAIL PROTECTED]>
Date: 8 Mar 2004
- Last Modified: 16 Sep 2006
+ Last Modified: 20 Sept 2006
Number: 3
- Version: 66
+ Version: 67
=head1 Changes to Perl 5 operators
@@ -65,7 +65,8 @@
argument, and C<+> imposes a numeric (C<Num>) context (as opposed
to being a no-op in Perl 5). Along the same lines, C<?> imposes
a boolean (C<Bool>) context, and the C<[,]> list operator imposes
-a function-arguments (C<Capture>) context on its arguments.
+a function-arguments (C<Capture>) context on its arguments (as does
+the C<|> sigil when used as an operator).
Unary sigils impose the container context implied by their sigil.
As with Perl 5, however, C<$$foo[bar]> parses as C<( $($foo) )[bar]>,
so you need C<$($foo[bar])> to mean the other way.
@@ -1295,11 +1296,14 @@
interpolator, by casting its operands to C<Capture> objects
and inserting them into the current argument list.
-It can be used to interpolate an C<Array> or C<Hash> into the current
-call, as positional and named arguments respectively.
+The C<|> capture sigil may also be used for this when you want to
+interpolate a single item.
+
+Either of these can be used to interpolate an C<Array> or C<Hash>
+into the current call, as positional and named arguments respectively.
Note that those arguments still must comply with the subroutine's
-signature, but the presence of C<[,]> defers that test until run time for
+signature, but the presence of C<|> or C<[,]> defers that test until run time
for
that argument (and for any subsequent arguments):
my @args = [EMAIL PROTECTED], @bar;
@@ -1312,7 +1316,16 @@
as is this:
my $args = \(@foo, @bar); # construct a Capture object
- push [,] @$args;
+ push |$args;
+
+The C<|> sigil functions as a unary form of the C<[,]>
+list operator, so we could have written the earlier example as:
+
+ my @args = [EMAIL PROTECTED], @bar;
+ push |@args;
+
+To the extent possible, the C<|> will treat its argument as
+a C<Capture> even if it isn't.
In list context, a C<Scalar> holding an C<Array> object does not flatten.
Hence
@@ -1320,15 +1333,16 @@
push @foo, $bar;
merely pushes a single C<Array> object onto C<@foo>. You can
-explicitly flatten it in either of these ways:
+explicitly flatten it in one of these ways:
push @foo, @$bar;
push @foo, $bar[];
+ push @foo, |$bar;
-Those two forms work because the slurpy array in C<push>'s signature
+Those three forms work because the slurpy array in C<push>'s signature
flattens the C<Array> object into a list argument.
-Note that those two forms also allow you to specify list context on
+Note that the first two forms also allow you to specify list context on
assignment:
@$bar = 1,2,3;
@@ -1351,18 +1365,20 @@
as well as the C<< <> >>, C<< .<> >>, C<«»>, and C<.«»> constant and
interpolating slice subscripting forms.
-The C<[,]> operator interpolates lazily for C<Array> and C<Range> objects.
+The C<[,]> and C<|> operators interpolate lazily for C<Array> and C<Range>
objects.
To get an immediate interpolation like Perl 5 does, add the C<eager> list
operator:
func([,] 1..Inf); # works fine
func([,] eager 1..Inf); # never terminates
-To interpolate a function's return value, you must say:
+To interpolate a function's return value, you must say one of:
push [,] func();
+ push |(func());
+ push |func(); # WRONG, would parse as (|func).()
-Within the argument list of a C<[,]>, function return values are
+Within such an argument list, function return values are
automatically exploded into their various parts, as if you'd said:
my \$capture := func();
@@ -1375,12 +1391,17 @@
as if its colon changed back to a comma.
If you already have a capture variable, you can interpolate all of
-its bits at once using the C<< prefix:<=> >> operator, which serves
-to iterate or dereference a scalar that would otherwise stay packed
-into its scalar value. The above is equivalent to:
+its bits at once using the C<< prefix:<|> >> operator (really a sigil).
my \$capture := func();
- push [,] =$capture;
+ push |$capture;
+
+Or you can use the bare sigiled forms:
+
+ my |capture := func();
+ push |capture;
+
+Bare lvalue capture variables may only be bound, not assigned.
=head1 Feed operators
@@ -1551,7 +1572,7 @@
method postfix .meth .+ .? .* .() .[] .{} .<> .«» .:: .= .^
autoincrement ++ --
exponentiation **
- symbolic unary ! + - ~ ? $ @ % & +^ ~^ ?^ \ ^ =
+ symbolic unary ! + - ~ ? $ @ % & | +^ ~^ ?^ \ ^ =
multiplicative * / % x xx +& +< +> ~& ~< ~> ?&
additive + - ~ +| +^ ~| ~^ ?| ?^
junctive and (all) &
Modified: doc/trunk/design/syn/S06.pod
==============================================================================
--- doc/trunk/design/syn/S06.pod (original)
+++ doc/trunk/design/syn/S06.pod Wed Sep 20 22:07:47 2006
@@ -373,23 +373,21 @@
doit :123<now>; # always a positional arg
Going the other way, pairs intended as named arguments that don't look
-like pairs must be introduced with the C<[,]> reduction operator:
+like pairs must be introduced with the C<[,]> reduction operator or
+the C<|> capture sigil:
$pair = :when<now>;
- doit $pair,1,2,3; # always a positional arg
- doit [,] %$pair,1,2,3; # always a named arg
- doit [,] %(get_pair()),1,2,3; # always a named arg
- doit [,] %('when' => 'now'),1,2,3; # always a named arg
-
-Note that, to apply C<[,]> to a single arg you may need to use parentheses.
-In general it doesn't matter.
+ doit $pair,1,2,3; # always a positional arg
+ doit |%$pair,1,2,3; # always a named arg
+ doit |%(get_pair()),1,2,3; # always a named arg
+ doit |%('when' => 'now'),1,2,3; # always a named arg
Likewise, if you wish to pass a hash and have its entries treated as
-named arguments, you must dereference it with a C<[,]>:
+named arguments, you must dereference it with a C<[,]> or C<|>:
%pairs = {:when<now> :what<any>};
doit %pairs,1,2,3; # always a positional arg
- doit [,](%pairs),1,2,3; # always named args
+ doit |%pairs,1,2,3; # always named args
Variables with a C<:> prefix in rvalue context autogenerate pairs, so you
can also say this:
@@ -465,7 +463,7 @@
parameters, similar to how hash constructors work:
# Allow "x" and "y" in %defaults to be overridden
- f( [,](%defaults), x => 1, y => 2 );
+ f( |%defaults, x => 1, y => 2 );
=head2 Invocant parameters
@@ -699,41 +697,39 @@
=head2 Argument list binding
The underlying C<Capture> object may be bound to a single scalar
-parameter marked with a C<\>.
+parameter marked with a C<|> sigil.
sub bar ($a,$b,$c,:$mice) { say $mice }
- sub foo (\$args) { say $args.perl; &bar.call($args); }
+ sub foo (|args) { say |args.perl; &bar.callargs(|args); }
-The C<.call> method of C<Code> objects accepts a single C<Capture>
-object, and calls it without introducing a C<CALLER> frame.
+The C<.callargs> method of C<Code> objects accepts an argument list,
+(which can be specified as a Capture object as above), and calls it
+without introducing an official C<CALLER> frame.
foo 1,2,3,:mice<blind>; # says "\(1,2,3,:mice<blind>)" then "blind"
-It is allowed to specify a return type:
-
- sub foo (\$args --> Num) { ... }
+It is allowed to specify additional parameters. The Capture binding merely
+takes a snapshot of what's left of the Capture at that point and then
+continues binding as if the Capture parameter weren't there:
-Apart from that, no other parameters are allowed in the signature
-after the C<Capture>. Parameters before the C<Capture> either do not show up
in
-the C<Capture> or are marked as already bound somehow. In other words,
-parameters are bound normally up to the C<Capture> parameter, and then
-C<\$args> takes a snapshot of the remaining input without further
-attempts at binding.
+ sub compare (|args Num $x, Num $y --> Bool) { ... }
=head2 Flattening argument lists
The reduce operator C<[,]> casts each of its arguments to a C<Capture>
object, then splices each of those captures into the argument list
-it occurs in.
+it occurs in. The unary C<|> sigil has the same effect on a single
+argument.
Casting C<Capture> to C<Capture> is a no-op:
[,](\(1, x=>2)); # Capture, becomes \(1, x=>2)
+ |(\(1, x=>2)); # Capture, becomes \(1, x=>2)
C<Pair> and C<Hash> become named arguments:
- [,](x=>1); # Pair, becomes \(x=>1)
- [,]{x=>1, y=>2}; # Hash, becomes \(x=>1, y=>2)
+ |(x=>1); # Pair, becomes \(x=>1)
+ |{x=>1, y=>2}; # Hash, becomes \(x=>1, y=>2)
C<List> (also C<Seq>, C<Range>, etc.) are simply turned into
positional arguments:
@@ -750,7 +746,7 @@
foo(1,2,3); # okay: three args found
foo(@onetothree); # error: only one arg
- foo([,[EMAIL PROTECTED]); # okay: @onetothree flattened to three
args
+ foo(|@onetothree); # okay: @onetothree flattened to three args
The C<[,]> operator flattens lazily -- the array is flattened only if
flattening is actually required within the subroutine. To flatten before
@@ -1922,7 +1918,7 @@
On the caller's end, the C<Capture> is interpolated into any new argument list
much like an array would be, that is, as a scalar in scalar context, and as a
list in list context. This is the default behavior, but as with an array, the
-caller may use C<< prefix:<[,]> >> to inline the returned values as part of the
+caller may use C<< prefix:<[,]> >> or the C<|> sigil to inline the returned
values as part of the
new argument list. The caller may also bind the returned C<Capture> directly.
=head2 The C<caller> function
@@ -2081,16 +2077,20 @@
=head2 Wrapping
Every C<Routine> object has a C<.wrap> method. This method expects a single
-C<Code> argument. Within the code, the special C<call> function will invoke
-the original routine, but does not introduce a C<CALLER> frame:
+C<Code> argument. Within the code, the special C<call> and C<callargs>
functions will invoke
+the original routine, but do not introduce an official C<CALLER> frame:
sub thermo ($t) {...} # set temperature in Celsius, returns old value
# Add a wrapper to convert from Fahrenheit...
- $handle = &thermo.wrap( { call( ($^t-32)/1.8 ) } );
+ $handle = &thermo.wrap( { callargs( ($^t-32)/1.8 ) } );
+
+The C<callargs> function lets you pass your own arguments to the wrapped
+function. The C<call> function takes no arguments and implicitly passes
+the original argument list through unchanged.
The call to C<.wrap> replaces the original C<Routine> with the C<Code>
-argument, and arranges that the call to C<call> invokes the previous
+argument, and arranges that the call to C<call> or C<callargs> invokes the
previous
version of the routine. In other words, the call to C<.wrap> has more
or less the same effect as:
@@ -2112,29 +2112,35 @@
# Add a wrapper to convert from Kelvin
# wrapper self-unwraps at end of current scope
- temp &thermo.wrap( { call($^t + 273.16) } );
+ temp &thermo.wrap( { callargs($^t + 273.16) } );
-The entire argument list may be captured by the C<\$args> parameter.
-It can then be passed to C<call> as C<[,] =$args>:
+The entire argument list may be captured by binding to a Capture parameter.
+It can then be passed to C<callargs> using that name:
# Double the return value for &thermo
- &thermo.wrap( -> \$args { call([,] =$args) * 2 } );
+ &thermo.wrap( -> |args { callargs(|args) * 2 } );
+
+In this case only the return value is changed.
The wrapper is not required to call the original routine; it can call another
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) } );
+ &thermo.wrap( -> |args { &other_thermo.callargs(|args) } );
+
+or more briefly:
+
+ &thermo.wrap( { &other_thermo.call } );
-Outside a wrapper, C<call> implicitly calls the next-most-likely method
-or multi-sub; see S12 for details.
+Outside a wrapper, the various C<call> functions and methods implicitly
+call the next-most-likely method or multi-sub; see S12 for details.
As with any return value, you may capture the returned C<Capture> of C<call>
by binding:
- my \$retval := call([,] =$args);
+ my |retval := callargs(|args);
... # postprocessing
- return [,] =$retval;
+ return |retval;
=head2 The C<&?ROUTINE> object
@@ -2584,7 +2590,7 @@
and pass the resulting C<Match> object as a C<Capture> to C<MAIN>:
@*ARGS ~~ /<MyGrammar::top>/;
- MAIN([,] =$/);
+ MAIN(|$/);
exit;
sub MAIN ($frompart, $topart, [EMAIL PROTECTED]) {
Modified: doc/trunk/design/syn/S12.pod
==============================================================================
--- doc/trunk/design/syn/S12.pod (original)
+++ doc/trunk/design/syn/S12.pod Wed Sep 20 22:07:47 2006
@@ -12,9 +12,9 @@
Maintainer: Larry Wall <[EMAIL PROTECTED]>
Date: 27 Oct 2004
- Last Modified: 14 Sept 2006
+ Last Modified: 20 Sept 2006
Number: 12
- Version: 26
+ Version: 27
=head1 Overview
@@ -1165,7 +1165,7 @@
Since the method name (but nothing else) is known at class construction
time, the following C<.wag> method is autogenerated for you:
- method wag ([EMAIL PROTECTED] is context(Lazy)) { $!tail.wag([,] @args) }
+ method wag ([EMAIL PROTECTED] is context(Lazy)) { $!tail.wag(|@args) }
You can specify multiple method names:
@@ -1175,7 +1175,7 @@
has been initialized to an object of a type supporting the method,
such as by:
- has Tail $.tail handles 'wag' = { .new([,] %_) };
+ has Tail $.tail handles 'wag' = { .new(|%_) };
Note that putting a C<Tail> type on the attribute does not necessarily
mean that the method is always delegated to the C<Tail> class.
