Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 3644 lines (2697 sloc) 146.605 kb
be1862e P6 Synopsis : ws changes - to help BOMers, added leading blank line to f...
Darren_Duncan authored
1
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
2 =encoding utf8
3
4 =head1 TITLE
5
6 Synopsis 6: Subroutines
7
8 =head1 VERSION
9
04840a3 [Spec] treat all authors equally
lwall authored
10 Created: 21 Mar 2003
7d103a5 [S06] only prefix:<foo> makes named unary, not sub foo ($)
lwall authored
11
4198be6 Moritz Lenz Undocument the "self" pragma
moritz authored
12 Last Modified: 27 Feb 2015
ab16f15 Moritz Lenz Document bare :D at al in parameter lists
moritz authored
13 Version: 166
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
14
15 This document summarizes Apocalypse 6, which covers subroutines and the
16 new type system.
17
18 =head1 Subroutines and other code objects
19
0a5a59c Larry Wall $! and $/ are created only by routines/compunits
TimToady authored
20 C<Routine> is the parent type of all keyword-declared code blocks.
21 All routines are born with undefined values of C<$_>, C<$!>,
22 and C<$/>, unless the routine declares them otherwise explicitly.
0b7df09 Larry Wall rename eval to EVAL to indicate specialness
TimToady authored
23 A compilation unit, such as a module file or an C<EVAL> string, is also
4301ccb lizmat An attempt at explaining what a thunk is
lizmat authored
24 considered a routine, or you would not be
25 able to reference C<$!> or C<$/> in them.
26
27 Non-routine code C<Block>s,
0a5a59c Larry Wall $! and $/ are created only by routines/compunits
TimToady authored
28 declared with C<< -> >> or with bare curlies, are born only with C<$_>,
08b8886 Larry Wall require parallelizers to declare $/ and $! dynvars
TimToady authored
29 which is aliased to its OUTER::<$_> unless bound as a parameter.
30 A block generally uses the C<$!> and C<$/> defined by the innermost
31 enclosing routine, unless C<$!> or C<$/> is explicitly declared in
4301ccb lizmat An attempt at explaining what a thunk is
lizmat authored
32 the block.
33
34 A thunk is a piece of code that may not execute immediately, for instance
35 because it is part of a conditional operator, or a default initialization of
36 an attribute. It has no scope of its own, so any new variables defined in
37 a thunk, will leak to the scope that they're in. Note however that
08b8886 Larry Wall require parallelizers to declare $/ and $! dynvars
TimToady authored
38 any and all lazy constructs, whether block-based or thunk-based,
6b3e9d8 Larry Wall more s/async/start/ tweaks
TimToady authored
39 such as gather or start or C<< ==> >> should declare their own C<$/>
08b8886 Larry Wall require parallelizers to declare $/ and $! dynvars
TimToady authored
40 and C<$!> so that the user's values for those variables cannot be
4301ccb lizmat An attempt at explaining what a thunk is
lizmat authored
41 clobbered asynchronously.
0a5a59c Larry Wall $! and $/ are created only by routines/compunits
TimToady authored
42
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
43 B<Subroutines> (keyword: C<sub>) are non-inheritable routines with
44 parameter lists.
45
46 B<Methods> (keyword: C<method>) are inheritable routines which always
47 have an associated object (known as their invocant) and belong to a
48 particular kind or class.
49
50 B<Submethods> (keyword: C<submethod>) are non-inheritable methods, or
51 subroutines masquerading as methods. They have an invocant and belong to
52 a particular kind or class.
53
54 B<Regexes> (keyword: C<regex>) are methods (of a grammar) that perform
55 pattern matching. Their associated block has a special syntax (see
56 Synopsis 5). (We also use the term "regex" for anonymous patterns
57 of the traditional form.)
58
59 B<Tokens> (keyword: C<token>) are regexes that perform low-level
60 non-backtracking (by default) pattern matching.
61
62 B<Rules> (keyword: C<rule>) are regexes that perform non-backtracking
63 (by default) pattern matching (and also enable rules to do whitespace
64 dwimmery).
65
9282235 Larry Wall start revising the highly maligned macro specs :-)
TimToady authored
66 B<Macros> (keyword: C<macro> or C<slang>) are routines or methods that are
67 installed such that they will be called as part of the compilation process,
68 and which can therefore take temporary control of the subsequent
69 compilation to cheat in any of the ways that a compiler might cheat.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
70
71 =head1 Routine modifiers
72
73 B<Multis> (keyword: C<multi>) are routines that can have multiple
74 variants that share the same name, selected by arity, types, or some
75 other constraints.
76
77 B<Prototypes> (keyword: C<proto>) specify the commonalities (such
78 as parameter names, fixity, and associativity) shared by all multis
79 of that name in the scope of the C<proto> declaration. A C<proto>
80 also adds an implicit C<multi> to all routines of the same short
81 name within its scope, unless they have an explicit modifier.
82 (This is particularly useful when adding to rule sets or when attempting
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
83 to compose conflicting methods from roles.) Abstractly, the C<proto>
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
84 is a generic wrapper around the dispatch to the C<multi>s. Each C<proto>
45ca8c8 nick patch fix typos
patch authored
85 is instantiated into an actual dispatcher for each scope that
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
86 needs a different candidate list.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
87
88 B<Only> (keyword: C<only>) routines do not share their short names
89 with other routines. This is the default modifier for all routines,
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
90 unless a C<proto> of the same name was already in scope. (For subs,
91 the governing C<proto> must have been declared in the same file, so
92 C<proto> declarations from the setting or other modules don't have
93 this effect unless explicitly imported.)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
94
95 A modifier keyword may occur before the routine keyword in a named routine:
96
97 only sub foo {...}
98 proto sub foo {...}
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
99 dispatch sub foo {...} # internal
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
100 multi sub foo {...}
101
102 only method bar {...}
103 proto method bar {...}
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
104 dispatch method bar {...} # internal
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
105 multi method bar {...}
106
107 If the routine keyword is omitted, it defaults to C<sub>.
108
109 Modifier keywords cannot apply to anonymous routines.
110
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
111 A C<proto> is a generic dispatcher, which any given scope with a unique
112 candidate list will instantiate into a C<dispatch> routine. Hence
113 a C<proto> is never called directly, much like a C<role> can't be
114 used as an instantiated object.
115
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
116 When you call any routine (or method, or rule) that may have multiple
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
117 candidates, the basic dispatcher is really only calling an "only"
118 sub or method--but if there are multiple candidates, the "only" that
119 will be found is really a dispatcher. This instantiated C<dispatch>
120 is always called first (at least in the abstract--this can often be
121 optimized away). In essence, a C<dispatch> is dispatched exactly
122 like an C<only> sub, but the C<dispatch> itself may delegate to any
123 of the candidates it is "managing".
124
125 It is the C<dispatch>'s responsibility to first vet the arguments for all the
126 candidates; any call that does not successfully bind the C<dispatch>'s signature fails outright.
127 (Its signature is a copy of one belonging to the C<proto> from which it was instantiated.)
128 The C<dispatch> does not necessarily send the original capture to its candidates, however.
129 Named arguments that bind to positionals in the C<dispatch> sig will become positionals
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
130 for all subsequent calls to its managed multis.
131
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
132 The dispatch then considers its list of managed candidates from the
133 viewpoint of the caller or object, sorts them into some order, and
134 dispatches them according to the rules of multiple dispatch as defined
135 for each of the various dispatchers. In the case of multi subs, the
136 candidate list is known at compile time. In the case of multi methods,
137 it may be necessary to generate (or regenerate) the candidate list at
138 run time, depending on what is known when about the inheritance tree.
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
139
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
140 This default dispatch behavior is symbolized within the original
141 C<proto> by a block containing of a single C<*> (that is, a
142 "whatever"). Hence the typical C<proto> will simply have a body
143 of C<{*}>.
a58dfe6 [S06] define a * statement to represent a call from a proto to its multi...
lwall authored
144
145 proto method bar {*}
146
147 (We don't use C<...> for that because it would fail at run time,
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
148 and the proto's instantiated C<dispatch> blocks are not stubs, but
149 are intended to be executed.)
a58dfe6 [S06] define a * statement to represent a call from a proto to its multi...
lwall authored
150
2d5a1a5 [S05,S06] more refinements to {*}
lwall authored
151 Other statements may be inserted before and after the C<{*}>
a58dfe6 [S06] define a * statement to represent a call from a proto to its multi...
lwall authored
152 statement to capture control before or after the multi dispatch:
153
2d5a1a5 [S05,S06] more refinements to {*}
lwall authored
154 proto foo ($a,$b) { say "Called with $a $b"; {*}; say "Returning"; }
a58dfe6 [S06] define a * statement to represent a call from a proto to its multi...
lwall authored
155
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
156 (That C<proto> is only good for C<multi>s with side effects and no return
a58dfe6 [S06] define a * statement to represent a call from a proto to its multi...
lwall authored
157 value, since it returns the result of C<say>, which might not be what
158 you want. See below for how to fix that.)
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
159
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
160 The syntactic form C<&foo> (without a modifying signature) can never
161 refer to a C<multi> candidate or a generic C<proto>. It may only
162 refer to the single C<only> or C<dispatch> routine that would first
163 be called by C<foo()>. Individual C<multi>s may be named by appending
164 a signature to the noun form: C<&foo:($,$,*@)>.
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
165
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
166 We used the term "managed" loosely above to indicate the set of C<multi>s in
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
167 question; the "managed set" is more accurately defined as the intersection
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
168 of all the C<multi>s in the C<proto>'s downward scope with all the C<multi>s that
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
169 are visible to the caller's upward-looking scope. For ordinary routines
170 this means looking down lexical scopes and looking up lexical scopes. [This
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
171 is more or less how C<multi>s already behave.]
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
172
173 For methods this means looking down or up the inheritance tree; "managed set"
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
174 in this case translates to the intersection of all methods in the C<proto>'s
175 class or its subclasses with all C<multi> methods visible to the object in its
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
176 parent classes, that is, the parent classes of the object's actual type on
177 whose behalf the method was called. [Note, this is a change from prior
178 multi method semantics, which restricted multimethods to a single class;
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
179 the old semantics is equivalent to defining a C<proto> in every class that has
180 multimethods. The new way gives the user the ability to intermix C<multi>s at
70a8dce lizmat Add missing closing ]
lizmat authored
181 different inheritance levels].
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
182
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
183 Also, the old semantics of C<proto> providing the most-default C<multi> body
184 is hereby deprecated. Default C<multi>s should be marked with "C<is default>".
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
185
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
186 It is still possible to provide default behavior in the C<proto>, however, by
187 using it as a wrapper:
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
188
2d5a1a5 [S05,S06] more refinements to {*}
lwall authored
189 my proto sub foo (@args) {
190 do-something-before(@args);
191 {*} # call into the managed set, then come back
192 do-something-after(@args);
a58dfe6 [S06] define a * statement to represent a call from a proto to its multi...
lwall authored
193 }
194
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
195 Note that this returns the value of do-something-after(), not the C<multi>.
2d5a1a5 [S05,S06] more refinements to {*}
lwall authored
196 There are two ways to get around that. Here's one way:
a58dfe6 [S06] define a * statement to represent a call from a proto to its multi...
lwall authored
197
2d5a1a5 [S05,S06] more refinements to {*}
lwall authored
198 my proto sub foo (@args) {
199 ENTER do-something-before(@args);
200 {*}
201 LEAVE do-something-after(@args);
9e98d52 [S06] long-threatened revamp of proto to keep routine and method semanti...
lwall authored
202 }
203
2d5a1a5 [S05,S06] more refinements to {*}
lwall authored
204 Alternately, you can spell out what C<{*}> is actually sugar for,
205 which would be some dispatcher macro such as:
206
eb862b2 japhb Banish |$ and \$ in more places
japhb authored
207 my proto sub foo (|cap (@args)) {
2d5a1a5 [S05,S06] more refinements to {*}
lwall authored
208 do-something-before(@args);
b9679d4 timo make a proto example work again.
timo authored
209 my \retcap = MULTI-DISPATCH-CALLWITH(&?ROUTINE, cap);
2d5a1a5 [S05,S06] more refinements to {*}
lwall authored
210 do-something-after(@args);
b9679d4 timo make a proto example work again.
timo authored
211 return retcap;
2d5a1a5 [S05,S06] more refinements to {*}
lwall authored
212 }
213
214 which optimizes (we hope) to an inlined multidispatcher to locate all
215 the candidates for these arguments (hopefully memoized), create the dynamic
216 scope of a dispatch, start the dispatch, manage C<callnext> and C<lastcall>
217 semantics, and return the result of whichever C<multi> succeeded, if any.
218
47af4ce Cory Spencer Fixed minor typo.
cspencer authored
219 Which is why we have C<{*}> instead.
a58dfe6 [S06] define a * statement to represent a call from a proto to its multi...
lwall authored
220
221 Another common variant would be to propagate control to the
222 outer/higher routine that would have been found if this one didn't
223 exist:
224
2d5a1a5 [S05,S06] more refinements to {*}
lwall authored
225 my proto method foo { {*}; UNDO nextsame; } # failover to super foo
a58dfe6 [S06] define a * statement to represent a call from a proto to its multi...
lwall authored
226
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
227 Note that, in addition to making C<multi>s work similarly to each other,
228 the new C<proto> semantics greatly simplify top-level dispatchers, which
229 never have to worry about C<multi>s, because C<multi>s are always in the
97e1532 [S06] More rationale for the proto simplification
lwall authored
230 second half of the double dispatch (again, just in the abstract, since
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
231 the first dispatch can often be optimized away, as if the C<proto> were
97e1532 [S06] More rationale for the proto simplification
lwall authored
232 inlined). So in the abstract, C<foo()> only ever calls a single
eea6822 felher [S06] convert "We Know Which One It Is" to lc
felher authored
233 C<only>/C<proto> routine, and we know which one it is at compile time.
97e1532 [S06] More rationale for the proto simplification
lwall authored
234
235 This is less of a shift for method dispatch, which already assumed that there
236 is something like a single proto in each class that redispatches inside
237 the class. Here the change is that multi-method dispatcher needs to look
238 more widely for its candidates than the current class. But note that our
239 semantics were inconsistent before, insofar as regex methods already had to
240 look for this larger managed set in order to do transitive LTM correctly.
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
241 Now the semantics of normal method C<proto>s and regex C<proto>s are nearly
97e1532 [S06] More rationale for the proto simplification
lwall authored
242 identical, apart from the fact that regex candidate lists naturally have
243 fancier tiebreaking rules involving longest token matching.
244
60aef3a Larry Wall Adjust proto semantics to address various concerns
TimToady authored
245 A C<dispatch> must be generated for every scope that contains one or more C<multi>
246 declaration. This is done by searching backwards and outwards (or up the
247 inheritance chain for methods) for a C<proto> to instantiate. If no such
248 C<proto> is found, a "most generic" C<proto> will be generated, something like:
249
250 proto sub foo (*@, *%) {*}
251 proto method foo (*@, *%) {*}
252
253 Obviously, no named-to-positional remapping can be done in this case.
254
255 [Conjecture: we could instead autogen a more specific signature for
256 each such autogenerated C<dispatch> once we know its exact candidate
257 set, such that consistent use of positional parameter names is rewarded
258 with positional names in the generated signature, which could remap
259 named parameters.]
260
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
261 =head2 Named subroutines
262
263 The general syntax for named subroutines is any of:
264
265 my RETTYPE sub NAME ( PARAMS ) TRAITS {...} # lexical only
f7d7198 Carl Mäsak [S06] corrected my/our fossil
masak authored
266 sub NAME ( PARAMS ) TRAITS {...} # same as "my"
267 our RETTYPE sub NAME ( PARAMS ) TRAITS {...} # package-scoped
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
268
269 The return type may also be put inside the parentheses:
270
271 sub NAME (PARAMS --> RETTYPE) {...}
272
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
jimmy authored
273 Unlike in Perl 5, named subroutines are considered expressions,
274 so this is valid Perl 6:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
275
276 my @subs = (sub foo { ... }, sub bar { ... });
277
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
278 Another difference is that subroutines default to C<my> scope rather
279 than C<our> scope. However, subroutine dispatch searches lexical
280 scopes outward, and subroutines are also allowed to be I<postdeclared>
281 after their use, so you won't notice this much. A subroutine that is
282 not declared yet may be called using parentheses around the arguments,
283 in the absence of parentheses, the subroutine call is assumed to take
284 multiple arguments in the form of a list operator.
285
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
286 =head2 Anonymous subroutines
287
288 The general syntax for anonymous subroutines is:
289
290 sub ( PARAMS ) TRAITS {...}
291
4b32e07 [S06] fossil, my/our anonymous subs were superseded by 'anon' some time ...
lwall authored
292 But one can also use the C<anon> scope modifier to introduce the return type first:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
293
4b32e07 [S06] fossil, my/our anonymous subs were superseded by 'anon' some time ...
lwall authored
294 anon RETTYPE sub ( PARAMS ) TRAITS {...}
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
295
93bd42f [S06] specify syntax for strongly-typed closure variables
diakopter authored
296 When an anonymous subroutine will be assigned to a scalar variable,
297 the variable can be declared with the signature of the routines that
298 will be assigned to it:
299
fc1083f [Spec] :() is now always signature. Use foofix:[...] as the general op ...
lwall authored
300 my $grammar_factory:(Str, int, int --> Grammar);
93bd42f [S06] specify syntax for strongly-typed closure variables
diakopter authored
301 $grammar_factory = sub (Str $name, int $n, int $x --> Grammar) { ... };
302
303 Covariance allows a routine (that has a more derived return type than what is
304 defined in the scalar's signature) to be assigned to that scalar.
305 Contravariance allows a routine (with parameter types that are less derived
306 than those in the scalar's signature) to be assigned to that scalar. The
307 compiler may choose to enforce (by type-checking) such assignments at
308 compile-time, if possible. Such type annotations are intended to help the
309 compiler optimize code to the extent such annotations are included and/or to
310 the extent they aid in type inference.
311
312 The same signature can be used to mark the type of a closure parameter to
313 another subroutine:
314
fc1083f [Spec] :() is now always signature. Use foofix:[...] as the general op ...
lwall authored
315 sub (int $n, &g_fact:(Str, int, int --> Grammar) --> Str) { ... }
93bd42f [S06] specify syntax for strongly-typed closure variables
diakopter authored
316
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
317 B<Trait> is the name for a compile-time (C<is>) property.
318 See L<"Properties and traits">.
319
320
321 =head2 Perl5ish subroutine declarations
322
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
jimmy authored
323 You can declare a sub without parameter list, as in Perl 5:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
324
325 sub foo {...}
326
895607e [S06] only add @_ and %_ to default sig if actually used in body
lwall authored
327 This is equivalent to one of:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
328
895607e [S06] only add @_ and %_ to default sig if actually used in body
lwall authored
329 sub foo () {...}
330 sub foo (*@_) {...}
331 sub foo (*%_) {...}
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
332 sub foo (*@_, *%_) {...}
333
895607e [S06] only add @_ and %_ to default sig if actually used in body
lwall authored
334 depending on whether either or both of those variables are used in the body of the routine.
335
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
336 Positional arguments implicitly come in via the C<@_> array, but
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
jimmy authored
337 unlike in Perl 5 they are C<readonly> aliases to actual arguments:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
338
339 sub say { print qq{"@_[]"\n}; } # args appear in @_
340
341 sub cap { $_ = uc $_ for @_ } # Error: elements of @_ are read-only
342
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
jimmy authored
343 Also unlike in Perl 5, Perl 6 has true named arguments, which come in
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
344 via C<%_> instead of C<@_>. (To construct pseudo-named arguments that
5ace2bd [S03] remove p5=> description since it's not supported in core
lwall authored
345 come in via C<@_> as in Perl 5, the p5-to-p6 translator will define and use the ugly
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
jimmy authored
346 C<< p5=> >> operator instead of Perl 6's C<< => >> Pair constructor.)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
347
348 If you need to modify the elements of C<@_> or C<%_>, declare the
349 array or hash explicitly with the C<is rw> trait:
350
351 sub swap (*@_ is rw, *%_ is rw) { @_[0,1] = @_[1,0]; %_<status> = "Q:S"; }
352
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
353 Note: the C<rw> container trait is automatically distributed to the
004d676 [Perl6/Spec] typos
schwarzer authored
354 individual elements by the slurpy star even though there is no
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
355 actual array or hash passed in. More precisely, the slurpy star
356 means the declared formal parameter is I<not> considered readonly; only
357 its elements are. See L</Parameters and arguments> below.
358
359 Note also that if the sub's block contains placeholder variables
360 (such as C<$^foo> or C<$:bar>), those are considered to be formal
361 parameters already, so in that case C<@_> or C<%_> fill the role of
362 sopping up unmatched arguments. That is, if those containers are
363 explicitly mentioned within the body, they are added as slurpy
364 parameters. This allows you to easily customize your error message
365 on unrecognized parameters. If they are not mentioned in the body,
366 they are not added to the signature, and normal dispatch rules will
367 simply fail if the signature cannot be bound.
368
369 =head2 Blocks
370
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
jimmy authored
371 Raw blocks are also executable code structures in Perl 6.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
372
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
373 Every block defines an object of type C<Block> (which C<does Callable>), which may either be
374 executed immediately or passed on as a C<Block> object. How a block is
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
375 parsed is context dependent.
376
377 A bare block where an operator is expected terminates the current
378 expression and will presumably be parsed as a block by the current
379 statement-level construct, such as an C<if> or C<while>. (If no
380 statement construct is looking for a block there, it's a syntax error.)
381 This form of bare block requires leading whitespace because a bare
382 block where a postfix is expected is treated as a hash subscript.
383
384
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
385 A bare block where a term is expected merely produces a C<Block> object.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
386 If the term bare block occurs in a list, it is considered the final
387 element of that list unless followed immediately by a comma or colon
388 (intervening C<\h*> or "unspace" is allowed).
389
390 =head2 "Pointy blocks"
391
392 Semantically the arrow operator C<< -> >> is almost a synonym for the
393 C<sub> keyword as used to declare an anonymous subroutine, insofar as
394 it allows you to declare a signature for a block of code. However,
395 the parameter list of a pointy block does not require parentheses,
396 and a pointy block may not be given traits. In most respects,
397 though, a pointy block is treated more like a bare block than like
398 an official subroutine. Syntactically, a pointy block may be used
399 anywhere a bare block could be used:
400
401 my $sq = -> $val { $val**2 };
402 say $sq(10); # 100
403
404 my @list = 1..3;
405 for @list -> $elem {
406 say $elem; # prints "1\n2\n3\n"
407 }
408
409 It also behaves like a block with respect to control exceptions.
410 If you C<return> from within a pointy block, the block is transparent
411 to the return; it will return from the innermost enclosing C<sub> or
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
412 C<method> (et al.), not from the block itself. It is referenced by C<&?BLOCK>,
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
413 not C<&?ROUTINE>.
414
415 A normal pointy block's parameters default to C<readonly>, just like
416 parameters to a normal sub declaration. However, the double-pointy variant
417 defaults parameters to C<rw>:
418
419 for @list <-> $elem {
420 $elem++;
421 }
422
423 This form applies C<rw> to all the arguments:
424
425 for @kv <-> $key, $value {
426 $key ~= ".jpg";
427 $value *= 2 if $key ~~ :e;
428 }
429
430 =head2 Stub declarations
431
432 To predeclare a subroutine without actually defining it, use a "stub block":
433
434 sub foo {...} # Yes, those three dots are part of the actual syntax
435
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
jimmy authored
436 The old Perl 5 form:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
437
438 sub foo;
439
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
jimmy authored
440 is a compile-time error in Perl 6 (because it would imply that the body of the
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
441 subroutine extends from that statement to the end of the file, as C<class> and
442 C<module> declarations do). The only allowed use of the semicolon form is to
443 declare a C<MAIN> sub--see L</Declaring a MAIN subroutine> below.
444
445 Redefining a stub subroutine does not produce an error, but redefining
446 an already-defined subroutine does. If you wish to redefine a defined sub,
98a74bb deprecate "is also" and "is instead" in favor of augment and supersede d...
lwall authored
447 you must explicitly use the "C<supersede>" declarator. (The compiler may
4a4297b typo
lwall authored
448 refuse to do this if it has already committed to the previous definition.)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
449
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
450 The C<...> is the "yadayadayada" operator, which is executable but
003891a Larry Wall Explication of lazy warnings
TimToady authored
451 returns a failure. You can also use C<???> to fail with a warning
fb6b129 Steve Mynott the the -> the
stmuk authored
452 (a lazy one, to be issued only if the value is actually used),
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
453 or C<!!!> to always die. These also officially define stub blocks.
454 Any of these yada operators will be taken as a stub if used as the main
455 operator of the first statement in the block. (Statement modifiers
456 are allowed on that statement.) The yada operators differ from their
457 respective named functions in that they all default to a message
458 such as: "Unimplemented stub of sub foo was executed".
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
459
460 It has been argued that C<...> as literal syntax is confusing when
461 you might also want to use it for metasyntax within a document.
462 Generally this is not an issue in context; it's never an issue in the
463 program itself, and the few places where it could be an issue in the
464 documentation, a comment will serve to clarify the intent, as above.
465 The rest of the time, it doesn't really matter whether the reader
466 takes C<...> as literal or not, since the purpose of C<...> is to
467 indicate that something is missing whichever way you take it.
468
469
470 =head2 Globally scoped subroutines
471
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
472 Subroutines and variables can be declared in the global namespace
473 (or any package in the global namespace), and are thereafter visible
474 everywhere in the program via the GLOBAL package (or one of its
475 subpackages). They may be made directly visible by importation,
476 but may not otherwise be called with a bare identifier, since subroutine
477 dispatch only looks in lexical scopes.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
478
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
479 Global subroutines and variables are normally referred to by prefixing
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
480 their identifiers with the C<*> twigil, to allow dynamically scoped overrides.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
481
f549796 [S06] remove the slightly non-sensical 'use GLOBAL' in favor of 'defines...
lwall authored
482 GLOBAL::<$next_id> = 0;
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
483 sub GLOBAL::saith($text) { say "Yea verily, $text" }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
484
485 module A {
afbd198 [Spec] get rid of some fossil uses of * spotted by masak++
lwall authored
486 my $next_id = 2; # hides any global or package $next_id
487 &*saith($next_id); # print the lexical $next_id;
f549796 [S06] remove the slightly non-sensical 'use GLOBAL' in favor of 'defines...
lwall authored
488 &*saith($*next_id); # print the dynamic $next_id;
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
489 }
490
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
491 To disallow dynamic overrides, you must access the globals directly:
f549796 [S06] remove the slightly non-sensical 'use GLOBAL' in favor of 'defines...
lwall authored
492
493 GLOBAL::saith($GLOBAL::next_id);
494
495 The fact that this is verbose is construed to be a feature. Alternately,
496 you may play aliasing tricks like this:
497
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
498 module B {
b1fb049 [S06,S11] kill infix:<defines>, replace with statement_control:<import>
lwall authored
499 import GLOBAL <&saith $next_id>;
f549796 [S06] remove the slightly non-sensical 'use GLOBAL' in favor of 'defines...
lwall authored
500 saith($next_id); # Unambiguously the global definitions
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
501 }
502
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
503 Despite the fact that subroutine dispatch only looks in lexical scopes, you
504 can always call a package subroutine directly if there's a lexical alias
505 to it, as the C<our> declarator does:
506
507 module C;
508 our sub saith($text) { say "Yea verily, $text" }
509 saith("I do!") # okay
510 C::saith("I do!") # also okay
511
afbd198 [Spec] get rid of some fossil uses of * spotted by masak++
lwall authored
512 =head2 Dynamically scoped subroutines
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
513
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
514 Similarly, you may define dynamically scoped subroutines:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
515
082a5ca [S06] ss/is context/is dynamic/ fossil
lwall authored
516 my sub myfunc ($x) is dynamic { ... }
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
517 my sub &*myfunc ($x) { ... } # same thing
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
518
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
519 This may then be invoked via the syntax for dynamic variables:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
520
11eaf51 correct fossil
lwall authored
521 &*myfunc(42);
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
522
523 =head2 Lvalue subroutines
524
525 Lvalue subroutines return a "proxy" object that can be assigned to.
526 It's known as a proxy because the object usually represents the
527 purpose or outcome of the subroutine call.
528
529 Subroutines are specified as being lvalue using the C<is rw> trait.
530
531 An lvalue subroutine may return a variable:
532
533 my $lastval;
534 sub lastval () is rw { return $lastval }
535
536 or the result of some nested call to an lvalue subroutine:
537
538 sub prevval () is rw { return lastval() }
539
540 or a specially tied proxy object, with suitably programmed
541 C<FETCH> and C<STORE> methods:
542
543 sub checklastval ($passwd) is rw {
8a99698 Moritz Lenz [S06] avoid indirect method call syntax
moritz authored
544 return Proxy.new:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
545 FETCH => method {
546 return lastval();
547 },
548 STORE => method ($val) {
549 die unless check($passwd);
550 lastval() = $val;
551 };
552 }
553
554 Other methods may be defined for specialized purposes such as temporizing
555 the value of the proxy.
556
45caa2b Larry Wall Allow 'is parcel' on subs that are only sorta rw
TimToady authored
557 =head2 Parcel subroutines
558
559 If the subroutine doesn't care whether the returned value is a container or not,
560 it may declare this with C<is parcel>, to indicate that the return value should
b327dcf Larry Wall typo spotted by lizmat++
TimToady authored
561 be returned raw, without attempting any decontainerization. This can be useful for
45caa2b Larry Wall Allow 'is parcel' on subs that are only sorta rw
TimToady authored
562 routines that wish to process mixed containers and non-containers without distinction.
563
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
564 =head2 Operator overloading
565
566 Operators are just subroutines with special names and scoping.
567 An operator name consists of a grammatical category name followed by
568 a single colon followed by an operator name specified as if it were
081817f lizmat Removed superfluous "a"
lizmat authored
569 one or more strings. So any of these indicates the same binary addition operator:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
570
571 infix:<+>
572 infix:«+»
573 infix:<<+>>
fc1083f [Spec] :() is now always signature. Use foofix:[...] as the general op ...
lwall authored
574 infix:['+']
575 infix:["+"]
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
576
577 Use the C<&> sigil just as you would on ordinary subs.
578
579 Unary operators are defined as C<prefix> or C<postfix>:
580
581 sub prefix:<OPNAME> ($operand) {...}
582 sub postfix:<OPNAME> ($operand) {...}
583
584 Binary operators are defined as C<infix>:
585
586 sub infix:<OPNAME> ($leftop, $rightop) {...}
587
588 Bracketing operators are defined as C<circumfix> where a term is expected
589 or C<postcircumfix> where a postfix is expected. A two-element slice
590 containing the leading and trailing delimiters is the name of the
591 operator.
592
593 sub circumfix:<LEFTDELIM RIGHTDELIM> ($contents) {...}
fc1083f [Spec] :() is now always signature. Use foofix:[...] as the general op ...
lwall authored
594 sub circumfix:['LEFTDELIM','RIGHTDELIM'] ($contents) {...}
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
595
596 Contrary to Apocalypse 6, there is no longer any rule about splitting an even
597 number of characters. You must use a two-element slice. Such names
598 are canonicalized to a single form within the symbol table, so you
599 must use the canonical name if you wish to subscript the symbol table
600 directly (as in C<< PKG::{'infix:<+>'} >>). Otherwise any form will
601 do. (Symbolic references do not count as direct subscripts since they
602 go through a parsing process.) The canonical form always uses angle
603 brackets and a single space between slice elements. The elements
fc1083f [Spec] :() is now always signature. Use foofix:[...] as the general op ...
lwall authored
604 are escaped on brackets, so C<< PKG::circumfix:['<','>'] >> is canonicalized
605 to C<<< PKG::{'circumfix:<\< \>>'} >>>, and decanonicalizing may always
606 be done left-to-right.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
607
608 Operator names can be any sequence of non-whitespace characters
609 including Unicode characters. For example:
610
611 sub infix:<(c)> ($text, $owner) { return $text but Copyright($owner) }
612 method prefix:<±> (Num $x --> Num) { return +$x | -$x }
613 multi sub postfix:<!> (Int $n) { $n < 2 ?? 1 !! $n*($n-1)! }
614
615 my $document = $text (c) $me;
616
617 my $tolerance = ±7!;
618
619 <!-- This is now a comment -->
620
621 Whitespace may never be part of the name (except as separator
622 within a C<< <...> >> or C<«...»> slice subscript, as in the example above).
623
624 A null operator name does not define a null or whitespace operator, but
625 a default matching subrule for that syntactic category, which is useful when
626 there is no fixed string that can be recognized, such as tokens beginning
627 with digits. Such an operator I<must> supply an C<is parsed> trait.
628 The Perl grammar uses a default subrule for the C<:1st>, C<:2nd>, C<:3rd>,
629 etc. regex modifiers, something like this:
630
631 sub regex_mod_external:<> ($x) is parsed(token { \d+[st|nd|rd|th] }) {...}
632
633 Such default rules are attempted in the order declared. (They always follow
634 any rules with a known prefix, by the longest-token-first rule.)
635
636 Although the name of an operator can be installed into any package or
637 lexical namespace, the syntactic effects of an operator declaration are
638 always lexically scoped. Operators other than the standard ones should
0849660 lizmat The * namespace is now called GLOBAL::
lizmat authored
639 not be installed into the C<GLOBAL::> namespace. Always use exportation to make
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
640 non-standard syntax available to other scopes.
641
e5b8663 Larry Wall --> as context for code body
TimToady authored
642 =head1 Calling conventions
643
644 In Perl 6 culture, we distinguish the terms I<parameter> and
645 I<argument>; a parameter is the formal name that will attach to an
646 incoming argument during the course of execution, while an argument
647 is the actual value that will be bound to the formal parameter.
648 The process of attaching these values (arguments) to their temporary
649 names (parameters) is known as I<binding>. (Some C.S. literature
650 uses the terms "formal argument" and "actual argument" for these
4909197 Carl Mäsak [S06] typo fixes
masak authored
651 two concepts, but here we try to avoid using the term "argument"
e5b8663 Larry Wall --> as context for code body
TimToady authored
652 for formal parameters.)
653
654 Various Perl 6 code objects (either routines or blocks) may be
aff4e89 lizmat s/an/a/
lizmat authored
655 declared with parameter lists, either explicitly by use of a signature
e5b8663 Larry Wall --> as context for code body
TimToady authored
656 declaration, or implicitly by use of placeholder variables within the body
657 of code. (Use of both for the same code block is not allowed.)
658
659 =head1 Signatures
660
661 A signature consists of a list of zero or more parameter declarations,
662 separated by commas. (These are described below.) Signatures are
663 usually found inside parentheses (within routine declarations), or
664 after an arrow C<< -> >> (within block declarations), but other forms
665 are possible for specialized cases. A signature may also indicate what
666 the code returns, either generally or specifically. This is indicated
667 by placing the return specification after a C<< --> >> token. If the
668 return specification names a type (that is, an indefinite object),
669 then a successful call to the code must always return a value of
670 that type. If the return specification returns a definite object,
671 then that value is always returned from a successful call. (For this
672 purpose the C<Nil> value is treated as definite.) An unsuccessful call
673 may always call C<fail> to return a C<Failure> object regardless of
674 the return specification.
675
676 Ordinarily, if the return is specified as a type (or is unspecified),
4909197 Carl Mäsak [S06] typo fixes
masak authored
677 the final statement of the block will be evaluated for its return
e5b8663 Larry Wall --> as context for code body
TimToady authored
678 value, and this will be the return value of the code block as a whole.
679 (It must conform to the return type specification, if provided.)
680 An explicit C<return> may be used instead to evaluate the C<return>'s
681 arguments as the code block's return value, and leave the code block
682 immediately, short-circuiting the rest of the block's execution.
683
48958ab Larry Wall Simplify Nil semantics; never means () now
TimToady authored
684 If the return specification is a definite immutable value (or C<Nil>) rather than
e5b8663 Larry Wall --> as context for code body
TimToady authored
685 a type, then all top-level statements in the code block are evaluated
686 only for their side effects; in other words, all of the statements are
687 evaluated in sink context, including the final statement. An explicit
688 C<return> statement is allowed, but only in argumentless form, to
689 indicate that execution is to be short-circuited and the I<declared>
690 return value is to be returned. No other value may be returned in
691 its place.
692
693 If the return specification is definite but not an immutable value,
694 then it must be a mutable container (variable) of some sort.
695 The container variable is declared as any other parameter would be, but
696 no incoming argument will ever be bound to it. It is permitted
697 to supply a default value, in which case the return variable will
caacd06 Rob Hoelz Clarify return variables' behavior wrt. shadowing
hoelzro authored
698 always be initialized with that default value. Like other variables
699 declared in a signature, a new variable will B<always> be created; any
700 existing variable will automatically be shadowed. If you want to have
701 the return variable reference an existing variable, you must resort to
702 C<< OUTER::<foo> >> hackery. As with value return, all top-level statements
703 are evaluated in sink context, and only argumentless C<return> is allowed,
704 indicating that the current contents of the return value should be returned.
e5b8663 Larry Wall --> as context for code body
TimToady authored
705
706 Note that the default return policy assumes functional semantics, with
707 the result that a loop as the final statement would be evaluated as
708 a map, which may surprise some people. An implementation is allowed
709 to warn when it finds such a loop; this warning may be suppressed by
710 supplying a return specification, which will also determine whether
711 the final loop statement is evaluated in sink context.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
712
e5b8663 Larry Wall --> as context for code body
TimToady authored
713 =head1 Parameters and arguments
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
714
715 By default, all parameters are readonly aliases to their corresponding
716 arguments--the parameter is just another name for the original
717 argument, but the argument can't be modified through it. This is
718 vacuously true for value arguments, since they may not be modified in
719 any case. However, the default forces any container argument to also
720 be treated as an immutable value. This extends down only one level;
721 an immutable container may always return an element that is mutable if
722 it so chooses. (For this purpose a scalar variable is not considered
723 a container of its singular object, though, so the top-level object
724 within a scalar variable is considered immutable by default. Perl 6
725 does not have references in the same sense that Perl 5 does.)
726
727 To allow modification, use the C<is rw> trait. This requires a mutable
f8fa7ce get rid of the term "protoobject" in favor of "type object" or just "typ...
lwall authored
728 object or container as an argument (or some kind of type object that
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
729 can be converted to a mutable object, such as might be returned
730 by an array or hash that knows how to autovivify new elements).
731 Otherwise the signature fails to bind, and this candidate routine
732 cannot be considered for servicing this particular call. (Other multi
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
733 candidates, if any, may succeed if they don't require C<rw> for this
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
734 parameter.) In any case, failure to bind does not by itself cause
735 an exception to be thrown; that is completely up to the dispatcher.
736
737 To pass-by-copy, use the C<is copy> trait. An object container will
738 be cloned whether or not the original is mutable, while an (immutable)
739 value will be copied into a suitably mutable container. The parameter
740 may bind to any argument that meets the other typological constraints
741 of the parameter.
742
743 If you have a readonly parameter C<$ro>, it may never be passed on to
744 a C<rw> parameter of a subcall, whether or not C<$ro> is currently
745 bound to a mutable object. It may only be rebound to readonly or
4bd6b5e [S06,S09] rename 'is ref' to 'is parcel' and make it synonymous with \
lwall authored
746 copy parameters. It may also be rebound to a parcel parameter (see
747 "C<is parcel>" below), but modification will fail as in the case where
748 an immutable value is bound to a C<parcel> parameter.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
749
750 Aliases of C<$ro> are also readonly, whether generated explicitly with C<:=>
751 or implicitly within a C<Capture> object (which are themselves immutable).
752
753 Also, C<$ro> may not be returned from an lvalue subroutine or method.
754
755 Parameters may be required or optional. They may be passed by position,
756 or by name. Individual parameters may confer an item or list context
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
jimmy authored
757 on their corresponding arguments, but unlike in Perl 5, this is decided
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
758 lazily at parameter binding time.
759
760 Arguments destined for required positional parameters must come before
761 those bound to optional positional parameters. Arguments destined
762 for named parameters may come before and/or after the positional
763 parameters. (To avoid confusion it is highly recommended that all
764 positional parameters be kept contiguous in the call syntax, but
765 this is not enforced, and custom arg list processors are certainly
766 possible on those arguments that are bound to a final slurpy or
767 arglist variable.)
768
2fc49e5 [S06] third attempt at describing elusive name collision
masak authored
769 A signature containing a name collision is considered a compile time
770 error. A name collision can occur between positional parameters, between
771 named parameters, or between a positional parameter and a named one.
772 The sigil is not considered in such a comparison, except in the case of
773 two positional parameters -- in other words, a signature in which two
774 or more parameters are identical except for the sigil is still OK (but
775 you won't be able to pass values by that name).
776
777 :($a, $a) # wrong, two $a
778 :($a, @a) # OK (but don't do that)
93a7eb5 lizmat Some elaboration on possible name collisions in signatures
lizmat authored
779 :($a, :a($b)) # wrong, one $a from positional, one $a from named parameter
780 :($a, :a(@b)) # wrong, same
781 :(:$a, :@a) # wrong, can only have one named parameter "a"
60657eb [S06] same-named non-anon positionals are a compile error
masak authored
782
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
783 =head2 Named arguments
784
785 Named arguments are recognized syntactically at the "comma" level.
786 Since parameters are identified using identifiers, the recognized
787 syntaxes are those where the identifier in question is obvious.
788 You may use either the adverbial form, C<:name($value)>, or the
789 autoquoted arrow form, C<< name => $value >>. These must occur at
790 the top "comma" level, and no other forms are taken as named pairs
791 by default. Pairs intended as positional arguments rather than named
792 arguments may be indicated by extra parens or by explicitly quoting
793 the key to suppress autoquoting:
794
795 doit :when<now>,1,2,3; # always a named arg
796 doit (:when<now>),1,2,3; # always a positional arg
797
798 doit when => 'now',1,2,3; # always a named arg
799 doit (when => 'now'),1,2,3; # always a positional arg
800 doit 'when' => 'now',1,2,3; # always a positional arg
801
781e726 Larry Wall Revert "fix 0 => $arg naminess"
TimToady authored
802 Only bare keys with valid identifier names are recognized as named arguments:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
803
804 doit when => 'now'; # always a named arg
805 doit 'when' => 'now'; # always a positional arg
781e726 Larry Wall Revert "fix 0 => $arg naminess"
TimToady authored
806 doit 123 => 'now'; # always a positional arg
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
807 doit :123<now>; # always a positional arg
808
809 Going the other way, pairs intended as named arguments that don't look
810 like pairs must be introduced with the C<|> prefix operator:
811
812 $pair = :when<now>;
813 doit $pair,1,2,3; # always a positional arg
814 doit |$pair,1,2,3; # always a named arg
815 doit |get_pair(),1,2,3; # always a named arg
816 doit |('when' => 'now'),1,2,3; # always a named arg
817
818 Note the parens are necessary on the last one due to precedence.
819
820 Likewise, if you wish to pass a hash and have its entries treated as
821 named arguments, you must dereference it with a C<|>:
822
823 %pairs = (:when<now>, :what<any>);
824 doit %pairs,1,2,3; # always a positional arg
825 doit |%pairs,1,2,3; # always named args
826 doit |%(get_pair()),1,2,3; # always a named arg
827 doit |%('when' => 'now'),1,2,3; # always a named arg
828
829 Variables with a C<:> prefix in rvalue context autogenerate pairs, so you
830 can also say this:
831
832 $when = 'now';
833 doit $when,1,2,3; # always a positional arg of 'now'
834 doit :$when,1,2,3; # always a named arg of :when<now>
835
836 In other words C<:$when> is shorthand for C<:when($when)>. This works
837 for any sigil:
838
839 :$what :what($what)
840 :@what :what(@what)
841 :%what :what(%what)
842 :&what :what(&what)
843
844 Ordinary hash notation will just pass the value of the hash entry as a
845 positional argument regardless of whether it is a pair or not.
846 To pass both key and value out of hash as a positional pair, use C<:p>
847 instead:
848
849 doit %hash<a>:p,1,2,3;
850 doit %hash{'b'}:p,1,2,3;
851
852 The C<:p> stands for "pairs", not "positional"--the C<:p> adverb may be
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
853 placed on any C<Associative> access subscript to make it mean "pairs" instead of "values".
f5aa846 [S06] fixed some spelling and consistency stuff
masak authored
854 If you want the pair (or pairs) to be interpreted as named arguments,
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
855 you may do so by prefixing with the C<< prefix:<|> >> operator:
856
c4304e7 Tim Smith [S06] Fix an example in the Named arguments section
softmoth authored
857 doit |(%hash<a>:p),1,2,3;
858 doit |(%hash{'b'}:p),1,2,3;
859
860 (The parens are required to keep the C<:p> adverb from attaching to C<< prefix:<|> >> operator.)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
861
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
862 C<Pair> constructors are recognized syntactically at the call level and
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
863 put into the named slot of the C<Capture> structure. Hence they may be
864 bound to positionals only by name, not as ordinary positional C<Pair>
865 objects. Leftover named arguments can be slurped into a slurpy hash.
866
867 Because named and positional arguments can be freely mixed, the
868 programmer always needs to disambiguate pairs literals from named
869 arguments with parentheses or quotes:
870
871 # Named argument "a"
872 push @array, 1, 2, :a<b>;
873
874 # Pair object (a=>'b')
875 push @array, 1, 2, (:a<b>);
876 push @array, 1, 2, 'a' => 'b';
877
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
jimmy authored
878 Perl 6 allows multiple same-named arguments, and records the relative
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
879 order of arguments with the same name. When there are more than one
880 argument, the C<@> sigil in the parameter list causes the arguments
881 to be concatenated:
882
8e6b864 skids Do not use positional params as named in code example
skids authored
883 sub fun (Int :@x) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
884 fun( x => 1, x => 2 ); # @x := (1, 2)
885 fun( x => (1, 2), x => (3, 4) ); # @x := (1, 2, 3, 4)
886
887 Other sigils bind only to the I<last> argument with that name:
888
8e6b864 skids Do not use positional params as named in code example
skids authored
889 sub fun (Int :$x) { ... }
f5aa846 [S06] fixed some spelling and consistency stuff
masak authored
890 fun( x => 1, x => 2 ); # $x := 2
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
891 fun( x => (1, 2), x => (3, 4) ); # $x := (3, 4)
892
893 This means a hash holding default values must come I<before> known named
894 parameters, similar to how hash constructors work:
895
896 # Allow "x" and "y" in %defaults to be overridden
897 f( |%defaults, x => 1, y => 2 );
898
899 =head2 Invocant parameters
900
901 A method invocant may be specified as the first parameter in the parameter
902 list, with a colon (rather than a comma) immediately after it:
903
904 method get_name ($self:) {...}
905 method set_name ($_: $newname) {...}
906
907 The corresponding argument (the invocant) is evaluated in item context
908 and is passed as the left operand of the method call operator:
909
910 print $obj.get_name();
911 $obj.set_name("Sam");
912
59032e7 Simplify meaning of Capture and Match in item context to preserve sanity
lwall authored
913 The invocant is actually stored as the first positional argument of a C<Capture>
914 object. It is special only to the dispatcher, otherwise it's just a normal
915 positional argument.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
916
59032e7 Simplify meaning of Capture and Match in item context to preserve sanity
lwall authored
917 Single-dispatch semantics may also be requested by using the indirect object syntax, with a colon
918 after the invocant argument. The colon is just a special form of the comma, and has the
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
919 same precedence:
920
ce337ef [S06] remove fossil spotted by jnthn++
lwall authored
921 set_name $obj: "Sam";
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
922 $obj.set_name("Sam"); # same as the above
923
924 An invocant is the topic of the corresponding method if that formal
4198be6 Moritz Lenz Undocument the "self" pragma
moritz authored
925 parameter is declared with the name C<$_>.
11fe4fc [S06] spec the \| parcel parameter syntax
lwall authored
926 If you have a call of the form:
59032e7 Simplify meaning of Capture and Match in item context to preserve sanity
lwall authored
927
928 foo(|$capture)
929
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
930 the compiler must defer the decision on whether to treat it as a method
931 or function dispatch based on whether the supplied C<Capture>'s first
59032e7 Simplify meaning of Capture and Match in item context to preserve sanity
lwall authored
932 argument is marked as an invocant. For ordinary calls this can
933 always be determined at compile time, however.
934
ab16f15 Moritz Lenz Document bare :D at al in parameter lists
moritz authored
935 =head2 Parameters with type constraints
936
937 Parameters can be constraint to other types than the default simply by
938 using the type name in from of the parameter:
939
940 sub double(Numeric $x) { 2 * $x }
941
942 If no explicit type constraint is given, it defaults to the type of the
943 surrounding package for method invocants, and to C<Any> everywhere else.
944
945 A bare C<:D>, C<:U>, C<:T> or C<:_> instead of a type constraint limits the
946 default type to definite, undefined, type objects or any object. The default
947 still applies, so in
948
949 class Con {
950 method man(:U: :D $x)
951 }
952
953 the signature is equivalent to C<(Con:U: Any:D $x)>.
954
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
955 =head2 Longname parameters
956
957 A routine marked with C<multi> can mark part of its parameters to
958 be considered in the multi dispatch. These are called I<longnames>;
959 see S12 for more about the semantics of multiple dispatch.
960
961 You can choose part of a C<multi>'s parameters to be its longname,
962 by putting a double semicolon after the last one:
963
964 multi sub handle_event ($window, $event;; $mode) {...}
965 multi method set_name ($self: $name;; $nick) {...}
966
967 A parameter list may have at most one double semicolon; parameters
968 after it are never considered for multiple dispatch (except of course
969 that they can still "veto" if their number or types mismatch).
970
971 [Conjecture: It might be possible for a routine to advertise multiple
972 long names, delimited by single semicolons. See S12 for details.]
973
974 If the parameter list for a C<multi> contains no semicolons to delimit
975 the list of important parameters, then all positional parameters are
976 considered important. If it's a C<multi method> or C<multi submethod>,
977 an additional implicit unnamed C<self> invocant is added to the
978 signature list unless the first parameter is explicitly marked with a colon.
979
980
981 =head2 Required parameters
982
983 Required parameters are specified at the start of a subroutine's parameter
984 list:
985
986 sub numcmp ($x, $y) { return $x <=> $y }
987
988 Required parameters may optionally be declared with a trailing C<!>,
989 though that's already the default for positional parameters:
990
991 sub numcmp ($x!, $y!) { return $x <=> $y }
992
25eb879 Carl Mäsak [S06] remove fossil
masak authored
993 Not passing all of the required arguments to a normal subroutine
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
994 is a fatal error. Passing a named argument that cannot be bound to a normal
995 subroutine is also a fatal error. (Methods are different.)
996
997 The number of required parameters a subroutine has can be determined by
998 calling its C<.arity> method:
999
1000 $args_required = &foo.arity;
1001
1002
1003 =head2 Optional parameters
1004
1005 Optional positional parameters are specified after all the required
1006 parameters and each is marked with a C<?> after the parameter:
1007
1008 sub my_substr ($str, $from?, $len?) {...}
1009
1010 Alternately, optional fields may be marked by supplying a default value.
1011 The C<=> sign introduces a default value:
1012
1013 sub my_substr ($str, $from = 0, $len = Inf) {...}
1014
1015 Default values can be calculated at run-time. They may even use the values of
1016 preceding parameters:
1017
1018 sub xml_tag ($tag, $endtag = matching_tag($tag) ) {...}
1019
1020 Arguments that correspond to optional parameters are evaluated in
1021 item context. They can be omitted, passed positionally, or passed by
1022 name:
1023
1024 my_substr("foobar"); # $from is 0, $len is infinite
1025 my_substr("foobar",1); # $from is 1, $len is infinite
1026 my_substr("foobar",1,3); # $from is 1, $len is 3
1027 my_substr("foobar",len=>3); # $from is 0, $len is 3
1028
1029 Missing optional arguments default to their default values, or to
1030 an undefined value if they have no default. (A supplied argument that is
1031 undefined is not considered to be missing, and hence does not trigger
1032 the default. Use C<//=> within the body for that.)
1033
1034 You may check whether an optional parameter was bound to anything
1035 by calling C<VAR($param).defined>.
1036
1037 =head2 Named parameters
1038
1039 Named-only parameters follow any required or optional parameters in the
1040 signature. They are marked by a prefix C<:>:
1041
1042 sub formalize($text, :$case, :$justify) {...}
1043
1044 This is actually shorthand for:
1045
1046 sub formalize($text, :case($case), :justify($justify)) {...}
1047
1048 If the longhand form is used, the label name and variable name can be
1049 different:
1050
1051 sub formalize($text, :case($required_case), :justify($justification)) {...}
1052
1053 so that you can use more descriptive internal parameter names without
1054 imposing inconveniently long external labels on named arguments.
1055 Multiple name wrappings may be given; this allows you to give both a
1056 short and a long external name:
1057
1058 sub globalize (:g(:global($gl))) {...}
1059
1060 Or equivalently:
1061
1062 sub globalize (:g(:$global)) {...}
1063
1064 Arguments that correspond to named parameters are evaluated in item
1065 context. They can only be passed by name, so it doesn't matter what
1066 order you pass them in:
1067
1068 $formal = formalize($title, case=>'upper');
1069 $formal = formalize($title, justify=>'left');
1070 $formal = formalize($title, :justify<right>, :case<title>);
1071
1072 See S02 for the correspondence between adverbial form and arrow notation.
1073
1074 While named and position arguments may be intermixed, it is suggested
1075 that you keep all the positionals in one place for clarity unless you
1076 have a good reason not to. This is likely bad style:
1077
1078 $formal = formalize(:justify<right>, $title, :case<title>, $date);
1079
1080 Named parameters are optional unless marked with a following C<!>.
1081 Default values for optional named parameters are defined in the same
1082 way as for positional parameters, but may depend only on existing
1083 values, including the values of parameters that have already been
48958ab Larry Wall Simplify Nil semantics; never means () now
TimToady authored
1084 bound. Named optional parameters default to C<Nil> (that is, they
1085 set the default of the container) if they have
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1086 no default. Named required parameters fail unless an argument pair
1087 of that name is supplied.
1088
94d0124 Larry Wall severely restrict named-to-positional binding
TimToady authored
1089 Bindings logically happen in declaration order, not call order, so
1090 any default may reliably depend on formal parameters to its left in
1091 the signature.
1092
1093 Another benefit of this policy is that, for routines that allow it,
1094 named arguments may be bound to positional parameters. (This is
1095 allowed only on routines that are I<explicitly> declared with either
1096 the C<proto> or the C<only> declarator.) If the first positional
1097 parameter is named C<$a>, for example, it will bind to a C<:a()>
1098 argument in preference to the first positional argument.
1099
1100 The restriction to explicit C<proto> and C<only> declarations is
1101 motivated by the desire for both API purity and efficiency. Normal
1102 C<multi> or C<sub> declarations and normal method declarations do not
1103 attempt to look for named bindings to positionals. At most there is
1104 one such binding for any dispatch, when it initially calls the C<proto>
1105 (or explicit C<only>). The C<proto> binder (for either sub or method)
1106 must automatically remap such named parameters to positionals before
1107 calling its internal multi dispatcher (the one represented by C<{*}>).
1108 In the case of a C<proto> sub, this mapping can be done at the point
1109 of the call, since there can only be one possible set of positional
1110 names, and the proto to be called can be known at compile time (in
45ca8c8 nick patch fix typos
patch authored
1111 the absence of CANDO declarations in the outer scopes). So after
94d0124 Larry Wall severely restrict named-to-positional binding
TimToady authored
1112
1113 proto foo ($x, $y, :$bar, :$baz) {*}
1114 multi foo ($a, $b, :$bar, :$baz) {...}
1115 multi foo ($n, $m, :$bar, :$baz) {...}
1116
1117 foo :y(2), :x(1); # can turn into foo(1,2)
1118
1119 the call to C<foo> can be turned into a pure positional call to
1120 the C<proto> (which can in turn be inlined because it's using the
1121 standard C<{*}> dispatcher--and likewise for methods, when the class
1122 containing the C<proto> is known to be finalizable). Note also that
1123 multi definitions are never required to use the same parameter names
1124 for positional parameters, since after the C<proto> binding is done,
1125 the names (if any) are never used again for positionals.
1126
1127 The C<$x> and C<$y> names above are part of the public API only
1128 because they are named in the C<proto>. Positional parameter names
1129 are never part of the advertised API unless explicitly enabled.
1130 An explicit C<proto> may easily refrain from advertising names by
45ca8c8 nick patch fix typos
patch authored
1131 declaring positionals with bare sigils:
94d0124 Larry Wall severely restrict named-to-positional binding
TimToady authored
1132
1133 proto foo ($, $, :$bar, :$baz) {*}
1134 multi foo ($x, $y, :$bar, :$baz) {...}
1135
1136 foo :x(1), :y(2); # illegal
1137
1138 (And an C<only> routine may control the positional API simply by
1139 using C<sub> instead, or by defining a C<proto> with a single C<multi>
1140 if finer control is desired.)
1141
1142 It follows from all this that an intuited proto never has to worry
1143 about supplying the API names of positional parameters. And no proto
45ca8c8 nick patch fix typos
patch authored
1144 ever has to worry about conflicting names in the positionals of the
94d0124 Larry Wall severely restrict named-to-positional binding
TimToady authored
1145 multis they dispatch to, since any remapping is handled before that.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1146
1147 =head2 List parameters
1148
1149 List parameters capture a variable length list of data. They're used
1150 in subroutines like C<print>, where the number of arguments needs to be
1151 flexible. They're also called "variadic parameters", because they take a
1152 I<variable> number of arguments. But generally we call them "slurpy"
1153 parameters because they slurp up arguments.
1154
1155 Slurpy parameters follow any required or optional parameters. They are
1156 marked by a C<*> before the parameter:
1157
1158 sub duplicate($n, *%flag, *@data) {...}
1159
1160 Named arguments are bound to the slurpy hash (C<*%flag>
1161 in the above example). Such arguments are evaluated in item context.
1162 Any remaining variadic arguments at the end of the argument list
1163 are bound to the slurpy array (C<*@data> above) and are evaluated
1164 in list context.
1165
1166 For example:
1167
1168 duplicate(3, reverse => 1, collate => 0, 2, 3, 5, 7, 11, 14);
1169 duplicate(3, :reverse, :!collate, 2, 3, 5, 7, 11, 14); # same
1170
1171 # The @data parameter receives [2, 3, 5, 7, 11, 14]
1172 # The %flag parameter receives { reverse => 1, collate => 0 }
1173
1174 Slurpy scalar parameters capture what would otherwise be the first
1175 elements of the variadic array:
1176
1177 sub head(*$head, *@tail) { return $head }
1178 sub neck(*$head, *$neck, *@tail) { return $neck }
1179 sub tail(*$head, *@tail) { return @tail }
1180
1181 head(1, 2, 3, 4, 5); # $head parameter receives 1
1182 # @tail parameter receives [2, 3, 4, 5]
1183
1184 neck(1, 2, 3, 4, 5); # $head parameter receives 1
1185 # $neck parameter receives 2
1186 # @tail parameter receives [3, 4, 5]
1187
1188 Slurpy scalars still impose list context on their arguments.
1189
cc595c7 [S06] supply missing list splitting primitive as a form of binding, masa...
lwall authored
1190 Single slurpy parameters are treated lazily -- the list is only flattened
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1191 into an array when individual elements are actually accessed:
1192
1193 @fromtwo = tail(1..Inf); # @fromtwo contains a lazy [2..Inf]
1194
cc595c7 [S06] supply missing list splitting primitive as a form of binding, masa...
lwall authored
1195 [Conjecture: However, if you use two or more slurpy arrays in a
1196 signature, the list is instead evaluated in hyper context, and will
1197 be asked to split itself into the number of lists corresponding to
1198 the number of slurpies so declared. A non-hyperable list will return
1199 failure for this splitting operation, so the signature should only bind
839c329 felher [S06] typo fix: insert missing 'is'
felher authored
1200 on parallelizable list operations. Likewise a list that is "too short to
cc595c7 [S06] supply missing list splitting primitive as a form of binding, masa...
lwall authored
1201 split" fails to bind, so a separate signature may match empty lists,
6faacb9 felher [S06] typo fix: remove lonely ')'
felher authored
1202 and perhaps singletons, if we define "too short" that way.]
cc595c7 [S06] supply missing list splitting primitive as a form of binding, masa...
lwall authored
1203
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1204 You can't bind to the name of a slurpy parameter: the name is just there
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
1205 so you can refer to it within the body.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1206
1207 sub foo(*%flag, *@data) {...}
1208
1209 foo(:flag{ a => 1 }, :data[ 1, 2, 3 ]);
1210 # %flag has elements (flag => (a => 1)) and (data => [1,2,3])
1211 # @data has nothing
1212
1213 =head2 Slurpy block
1214
1215 It's also possible to declare a slurpy block: C<*&block>. It slurps
1216 up any nameless block, specified by C<{...}>, at either the current positional
1217 location or the end of the syntactic list. Put it first if you want the
1218 option of putting a block either first or last in the arguments. Put it
1219 last if you want to force it to come in as the last argument.
1220
1221 =head2 Argument list binding
1222
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1223 The underlying C<Capture> object may be bound to a single
1224 name marked with a C<|>.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1225
1226 sub bar ($a,$b,$c,:$mice) { say $mice }
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1227 sub foo (|args) { say args.perl; &bar.callwith(|args); }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1228
1229 This prints:
1230
1231 foo 1,2,3,:mice<blind>; # says "\(1,2,3,:mice<blind>)" then "blind"
1232
1233 As demonstrated above, the capture may be interpolated into another
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1234 call's arguments. (The C<|> prefix is described below.)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1235 Use of C<callwith> allows the routine to be called without introducing
1236 an official C<CALLER> frame. For more see "Wrapping" below.
1237
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1238 The C<|> parameter takes a snapshot of the current binding state, but
1239 does not consume any arguments from it.
1240 It is allowed to have more parameters within the signature:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1241
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1242 sub compare (|args, Num $x, Num $y --> Bool) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1243
1244 For all normal declarative purposes (invocants and multiple dispatch
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1245 types, for instance), capture parameters are ignored.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1246
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1247 method addto (|args, $self: @x) { trace(args); $self += [+] @x }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1248
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1249 The extra signature is not required for non-C<multi>s since there can
1250 only be one candidate, but for multiple dispatch the extra signature
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1251 is required at least for its types, or the declaration would not know
1252 what signature to match against.
1253
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1254 multi foo (|args, Int, Bool?, *@, *%)) { reallyintfoo(args) }
1255 multi foo (|args, Str, Bool?, *@, *%)) { reallystrfoo(args) }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1256
11fe4fc [S06] spec the \| parcel parameter syntax
lwall authored
1257 =head2 Parcel binding
1258
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1259 When you bind an argument to a sigiled variable, it enforces the contract
1260 of that sigil, but sometimes you don't want that.
1261 It is possible to bind an argument to a simple name instead, which represents
1262 that argument in its rawest form, which is what we call a parcel. (It might
1263 actually be a C<Parcel> object, or any item that can function as a parcel.)
1264 In any case, it's a raw reference to whatever was passed, with no commitment
1265 to structure or mutability.
11fe4fc [S06] spec the \| parcel parameter syntax
lwall authored
1266
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1267 sub foo (\x, \y) { x = y; } # might or might not succeed
11fe4fc [S06] spec the \| parcel parameter syntax
lwall authored
1268
7b498ac Larry Wall de-sigil the |capture and \parcel params
TimToady authored
1269 A C<\> parameter effectively declares a new term in the language for
1270 the rest of the current scope, so when you use that term, it is not
1271 parsed as a list operator, so it will not look for any subsequent
1272 arguments.
1273
1274 sub foo (\x) { x 42; } # syntax error; two terms in a row
1275
1276 Parcel parameters make it relatively easy to program in a "sigilless" style,
1277 if you desire:
1278
1279 sub say-sins (\angles) {
1280 for angles -> \𝜃 { say sin 𝜃 }
1281 }
1282
1283 or
1284
1285 my \𝑖 = some-integer; say 𝑖 + 2;
1286
1287 Note how C<𝑖> would be misinterpreted if it treated C<+ 2> as an argument, but
1288 since it's a simple term, it doesn't.
1289
1290 The term does act like a function call in one way, however. Since it returns a
1291 parcel, the value will flatten in a list context, but itemize in an item context.
1292 You can use C<< prefix:<|> >> to force flattening into an outer argument list, if
1293 needed.
11fe4fc [S06] spec the \| parcel parameter syntax
lwall authored
1294
da0c71f Larry Wall include ability to have non-identifier aliases
TimToady authored
1295 It is possible to alias to a non-identifier by using the C<term> syntactic category:
1296
1297 my \term:<∞> = Inf;
1298
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1299 =head2 Flattening argument lists
1300
1301 The unary C<|> operator casts its argument to a C<Capture>
1302 object, then splices that capture into the argument list
1303 it occurs in. To get the same effect on multiple arguments you
1304 can use the C<< |« >> hyperoperator.
1305
1306 C<Pair> and C<Hash> become named arguments:
1307
1308 |(x=>1); # Pair, becomes \(x=>1)
1309 |{x=>1, y=>2}; # Hash, becomes \(x=>1, y=>2)
1310
736a666 [Spec] random whackage on List, Seq, Parcel, Capture, Iterator, Nil etc.
lwall authored
1311 Anything else that is C<Iterable> is simply turned into
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1312 positional arguments:
1313
82431de lizmat Eradicate Seq
lizmat authored
1314 |(1,2,3); # Parcel, becomes \(1,2,3)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1315 |(1..3); # Range, becomes \(1,2,3)
736a666 [Spec] random whackage on List, Seq, Parcel, Capture, Iterator, Nil etc.
lwall authored
1316 |(1..2, 3); # Parcel, becomes \(1,2,3)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1317 |([x=>1, x=>2]); # List (from an Array), becomes \((x=>1), (x=>2))
1318
1319 For example:
1320
1321 sub foo($x, $y, $z) {...} # expects three scalars
1322 @onetothree = 1..3; # array stores three scalars
1323
1324 foo(1,2,3); # okay: three args found
1325 foo(@onetothree); # error: only one arg
1326 foo(|@onetothree); # okay: @onetothree flattened to three args
1327
1328 The C<|> operator flattens lazily -- the array is flattened only if
1329 flattening is actually required within the subroutine. To flatten before
0bf13db [S02,S06] continue de-confusing flat and eager
lwall authored
1330 the list is even passed into the subroutine, use the C<flat> list
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1331 operator:
1332
0bf13db [S02,S06] continue de-confusing flat and eager
lwall authored
1333 foo(|flat 1,2,3 Z 4,5,6); # zip list flattened before interpolation
1334 foo |(1,2,3 Z 4,5,6).flat # same thing
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1335
1336
1337 =head2 Multidimensional argument list binding
1338
1339 Some functions take more than one list of positional and/or named arguments,
1340 that they wish not to be flattened into one list. For instance, C<zip()> wants
1341 to iterate several lists in parallel, while array and hash subscripts want to
1342 process a multidimensional slice. The set of underlying argument lists may be
9eb1b35 [S06] more @@ clobberation.
lwall authored
1343 bound to a single array parameter declared with a double C<**> marker:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1344
9eb1b35 [S06] more @@ clobberation.
lwall authored
1345 sub foo (**@slice) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1346
1347 Note that this is different from
1348
eb862b2 japhb Banish |$ and \$ in more places
japhb authored
1349 sub foo (|slice) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1350
eb862b2 japhb Banish |$ and \$ in more places
japhb authored
1351 insofar as C<|slice> is bound to a single argument-list object that
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1352 makes no commitment to processing its structure (and maybe doesn't
9eb1b35 [S06] more @@ clobberation.
lwall authored
1353 even know its own structure yet), while C<**@slice> has to create
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1354 an array that binds the incoming dimensional lists to the array's
1355 dimensions, and make that commitment visible to the rest of the scope
1356 via the sigil so that constructs expecting multidimensional lists
1357 know that multidimensionality is the intention.
1358
1359 It is allowed to specify a return type:
1360
9eb1b35 [S06] more @@ clobberation.
lwall authored
1361 sub foo (**@slice --> Num) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1362
1363 The invocant does not participate in multi-dimensional argument lists,
9eb1b35 [S06] more @@ clobberation.
lwall authored
1364 so C<self> is not present in the C<**@slice> below:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1365
9eb1b35 [S06] more @@ clobberation.
lwall authored
1366 method foo (**@slice) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1367
9eb1b35 [S06] more @@ clobberation.
lwall authored
1368 The C<**> marker is just a variant of the C<*> marker that ends up
07265d7 [Spec] s/getobj/getarg/ to be slightly more accurate
lwall authored
1369 requesting parcels when binding (underlyingly calling C<.getarg>) rather
45ca8c8 nick patch fix typos
patch authored
1370 than requesting individual elements as the flattening C<*> does (underlyingly
07265d7 [Spec] s/getobj/getarg/ to be slightly more accurate
lwall authored
1371 calling C<.get>).
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1372
1373 =head2 Zero-dimensional argument list
1374
1375 If you call a function without parens and supply no arguments, the
1376 argument list becomes a zero-dimensional slice. It differs from
1377 C<\()> in several ways:
1378
9eb1b35 [S06] more @@ clobberation.
lwall authored
1379 sub foo (**@slice) {...}
1380 foo; # +@slice == 0
1381 foo(); # +@slice == 1
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1382
eb862b2 japhb Banish |$ and \$ in more places
japhb authored
1383 sub bar (|args = \(1,2,3)) {...}
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1384 bar; # $args === \(1,2,3)
1385 bar(); # $args === \()
1386
1387 =head2 Feed operators
1388
1389 The variadic list of a subroutine call can be passed in separately from
1390 the normal argument list, by using either of the I<feed> operators:
1391 C<< <== >> or C<< ==> >>. Syntactically, feed operators expect to find a
1392 statement on either end. Any statement can occur on the source end;
1393 however not all statements are suitable for use on the sink end of a feed.
1394
1395 Each operator expects to find a call to a variadic receiver on its
1396 "sharp" end, and a list of values on its "blunt" end:
1397
1398 grep { $_ % 2 } <== @data;
1399
1400 @data ==> grep { $_ % 2 };
1401
1402 It binds the (potentially lazy) list from the blunt end to the slurpy
1403 parameter(s) of the receiver on the sharp end. In the case of a receiver
1404 that is a variadic function, the feed is received as part of its slurpy list.
1405 So both of the calls above are equivalent to:
1406
1407 grep { $_ % 2 }, @data;
1408
1409 Note that all such feeds (and indeed all lazy argument lists) supply
1410 an implicit promise that the code producing the lists may execute
1411 in parallel with the code receiving the lists. (Feeds, hyperops,
1412 and junctions all have this promise of parallelizability in common,
1413 but differ in interface. Code which violates these promises is
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
1414 erroneous, and will produce undefined results when parallelized.)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1415
1416 However, feeds go a bit further than ordinary lazy lists in enforcing
1417 the parallel discipline: they explicitly treat the blunt end as a
1418 cloned closure that starts a subthread (presumably cooperative). The only variables shared
1419 by the inner scope with the outer scope are those lexical variables
1420 declared in the outer scope that are visible at the time the closure is
1421 cloned and the subthread spawned. Use of such shared variables will
1422 automatically be subject to transactional protection (and associated
1423 overhead). Package variables are not cloned unless predeclared
1424 as lexical names with C<our>. Variables declared within the blunt
1425 end are not visible outside, and in fact it is illegal to declare a
1426 lexical on the blunt end that is not enclosed in curlies somehow.
1427
1428 Because feeds are defined as lazy pipes, a chain of feeds may not begin
1429 and end with the same array without some kind of eager sequence point.
1430 That is, this isn't guaranteed to work:
1431
1432 @data <== grep { $_ % 2 } <== @data;
1433
1434 either of these do:
1435
1436 @data <== grep { $_ % 2 } <== eager @data;
1437 @data <== eager grep { $_ % 2 } <== @data;
1438
1439 Conjecture: if the cloning process eagerly duplicates C<@data>, it could
1440 be forced to work. Not clear if this is desirable, since ordinary clones
1441 just clone the container, not the value.
1442
1443 Leftward feeds are a convenient way of explicitly indicating the typical
1444 right-to-left flow of data through a chain of operations:
1445
1446 @oddsquares = map { $_**2 }, sort grep { $_ % 2 }, @nums;
1447
1448 # perhaps more clearly written as...
1449
1450 @oddsquares = do {
1451 map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums;
1452 }
1453
1454 Rightward feeds are a convenient way of reversing the normal data flow in a
1455 chain of operations, to make it read left-to-right:
1456
1457 @oddsquares = do {
1458 @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 };
1459 }
1460
1461 Note that something like the C<do> is necessary because feeds operate
1462 at the statement level. Parens would also work, since a statement is
1463 expected inside:
1464
1465 @oddsquares = (
1466 @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 };
1467 );
1468
1469 But as described below, you can also just write:
1470
1471 @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 } ==> @oddsquares;
1472
1473 If the operand on the sharp end of a feed is not a call to a variadic
1474 operation, it must be something else that can be interpreted as a list
1475 receiver, or a scalar expression that can be evaluated to produce an
1476 object that does the C<KitchenSink> role, such as an C<IO> object.
1477 Such an object provides C<.clear> and C<.push> methods that will
1478 be called as appropriate to send data. (Note that an C<IO> object
1479 used as a sink will force eager evaluation on its pipeline, so the
1480 next statement is guaranteed not to run till the file is closed.
1481 In contrast, an C<Array> object used as a sink turns into a lazy
1482 array.)
1483
1484 Any non-variadic object (such as an C<Array> or C<IO> object) used as a filter
1485 between two feeds is treated specially as a I<tap> that merely captures
1486 data I<en passant>. You can safely install such a tap in an extended pipeline
1487 without changing the semantics. An C<IO> object used as a tap does not
1488 force eager evaluation since the eagerness is controlled instead by the
1489 downstream feed.
1490
1491 Any prefix list operator is considered a variadic operation, so ordinarily
1492 a list operator adds any feed input to the end of its list.
1493 But sometimes you want to interpolate elsewhere, so any contextualizer
1494 with C<*> as an argument may be used to indicate the target of a
1495 feed without the use of a temporary array:
1496
1497 foo() ==> say @(*), " is what I meant";
9eb1b35 [S06] more @@ clobberation.
lwall authored
1498 bar() ==> @(*).baz();
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1499
1500 Likewise, an C<Array> used as a tap may be distinguished from an C<Array> used
1501 as a translation function:
1502
1503 numbers() ==> @array ==> bar() # tap
1504 numbers() ==> @array[@(*)] ==> bar() # translation
1505
1506 To append multiple sources to the next sink, double the angle:
1507
9eb1b35 [S06] more @@ clobberation.
lwall authored
1508 my $sink;
1509 0..* ==> $sink;
1510 'a'..* ==>> $sink;
1511 pidigits() ==>> $sink;
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1512
1513 # outputs "(0, 'a', 3)\n"...
9eb1b35 [S06] more @@ clobberation.
lwall authored
1514 for $sink.zip { .perl.say }
1515
1516 Each such append adds another slice element (that is, a parcel), to
1517 the sink. (The original feed also created a parcel.)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1518
1519 You may use a variable (or variable declaration) as a receiver, in
1520 which case the list value is bound as the "todo" of the variable.
1521 (The append form binds addition todos to the receiver's todo list.)
1522 Do not think of it as an assignment, nor as an ordinary binding.
1523 Think of it as iterator creation. In the case of a scalar variable,
1524 that variable contains the newly created iterator itself. In the case
1525 of an array, the new iterator is installed as the method for extending
1526 the array. As with assignment, the old todo list is clobbered; use the
9eb1b35 [S06] more @@ clobberation.
lwall authored
1527 append form to avoid that and get push semantics. In any case, feeding
1528 an array always flattens. You must use the scalar form to preserve
1529 slice information.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1530
1531 In general you can simply think of a receiver array as representing
1532 the results of the chain, so you can equivalently write any of:
1533
1534 my @oddsquares <== map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums;
1535
1536 my @oddsquares
1537 <== map { $_**2 }
1538 <== sort
1539 <== grep { $_ % 2 }
1540 <== @nums;
1541
1542 @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 } ==> my @oddsquares;
1543
1544 @nums
1545 ==> grep { $_ % 2 }
1546 ==> sort
1547 ==> map { $_**2 }
1548 ==> my @oddsquares;
1549
1550 Since the feed iterator is bound into the final variable, the variable
1551 can be just as lazy as the feed that is producing the values.
1552
1553 When feeds are bound to arrays with "push" semantics, you can have
1554 a receiver for multiple feeds:
1555
1556 my @foo;
1557 0..2 ==> @foo;
1558 'a'..'c' ==>> @foo;
1559 say @foo; # 0,1,2,'a','b','c'
1560
1561 Note how the feeds are concatenated in C<@foo> so that C<@foo>
1562 is a list of 6 elements. This is the default behavior. However,
1563 sometimes you want to capture the outputs as a list of two iterators,
1564 namely the two iterators that represent the two input feeds. You can
9eb1b35 [S06] more @@ clobberation.
lwall authored
1565 get at those two iterators by using a scalar instead, which
1566 will preserve the slice structure, which can be fed to any operation
1567 that knows how to deal with a list of parcels as a slice, such as C<zip>:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1568
9eb1b35 [S06] more @@ clobberation.
lwall authored
1569 0..* ==> $foo;
1570 'a'..* ==>> $foo;
1571 pidigits() ==>> $foo;
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1572
9eb1b35 [S06] more @@ clobberation.
lwall authored
1573 for $foo.zip { .say }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1574
1575 [0,'a',3]
1576 [1,'b',1]
1577 [2,'c',4]
1578 [3,'d',1]
1579 [4,'e',5]
1580 [5,'f',9]
1581 ...
1582
9eb1b35 [S06] more @@ clobberation.
lwall authored
1583 Here C<$foo> is a list of three parcels, so
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1584
9eb1b35 [S06] more @@ clobberation.
lwall authored
1585 $foo.zip
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1586
1587 is equivalent to
1588
9eb1b35 [S06] more @@ clobberation.
lwall authored
1589 my (@a,@b,@c) := |$foo;
1590 zip(@a; @b; @c)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1591
1592 A named receiver array is useful when you wish to feed into an
1593 expression that is not an ordinary list operator, and you wish to be
1594 clear where the feed's destination is supposed to be:
1595
1596 picklist() ==> my @baz;
1597 my @foo = @bar[@baz];
1598
1599 Various contexts may or may not be expecting multi-dimensional slices
9eb1b35 [S06] more @@ clobberation.
lwall authored
1600 or feeds. By default, ordinary arrays are flattened in slurpy context, that is, they
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1601 have "list" semantics. If you say
1602
63a0d61 Larry Wall Remove notion of stacked feeds
TimToady authored
1603 zip(0..2; 'a'..'c') ==> my @tmp;
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1604 for @tmp { .say }
1605
45ca8c8 nick patch fix typos
patch authored
1606 then you get 0,1,2,'a','b','c'. If you have a multidimensional array, you
9eb1b35 [S06] more @@ clobberation.
lwall authored
1607 can ask for flattening semantics explicitly with C<flat>:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1608
63a0d61 Larry Wall Remove notion of stacked feeds
TimToady authored
1609 zip(0..2; 'a'..'c') ==> my $tmp;
9eb1b35 [S06] more @@ clobberation.
lwall authored
1610 for $tmp.flat { .say }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1611
1612 As we saw earlier, "zip" produces an interleaved result by taking one element
1613 from each list in turn, so
1614
63a0d61 Larry Wall Remove notion of stacked feeds
TimToady authored
1615 zip(0..2; 'a'..'c') ==> my $tmp;
9eb1b35 [S06] more @@ clobberation.
lwall authored
1616 for $tmp.zip { .say }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1617
1618 produces 0,'a',1,'b',2,'c'.
1619
9eb1b35 [S06] more @@ clobberation.
lwall authored
1620 If you want the zip's result as a list of subarrays, then you need to put
b962f00 Larry Wall refine tree contexts; slice context -> lol context
TimToady authored
1621 the zip itself into a "chunky" C<LoL> context instead:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1622
63a0d61 Larry Wall Remove notion of stacked feeds
TimToady authored
1623 zip(0..2; 'a'..'c') ==> my $tmp;
b962f00 Larry Wall refine tree contexts; slice context -> lol context
TimToady authored
1624 for $tmp.zip.lol { .say }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1625
b962f00 Larry Wall refine tree contexts; slice context -> lol context
TimToady authored
1626 This produces two values on each line. But usually you want the flat
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1627 form so you can just bind it directly to a signature:
1628
9eb1b35 [S06] more @@ clobberation.
lwall authored
1629 for $tmp.zip -> $i, $a { say "$i: $a" }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1630
1631 Otherwise you'd have to say this:
1632
b962f00 Larry Wall refine tree contexts; slice context -> lol context
TimToady authored
1633 for $tmp.zip.lol -> [$i, $a] { say "$i: $a" }
9eb1b35 [S06] more @@ clobberation.
lwall authored
1634
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1635 Note that with the current definition, the order of feeds is preserved
1636 left to right in general regardless of the position of the receiver.
1637
1638 So
1639
9eb1b35 [S06] more @@ clobberation.
lwall authored
1640 ('a'..*; 0..*) ==> $feed;
1641 for $feed.zip <== @foo) -> $a, $i, $x { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1642
1643 is the same as
1644
9eb1b35 [S06] more @@ clobberation.
lwall authored
1645 'a'..* ==> $feed;
1646 0..* ==>> $feed;
1647 for $feed.zip <== @foo) -> $a, $i, $x { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1648
1649 which is the same as
1650
1651 for zip('a'..*; 0..*; @foo) -> $a, $i, $x { ... }
1652
1653 Also note that these come out to be identical for ordinary arrays:
1654
1655 @foo.zip
1656 @foo.cat
1657
1658 =head2 Closure parameters
1659
1660 Parameters declared with the C<&> sigil take blocks, closures, or
1661 subroutines as their arguments. Closure parameters can be required,
1662 optional, named, or slurpy.
1663
1664 sub limited_grep (Int $count, &block, *@list) {...}
1665
1666 # and later...
1667
1668 @first_three = limited_grep 3, {$_<10}, @data;
1669
1670 (The comma is required after the closure.)
1671
1672 Within the subroutine, the closure parameter can be used like any other
1673 lexically scoped subroutine:
1674
1675 sub limited_grep (Int $count, &block, *@list) {
1676 ...
1677 if block($nextelem) {...}
1678 ...
1679 }
1680
1681 The closure parameter can have its own signature in a type specification written
1682 with C<:(...)>:
1683
1684 sub limited_Dog_grep ($count, &block:(Dog), Dog *@list) {...}
1685
1686 and even a return type:
1687
1688 sub limited_Dog_grep ($count, &block:(Dog --> Bool), Dog *@list) {...}
1689
1690 When an argument is passed to a closure parameter that has this kind of
1691 signature, the argument must be a C<Code> object with a compatible
1692 parameter list and return type.
1693
55a537b [S06]
lwall authored
1694 =head2 En passant type capture
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1695
1696 Unlike normal parameters, type parameters often come in piggybacked
1697 on the actual value as "kind", and you'd like a way to capture both
55a537b [S06]
lwall authored
1698 the value and its kind at once. (A "kind" is a storage type, that is, a class or type that
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1699 an object is allowed to be. An object is not officially allowed
1700 to take on a constrained or contravariant type.) A type variable
1701 can be used anywhere a type name can, but instead of asserting that
1702 the value must conform to a particular type, it captures the
1703 actual "kind" of the object and also declares a package/type name
1704 by which you can refer to that kind later in the signature or body.
55a537b [S06]
lwall authored
1705 In addition, it captures the nominal typing of any associated nominal
1706 type.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1707 For instance, if you wanted to match any two Dogs as long as they
1708 were of the same kind, you can say:
1709
1710 sub matchedset (Dog ::T $fido, T $spot) {...}
1711
55a537b [S06]
lwall authored
1712 This actually turns into something more like
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1713
55a537b [S06]
lwall authored
1714 sub matchedset (Dog ::T $fido, Dog $spot where T) {...}
1715
1716 Note that C<::T> is not required to contain C<Dog>, only
1717 a type that is compatible with C<Dog>. Note also that the nominal
1718 type, C<Dog>, is also included in the meaning of C<T>, along
1719 with the notion that the actual type must match the storage
1720 type of C<$fido>.
1721
1722 The C<::> quasi-sigil is short for "subset" in much the same way that C<&> is
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1723 short for "sub". Just as C<&> can be used to name any kind of code,
1724 so too C<::> can be used to name any kind of type. Both of them insert
1725 a bare identifier into the symbol table, though they fill different syntactic
1726 spots.
1727
1728 Note that it is not required to capture the object associated with the
1729 class unless you want it. The sub above could be written as
1730
1731 sub matchedset (Dog ::T, T) {...}
1732
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
1733 if we're not interested in C<$fido> or C<$spot>. Or just
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1734
1735 sub matchedset (::T, T) {...}
1736
55a537b [S06]
lwall authored
1737 if we don't care about anything but the matching. Note here that
1738 the second parameter may be more derived than the first. If you
1739 need them to be identical, you must say something like
1740
1741 sub matchedset (::T, $ where { $_.WHAT === T }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1742
1743 =head2 Unpacking array parameters
1744
1745 Instead of specifying an array parameter as an array:
1746
1747 sub quicksort (@data, $reverse?, $inplace?) {
1748 my $pivot := shift @data;
1749 ...
1750 }
1751
1752 it may be broken up into components in the signature, by
1753 specifying the parameter as if it were an anonymous array of
1754 parameters:
1755
1756 sub quicksort ([$pivot, *@data], $reverse?, $inplace?) {
1757 ...
1758 }
1759
1760 This subroutine still expects an array as its first argument, just like
1761 the first version.
1762
1763 =head2 Unpacking a single list argument
1764
1765 To match the first element of the slurpy list, use a "slurpy" scalar:
1766
1767 sub quicksort (:$reverse, :$inplace, *$pivot, *@data)
1768
1769 =head2 Unpacking tree node parameters
1770
1771 You can unpack hash values and tree nodes in various dwimmy ways by enclosing the bindings
1772 of child nodes and attributes in parentheses following the declaration of
1773 the node itself:
1774
1775 sub traverse ( BinTree $top ( $left, $right ) ) {
1776 traverse($left);
1777 traverse($right);
1778 }
1779
1780 In this, C<$left> and C<$right> are automatically bound to the left
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
1781 and right nodes of the tree. If C<$top> is an ordinary object, it binds
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1782 the C<$top.left> and C<$top.right> attributes. If it's a hash,
1783 it binds C<< $top<left> >> and C<< $top<right> >>. If C<BinTree> is a
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
1784 signature type and $top is a C<Capture> (argument list) object, the child types
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1785 of the signature are applied to the actual arguments in the argument
1786 list object. (Signature types have the benefit that you can view
1787 them inside-out as constructors with positional arguments, such that
1788 the transformations can be reversible.)
1789
1790 However, the full power of signatures can be applied to pattern match
1791 just about any argument or set of arguments, even though in some cases
1792 the reverse transformation is not derivable. For instance, to bind to
1793 an array of children named C<.kids> or C<< .<kids> >>, use something
1794 like:
1795
831d805 [spec] random cleanup of fossils from before proto became a multi wrappe...
lwall authored
1796 proto traverse ($) {*}
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1797 multi traverse ( NAry $top ( :kids [$eldest, *@siblings] ) ) {
1798 traverse($eldest);
1799 traverse(:kids(@siblings)); # (binds @siblings to $top)
1800 }
1801 multi traverse ( $leaf ) {...}
1802
1803 The second candidate is called only if the parameter cannot be bound to
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callable ...
jdlugosz authored
1804 both C<$top> and to the "kids" parsing subparameter.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1805
1806 Likewise, to bind to a hash element of the node and then bind to
1807 keys in that hash by name:
1808
1809 sub traverse ( AttrNode $top ( :%attr{ :$vocalic, :$tense } ) ) {
1810 say "Has {+%attr} attributes, of which";
1811 say "vocalic = $vocalic";
1812 say "tense = $tense";
1813 }
1814
1815 You may omit the top variable if you prefix the parentheses with a colon
1816 to indicate a signature. Otherwise you must at least put the sigil of
1817 the variable, or we can't correctly differentiate:
1818
1819 my Dog ($fido, $spot) := twodogs(); # list of two dogs
1820 my Dog $ ($fido, $spot) := twodogs(); # one twodog object
1821 my Dog :($fido, $spot) := twodogs(); # one twodog object
1822
1823 Sub signatures can be matched directly within regexes by using C<:(...)>
1824 notation.
1825
1826 push @a, "foo";
1827 push @a, \(1,2,3);
1828 push @a, "bar";
1829 ...
1830 my ($i, $j, $k);
1831 @a ~~ rx/
1832 <,> # match initial elem boundary
1833 :(Int $i,Int $j,Int? $k) # match lists with 2 or 3 ints
1834 <,> # match final elem boundary
1835 /;
1836 say "i = $<i>";
1837 say "j = $<j>";
1838 say "k = $<k>" if defined $<k>;
1839
1840 If you want a parameter bound into C<$/>, you have to say C<< $<i> >>
1841 within the signature. Otherwise it will try to bind an external C<$i>
1842 instead, and fail if no such variable is declared.
1843
1844 Note that unlike a sub declaration, a regex-embedded signature has no
1845 associated "returns" syntactic slot, so you have to use C<< --> >>
1846 within the signature to specify the C<of> type of the signature, or match as
1847 an arglist:
1848
1849 :(Num, Num --> Coord)
1850 :(\Coord(Num, Num))
1851
1852 A consequence of the latter form is that you can match the type of
1853 an object with C<:(\Dog)> without actually breaking it into its components.
1854 Note, however, that it's not equivalent to say
1855
1856 :(--> Dog)
1857
1858 which would be equivalent to
1859
1860 :(\Dog())
1861
1862 that is, match a nullary function of type C<Dog>. Nor is it equivalent to
1863
1864 :(Dog)
1865
1866 which would be equivalent to
1867
1868 :(\Any(Dog))
1869
1870 and match a function taking a single parameter of type Dog.
1871
1872 Note also that bare C<\(1,2,3)> is never legal in a regex since the
1873 first (escaped) paren would try to match literally.
1874
1875 =head2 Attributive parameters
1876
1877 If a submethod's parameter is declared with a C<.> or C<!> after the
1878 sigil (like an attribute):
1879
1880 submethod initialize($.name, $!age) {}
1881
74206e4 [S06,S12] make attributive parameters default to 'is copy' binding
lwall authored
1882 then the argument is bound directly to the object's attribute of the
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1883 same name. This avoids the frequent need to write code like:
1884
1885 submethod initialize($name, $age) {
1886 $.name = $name;
1887 $!age = $age;
1888 }
1889
74206e4 [S06,S12] make attributive parameters default to 'is copy' binding
lwall authored
1890 The initialization of attributes requires special care to preserve
1891 encapsulation; therefore the default for attributive parameters is
1892 value semantics, that is, as if specified with C<is copy>. Hence,
1893 the submethod above is really more like:
1894
1895 submethod initialize($name is copy, $age is copy) {
1896 $.name := $name; # or maybe = here, since it's a parent's attr
1897 $!age := $age; # or maybe only $! parameters work really
1898 }
1899
1900 If you wish to allow the user to initialize an attribute by reference,
1901 you may either write your own initializer submethod explicitly, or
554918c Kris Shannon Missed a "is ref" to "is parcel" in a02e2e1d
KrisShannon authored
1902 simply mark the attributes you want to work that way with C<is parcel>:
74206e4 [S06,S12] make attributive parameters default to 'is copy' binding
lwall authored
1903
a02e2e1 lizmat