Perl6::Bible::S06(3) User Contributed Perl Documentation Perl6::Bible::S06(3)NAME
Synopsis_06 - Subroutines
AUTHOR
Damian Conway <damian@conway.org> and Allison Randal <al@shadowed.net>
VERSION
Maintainer: Larry Wall <larry@wall.org>
Date: 21 Mar 2003
Last Modified: 24 Feb 2006
Number: 6
Version: 18
This document summarizes Apocalypse 6, which covers subroutines and the
new type system.
Subroutines and other code objects
Subroutines (keyword: "sub") are non-inheritable routines with
parameter lists.
Methods (keyword: "method") are inheritable routines which always have
an associated object (known as their invocant) and belong to a
particular kind or class.
Submethods (keyword: "submethod") are non-inheritable methods, or
subroutines masquerading as methods. They have an invocant and belong
to a particular kind or class.
Multimethods (keyword: "multi") are routines that transcend class
boundaries, and can have one or more invocants.
Rules (keyword: "rule") are methods (of a grammar) that perform pattern
matching. Their associated block has a special syntax (see Synopsis 5).
Tokens (keyword: "token") are rules that perform low-level pattern
matching (and also enable rules to do whitespace dwimmery).
Macros (keyword: "macro") are routines whose calls execute as soon as
they are parsed (i.e. at compile-time). Macros may return another
source code string or a parse-tree.
Named subroutines
The general syntax for named subroutines is any of:
my RETTYPE sub NAME ( PARAMS ) TRAITS {...} # lexical only
our RETTYPE sub NAME ( PARAMS ) TRAITS {...} # also package-scoped
sub NAME ( PARAMS ) TRAITS {...} # same as "our"
The return type may also be put inside the parentheses:
sub NAME (PARAMS --> RETTYPE) {...}
Unlike in Perl 5, named subroutines are considered expressions, so this
is valid Perl 6:
my @subs = (sub foo { ... }, sub bar { ... });
Anonymous subroutines
The general syntax for anonymous subroutines is:
sub ( PARAMS ) TRAITS {...}
But one can also use a scope modifier to introduce the return type
first:
my RETTYPE sub ( PARAMS ) TRAITS {...}
our RETTYPE sub ( PARAMS ) TRAITS {...} # means the same as "my" here
Trait is the name for a compile-time ("is") property. See "Traits and
Properties"
Perl5ish subroutine declarations
You can declare a sub without parameter list, as in Perl 5:
sub foo {...}
Arguments implicitly come in via the @_ array, but they are "readonly"
aliases to actual arguments:
sub say { print qq{"@_[]"\n}; } # args appear in @_
sub cap { $_ = uc $_ for @_ } # Error: elements of @_ are constant
If you need to modify the elements of @_, declare it explicitly with
the "is rw" trait:
sub swap (*@_ is rw) { @_[0,1] = @_[1,0] }
Blocks
Raw blocks are also executable code structures in Perl 6.
Every block defines an object of type "Code", which may either be
executed immediately or passed on as a "Code" reference argument. A
bare block where an operator is expected is bound to the current
statement level control syntax. A bare block where a term is expected
merely produces a reference. If the term bare block occurs in a list,
it is considered the final element of that list unless followed
immediately by a comma or comma surrogate.
"Pointy subs"
Semantically the arrow operator "->" is almost a synonym for the
anonymous "sub" keyword, except that the parameter list of a pointy sub
does not require parentheses, and a pointy sub may not be given traits.
Syntactically a pointy sub is parsed exactly like a bare block.
$sq = -> $val { $val**2 }; # Same as: $sq = sub ($val) { $val**2 };
for @list -> $elem { # Same as: for @list, sub ($elem) {
print "$elem\n"; # print "$elem\n";
} # }
It also behaves like a block with respect to control exceptions. If
you "return" from within a pointy sub, it will return from the
innermost enclosing "sub" or "method", not the block itself. It is
referenced by "&?BLOCK", not "&?SUB".
Stub declarations
To predeclare a subroutine without actually defining it, use a "stub
block":
sub foo {...} # Yes, those three dots are part of the actual syntax
The old Perl 5 form:
sub foo;
is a compile-time error in Perl 6 (for reasons explained in Apocalypse
6).
Redefining a stub subroutine does not produce an error. To redefine
any other subroutine you must explicitly use the ""is instead"" trait.
The "..." is the "yadayadayada" operator, which is executable but
returns a failure. You can also use "???" to produce a warning, or
"!!!" to always die. These also officially define stub blocks if used
as the only expression in the block.
Globally scoped subroutines
Subroutines and variables can be declared in the global namespace, and
are thereafter visible everywhere in a program.
Global subroutines and variables are normally referred to by prefixing
their identifiers with "*" (short for ""GLOBAL::""). The "*" is
normally required on the declaration but may be omitted on use if the
reference is unambiguous:
$*next_id = 0;
sub *saith($text) { print "Yea verily, $text" }
module A {
my $next_id = 2; # hides any global or package $next_id
saith($next_id); # print the lexical $next_id;
saith($*next_id); # print the global $next_id;
}
module B {
saith($next_id); # Unambiguously the global $next_id
}
Only the name is installed into the "GLOBAL" package by "*". To define
subs completely within the scope of the "GLOBAL" namespace you should
use ""package GLOBAL {...}"" around the declaration.
Lvalue subroutines
Lvalue subroutines return a "proxy" object that can be assigned to.
It's known as a proxy because the object usually represents the purpose
or outcome of the subroutine call.
Subroutines are specified as being lvalue using the "is rw" trait.
An lvalue subroutine may return a variable:
my $lastval;
sub lastval () is rw { return $lastval }
or the result of some nested call to an lvalue subroutine:
sub prevval () is rw { return lastval() }
or a specially tied proxy object, with suitably programmed "FETCH" and
"STORE" methods:
sub checklastval ($passwd) is rw {
return new Proxy:
FETCH => sub ($self) {
return lastval();
},
STORE => sub ($self, $val) {
die unless check($passwd);
lastval() = $val;
};
}
Other methods may be defined for specialized purposes such as
temporizing the value of the proxy.
Operator overloading
Operators are just subroutines with special names and scoping. An
operator name consists of a grammatical category name followed by a
single colon followed by an operator name specified as if it were a
hash subscript (but evaluated at compile time). So any of these
indicate the same binary addition operator:
infix:<+>
infix:X+X
infix:<<+>>
infix:{'+'}
infix:{"+"}
Use the "&" sigil just as you would on ordinary subs.
Unary operators are defined as "prefix" or "postfix":
sub prefix:<OPNAME> ($operand) {...}
sub postfix:<OPNAME> ($operand) {...}
Binary operators are defined as "infix":
sub infix:<OPNAME> ($leftop, $rightop) {...}
Bracketing operators are defined as "circumfix" where a term is
expected or "postcircumfix" where a postfix is expected. A two-element
slice containing the leading and trailing delimiters is the name of the
operator.
sub circumfix:<LEFTDELIM RIGHTDELIM> ($contents) {...}
sub circumfix:{'LEFTDELIM','RIGHTDELIM'} ($contents) {...}
Contrary to A6, there is no longer any rule about splitting an even
number of characters. You must use a two element slice. Such names
are canonicalized to a single form within the symbol table, so you must
use the canonical name if you wish to subscript the symbol table
directly (as in "PKG::{'infix:<+>'}"). Otherwise any form will do.
(Symbolic references do not count as direct subscripts since they go
through a parsing process.) The canonical form always uses angle
brackets and a single space between slice elements. The elements are
not escaped, so "PKG::circumfix:{'<','>'}" is canonicalized to
"PKG::{'circumfix:<< >>'}", and decanonicalizing always involves
stripping the outer angles and splitting on space, if any. This works
because a hash key knows how long it is, so there's no ambiguity about
where the final angle is. And space works because operators are not
allowed to contain spaces.
Operator names can be any sequence of non-whitespace characters
including Unicode characters. For example:
sub infix:<(c)> ($text, $owner) { return $text but Copyright($owner) }
method prefix:<X> (Num $x) returns Num { return +$x | -$x }
multi sub postfix:<!> (Int $n) { $n < 2 ?? 1 :: $n*($n-1)! }
macro circumfix:X<!-- -->X ($text) is parsed / .*? / { "" }
my $document = $text (c) $me;
my $tolerance = X7!;
<!-- This is now a comment -->
Whitespace may never be part of the name (except as separator within a
"<...>" or "X...X" slice, as in the example above).
A null operator name does not define a null or whitespace operator, but
a default matching rule for that syntactic category, which is useful
when there is no fixed string that can be recognized, such as tokens
beginning with digits. Such an operator must supply an "is parsed"
trait. The Perl grammar uses a default rule for the ":1st", ":2nd",
":3rd", etc. rule modifiers, something like this:
sub rxmodexternal:<> ($x) is parsed(rx:p/\d+[st|nd|rd|th]/) {...}
Such default rules are attempted in the order declared. (They always
follow any rules with a known prefix, by the longest-token-first rule.)
Although the name of an operator can be installed into any package or
lexical namespace, the syntactic effects of an operator declaration are
always lexically scoped. Operators other than the standard ones should
not be installed into the "*" namespace. Always use exportation to
make non-standard syntax available to other scopes.
Parameters and arguments
Perl 6 subroutines may be declared with parameter lists.
By default, all parameters are readonly aliases to their corresponding
arguments--the parameter is just another name for the original
argument, but the argument can't be modified through it. To allow
modification, use the "is rw" trait. To pass-by-copy, use the "is copy"
trait.
Parameters may be required or optional. They may be passed by position,
or by name. Individual parameters may confer a scalar or list context
on their corresponding arguments, but unlike in Perl 5, this is decided
lazily at parameter binding time.
Arguments destined for required positional parameters must come before
those bound to optional positional parameters. Arguments destined for
named parameters may come before and/or after the positional
parameters. (To avoid confusion it is highly recommended that all
positional parameters be kept contiguous in the call syntax, but this
is not enforced, and custom arg list processors are certainly possible
on those arguments that are bound to a final slurpy or arglist
variable.)
Named arguments are recognized syntactically at the "comma" level.
Pairs intended as positional arguments rather than named arguments must
be isolated by extra parens:
doit :when<now>,1,2,3; # always a named arg
doit (:when<now>),1,2,3; # always a positional arg
doit when => 'now',1,2,3; # always a named arg
doit (when => 'now'),1,2,3; # always a positional arg
Going the other way, pairs intended as named arguments that don't look
like pairs must be introduced with "*":
$pair = :when<now>;
doit $pair,1,2,3; # always a positional arg
doit *$pair,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 introduce it with a "*":
%pairs = {:when<now> :what<any>};
doit %pairs,1,2,3; # always a positional arg
doit *%pairs,1,2,3; # always named args
Variables with a ":" prefix in rvalue context autogenerate pairs, so
you can also say this:
$when = 'now';
doit $when,1,2,3; # always a positional arg of 'now'
doit :$when,1,2,3; # always a named arg of :when<now>
In other words ":$when" is shorthand for ":when($when)". This works
for any sigil:
:$what :what($what)
:@what :what(@what)
:%what :what(%what)
:&what :what(&what)
There is a corresponding shortcut for hash keys if you prefix the
subscript instead of the sigil. The ":" is not functioning as an
operator here, but as a modifier of the following token:
doit %hash:<a>,1,2,3;
doit %hash:{'b'},1,2,3;
are short for
doit :a(%hash<a>),1,2,3;
doit :b(%hash{'b'}),1,2,3;
Ordinary hash notation will just pass the value of the hash entry as a
positional argument regardless of whether it is a pair or not. To pass
both key and value out of hash as a positional pair, use ":p".
doit %hash<a>:p,1,2,3;
doit %hash{'b'}:p,1,2,3;
instead.. (The ":p" stands for "pairs", not "positional"--the ":p"
adverb may be placed on any hash reference to make it mean "pairs"
instead of "values".)
Pairs are recognized syntactically at the call level and mystically
transformed into special "Named" objects that may be bound to
positionals only by name, not as ordinary positional "Pair" objects.
Leftover special "Named" objects can be slurped into a slurpy hash.
After the positional and named arguments, all the rest of the arguments
are taken to be list arguments. Any pairs within the list are taken to
be list elements rather than named arguments, and mystically show up as
"Pair" arguments even if the compiler marked them as "Named".
It is possible that named pairs are not really a separate type; it
would be sufficient to have a bit somewhere in the Pair that can be
interrogated under the ".named" property. The compiler is allowed to
stop marking "named" pairs at the first "<==", but the code that
converts unused positional arguments to implicit slurpy list needs to
be careful to clear the ".named" property on arguments so converted.
For instance, if you say
push @array, 1, 2, :a<b>;
the compiler cannot know that the slurpy list starts at 1, so it markes
:a<b> as a named pair. But that mark needs to be cleared, or
say pop(@array);
will then think you said:
say *pop(@array);
and treat :a<b> as a named argument to print, which is not what you
want.
In any event, the named parameters need to be kept in the list until
bound. An implementation that pulls named parameters out of the list
into a hash prematurely will lose the ordering of the push above, for
instance.
Invocant parameters
A method invocant is specified as the first parameter in the parameter
list, with a colon (rather than a comma) immediately after it:
method get_name ($self:) {...}
method set_name ($me: $newname) {...}
The corresponding argument (the invocant) is evaluated in scalar
context and is passed as the left operand of the method call operator:
print $obj.get_name();
$obj.set_name("Sam");
Multimethod and multisub invocants are specified at the start of the
parameter list, with a colon terminating the list of invocants:
multi sub handle_event ($window, $event: $mode) {...} # two invocants
Multi invocant arguments are passed positionally, though the first
invocant can be passed via the method call syntax if the multi happens
to be defined as a multi method within the class of the first invocant.
# Multimethod calls...
handle_event($w, $e, $m);
$w.handle_event($e, $m);
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 same precedence:
# Indirect method call...
set_name $obj: "Sam";
# Indirect multimethod call...
handle_event $w, $e: $m;
Passing too many or too few invocants is a fatal error if no matching
definition can be found.
An invocant is the topic of the corresponding method or multi if that
formal parameter is declared with the name $_. A method's single
invocant always has the alias "self". Other styles of self can be
declared with the "self" pragma.
Required parameters
Required parameters are specified at the start of a subroutine's
parameter list:
sub numcmp ($x, $y) { return $x <=> $y }
Required parameters may optionally be declared with a trailing "!",
though that's already the default for positional parameters:
sub numcmp ($x!, $y!) { return $x <=> $y }
The corresponding arguments are evaluated in scalar context and may be
passed positionally or by name. To pass an argument by name, specify it
as a pair: "parameter_name => argument_value".
$comparison = numcmp(2,7);
$comparison = numcmp(x=>2, y=>7);
$comparison = numcmp(y=>7, x=>2);
Pairs may also be passed in adverbial pair notation:
$comparison = numcmp(:x(2), :y(7));
$comparison = numcmp(:y(7), :x(2));
Passing the wrong number of required arguments to a normal subroutine
is a fatal error. Passing a NamedArg that cannot be bound to a normal
subroutine is also a fatal error. (Methods are different.)
The number of required parameters a subroutine has can be determined by
calling its ".arity" method:
$args_required = &foo.arity;
Optional parameters
Optional positional parameters are specified after all the required
parameters and each is marked with a "?" after the parameter:
sub my_substr ($str, $from?, $len?) {...}
Alternately, optional fields may be marked by supplying a default
value. The "=" sign introduces a default value:
sub my_substr ($str, $from = 0, $len = Inf) {...}
Default values can be calculated at run-time. They may even use the
values of preceding parameters:
sub xml_tag ($tag, $endtag = matching_tag($tag) ) {...}
Arguments that correspond to optional parameters are evaluated in
scalar context. They can be omitted, passed positionally, or passed by
name:
my_substr("foobar"); # $from is 0, $len is infinite
my_substr("foobar",1); # $from is 1, $len is infinite
my_substr("foobar",1,3); # $from is 1, $len is 3
my_substr("foobar",len=>3); # $from is 0, $len is 3
Missing optional arguments default to their default value, or to an
undefined value if they have no default. (A supplied argument that is
undefined is not considered to be missing, and hence does not trigger
the default. Use "//=" within the body for that.)
(Conjectural: Within the body you may also use "exists" on the
parameter name to determine whether it was passed. Maybe this will
have to be restricted to the "?" form, unless we're willing to admit
that a parameter could be simultaneously defined and non-existant.)
Named parameters
Named-only parameters follow any required or optional parameters in the
signature. They are marked by a ":":
sub formalize($text, :$case, :$justify) {...}
This is actually shorthand for:
sub formalize($text, :case($case), :justify($justify)) {...}
Arguments 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:
$formal = formalize($title, case=>'upper');
$formal = formalize($title, justify=>'left');
$formal = formalize($title, :justify<right>, :case<title>);
Named parameters are optional unless marked with "!". Default values
for optional named parameters are defined in the same way as for
positional parameters, but may depend only on the values of parameters
that have already been bound. (Note that binding happens in the call
order, not declaration order.) Named optional parameters default to
"undef" if they have no default. Named required parameters fail unless
an argument pair of that name is supplied.
Again, note the use of adverbial pairs in the argument list. The
following table shows the correspondence:
Fat arrow Adverbial pair
========= ==============
a => 1 :a
a => 0 :a(0)
a => $x :a($x)
a => 'foo' :a<foo>
a => <foo bar> :a<foo bar>
a => X$foo @barX :aX$foo @barX
a => {...} :a{...}
a => [...] :a[...]
a => $a :$a
a => @a :@a
a => %a :%a
a => %foo<a> %foo:<a>
List parameters
List parameters capture a variable length list of data. They're used in
subroutines like "print", where the number of arguments needs to be
flexible. They're also called "variadic parameters", because they take
a variable number of arguments. But generally we call them "slurpy"
parameters because they slurp up arguments.
Slurpy parameters follow any required or optional parameters. They are
marked by a "*" before the parameter:
sub duplicate($n, *%flag, *@data) {...}
Named arguments are bound to the slurpy hash (*%flag in the above
example). Such arguments are evaluated in scalar context. Any
remaining variadic arguments at the end of the argument list are bound
to the slurpy array (*@data above) and are evaluated in list context.
For example:
duplicate(3, reverse => 1, collate => 0, 2, 3, 5, 7, 11, 14);
duplicate(3, :reverse, :collate(0), 2, 3, 5, 7, 11, 14); # same
# The @data parameter receives [2, 3, 5, 7, 11, 14]
# The %flag parameter receives { reverse => 1, collate => 0 }
Slurpy scalar parameters capture what would otherwise be the first
elements of the variadic array:
sub head(*$head, *@tail) { return $head }
sub neck(*$head, *$neck, *@tail) { return $neck }
sub tail(*$head, *@tail) { return @tail }
head(1, 2, 3, 4, 5); # $head parameter receives 1
# @tail parameter receives [2, 3, 4, 5]
neck(1, 2, 3, 4, 5); # $head parameter receives 1
# $neck parameter receives 2
# @tail parameter receives [3, 4, 5]
Slurpy scalars still impose list context on their arguments.
Slurpy parameters are treated lazily -- the list is only flattened into
an array when individual elements are actually accessed:
@fromtwo = tail(1..Inf); # @fromtwo contains a lazy [2..Inf]
You can't bind to the name of a slurpy parameter: the name is just
there so you can refer to it within the body.
sub foo(*%flag, *@data) {...}
foo(:flag{ a => 1 }, :data[ 1, 2, 3 ]);
# %flag has elements (flag => (a => 1)) and (data => [1,2,3])
# @data has nothing
Slurpy block
It's also possible to declare a slurpy block: *&block. It slurps up
any nameless block, specified by "{...}", at either the current
positional location or the end of the syntactic list. Put it first if
you want the option of putting a block either first or last in the
arguments. Put it last if you want to force it to come in as the last
argument.
Argument list binding
The underlying argument list (List) object may be bound to a single
scalar parameter marked with a "\":
sub foo (\$args) { say $args.perl; &bar.call(*$args); }
sub bar ($a,$b,$c,:$mice) { say $mice }
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) { ... }
Apart from that, no other parameters are allowed in the signature after
the List. Parameters before the List either do not show up in the List
or are marked as already bound somehow. In other words, parameters are
bound normally up to the List parameter, and then "\$args" takes a
snapshot of the remaining input without further attempts at binding.
Flattening argument lists
The unary prefix operator "*" dereferences its operand (which allows
the elements of an array or iterator or List or Tuple to be used as
part of an argument list). The "*" operator also causes its operand --
and any subsequent arguments in the argument list -- to be evaluated in
list context. It also turns off syntactic recognition of named pairs.
The eventual argument list will be parsed at call time for named pairs.
All contiguous pairs are treated as named arguments until the first
non-Pair, and the rest of the arguments are considered slurpy args.
[XXX still underspecified...]
sub foo($x, $y, $z) {...} # expects three scalars
@onetothree = 1..3; # array stores three scalars
foo(1,2,3); # okay: three args found
foo(@onetothree); # error: only one arg
foo(*@onetothree); # okay: @onetothree flattened to three args
The "*" operator flattens lazily -- the array is flattened only if
flattening is actually required within the subroutine. To flatten
before the list is even passed into the subroutine, use the unary
prefix "**" operator:
foo(**@onetothree); # array flattened before &foo called
Multidimensional argument list binding
Some functions take multiple Lists that they wish not to be flattened
into one list. For instance, "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 ";"
twigil:
sub foo (*@;slices) { ... }
It is allowed to specify a return type:
sub foo (*@;slices --> Num) { ... }
Pipe operators
The variadic array of a subroutine call can be passed in separately
from the normal argument list, by using either of the "pipe" operators:
"<==" or "==>".
Each operator expects to find a call to a variadic receiver on its
"sharp" end, and a list of values on its "blunt" end:
grep { $_ % 2 } <== @data;
@data ==> grep { $_ % 2 };
It binds the (potentially lazy) list from the blunt end to the slurpy
parameter(s) of the receiver on the sharp end. In the case of a
receiver that is a variadic function, the pipe is received as part of
its slurpy list. So both of the calls above are equivalent to:
grep { $_ % 2 } @data;
Leftward pipes are a convenient way of explicitly indicating the
typical right-to-left flow of data through a chain of operations:
@oddsquares = map { $_**2 }, sort grep { $_ % 2 }, @nums;
# more clearly written as...
@oddsquares = map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums;
Rightward pipes are a convenient way of reversing the normal data flow
in a chain of operations, to make it read left-to-right:
@oddsquares =
(@nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 });
Note that the parens are necessary there due to precedence.
If the operand on the sharp end of a pipe is not a call to a variadic
operation, it must be something else that can be interpreted as a list
receiver.
You may use a variable (or variable declaration) as a receiver, in
which case the list value is bound as the "todo" of the variable. Do
not think of it as an assignment, nor as an ordinary binding. Think of
it as iterator creation. In the case of a scalar variable, that
variable contains the newly created iterator itself. In the case of an
array, the new iterator is installed as the method for extending the
array. Unlike with assignment, no clobbering of the array is implied.
It's therefore more like a push than an assignment.
In general you can simply think of a receiver array as representing the
results of the pipeline, so you can equivalently write any of:
my @oddsquares <== map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums;
my @oddsquares
<== map { $_**2 }
<== sort
<== grep { $_ % 2 }
<== @nums;
@nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 } ==> my @oddsquares;
@nums
==> grep { $_ % 2 }
==> sort
==> map { $_**2 }
==> my @oddsquares;
Since the pipe iterator is bound into the final variable, the variable
can be just as lazy as the pipe that is producing the values.
Because pipes are bound to arrays with "push" semantics, you can have a
receiver for multiple pipes:
my @foo;
0..2 ==> @foo;
'a'..'c' ==> @foo;
say @foo; # 0,1,2,'a','b','c'
Note how the pipes are concatenated in @foo so that @foo is a list of 6
elements. This is the default behavior. However, sometimes you want
to capture the outputs as a list of two iterators, namely the two
iterators that represent the two input pipes. You can get at those two
iterators by using the name "@;foo" instead, where the "pipe" twigil
marks a multidimensional array, that is, an array of slices.
0... ==> @;foo;
'a'... ==> @;foo;
pidigits() ==> @;foo;
for zip(@;foo) { say }
[0,'a',3]
[1,'b',1]
[2,'c',4]
[3,'d',1]
[4,'e',5]
[5,'f',9]
...
Here "@;foo" is an array of three iterators, so
zip(@;foo)
is equivalent to
zip(@;foo[0]; @;foo[1]; @;foo[2])
A semicolon inside brackets is equivalent to stacked pipes. The code
above could be rewritten as:
(0...; 'a'...; pidigits()) ==> my @;foo;
for @;foo.zip { say }
which is in turn equivalent to
for zip(0...; 'a'...; pidigits()) { say }
A named receiver array is useful when you wish to pipe into an
expression that is not an ordinary list operator, and you wish to be
clear where the pipe's destination is supposed to be:
picklist() ==> my @baz;
my @foo = @bar[@baz];
Various contexts may or may not be expecting multi-dimensional slices
or pipes. By default, ordinary arrays are flattened, that is, they
have "cat" semantics. If you say
(0..2; 'a'..'c') ==> my @tmp;
for @tmp { say }
then you get 0,1,2,'a','b','c'. If you have a multidim array, you can
ask for cat semantics explicitly with cat():
(0..2; 'a'..'c') ==> my @;tmp;
for @;tmp.cat { say }
As we saw earlier, "zip" produces little arrays by taking one element
from each list in turn, so
(0..2; 'a'..'c') ==> my @;tmp;
for @;tmp.zip { say }
produces [0,'a'],[1,'b'],[2,'c']. If you don't want the subarrays,
then use "each()" instead:
(0..2; 'a'..'c') ==> my @;tmp;
for @;tmp.map { say }
and then you just get 0,'a',1,'b',2,'c'. This is good for
for @;tmp.map -> $i, $a { say "$i: $a" }
In list context the "@;foo" notation is really a shorthand for
"[;](@;foo)".
Every lexical scope gets its own implicitly declared "@;" variable,
which is the default receiver. So instead of using "@;foo" above you
can just say
0... ==> ;
'a'... ==> ;
pidigits() ==> ;
for zip(@;) { say }
Note that with the current definition, the order of pipes is preserved
left to right in general regardless of the position of the receiver.
So
('a'...; 0...) ==> ;
for zip(@; <== @foo) -> [$a, $i, $x] { ...}
is the same as
'a'... ==> ;
0... ==> ;
for zip(@; <== @foo) -> [$a, $i, $x] { ...}
which is the same as
for zip('a'...; 0...; @foo) -> [$a, $i, $x] { ...}
And
@foo ==> ;
0... ==> ;
for each(@;) -> $x, $i { ...}
is the same as
0... ==> ;
for each(@foo; @;) -> $x, $i { ...}
which is the same as
for each(@foo; 0...) -> $x, $i { ...}
Note that the each method is also sensitive to multislicing, so you
could also just write that as:
(@foo; 0...).map: -> $x, $i { ...}
Also note that these come out to identical for ordinary arrays:
@foo.map
@foo.cat
Closure parameters
Parameters declared with the "&" sigil take blocks, closures, or
subroutines as their arguments. Closure parameters can be required,
optional, named, or slurpy.
sub limited_grep (Int $count, &block, *@list) {...}
# and later...
@first_three = limited_grep 3, {$_<10}, @data;
Within the subroutine, the closure parameter can be used like any other
lexically scoped subroutine:
sub limited_grep (Int $count, &block, *@list) {
...
if block($nextelem) {...}
...
}
The closure parameter can have its own signature in a type
specification written with ":(...)":
sub limited_Dog_grep ($count, &block:(Dog), Dog *@list) {...}
and even a return type:
sub limited_Dog_grep ($count, &block:(Dog --> Bool), Dog *@list) {...}
When an argument is passed to a closure parameter that has this kind of
signature, the argument must be a "Code" object with a compatible
parameter list and return type.
Type parameters
Unlike normal parameters, type parameters often come in piggybacked on
the actual value as "kind", and you'd like a way to capture both the
value and its kind at once. (A "kind" is a class or type that an
object is allowed to be. An object is not officially allowed to take
on a constrained or contravariant type.) A type variable can be used
anywhere a type name can, but instead of asserting that the value must
conform to a particular type, instead captures the actual "kind" of
object and also declares a package/type name by which you can refer to
that kind later in the signature or body. For instance, if you wanted
to match any two Dogs as long as they were of the same kind, you can
say:
sub matchedset (Dog ::T $fido, T $spot) {...}
(Note that "::T" is not required to contain "Dog", only a type that is
compatible with "Dog".)
The "::" sigil is short for "subset" in much the same way that "&" is
short for "sub". Just as "&" can be used to name any kind of code, so
too "::" can be used to name any kind of type. Both of them insert a
bare identifier into the grammar, though they fill different syntactic
spots.
Note that it is not required to capture the object associated with the
class unless you want it. The sub above could be written
sub matchedset (Dog ::T, T) {...}
if we're not interested in $fido or $spot. Or just
sub matchedset (::T, T) {...}
if we don't care about anything but the matching.
Unpacking array parameters
Instead of specifying an array parameter as an array:
sub quicksort (@data, ?$reverse, ?$inplace) {
my $pivot := shift @data;
...
}
it may be broken up into components in the signature, by specifying the
parameter as if it were an anonymous array of parameters:
sub quicksort ([$pivot, *@data], ?$reverse, ?$inplace) {
...
}
This subroutine still expects an array as its first argument, just like
the first version.
Unpacking a single list argument
To match the first element of the slurpy list, use a "slurpy" scalar:
sub quicksort (:$reverse, :$inplace, *$pivot, *@data)
Unpacking hash parameters
Likewise, a hash argument can be mapped to a hash of parameters,
specified as named parameters within curlies. Instead of saying:
sub register (%guest_data, $room_num) {
my $name := delete %guest_data<name>;
my $addr := delete %guest_data<addr>;
...
}
you can get the same effect with:
sub register ({:$name, :$addr, *%guest_data}, $room_num) {
...
}
Unpacking tree node parameters
You can unpack tree nodes in various dwimmy ways by enclosing the
bindings of child nodes and attributes in parentheses following the
declaration of the node itself
sub traverse ( BinTree $top ( $left, $right ) ) {
traverse($left);
traverse($right);
}
In this, $left and $right are automatically bound to the left and right
nodes of the tree. If $top is an ordinary object, it binds the
"$top.left" and "$top.right" attributes. If it's a hash, it binds
"$top<left>" and "$top<right>". If "BinTree" is a signature type and
$top is a List (argument list) object, the child types of the signature
are applied to the actual arguments in the argument list object.
(Signature types have the benefit that you can view them inside-out as
constructors with positional arguments, such that the transformations
can be reversible.)
However, the full power of signatures can be applied to pattern match
just about any argument or set of arguments, even though in some cases
the reverse transformation is not intuitable. For instance, to bind to
an array of children named ".kids" or ".<kids>", use something like:
sub traverse ( NAry $top ( :kids [$eldest, *@siblings] ) ) {
traverse($eldest);
traverse(@siblings);
}
Likewise, to bind to a hash element of the node and then bind to keys
in that hash by name:
sub traverse ( AttrNode $top ( :%attr{ :$vocalic, :$tense } ) {
say "Has {+%attr} attributes, of which";
say "vocalic = $vocalic";
say "tense = $tense";
}
You may omit the top variable if you prefix the parentheses with a
colon to indicate a signature. Otherwise you must at least put the
sigil of the variable, or we can't correctly differentiate:
my Dog ($fido, $spot) = twodogs(); # list of two dogs
my Dog $ ($fido, $spot) := twodogs(); # one twodog object
my Dog :($fido, $spot) := twodogs(); # one twodog object
Subsignatures can be matched directly with rules by using ":(...)"
notation.
push @a, "foo";
push @a, \(1,2,3);
push @a, "bar";
...
my ($i, $j, $k);
@a ~~ rx/
<,> # match initial elem boundary
:(Int $i,Int $j,Int? $k) # match tuple with 2 or 3 ints
<,> # match final elem boundary
/;
say "i = $<i>";
say "j = $<j>";
say "k = $<k>" if defined $<k>;
If you want a parameter bound into $/, you have to say "$<i>" within
the signature. Otherwise it will try to bind an external $i instead,
and fail if no such variable is declared.
Note that unlike a sub declaration, a rule-embedded signature has no
associated "returns" syntactic slot, so you have to use "-->" within
the signature to specify the type of the tuple, or match as an arglist:
:(Num, Num --> Coord)
:(\Coord(Num, Num))
A consequence of the latter form is that you can match the type of an
object with ":(\Dog)" without actually breaking it into its components.
Note, however, that it's not equivalent to say
:(--> Dog)
which would be equivalent to
:(\Dog())
that is, match a null tuple of type "Dog". Nor is it equivalent to
:(Dog)
which would be equivalent to
:(\Any(Dog))
or
:([Dog])
and match a tuple-ish item with a single value of type Dog.
Note also that bare "\(1,2,3)" is never legal in a rule since the first
paren would try to match literally.
Attributive parameters
If a submethod's parameter is declared with a "." or "!" after the
sigil (like an attribute):
submethod initialize($.name, $!age) {}
then the argument is assigned directly to the object's attribute of the
same name. This avoids the frequent need to write code like:
submethod initialize($name, $age) {
$.name = $name;
$!age = $age;
}
To rename an attribute parameter you can use the explicit pair form:
submethod initialize(:moniker($.name), :youth($!age)) {}
The ":$name" shortcut may be combined with the "$.name" shortcut, but
the twigil is ignored for the parameter name, so
submethod initialize(:$.name, :$!age) {}
is the same as:
submethod initialize(:name($.name), :age($!age)) {}
Note that "$!age" actually refers to the private ""has"" variable that
can be referred to either as $age or "$!age".
Placeholder variables
Even though every bare block is a closure, bare blocks can't have
explicit parameter lists. Instead, they use "placeholder" variables,
marked by a caret ("^") after their sigils.
Using placeholders in a block defines an implicit parameter list. The
signature is the list of distinct placeholder names, sorted in Unicode
order. So:
{ $^y < $^z && $^x != 2 }
is a shorthand for:
-> $x,$y,$z { $y < $z && $x != 2 }
Note that placeholder variables syntactically cannot have type
constraints.
Types
These are some of the standard type names in Perl 6 (at least this
week):
bit single native bit
int native integer
buf native 8-bit string (sequence of 8-bit integers, no Unicode)
str native string (sequence of arbitrary integers, no Unicode)
num native floating point
complex native complex number
ref native pointer
bool native boolean
Bit Perl single bit (allows traits, aliasing, undef, etc.)
Int Perl integer (allows traits, aliasing, undef, etc.)
Str Perl string (Unicode semantics)
Num Perl number
Complex Perl complex number
Ref Perl reference
Bool Perl boolean
Array Perl array
Hash Perl hash
IO Perl filehandle
Code Base class for all executable objects
Routine Base class for all nameable executable objects
Sub Perl subroutine
Method Perl method
Submethod Perl subroutine acting like a method
Macro Perl compile-time subroutine
Rule Perl pattern
Block Base class for all embedded executable objects
Package Perl 5 compatible namespace
Module Perl 6 standard namespace
Class Perl 6 standard class namespace
Role Perl 6 standard generic interface/implementation
Object Perl 6 object
Grammar Perl 6 pattern matching namespace
List Lazy Perl list
Tuple Completely evaluated (hence immutable) list
Value types
Explicit types are optional. Perl variables have two associated types:
their "value type" and their "implementation type". (More generally,
any container has an implementation type, including subroutines and
modules.)
The value type specifies what kinds of values may be stored in the
variable. A value type is given as a prefix or with the "returns" or
"of" keywords:
my Dog $spot;
my $spot returns Dog;
my $spot of Dog;
our Animal sub get_pet() {...}
sub get_pet() returns Animal {...}
sub get_pet() of Animal {...}
A value type on an array or hash specifies the type stored by each
element:
my Dog @pound; # each element of the array stores a Dog
my Rat %ship; # the value of each entry stores a Rat
The key type of a hash may be specified as a shape trait--see S09.
Implementation types
The implementation type specifies how the variable itself is
implemented. It is given as a trait of the variable:
my $spot is Scalar; # this is the default
my $spot is PersistentScalar;
my $spot is DataBase;
Defining an implementation type is the Perl 6 equivalent to tying a
variable in Perl 5. But Perl 6 variables are tied directly at
declaration time, and for performance reasons may not be tied with a
run-time "tie" statement unless the variable is explicitly declared
with an implementation type that does the "Tieable" role.
Hierarchical types
A non-scalar type may be qualified, in order to specify what type of
value each of its elements stores:
my Egg $cup; # the value is an Egg
my Egg @carton; # each elem is an Egg
my Array of Egg @box; # each elem is an array of Eggs
my Array of Array of Egg @crate; # each elem is an array of arrays of Eggs
my Hash of Array of Recipe %book; # each value is a hash of arrays of Recipes
Each successive "of" makes the type on its right a parameter of the
type on its left. Parametric types are named using square brackets, so:
my Hash of Array of Recipe %book;
actually means:
my Hash[returns => Array[returns => Recipe]] %book;
Because the actual variable can be hard to find when complex types are
specified, there is a postfix form as well:
my Hash of Array of Recipe %book; # HoHoAoRecipe
my %book of Hash of Array of Recipe; # same thing
my %book returns Hash of Array of Recipe; # same thing
The "returns" form is more commonly seen in subroutines:
my Hash of Array of Recipe sub get_book ($key) {...}
my sub get_book ($key) of Hash of Array of Recipe {...}
my sub get_book ($key) returns Hash of Array of Recipe {...}
Alternately, the return type may be specified within the signature:
my sub get_book ($key --> Hash of Array of Recipe) {...}
There is a slight difference, insofar as the type inferencer will
ignore a "returns" but pay attention to "-->" declarations. Only the
inside of the subroutine pays attention to "returns".
Polymorphic types
Anywhere you can use a single type you can use a set of types, for
convenience specifiable as if it were an "or" junction:
my Int|Str $error = $val; # can assign if $val~~Int or $val~~Str
Fancier type constraints may be expressed through a subtype:
subset Shinola of Any where {.does(DessertWax) and .does(FloorTopping)};
if $shimmer ~~ Shinola {...} # $shimmer must do both interfaces
Since the terms in a parameter could be viewed as a set of contraints
that are implicitly "anded" together (the variable itself supplies type
constraints, and where clauses or tree matching just add more
constraints), we relax this to allow juxtaposition of anded types:
my Cat|Dog Fish $mitsy = new Fish but { int rand 2 ?? .does Cat;
!! .does Dog };
Parameter types
Parameters may be given types, just like any other variable:
sub max (int @array is rw) {...}
sub max (@array of int is rw) {...}
Generic types
Within a declaration, a class variable (either by itself or following
an existing type name) declares a new type name and takes its
parametric value from the actual type of the parameter it is associated
with. It declares the new type name in the same scope as the
associated declaration.
sub max (Num ::X @array ) {
push @array, X.new();
}
The new type name is introduced immediately, so two such types in the
same signature must unify compatibly if they have the same name:
sub compare (Any ::T $x, T $y) {
return $x eqv $y;
}
Return types
On a scoped subroutine, a return type can be specified before or after
the name:
our Egg sub lay {...}
our sub lay returns Egg {...}
my Rabbit sub hat {...}
my sub hat returns Rabbit {...}
If a subroutine is not explicitly scoped, it belongs to the current
namespace (module, class, grammar, or package), as if it's scoped with
the "our" scope modifier. Any return type must go after the name:
sub lay returns Egg {...}
On an anonymous subroutine, any return type can only go after the "sub"
keyword:
$lay = sub returns Egg {...};
but you can use a scope modifier to introduce a return type:
$lay = my Egg sub {...};
$hat = my Rabbit sub {...};
Because they are anonymous, you can change the "my" modifier to "our"
without affecting the meaning.
The return type may also be specified after a "-->" token within the
signature. This doesn't mean exactly the same thing as "returns". The
arrow form is an "official" return type, and may be used to do type
inferencing outside the sub. The "returns" form only makes the return
type available to the internals of the sub so that the "return"
statement can know its context, but outside the sub we don't know
anything about the return value, as if no return type had been
declared. The prefix form actually corresponds to the "-->" semantics
rather than the "returns" semantics, so the return type of
my Fish sub wanda ($x) { ... }
is known to return an object of type Fish, as if you'd said:
my sub wanda ($x --> Fish) { ... }
not as if you'd said
my sub wanda ($x) returns Fish { ... }
It is possible for the outer type to disagree with the outside type:
my Squid sub wanda ($x) returns Fish { ... }
or equivalently,
my sub wanda ($x --> Squid) returns Fish { ... }
It's not clear why you'd want to lie to yourself like that, though.
Properties and traits
Compile-time properties are called "traits". The "is NAME (DATA)"
syntax defines traits on containers and subroutines, as part of their
declaration:
my $pi is constant = 3;
my $key is Persistent(:file<.key>);
sub fib is cached {...}
The "will NAME BLOCK" syntax is a synonym for "is NAME (BLOCK)":
my $fh will undo { close $fh }; # Same as: my $fh is undo({ close $fh });
The "but NAME (DATA)" syntax specifies run-time properties on values:
my $pi = 3 but Approximate("legislated");
sub system {
...
return $error but false if $error;
return 0 but true;
}
Properties are predeclared as roles and implemented as mixins--see S12.
Subroutine traits
These traits may be declared on the subroutine as a whole (individual
parameters take other traits).
"is signature"
The signature of a subroutine. Normally declared implicitly, by
providing a parameter list and/or return type.
"returns"/"is returns"
The type returned by a subroutine.
"will do"
The block of code executed when the subroutine is called. Normally
declared implicitly, by providing a block after the subroutine's
signature definition.
"is rw"
Marks a subroutine as returning an lvalue.
"is parsed"
Specifies the rule by which a macro call is parsed.
"is cached"
Marks a subroutine as being memoized.
"is inline"
Suggests to the compiler that the subroutine is a candidate for
optimization via inlining.
"is tighter"/"is looser"/"is equiv"
Specifies the precedence of an operator relative to an existing
operator. "equiv" also specifies the default associativity to be
the same as the operator to which the new operator is equivalent.
"tighter" and "looser" operators default to left associative.
"is assoc"
Specifies the associativity of an operator explicitly. Valid
values are:
Tag Examples Meaning of $a op $b op $c
=== ======== =========================
left + - * / x ($a op $b) op $c
right ** = $a op ($b op $c)
non cmp <=> .. ILLEGAL
chain == eq ~~ ($a op $b) and ($b op $c)
list | & ^ X listop($a, $b, $c) or listop($a; $b; $c)
Note that operators ""equiv"" to relationals are automatically
considered chaining operators. When creating a new precedence
level, the chaining is determined by by the presence or absence of
""is assoc('chaining')"", and other operators defined at that level
are required to be the same.
"PRE"/"POST"
Mark blocks that are to be unconditionally executed before/after
the subroutine's "do" block. These blocks must return a true value,
otherwise an exception is thrown.
"FIRST"/"LAST"/"NEXT"/"KEEP"/"UNDO"/etc.
Mark blocks that are to be conditionally executed before or after
the subroutine's "do" block. These blocks are generally used only
for their side effects, since most return values will be ignored.
"FIRST" may be an exception, but in that case you probably want to
use a state variable anyway.
Parameter traits
The following traits can be applied to many types of parameters.
"is readonly"
Specifies that the parameter cannot be modified (e.g. assigned to,
incremented). It is the default for parameters.
"is rw"
Specifies that the parameter can be modified (assigned to,
incremented, etc). Requires that the corresponding argument is an
lvalue or can be converted to one.
When applied to a variadic parameter, the "rw" trait applies to
each element of the list:
sub incr (*@vars is rw) { $_++ for @vars }
(The variadic array as a whole is always modifiable, but such
modifications have no effect on the original argument list.)
"is ref"
Specifies that the parameter is passed by reference. Unlike "is
rw", the corresponding argument must already be a suitable lvalue.
No attempt at coercion or autovivification is made, so unsuitable
values throw an exception when you try to modify them.
"is copy"
Specifies that the parameter receives a distinct, read-writable
copy of the original argument. This is commonly known as "pass-by-
value".
sub reprint ($text, $count is copy) {
print $text while $count-- > 0;
}
"is context(TYPE)"
Specifies the context that a parameter applies to its argument.
Typically used to cause a final list parameter to apply a series of
scalar contexts:
# &format may have as many arguments as it likes,
# each of which is evaluated in scalar context
sub format(*@data is context(Scalar)) {...}
Note that the compiler may not be able to propagate such a scalar
context to a function call used as a parameter to a method or
multisub whose signature is not visible until dispatch time. Such
function call parameters are called in list context by default, and
must be coerced to scalar context explicitly if that is desired.
Advanced subroutine features
The "caller" function
The "caller" function returns an object that describes a particular
"higher" dynamic scope, from which the current scope was called.
print "In ", caller.sub,
" called from ", caller.file,
" line ", caller.line,
"\n";
"caller" may be given arguments telling it what kind of higher scope to
look for, and how many such scopes to skip over when looking:
$caller = caller; # immediate caller
$caller = caller Method; # nearest caller that is method
$caller = caller Bare; # nearest caller that is bare block
$caller = caller Sub, :skip(2); # caller three levels up
$caller = caller Block, :label<Foo>; # caller whose label is 'Foo'
The "want" function
The "want" function returns an object that contains information about
the context in which the current block, closure, or subroutine was
called.
The returned context object is typically tested with a smart match
("~~") or a "when":
given want {
when Scalar {...} # called in scalar context
when List {...} # called in list context
when Lvalue {...} # expected to return an lvalue
when 2 {...} # expected to return two values
...
}
or has the corresponding methods called on it:
if (want.Scalar) {...} # called in scalar context
elsif (want.List) {...} # called in list context
elsif (want.rw) {...} # expected to return an lvalue
elsif (want.count > 2) {...} # expected to return more than two values
Note these are pseudo type associations. There's no such thing as an
Lvalue object, and a List is really an unbound argument list object,
parts of which may in fact be eventually bound into scalar context.
The "leave" function
A "return" statement causes the innermost surrounding subroutine,
method, rule, macro, or multimethod to return. Only declarations with
an explicit keyword such as "sub" may be returned from.
To return from other types of code structures, the "leave" function is
used:
leave; # return from innermost block of any kind
leave Method; # return from innermost calling method
leave &?SUB <== 1,2,3; # Return from current sub. Same as: return 1,2,3
leave &foo <== 1,2,3; # Return from innermost surrounding call to &foo
leave Loop, :label<COUNT>; # Same as: last COUNT;
Temporization
The "temp" function temporarily replaces the value of an existing
variable, subroutine, or other object in a given scope:
{
temp $*foo = 'foo'; # Temporarily replace global $foo
temp &bar = sub {...}; # Temporarily replace sub &bar
...
} # Old values of $*foo and &bar reinstated at this point
"temp" invokes its argument's ".TEMP" method. The method is expected to
return a reference to a subroutine that can later restore the current
value of the object. At the end of the lexical scope in which the
"temp" was applied, the subroutine returned by the ".TEMP" method is
executed.
The default ".TEMP" method for variables simply creates a closure that
assigns the variable's pre-"temp" value back to the variable.
New kinds of temporization can be created by writing storage classes
with their own ".TEMP" methods:
class LoudArray is Array {
method TEMP {
print "Replacing $_.id() at $(caller.location)\n";
my $restorer = .SUPER::TEMP();
return {
print "Restoring $_.id() at $(caller.location)\n";
$restorer();
};
}
}
You can also modify the behaviour of temporized code structures, by
giving them a "TEMP" block. As with ".TEMP" methods, this block is
expected to return a closure, which will be executed at the end of the
temporizing scope to restore the subroutine to its pre-"temp" state:
my $next = 0;
sub next {
my $curr = $next++;
TEMP {{ $next = $curr }} # TEMP block returns the closure { $next = $curr }
return $curr;
}
# and later...
say next(); # prints 0; $next == 1
say next(); # prints 1; $next == 2
say next(); # prints 2; $next == 3
if ($hiccough) {
say temp next(); # prints 3; closes $curr at 3; $next == 4
say next(); # prints 4; $next == 5
say next(); # prints 5; $next == 6
} # $next = 3
say next(); # prints 3; $next == 4
say next(); # prints 4; $next == 5
Hypothetical variables use the same mechanism, except that the
restoring closure is called only on failure.
Note that "env" variables may be a better solution than temporized
globals in the face of multithreading.
Wrapping
Every subroutine has a ".wrap" method. This method expects a single
argument consisting of a block, closure, or subroutine. That argument
must contain a call to the special "call" function:
sub thermo ($t) {...} # set temperature in Celsius, returns old temp
# Add a wrapper to convert from Fahrenheit...
$id = &thermo.wrap( { call( ($^t-32)/1.8 ) } );
The call to ".wrap" replaces the original subroutine with the closure
argument, and arranges that the closure's call to "call" invokes the
original (unwrapped) version of the subroutine. In other words, the
call to ".wrap" has more or less the same effect as:
&old_thermo := &thermo;
&thermo := sub ($t) { old_thermo( ($t-32)/1.8 ) }
The call to ".wrap" returns a unique identifier that can later be
passed to the ".unwrap" method, to undo the wrapping:
&thermo.unwrap($id);
A wrapping can also be restricted to a particular dynamic scope with
temporization:
# Add a wrapper to convert from Kelvin
# wrapper self-unwraps at end of current scope
temp &thermo.wrap( { call($^t + 273.16) } );
Within a wrapper, the &_ variable is implicitly declared as a lexical
by the wrapper, and refers to the function that "call" implicitly
calls. Thus, for non-wrappers, you may also declare your own &_
lexical variable (or parameter) and then use "call" to call whatever is
referenced by &_. (In the absence of such a declaration, "call"
magically steals the dispatch list from the current dispatcher, and
redispatches to the next-most-likely method or multi-sub.)
The entire unprocessed argument List can be captured by a "\$args"
parameter. It can then be passed to "call" as *$args.
The "&?SUB" routine
"&?SUB" is always an alias for the current subroutine, so you can
specify tail-recursion on an anonymous sub:
my $anonfactorial = sub (Int $n) {
return 1 if $n<2;
return $n * &?SUB($n-1);
};
"$?SUBNAME" contains the name of the current subroutine, if any.
Note that "&?SUB" refers to the current single sub, even if it is
declared "multi". To redispatch to the entire suite under a given
short name, just use the named form, since there are no anonymous
multis.
The "&?BLOCK" routine
"&?BLOCK" is always an alias for the current block, so you can specify
tail-recursion on an anonymous block:
my $anonfactorial = -> Int $n { $n < 2
?? 1
:: $n * &?BLOCK($n-1)
};
"$?BLOCKLABEL" contains the label of the current block, if any.
[Note: to refer to any $? or "&?" variable at the time the sub or block
is being compiled, use the "COMPILING::" pseudopackage.]
Currying
Every subroutine has an ".assuming" method. This method does a partial
binding of a set of arguments to a signature and returns a new function
that takes only the remaining arguments.
&textfrom := &substr.assuming(str=>$text, len=>Inf);
or equivalently:
&textfrom := &substr.assuming(:str($text) :len(Inf));
or even:
&textfrom := &substr.assuming:str($text):len(Inf);
It returns a reference to a subroutine that implements the same
behaviour as the original subroutine, but has the values passed to
".assuming" already bound to the corresponding parameters:
$all = $textfrom(0); # same as: $all = substr($text,0,Inf);
$some = $textfrom(50); # same as: $some = substr($text,50,Inf);
$last = $textfrom(-1); # same as: $last = substr($text,-1,Inf);
The result of a "use" statement is a (compile-time) object that also
has an ".assuming" method, allowing the user to bind parameters in all
the module's subroutines/methods/etc. simultaneously:
(use IO::Logging).assuming(logfile => ".log");
This form should generally be restricted to named parameters.
To curry a particular multimethod it may be necessary to specify the
type of one or more of its invocants:
&woof ::= &bark:(Dog).assuming :pitch<low>;
&pine ::= &bark:(Tree).assuming :pitch<yes>;
Macros
Macros are functions or operators that are called by the compiler as
soon as their arguments are parsed (if not sooner). The syntactic
effect of a macro declaration or importation is always lexically
scoped, even if the name of the macro is visible elsewhere. As with
ordinary operators, macros may be classified by their grammatical
category. For a given grammatical category, a default parsing rule or
set of rules is used, but those rules that have not yet been "used" by
the time the macro keyword or token is seen can be replaced by use of
"is parsed" trait. (This means, for instance, that an infix operator
can change the parse rules for its right operand but not its left
operand.)
In the absence of a signature to the contrary, a macro is called as if
it were a method on the current match object returned from the grammar
rule being reduced; that is, all the current parse information is
available by treating "self" as if it were a $/ object. [Conjecture:
alternate representations may be available if arguments are declared
with particular AST types.]
Macros may return either a string to be reparsed, or a syntax tree that
needs no further parsing. The textual form is handy, but the syntax
tree form is generally preferred because it allows the parser and
debugger to give better error messages. Textual substitution on the
other hand tends to yield error messages that are opaque to the user.
Syntax trees are also better in general because they are reversible, so
things like syntax highlighters can get back to the original language
and know which parts of the derived program come from which parts of
the user's view of the program.
In aid of returning syntax tree, Perl provides a "quasiquoting"
mechanism using the quote "q:code", followed by a block intended to
represent an AST:
return q:code { say "foo" };
Modifiers to the ":code" adverb can modify the operation:
:ast(MyAst) # Default :ast(AST)
:lang(Ruby) # Default :lang($?PARSER)
:unquote<[: :]> # Default "triple rule"
Within a quasiquote, variable and function names resolve according to
the lexical scope of the macro definition. Unrecognized symbols raise
errors when the macro is being compiled, not when it's being used.
To make a symbol resolve to the (partially compiled) scope of the macro
call, use the "COMPILING::" pseudo-package:
macro moose () { q:code { $COMPILING::x } }
moose(); # macro-call-time error
my $x;
moose(); # resolves to 'my $x'
If you want to mention symbols from the scope of the macro call, use
the import syntax as modifiers to ":code":
:COMPILING<$x> # $x always refers to $x in caller's scope
:COMPILING # All free variables fallback to caller's scope
If those symbols do not exist in the scope of the compiling scope, a
compile-time exception is thrown at macro call time.
Similarly, in the macro body you may either refer to the $x declared in
the scope of the macro call as $COMPILING::x, or bind to them
explicitly:
my $x := $COMPILING::x;
You may also use an import list to bind multiple symbols into the
macro's lexical scope:
require COMPILING <$x $y $z>;
Note that you need to use the run-time ":=" and "require" forms, not
"::=" and "use", because the macro caller's compile-time is the macro's
runtime.
Splicing
Bare AST variables (such as the arguments to the macro) may not be
spliced directly into a quasiquote because they would be taken as
normal bindings. Likewise, program text strings to be inserted need to
be specially marked or they will be bound normally. To insert a
"unquoted" expression of either type within a quasiquote, use the
quasiquote delimiter tripled, typically a bracketing quote of some
sort:
return q:code { say $a + {{{ $ast }}} }
return q:code [ say $a + [[[ $ast ]]] ]
return q:code < say $a + <<< $ast >>> >
return q:code ( say $a + ((( $ast ))) )
(Note to implementors: this must not be implemented by finding the
final closing delimiter and preprocessing, or we'll violate our one-
pass parsing rule. Perl 6 parsing rules are parameterized to know
their closing delimiter, so adding the opening delimiter should not be
a hardship. Alternately the opening delimiter can be deduced from the
closing delimiter. Writing a rule that looks for three opening
delimiters in a row should not be a problem. It has to be a special
grammar rule, though, not a fixed token, since we need to be able to
nest code blocks with different delimiters. Likewise when parsing the
inner expression, the inner parser rule is parameterized to know that
"}}}" or whatever is its closing delimiter.)
The delimiters don't have to be bracketing quotes, but the following is
probably to be construed as Bad Style:
return q:code / say $a + /// $ast /// /
Dequoted expressions are inserted appropriately depending on the type
of the variable, which may be either a syntax tree or a string.
(Again, syntax tree is preferred.) The case is similar to that of a
macro called from within the quasiquote, insofar as reparsing only
happens with the string version of interpolation, except that such a
reparse happens at macro call time rather than macro definition time,
so its result cannot change the parser's expectations about what
follows the interpolated variable.
Hence, while the quasiquote itself is being parsed, the syntactic
interpolation of a unquoted expression into the quasiquote always
results in the expectation of an operator following the variable. (You
must use a call to a submacro if you want to expect something else.)
Of course, the macro definition as a whole can expect whatever it likes
afterwards, according to its syntactic category. (Generally, a term
expects a following postfix or infix operator, and an operator expects
a following term or prefix operator.)
A quasiquote is not a block (even if the delimiters are curlies), so
any declaration of a variable is taken to be part of the block
surrounding the macro call location. Add your own {...} if you want a
block to surround your declarations.
Other matters
Anonymous hashes vs blocks
"{...}" is always a block. However, if it is completely empty or
consists of a single list, the first element of which is either a hash
or a pair, it is executed immediately to compose a hash reference.
The standard "pair" list operator is equivalent to:
sub pair (*@LIST) {
my @pairs;
for @LIST -> $key, $val {
push @pairs, $key => $val;
}
return @pairs;
}
or more succinctly (and lazily):
sub pair (*@LIST) {
gather {
for @LIST -> $key, $val {
take $key => $val;
}
}
}
The standard "hash" list operator is equivalent to:
sub hash (*@LIST) {
return { pair @LIST };
}
So you may use "sub" or "hash" or "pair" to disambiguate:
$ref = sub { 1, 2, 3, 4, 5, 6 }; # Anonymous sub returning list
$ref = { 1, 2, 3, 4, 5, 6 }; # Anonymous sub returning list
$ref = { 1=>2, 3=>4, 5=>6 }; # Anonymous hash
$ref = { 1=>2, 3, 4, 5, 6 }; # Anonymous hash
$ref = hash( 1, 2, 3, 4, 5, 6 ); # Anonymous hash
$ref = hash 1, 2, 3, 4, 5, 6 ; # Anonymous hash
$ref = { pair 1, 2, 3, 4, 5, 6 }; # Anonymous hash
Pairs as lvalues
Pairs can be used as lvalues. The value of the pair is the recipient of
the assignment:
(key => $var) = "value";
When binding pairs, names can be used to "match up" lvalues and
rvalues, provided you write the left side as a signature using ":(...)"
notation:
:(:who($name), :why($reason)) := (why => $because, who => "me");
(Otherwise the parser doesn't know it should parse the insides as a
signature and not as an ordinary expression until it gets to the ":=",
and that would be bad. Possibly we should require a ""my"" out front
as well...)
Out-of-scope names
"GLOBAL::<$varname>" specifies the $varname declared in the "*"
namespace. Or maybe it's the other way around...
"CALLER::<$varname>" specifies the $varname visible in the dynamic
scope from which the current block/closure/subroutine was called,
provided that variable is declared with the ""env"" declarator.
(Implicit lexicals such as $_ are automatically assumed to be
environmental.)
"ENV::<$varname>" specifies the $varname visible in the innermost
dynamic scope that declares the variable with the ""env"" declarator.
"MY::<$varname>" specifies the lexical $varname declared in the current
lexical scope.
"OUR::<$varname>" specifies the $varname declared in the current
package's namespace.
"COMPILING::<$varname>" specifies the $varname declared (or about to be
declared) in the lexical scope currently being compiled.
"OUTER::<$varname>" specifies the $varname declared in the lexical
scope surrounding the current lexical scope (i.e. the scope in which
the current block was defined).
perl v5.14.0 2006-02-28 Perl6::Bible::S06(3)
