Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 3645 lines (2698 sloc) 146.7 kb
be1862e P6 Synopsis : ws changes - to help BOMers, added leading blank line t…
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 Undocument the "self" pragma
moritz authored
12 Last Modified: 27 Feb 2015
ab16f15 @moritz 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 @TimToady $! 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 @TimToady 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 @TimToady $! and $/ are created only by routines/compunits
TimToady authored
28 declared with C<< -> >> or with bare curlies, are born only with C<$_>,
08b8886 @TimToady 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 @TimToady require parallelizers to declare $/ and $! dynvars
TimToady authored
38 any and all lazy constructs, whether block-based or thunk-based,
6b3e9d8 @TimToady more s/async/start/ tweaks
TimToady authored
39 such as gather or start or C<< ==> >> should declare their own C<$/>
08b8886 @TimToady 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 @TimToady $! 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 @TimToady 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 wra…
lwall authored
83 to compose conflicting methods from roles.) Abstractly, the C<proto>
60aef3a @TimToady 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 @patch fix typos
patch authored
85 is instantiated into an actual dispatcher for each scope that
60aef3a @TimToady 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 @TimToady 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 @TimToady 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 @TimToady 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 @TimToady 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 sema…
lwall authored
116 When you call any routine (or method, or rule) that may have multiple
60aef3a @TimToady 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 sema…
lwall authored
130 for all subsequent calls to its managed multis.
131
60aef3a @TimToady 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 sema…
lwall authored
139
60aef3a @TimToady 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 mu…
lwall authored
144
145 proto method bar {*}
146
147 (We don't use C<...> for that because it would fail at run time,
60aef3a @TimToady 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 mu…
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 mu…
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 mu…
lwall authored
155
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
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 mu…
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 sema…
lwall authored
159
60aef3a @TimToady 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 sema…
lwall authored
165
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
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 sema…
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 wra…
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 sema…
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 wra…
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 sema…
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 wra…
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 sema…
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 wra…
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 sema…
lwall authored
182
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
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 sema…
lwall authored
185
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
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 sema…
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 mu…
lwall authored
193 }
194
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
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 mu…
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 sema…
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 @cspencer 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 mu…
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 mu…
lwall authored
226
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
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 wra…
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 wra…
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 @TimToady 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 @masak [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…
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 ti…
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 ti…
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 …
lwall authored
300 my $grammar_factory:(Str, int, int --> Grammar);
22f4608 @paultcochrane Purge trailing whitespace in S06 -- S17
paultcochrane authored
301 $grammar_factory = sub (Str $name, int $n, int $x --> Grammar) { ... };
93bd42f [S06] specify syntax for strongly-typed closure variables
diakopter authored
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 …
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…
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…
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…
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…
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 Callab…
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…
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 Callab…
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 Callab…
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 Callab…
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…
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…
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
7e8ba5b @TimToady document new unit declarator
TimToady authored
443 declare a C<MAIN> sub--see L</Declaring a MAIN subroutine> below. (And this
444 form requires the C<unit> declarator in front.)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
445
446 Redefining a stub subroutine does not produce an error, but redefining
447 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 supersed…
lwall authored
448 you must explicitly use the "C<supersede>" declarator. (The compiler may
4a4297b typo
lwall authored
449 refuse to do this if it has already committed to the previous definition.)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
450
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
451 The C<...> is the "yadayadayada" operator, which is executable but
003891a @TimToady Explication of lazy warnings
TimToady authored
452 returns a failure. You can also use C<???> to fail with a warning
fb6b129 @stmuk the the -> the
stmuk authored
453 (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
454 or C<!!!> to always die. These also officially define stub blocks.
455 Any of these yada operators will be taken as a stub if used as the main
456 operator of the first statement in the block. (Statement modifiers
457 are allowed on that statement.) The yada operators differ from their
458 respective named functions in that they all default to a message
459 such as: "Unimplemented stub of sub foo was executed".
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
460
461 It has been argued that C<...> as literal syntax is confusing when
462 you might also want to use it for metasyntax within a document.
463 Generally this is not an issue in context; it's never an issue in the
464 program itself, and the few places where it could be an issue in the
465 documentation, a comment will serve to clarify the intent, as above.
466 The rest of the time, it doesn't really matter whether the reader
467 takes C<...> as literal or not, since the purpose of C<...> is to
468 indicate that something is missing whichever way you take it.
469
470
471 =head2 Globally scoped subroutines
472
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
473 Subroutines and variables can be declared in the global namespace
474 (or any package in the global namespace), and are thereafter visible
475 everywhere in the program via the GLOBAL package (or one of its
476 subpackages). They may be made directly visible by importation,
477 but may not otherwise be called with a bare identifier, since subroutine
478 dispatch only looks in lexical scopes.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
479
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callab…
jdlugosz authored
480 Global subroutines and variables are normally referred to by prefixing
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
481 their identifiers with the C<*> twigil, to allow dynamically scoped overrides.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
482
f549796 [S06] remove the slightly non-sensical 'use GLOBAL' in favor of 'defi…
lwall authored
483 GLOBAL::<$next_id> = 0;
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
484 sub GLOBAL::saith($text) { say "Yea verily, $text" }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
485
486 module A {
afbd198 [Spec] get rid of some fossil uses of * spotted by masak++
lwall authored
487 my $next_id = 2; # hides any global or package $next_id
488 &*saith($next_id); # print the lexical $next_id;
f549796 [S06] remove the slightly non-sensical 'use GLOBAL' in favor of 'defi…
lwall authored
489 &*saith($*next_id); # print the dynamic $next_id;
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
490 }
491
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
492 To disallow dynamic overrides, you must access the globals directly:
f549796 [S06] remove the slightly non-sensical 'use GLOBAL' in favor of 'defi…
lwall authored
493
494 GLOBAL::saith($GLOBAL::next_id);
495
496 The fact that this is verbose is construed to be a feature. Alternately,
497 you may play aliasing tricks like this:
498
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
499 module B {
b1fb049 [S06,S11] kill infix:<defines>, replace with statement_control:<import>
lwall authored
500 import GLOBAL <&saith $next_id>;
f549796 [S06] remove the slightly non-sensical 'use GLOBAL' in favor of 'defi…
lwall authored
501 saith($next_id); # Unambiguously the global definitions
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
502 }
503
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
504 Despite the fact that subroutine dispatch only looks in lexical scopes, you
505 can always call a package subroutine directly if there's a lexical alias
506 to it, as the C<our> declarator does:
507
7e8ba5b @TimToady document new unit declarator
TimToady authored
508 unit module C;
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
509 our sub saith($text) { say "Yea verily, $text" }
510 saith("I do!") # okay
511 C::saith("I do!") # also okay
512
afbd198 [Spec] get rid of some fossil uses of * spotted by masak++
lwall authored
513 =head2 Dynamically scoped subroutines
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
514
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
515 Similarly, you may define dynamically scoped subroutines:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
516
082a5ca [S06] ss/is context/is dynamic/ fossil
lwall authored
517 my sub myfunc ($x) is dynamic { ... }
934a2fc [S06,S12] clarify when yada is taken to be a stub
lwall authored
518 my sub &*myfunc ($x) { ... } # same thing
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
519
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
520 This may then be invoked via the syntax for dynamic variables:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
521
11eaf51 correct fossil
lwall authored
522 &*myfunc(42);
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
523
524 =head2 Lvalue subroutines
525
526 Lvalue subroutines return a "proxy" object that can be assigned to.
527 It's known as a proxy because the object usually represents the
528 purpose or outcome of the subroutine call.
529
530 Subroutines are specified as being lvalue using the C<is rw> trait.
531
532 An lvalue subroutine may return a variable:
533
534 my $lastval;
535 sub lastval () is rw { return $lastval }
536
537 or the result of some nested call to an lvalue subroutine:
538
539 sub prevval () is rw { return lastval() }
540
541 or a specially tied proxy object, with suitably programmed
542 C<FETCH> and C<STORE> methods:
543
544 sub checklastval ($passwd) is rw {
8a99698 @moritz [S06] avoid indirect method call syntax
moritz authored
545 return Proxy.new:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
546 FETCH => method {
547 return lastval();
548 },
549 STORE => method ($val) {
550 die unless check($passwd);
551 lastval() = $val;
552 };
553 }
554
555 Other methods may be defined for specialized purposes such as temporizing
556 the value of the proxy.
557
45caa2b @TimToady Allow 'is parcel' on subs that are only sorta rw
TimToady authored
558 =head2 Parcel subroutines
559
560 If the subroutine doesn't care whether the returned value is a container or not,
561 it may declare this with C<is parcel>, to indicate that the return value should
b327dcf @TimToady typo spotted by lizmat++
TimToady authored
562 be returned raw, without attempting any decontainerization. This can be useful for
45caa2b @TimToady Allow 'is parcel' on subs that are only sorta rw
TimToady authored
563 routines that wish to process mixed containers and non-containers without distinction.
564
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
565 =head2 Operator overloading
566
567 Operators are just subroutines with special names and scoping.
568 An operator name consists of a grammatical category name followed by
569 a single colon followed by an operator name specified as if it were
081817f @lizmat Removed superfluous "a"
lizmat authored
570 one or more strings. So any of these indicates the same binary addition operator:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
571
572 infix:<+>
573 infix:«+»
574 infix:<<+>>
fc1083f [Spec] :() is now always signature. Use foofix:[...] as the general …
lwall authored
575 infix:['+']
576 infix:["+"]
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
577
578 Use the C<&> sigil just as you would on ordinary subs.
579
580 Unary operators are defined as C<prefix> or C<postfix>:
581
582 sub prefix:<OPNAME> ($operand) {...}
583 sub postfix:<OPNAME> ($operand) {...}
584
585 Binary operators are defined as C<infix>:
586
587 sub infix:<OPNAME> ($leftop, $rightop) {...}
588
589 Bracketing operators are defined as C<circumfix> where a term is expected
590 or C<postcircumfix> where a postfix is expected. A two-element slice
591 containing the leading and trailing delimiters is the name of the
592 operator.
593
594 sub circumfix:<LEFTDELIM RIGHTDELIM> ($contents) {...}
fc1083f [Spec] :() is now always signature. Use foofix:[...] as the general …
lwall authored
595 sub circumfix:['LEFTDELIM','RIGHTDELIM'] ($contents) {...}
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
596
597 Contrary to Apocalypse 6, there is no longer any rule about splitting an even
598 number of characters. You must use a two-element slice. Such names
599 are canonicalized to a single form within the symbol table, so you
600 must use the canonical name if you wish to subscript the symbol table
601 directly (as in C<< PKG::{'infix:<+>'} >>). Otherwise any form will
602 do. (Symbolic references do not count as direct subscripts since they
603 go through a parsing process.) The canonical form always uses angle
604 brackets and a single space between slice elements. The elements
fc1083f [Spec] :() is now always signature. Use foofix:[...] as the general …
lwall authored
605 are escaped on brackets, so C<< PKG::circumfix:['<','>'] >> is canonicalized
606 to C<<< PKG::{'circumfix:<\< \>>'} >>>, and decanonicalizing may always
607 be done left-to-right.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
608
609 Operator names can be any sequence of non-whitespace characters
610 including Unicode characters. For example:
611
612 sub infix:<(c)> ($text, $owner) { return $text but Copyright($owner) }
613 method prefix:<±> (Num $x --> Num) { return +$x | -$x }
614 multi sub postfix:<!> (Int $n) { $n < 2 ?? 1 !! $n*($n-1)! }
615
616 my $document = $text (c) $me;
617
618 my $tolerance = ±7!;
619
620 <!-- This is now a comment -->
621
622 Whitespace may never be part of the name (except as separator
623 within a C<< <...> >> or C<«...»> slice subscript, as in the example above).
624
625 A null operator name does not define a null or whitespace operator, but
626 a default matching subrule for that syntactic category, which is useful when
627 there is no fixed string that can be recognized, such as tokens beginning
628 with digits. Such an operator I<must> supply an C<is parsed> trait.
629 The Perl grammar uses a default subrule for the C<:1st>, C<:2nd>, C<:3rd>,
630 etc. regex modifiers, something like this:
631
632 sub regex_mod_external:<> ($x) is parsed(token { \d+[st|nd|rd|th] }) {...}
633
634 Such default rules are attempted in the order declared. (They always follow
635 any rules with a known prefix, by the longest-token-first rule.)
636
637 Although the name of an operator can be installed into any package or
638 lexical namespace, the syntactic effects of an operator declaration are
639 always lexically scoped. Operators other than the standard ones should
0849660 @lizmat The * namespace is now called GLOBAL::
lizmat authored
640 not be installed into the C<GLOBAL::> namespace. Always use exportation to make
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
641 non-standard syntax available to other scopes.
642
e5b8663 @TimToady --> as context for code body
TimToady authored
643 =head1 Calling conventions
644
645 In Perl 6 culture, we distinguish the terms I<parameter> and
646 I<argument>; a parameter is the formal name that will attach to an
647 incoming argument during the course of execution, while an argument
648 is the actual value that will be bound to the formal parameter.
649 The process of attaching these values (arguments) to their temporary
650 names (parameters) is known as I<binding>. (Some C.S. literature
651 uses the terms "formal argument" and "actual argument" for these
4909197 @masak [S06] typo fixes
masak authored
652 two concepts, but here we try to avoid using the term "argument"
e5b8663 @TimToady --> as context for code body
TimToady authored
653 for formal parameters.)
654
655 Various Perl 6 code objects (either routines or blocks) may be
aff4e89 @lizmat s/an/a/
lizmat authored
656 declared with parameter lists, either explicitly by use of a signature
e5b8663 @TimToady --> as context for code body
TimToady authored
657 declaration, or implicitly by use of placeholder variables within the body
658 of code. (Use of both for the same code block is not allowed.)
659
660 =head1 Signatures
661
662 A signature consists of a list of zero or more parameter declarations,
663 separated by commas. (These are described below.) Signatures are
664 usually found inside parentheses (within routine declarations), or
665 after an arrow C<< -> >> (within block declarations), but other forms
666 are possible for specialized cases. A signature may also indicate what
667 the code returns, either generally or specifically. This is indicated
668 by placing the return specification after a C<< --> >> token. If the
669 return specification names a type (that is, an indefinite object),
670 then a successful call to the code must always return a value of
671 that type. If the return specification returns a definite object,
672 then that value is always returned from a successful call. (For this
673 purpose the C<Nil> value is treated as definite.) An unsuccessful call
674 may always call C<fail> to return a C<Failure> object regardless of
675 the return specification.
676
677 Ordinarily, if the return is specified as a type (or is unspecified),
4909197 @masak [S06] typo fixes
masak authored
678 the final statement of the block will be evaluated for its return
e5b8663 @TimToady --> as context for code body
TimToady authored
679 value, and this will be the return value of the code block as a whole.
680 (It must conform to the return type specification, if provided.)
681 An explicit C<return> may be used instead to evaluate the C<return>'s
682 arguments as the code block's return value, and leave the code block
683 immediately, short-circuiting the rest of the block's execution.
684
48958ab @TimToady Simplify Nil semantics; never means () now
TimToady authored
685 If the return specification is a definite immutable value (or C<Nil>) rather than
e5b8663 @TimToady --> as context for code body
TimToady authored
686 a type, then all top-level statements in the code block are evaluated
687 only for their side effects; in other words, all of the statements are
688 evaluated in sink context, including the final statement. An explicit
689 C<return> statement is allowed, but only in argumentless form, to
690 indicate that execution is to be short-circuited and the I<declared>
691 return value is to be returned. No other value may be returned in
692 its place.
693
694 If the return specification is definite but not an immutable value,
695 then it must be a mutable container (variable) of some sort.
696 The container variable is declared as any other parameter would be, but
697 no incoming argument will ever be bound to it. It is permitted
698 to supply a default value, in which case the return variable will
caacd06 @hoelzro Clarify return variables' behavior wrt. shadowing
hoelzro authored
699 always be initialized with that default value. Like other variables
700 declared in a signature, a new variable will B<always> be created; any
701 existing variable will automatically be shadowed. If you want to have
702 the return variable reference an existing variable, you must resort to
703 C<< OUTER::<foo> >> hackery. As with value return, all top-level statements
704 are evaluated in sink context, and only argumentless C<return> is allowed,
705 indicating that the current contents of the return value should be returned.
e5b8663 @TimToady --> as context for code body
TimToady authored
706
707 Note that the default return policy assumes functional semantics, with
708 the result that a loop as the final statement would be evaluated as
709 a map, which may surprise some people. An implementation is allowed
710 to warn when it finds such a loop; this warning may be suppressed by
711 supplying a return specification, which will also determine whether
712 the final loop statement is evaluated in sink context.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
713
e5b8663 @TimToady --> as context for code body
TimToady authored
714 =head1 Parameters and arguments
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
715
716 By default, all parameters are readonly aliases to their corresponding
717 arguments--the parameter is just another name for the original
718 argument, but the argument can't be modified through it. This is
719 vacuously true for value arguments, since they may not be modified in
720 any case. However, the default forces any container argument to also
721 be treated as an immutable value. This extends down only one level;
722 an immutable container may always return an element that is mutable if
723 it so chooses. (For this purpose a scalar variable is not considered
724 a container of its singular object, though, so the top-level object
725 within a scalar variable is considered immutable by default. Perl 6
726 does not have references in the same sense that Perl 5 does.)
727
728 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 "…
lwall authored
729 object or container as an argument (or some kind of type object that
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
730 can be converted to a mutable object, such as might be returned
731 by an array or hash that knows how to autovivify new elements).
732 Otherwise the signature fails to bind, and this candidate routine
733 cannot be considered for servicing this particular call. (Other multi
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callab…
jdlugosz authored
734 candidates, if any, may succeed if they don't require C<rw> for this
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
735 parameter.) In any case, failure to bind does not by itself cause
736 an exception to be thrown; that is completely up to the dispatcher.
737
738 To pass-by-copy, use the C<is copy> trait. An object container will
739 be cloned whether or not the original is mutable, while an (immutable)
740 value will be copied into a suitably mutable container. The parameter
741 may bind to any argument that meets the other typological constraints
742 of the parameter.
743
744 If you have a readonly parameter C<$ro>, it may never be passed on to
745 a C<rw> parameter of a subcall, whether or not C<$ro> is currently
746 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
747 copy parameters. It may also be rebound to a parcel parameter (see
748 "C<is parcel>" below), but modification will fail as in the case where
749 an immutable value is bound to a C<parcel> parameter.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
750
751 Aliases of C<$ro> are also readonly, whether generated explicitly with C<:=>
752 or implicitly within a C<Capture> object (which are themselves immutable).
753
754 Also, C<$ro> may not be returned from an lvalue subroutine or method.
755
756 Parameters may be required or optional. They may be passed by position,
757 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…
jimmy authored
758 on their corresponding arguments, but unlike in Perl 5, this is decided
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
759 lazily at parameter binding time.
760
761 Arguments destined for required positional parameters must come before
762 those bound to optional positional parameters. Arguments destined
763 for named parameters may come before and/or after the positional
764 parameters. (To avoid confusion it is highly recommended that all
765 positional parameters be kept contiguous in the call syntax, but
766 this is not enforced, and custom arg list processors are certainly
767 possible on those arguments that are bound to a final slurpy or
768 arglist variable.)
769
2fc49e5 [S06] third attempt at describing elusive name collision
masak authored
770 A signature containing a name collision is considered a compile time
771 error. A name collision can occur between positional parameters, between
772 named parameters, or between a positional parameter and a named one.
773 The sigil is not considered in such a comparison, except in the case of
774 two positional parameters -- in other words, a signature in which two
775 or more parameters are identical except for the sigil is still OK (but
776 you won't be able to pass values by that name).
777
778 :($a, $a) # wrong, two $a
779 :($a, @a) # OK (but don't do that)
93a7eb5 @lizmat Some elaboration on possible name collisions in signatures
lizmat authored
780 :($a, :a($b)) # wrong, one $a from positional, one $a from named parameter
22f4608 @paultcochrane Purge trailing whitespace in S06 -- S17
paultcochrane authored
781 :($a, :a(@b)) # wrong, same
93a7eb5 @lizmat Some elaboration on possible name collisions in signatures
lizmat authored
782 :(:$a, :@a) # wrong, can only have one named parameter "a"
60657eb [S06] same-named non-anon positionals are a compile error
masak authored
783
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
784 =head2 Named arguments
785
786 Named arguments are recognized syntactically at the "comma" level.
787 Since parameters are identified using identifiers, the recognized
788 syntaxes are those where the identifier in question is obvious.
789 You may use either the adverbial form, C<:name($value)>, or the
790 autoquoted arrow form, C<< name => $value >>. These must occur at
791 the top "comma" level, and no other forms are taken as named pairs
792 by default. Pairs intended as positional arguments rather than named
793 arguments may be indicated by extra parens or by explicitly quoting
794 the key to suppress autoquoting:
795
796 doit :when<now>,1,2,3; # always a named arg
797 doit (:when<now>),1,2,3; # always a positional arg
798
799 doit when => 'now',1,2,3; # always a named arg
800 doit (when => 'now'),1,2,3; # always a positional arg
801 doit 'when' => 'now',1,2,3; # always a positional arg
802
781e726 @TimToady Revert "fix 0 => $arg naminess"
TimToady authored
803 Only bare keys with valid identifier names are recognized as named arguments:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
804
805 doit when => 'now'; # always a named arg
806 doit 'when' => 'now'; # always a positional arg
781e726 @TimToady Revert "fix 0 => $arg naminess"
TimToady authored
807 doit 123 => 'now'; # always a positional arg
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
808 doit :123<now>; # always a positional arg
809
810 Going the other way, pairs intended as named arguments that don't look
811 like pairs must be introduced with the C<|> prefix operator:
812
813 $pair = :when<now>;
814 doit $pair,1,2,3; # always a positional arg
815 doit |$pair,1,2,3; # always a named arg
816 doit |get_pair(),1,2,3; # always a named arg
817 doit |('when' => 'now'),1,2,3; # always a named arg
818
819 Note the parens are necessary on the last one due to precedence.
820
821 Likewise, if you wish to pass a hash and have its entries treated as
822 named arguments, you must dereference it with a C<|>:
823
824 %pairs = (:when<now>, :what<any>);
825 doit %pairs,1,2,3; # always a positional arg
826 doit |%pairs,1,2,3; # always named args
827 doit |%(get_pair()),1,2,3; # always a named arg
828 doit |%('when' => 'now'),1,2,3; # always a named arg
829
830 Variables with a C<:> prefix in rvalue context autogenerate pairs, so you
831 can also say this:
832
833 $when = 'now';
834 doit $when,1,2,3; # always a positional arg of 'now'
835 doit :$when,1,2,3; # always a named arg of :when<now>
836
837 In other words C<:$when> is shorthand for C<:when($when)>. This works
838 for any sigil:
839
840 :$what :what($what)
841 :@what :what(@what)
842 :%what :what(%what)
843 :&what :what(&what)
844
845 Ordinary hash notation will just pass the value of the hash entry as a
846 positional argument regardless of whether it is a pair or not.
847 To pass both key and value out of hash as a positional pair, use C<:p>
848 instead:
849
850 doit %hash<a>:p,1,2,3;
851 doit %hash{'b'}:p,1,2,3;
852
853 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 Callab…
jdlugosz authored
854 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
855 If you want the pair (or pairs) to be interpreted as named arguments,
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
856 you may do so by prefixing with the C<< prefix:<|> >> operator:
857
c4304e7 @softmoth [S06] Fix an example in the Named arguments section
softmoth authored
858 doit |(%hash<a>:p),1,2,3;
859 doit |(%hash{'b'}:p),1,2,3;
860
861 (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
862
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callab…
jdlugosz authored
863 C<Pair> constructors are recognized syntactically at the call level and
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
864 put into the named slot of the C<Capture> structure. Hence they may be
865 bound to positionals only by name, not as ordinary positional C<Pair>
866 objects. Leftover named arguments can be slurped into a slurpy hash.
867
868 Because named and positional arguments can be freely mixed, the
869 programmer always needs to disambiguate pairs literals from named
870 arguments with parentheses or quotes:
871
872 # Named argument "a"
873 push @array, 1, 2, :a<b>;
874
875 # Pair object (a=>'b')
876 push @array, 1, 2, (:a<b>);
877 push @array, 1, 2, 'a' => 'b';
878
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
879 Perl 6 allows multiple same-named arguments, and records the relative
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
880 order of arguments with the same name. When there are more than one
881 argument, the C<@> sigil in the parameter list causes the arguments
882 to be concatenated:
883
8e6b864 @skids Do not use positional params as named in code example
skids authored
884 sub fun (Int :@x) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
885 fun( x => 1, x => 2 ); # @x := (1, 2)
886 fun( x => (1, 2), x => (3, 4) ); # @x := (1, 2, 3, 4)
887
888 Other sigils bind only to the I<last> argument with that name:
889
8e6b864 @skids Do not use positional params as named in code example
skids authored
890 sub fun (Int :$x) { ... }
f5aa846 [S06] fixed some spelling and consistency stuff
masak authored
891 fun( x => 1, x => 2 ); # $x := 2
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
892 fun( x => (1, 2), x => (3, 4) ); # $x := (3, 4)
893
894 This means a hash holding default values must come I<before> known named
895 parameters, similar to how hash constructors work:
896
897 # Allow "x" and "y" in %defaults to be overridden
898 f( |%defaults, x => 1, y => 2 );
899
900 =head2 Invocant parameters
901
902 A method invocant may be specified as the first parameter in the parameter
903 list, with a colon (rather than a comma) immediately after it:
904
905 method get_name ($self:) {...}
906 method set_name ($_: $newname) {...}
907
908 The corresponding argument (the invocant) is evaluated in item context
909 and is passed as the left operand of the method call operator:
910
911 print $obj.get_name();
912 $obj.set_name("Sam");
913
59032e7 Simplify meaning of Capture and Match in item context to preserve sanity
lwall authored
914 The invocant is actually stored as the first positional argument of a C<Capture>
915 object. It is special only to the dispatcher, otherwise it's just a normal
916 positional argument.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
917
59032e7 Simplify meaning of Capture and Match in item context to preserve sanity
lwall authored
918 Single-dispatch semantics may also be requested by using the indirect object syntax, with a colon
919 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
920 same precedence:
921
ce337ef [S06] remove fossil spotted by jnthn++
lwall authored
922 set_name $obj: "Sam";
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
923 $obj.set_name("Sam"); # same as the above
924
925 An invocant is the topic of the corresponding method if that formal
4198be6 @moritz Undocument the "self" pragma
moritz authored
926 parameter is declared with the name C<$_>.
11fe4fc [S06] spec the \| parcel parameter syntax
lwall authored
927 If you have a call of the form:
59032e7 Simplify meaning of Capture and Match in item context to preserve sanity
lwall authored
928
929 foo(|$capture)
930
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
931 the compiler must defer the decision on whether to treat it as a method
932 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
933 argument is marked as an invocant. For ordinary calls this can
934 always be determined at compile time, however.
935
ab16f15 @moritz Document bare :D at al in parameter lists
moritz authored
936 =head2 Parameters with type constraints
937
938 Parameters can be constraint to other types than the default simply by
939 using the type name in from of the parameter:
940
941 sub double(Numeric $x) { 2 * $x }
942
943 If no explicit type constraint is given, it defaults to the type of the
944 surrounding package for method invocants, and to C<Any> everywhere else.
945
946 A bare C<:D>, C<:U>, C<:T> or C<:_> instead of a type constraint limits the
947 default type to definite, undefined, type objects or any object. The default
948 still applies, so in
949
950 class Con {
951 method man(:U: :D $x)
952 }
953
954 the signature is equivalent to C<(Con:U: Any:D $x)>.
955
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
956 =head2 Longname parameters
957
958 A routine marked with C<multi> can mark part of its parameters to
959 be considered in the multi dispatch. These are called I<longnames>;
960 see S12 for more about the semantics of multiple dispatch.
961
962 You can choose part of a C<multi>'s parameters to be its longname,
963 by putting a double semicolon after the last one:
964
965 multi sub handle_event ($window, $event;; $mode) {...}
966 multi method set_name ($self: $name;; $nick) {...}
967
968 A parameter list may have at most one double semicolon; parameters
969 after it are never considered for multiple dispatch (except of course
970 that they can still "veto" if their number or types mismatch).
971
972 [Conjecture: It might be possible for a routine to advertise multiple
973 long names, delimited by single semicolons. See S12 for details.]
974
975 If the parameter list for a C<multi> contains no semicolons to delimit
976 the list of important parameters, then all positional parameters are
977 considered important. If it's a C<multi method> or C<multi submethod>,
978 an additional implicit unnamed C<self> invocant is added to the
979 signature list unless the first parameter is explicitly marked with a colon.
980
981
982 =head2 Required parameters
983
984 Required parameters are specified at the start of a subroutine's parameter
985 list:
986
987 sub numcmp ($x, $y) { return $x <=> $y }
988
989 Required parameters may optionally be declared with a trailing C<!>,
990 though that's already the default for positional parameters:
991
992 sub numcmp ($x!, $y!) { return $x <=> $y }
993
25eb879 @masak [S06] remove fossil
masak authored
994 Not passing all of the required arguments to a normal subroutine
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
995 is a fatal error. Passing a named argument that cannot be bound to a normal
996 subroutine is also a fatal error. (Methods are different.)
997
998 The number of required parameters a subroutine has can be determined by
999 calling its C<.arity> method:
1000
1001 $args_required = &foo.arity;
1002
1003
1004 =head2 Optional parameters
1005
1006 Optional positional parameters are specified after all the required
1007 parameters and each is marked with a C<?> after the parameter:
1008
1009 sub my_substr ($str, $from?, $len?) {...}
1010
1011 Alternately, optional fields may be marked by supplying a default value.
1012 The C<=> sign introduces a default value:
1013
1014 sub my_substr ($str, $from = 0, $len = Inf) {...}
1015
1016 Default values can be calculated at run-time. They may even use the values of
1017 preceding parameters:
1018
1019 sub xml_tag ($tag, $endtag = matching_tag($tag) ) {...}
1020
1021 Arguments that correspond to optional parameters are evaluated in
1022 item context. They can be omitted, passed positionally, or passed by
1023 name:
1024
1025 my_substr("foobar"); # $from is 0, $len is infinite
1026 my_substr("foobar",1); # $from is 1, $len is infinite
1027 my_substr("foobar",1,3); # $from is 1, $len is 3
1028 my_substr("foobar",len=>3); # $from is 0, $len is 3
1029
1030 Missing optional arguments default to their default values, or to
1031 an undefined value if they have no default. (A supplied argument that is
1032 undefined is not considered to be missing, and hence does not trigger
1033 the default. Use C<//=> within the body for that.)
1034
1035 You may check whether an optional parameter was bound to anything
1036 by calling C<VAR($param).defined>.
1037
1038 =head2 Named parameters
1039
1040 Named-only parameters follow any required or optional parameters in the
1041 signature. They are marked by a prefix C<:>:
1042
1043 sub formalize($text, :$case, :$justify) {...}
1044
1045 This is actually shorthand for:
1046
1047 sub formalize($text, :case($case), :justify($justify)) {...}
1048
1049 If the longhand form is used, the label name and variable name can be
1050 different:
1051
1052 sub formalize($text, :case($required_case), :justify($justification)) {...}
1053
1054 so that you can use more descriptive internal parameter names without
1055 imposing inconveniently long external labels on named arguments.
1056 Multiple name wrappings may be given; this allows you to give both a
1057 short and a long external name:
1058
1059 sub globalize (:g(:global($gl))) {...}
1060
1061 Or equivalently:
1062
1063 sub globalize (:g(:$global)) {...}
1064
1065 Arguments that correspond to named parameters are evaluated in item
1066 context. They can only be passed by name, so it doesn't matter what
1067 order you pass them in:
1068
1069 $formal = formalize($title, case=>'upper');
1070 $formal = formalize($title, justify=>'left');
1071 $formal = formalize($title, :justify<right>, :case<title>);
1072
1073 See S02 for the correspondence between adverbial form and arrow notation.
1074
1075 While named and position arguments may be intermixed, it is suggested
1076 that you keep all the positionals in one place for clarity unless you
1077 have a good reason not to. This is likely bad style:
1078
1079 $formal = formalize(:justify<right>, $title, :case<title>, $date);
1080
1081 Named parameters are optional unless marked with a following C<!>.
1082 Default values for optional named parameters are defined in the same
1083 way as for positional parameters, but may depend only on existing
1084 values, including the values of parameters that have already been
48958ab @TimToady Simplify Nil semantics; never means () now
TimToady authored
1085 bound. Named optional parameters default to C<Nil> (that is, they
1086 set the default of the container) if they have
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1087 no default. Named required parameters fail unless an argument pair
1088 of that name is supplied.
1089
94d0124 @TimToady severely restrict named-to-positional binding
TimToady authored
1090 Bindings logically happen in declaration order, not call order, so
1091 any default may reliably depend on formal parameters to its left in
1092 the signature.
1093
1094 Another benefit of this policy is that, for routines that allow it,
1095 named arguments may be bound to positional parameters. (This is
1096 allowed only on routines that are I<explicitly> declared with either
1097 the C<proto> or the C<only> declarator.) If the first positional
1098 parameter is named C<$a>, for example, it will bind to a C<:a()>
1099 argument in preference to the first positional argument.
1100
1101 The restriction to explicit C<proto> and C<only> declarations is
1102 motivated by the desire for both API purity and efficiency. Normal
1103 C<multi> or C<sub> declarations and normal method declarations do not
1104 attempt to look for named bindings to positionals. At most there is
1105 one such binding for any dispatch, when it initially calls the C<proto>
1106 (or explicit C<only>). The C<proto> binder (for either sub or method)
1107 must automatically remap such named parameters to positionals before
1108 calling its internal multi dispatcher (the one represented by C<{*}>).
1109 In the case of a C<proto> sub, this mapping can be done at the point
1110 of the call, since there can only be one possible set of positional
1111 names, and the proto to be called can be known at compile time (in
45ca8c8 @patch fix typos
patch authored
1112 the absence of CANDO declarations in the outer scopes). So after
94d0124 @TimToady severely restrict named-to-positional binding
TimToady authored
1113
1114 proto foo ($x, $y, :$bar, :$baz) {*}
1115 multi foo ($a, $b, :$bar, :$baz) {...}
1116 multi foo ($n, $m, :$bar, :$baz) {...}
1117
1118 foo :y(2), :x(1); # can turn into foo(1,2)
1119
1120 the call to C<foo> can be turned into a pure positional call to
1121 the C<proto> (which can in turn be inlined because it's using the
1122 standard C<{*}> dispatcher--and likewise for methods, when the class
1123 containing the C<proto> is known to be finalizable). Note also that
1124 multi definitions are never required to use the same parameter names
1125 for positional parameters, since after the C<proto> binding is done,
1126 the names (if any) are never used again for positionals.
1127
1128 The C<$x> and C<$y> names above are part of the public API only
1129 because they are named in the C<proto>. Positional parameter names
1130 are never part of the advertised API unless explicitly enabled.
1131 An explicit C<proto> may easily refrain from advertising names by
45ca8c8 @patch fix typos
patch authored
1132 declaring positionals with bare sigils:
94d0124 @TimToady severely restrict named-to-positional binding
TimToady authored
1133
1134 proto foo ($, $, :$bar, :$baz) {*}
1135 multi foo ($x, $y, :$bar, :$baz) {...}
1136
1137 foo :x(1), :y(2); # illegal
1138
1139 (And an C<only> routine may control the positional API simply by
1140 using C<sub> instead, or by defining a C<proto> with a single C<multi>
1141 if finer control is desired.)
1142
1143 It follows from all this that an intuited proto never has to worry
1144 about supplying the API names of positional parameters. And no proto
45ca8c8 @patch fix typos
patch authored
1145 ever has to worry about conflicting names in the positionals of the
94d0124 @TimToady severely restrict named-to-positional binding
TimToady authored
1146 multis they dispatch to, since any remapping is handled before that.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1147
1148 =head2 List parameters
1149
1150 List parameters capture a variable length list of data. They're used
1151 in subroutines like C<print>, where the number of arguments needs to be
1152 flexible. They're also called "variadic parameters", because they take a
1153 I<variable> number of arguments. But generally we call them "slurpy"
1154 parameters because they slurp up arguments.
1155
1156 Slurpy parameters follow any required or optional parameters. They are
1157 marked by a C<*> before the parameter:
1158
1159 sub duplicate($n, *%flag, *@data) {...}
1160
1161 Named arguments are bound to the slurpy hash (C<*%flag>
1162 in the above example). Such arguments are evaluated in item context.
1163 Any remaining variadic arguments at the end of the argument list
1164 are bound to the slurpy array (C<*@data> above) and are evaluated
1165 in list context.
1166
1167 For example:
1168
1169 duplicate(3, reverse => 1, collate => 0, 2, 3, 5, 7, 11, 14);
1170 duplicate(3, :reverse, :!collate, 2, 3, 5, 7, 11, 14); # same
1171
1172 # The @data parameter receives [2, 3, 5, 7, 11, 14]
1173 # The %flag parameter receives { reverse => 1, collate => 0 }
1174
1175 Slurpy scalar parameters capture what would otherwise be the first
1176 elements of the variadic array:
1177
1178 sub head(*$head, *@tail) { return $head }
1179 sub neck(*$head, *$neck, *@tail) { return $neck }
1180 sub tail(*$head, *@tail) { return @tail }
1181
1182 head(1, 2, 3, 4, 5); # $head parameter receives 1
1183 # @tail parameter receives [2, 3, 4, 5]
1184
1185 neck(1, 2, 3, 4, 5); # $head parameter receives 1
1186 # $neck parameter receives 2
1187 # @tail parameter receives [3, 4, 5]
1188
1189 Slurpy scalars still impose list context on their arguments.
1190
cc595c7 [S06] supply missing list splitting primitive as a form of binding, m…
lwall authored
1191 Single slurpy parameters are treated lazily -- the list is only flattened
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1192 into an array when individual elements are actually accessed:
1193
1194 @fromtwo = tail(1..Inf); # @fromtwo contains a lazy [2..Inf]
1195
cc595c7 [S06] supply missing list splitting primitive as a form of binding, m…
lwall authored
1196 [Conjecture: However, if you use two or more slurpy arrays in a
1197 signature, the list is instead evaluated in hyper context, and will
1198 be asked to split itself into the number of lists corresponding to
1199 the number of slurpies so declared. A non-hyperable list will return
1200 failure for this splitting operation, so the signature should only bind
839c329 @felher [S06] typo fix: insert missing 'is'
felher authored
1201 on parallelizable list operations. Likewise a list that is "too short to
cc595c7 [S06] supply missing list splitting primitive as a form of binding, m…
lwall authored
1202 split" fails to bind, so a separate signature may match empty lists,
6faacb9 @felher [S06] typo fix: remove lonely ')'
felher authored
1203 and perhaps singletons, if we define "too short" that way.]
cc595c7 [S06] supply missing list splitting primitive as a form of binding, m…
lwall authored
1204
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1205 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
1206 so you can refer to it within the body.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1207
1208 sub foo(*%flag, *@data) {...}
1209
1210 foo(:flag{ a => 1 }, :data[ 1, 2, 3 ]);
1211 # %flag has elements (flag => (a => 1)) and (data => [1,2,3])
1212 # @data has nothing
1213
1214 =head2 Slurpy block
1215
1216 It's also possible to declare a slurpy block: C<*&block>. It slurps
1217 up any nameless block, specified by C<{...}>, at either the current positional
1218 location or the end of the syntactic list. Put it first if you want the
1219 option of putting a block either first or last in the arguments. Put it
1220 last if you want to force it to come in as the last argument.
1221
1222 =head2 Argument list binding
1223
7b498ac @TimToady de-sigil the |capture and \parcel params
TimToady authored
1224 The underlying C<Capture> object may be bound to a single
1225 name marked with a C<|>.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1226
1227 sub bar ($a,$b,$c,:$mice) { say $mice }
3d4f2dc @TimToady s/callsame/nextsame/ for actual tailcall
TimToady authored
1228 sub foo (|args) { say args.perl; &bar.nextwith(|args); }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1229
1230 This prints:
1231
1232 foo 1,2,3,:mice<blind>; # says "\(1,2,3,:mice<blind>)" then "blind"
1233
1234 As demonstrated above, the capture may be interpolated into another
7b498ac @TimToady de-sigil the |capture and \parcel params
TimToady authored
1235 call's arguments. (The C<|> prefix is described below.)
3d4f2dc @TimToady s/callsame/nextsame/ for actual tailcall
TimToady authored
1236 Use of C<nextwith> allows the routine to be called without introducing
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1237 an official C<CALLER> frame. For more see "Wrapping" below.
1238
7b498ac @TimToady de-sigil the |capture and \parcel params
TimToady authored
1239 The C<|> parameter takes a snapshot of the current binding state, but
1240 does not consume any arguments from it.
1241 It is allowed to have more parameters within the signature:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1242
7b498ac @TimToady de-sigil the |capture and \parcel params
TimToady authored
1243 sub compare (|args, Num $x, Num $y --> Bool) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1244
1245 For all normal declarative purposes (invocants and multiple dispatch
7b498ac @TimToady de-sigil the |capture and \parcel params
TimToady authored
1246 types, for instance), capture parameters are ignored.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1247
7b498ac @TimToady de-sigil the |capture and \parcel params
TimToady authored
1248 method addto (|args, $self: @x) { trace(args); $self += [+] @x }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1249
7b498ac @TimToady de-sigil the |capture and \parcel params
TimToady authored
1250 The extra signature is not required for non-C<multi>s since there can
1251 only be one candidate, but for multiple dispatch the extra signature
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1252 is required at least for its types, or the declaration would not know
1253 what signature to match against.
1254
7b498ac @TimToady de-sigil the |capture and \parcel params
TimToady authored
1255 multi foo (|args, Int, Bool?, *@, *%)) { reallyintfoo(args) }
1256 multi foo (|args, Str, Bool?, *@, *%)) { reallystrfoo(args) }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1257
11fe4fc [S06] spec the \| parcel parameter syntax
lwall authored
1258 =head2 Parcel binding
1259
7b498ac @TimToady de-sigil the |capture and \parcel params
TimToady authored
1260 When you bind an argument to a sigiled variable, it enforces the contract
1261 of that sigil, but sometimes you don't want that.
1262 It is possible to bind an argument to a simple name instead, which represents
1263 that argument in its rawest form, which is what we call a parcel. (It might
1264 actually be a C<Parcel> object, or any item that can function as a parcel.)
1265 In any case, it's a raw reference to whatever was passed, with no commitment
1266 to structure or mutability.
11fe4fc [S06] spec the \| parcel parameter syntax
lwall authored
1267
7b498ac @TimToady de-sigil the |capture and \parcel params
TimToady authored
1268 sub foo (\x, \y) { x = y; } # might or might not succeed
11fe4fc [S06] spec the \| parcel parameter syntax
lwall authored
1269
7b498ac @TimToady de-sigil the |capture and \parcel params
TimToady authored
1270 A C<\> parameter effectively declares a new term in the language for
1271 the rest of the current scope, so when you use that term, it is not
1272 parsed as a list operator, so it will not look for any subsequent
1273 arguments.
1274
1275 sub foo (\x) { x 42; } # syntax error; two terms in a row
1276
1277 Parcel parameters make it relatively easy to program in a "sigilless" style,
1278 if you desire:
1279
1280 sub say-sins (\angles) {
1281 for angles -> \𝜃 { say sin 𝜃 }
1282 }
1283
1284 or
1285
1286 my \𝑖 = some-integer; say 𝑖 + 2;
1287
1288 Note how C<𝑖> would be misinterpreted if it treated C<+ 2> as an argument, but
1289 since it's a simple term, it doesn't.
1290
1291 The term does act like a function call in one way, however. Since it returns a
1292 parcel, the value will flatten in a list context, but itemize in an item context.
1293 You can use C<< prefix:<|> >> to force flattening into an outer argument list, if
1294 needed.
11fe4fc [S06] spec the \| parcel parameter syntax
lwall authored
1295
da0c71f @TimToady include ability to have non-identifier aliases
TimToady authored
1296 It is possible to alias to a non-identifier by using the C<term> syntactic category:
1297
1298 my \term:<∞> = Inf;
1299
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1300 =head2 Flattening argument lists
1301
1302 The unary C<|> operator casts its argument to a C<Capture>
1303 object, then splices that capture into the argument list
1304 it occurs in. To get the same effect on multiple arguments you
1305 can use the C<< |« >> hyperoperator.
1306
1307 C<Pair> and C<Hash> become named arguments:
1308
1309 |(x=>1); # Pair, becomes \(x=>1)
1310 |{x=>1, y=>2}; # Hash, becomes \(x=>1, y=>2)
1311
736a666 [Spec] random whackage on List, Seq, Parcel, Capture, Iterator, Nil etc.
lwall authored
1312 Anything else that is C<Iterable> is simply turned into
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1313 positional arguments:
1314
82431de @lizmat Eradicate Seq
lizmat authored
1315 |(1,2,3); # Parcel, becomes \(1,2,3)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1316 |(1..3); # Range, becomes \(1,2,3)
736a666 [Spec] random whackage on List, Seq, Parcel, Capture, Iterator, Nil etc.
lwall authored
1317 |(1..2, 3); # Parcel, becomes \(1,2,3)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1318 |([x=>1, x=>2]); # List (from an Array), becomes \((x=>1), (x=>2))
1319
1320 For example:
1321
1322 sub foo($x, $y, $z) {...} # expects three scalars
1323 @onetothree = 1..3; # array stores three scalars
1324
1325 foo(1,2,3); # okay: three args found
1326 foo(@onetothree); # error: only one arg
1327 foo(|@onetothree); # okay: @onetothree flattened to three args
1328
1329 The C<|> operator flattens lazily -- the array is flattened only if
1330 flattening is actually required within the subroutine. To flatten before
0bf13db [S02,S06] continue de-confusing flat and eager
lwall authored
1331 the list is even passed into the subroutine, use the C<flat> list
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1332 operator:
1333
0bf13db [S02,S06] continue de-confusing flat and eager
lwall authored
1334 foo(|flat 1,2,3 Z 4,5,6); # zip list flattened before interpolation
1335 foo |(1,2,3 Z 4,5,6).flat # same thing
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1336
1337
1338 =head2 Multidimensional argument list binding
1339
1340 Some functions take more than one list of positional and/or named arguments,
1341 that they wish not to be flattened into one list. For instance, C<zip()> wants
1342 to iterate several lists in parallel, while array and hash subscripts want to
1343 process a multidimensional slice. The set of underlying argument lists may be
9eb1b35 [S06] more @@ clobberation.
lwall authored
1344 bound to a single array parameter declared with a double C<**> marker:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1345
9eb1b35 [S06] more @@ clobberation.
lwall authored
1346 sub foo (**@slice) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1347
1348 Note that this is different from
1349
eb862b2 @japhb Banish |$ and \$ in more places
japhb authored
1350 sub foo (|slice) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1351
eb862b2 @japhb Banish |$ and \$ in more places
japhb authored
1352 insofar as C<|slice> is bound to a single argument-list object that
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1353 makes no commitment to processing its structure (and maybe doesn't
9eb1b35 [S06] more @@ clobberation.
lwall authored
1354 even know its own structure yet), while C<**@slice> has to create
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1355 an array that binds the incoming dimensional lists to the array's
1356 dimensions, and make that commitment visible to the rest of the scope
1357 via the sigil so that constructs expecting multidimensional lists
1358 know that multidimensionality is the intention.
1359
1360 It is allowed to specify a return type:
1361
9eb1b35 [S06] more @@ clobberation.
lwall authored
1362 sub foo (**@slice --> Num) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1363
1364 The invocant does not participate in multi-dimensional argument lists,
9eb1b35 [S06] more @@ clobberation.
lwall authored
1365 so C<self> is not present in the C<**@slice> below:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1366
9eb1b35 [S06] more @@ clobberation.
lwall authored
1367 method foo (**@slice) { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1368
9eb1b35 [S06] more @@ clobberation.
lwall authored
1369 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
1370 requesting parcels when binding (underlyingly calling C<.getarg>) rather
45ca8c8 @patch fix typos
patch authored
1371 than requesting individual elements as the flattening C<*> does (underlyingly
07265d7 [Spec] s/getobj/getarg/ to be slightly more accurate
lwall authored
1372 calling C<.get>).
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1373
1374 =head2 Zero-dimensional argument list
1375
1376 If you call a function without parens and supply no arguments, the
1377 argument list becomes a zero-dimensional slice. It differs from
1378 C<\()> in several ways:
1379
9eb1b35 [S06] more @@ clobberation.
lwall authored
1380 sub foo (**@slice) {...}
1381 foo; # +@slice == 0
1382 foo(); # +@slice == 1
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1383
eb862b2 @japhb Banish |$ and \$ in more places
japhb authored
1384 sub bar (|args = \(1,2,3)) {...}
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1385 bar; # $args === \(1,2,3)
1386 bar(); # $args === \()
1387
1388 =head2 Feed operators
1389
1390 The variadic list of a subroutine call can be passed in separately from
1391 the normal argument list, by using either of the I<feed> operators:
1392 C<< <== >> or C<< ==> >>. Syntactically, feed operators expect to find a
1393 statement on either end. Any statement can occur on the source end;
1394 however not all statements are suitable for use on the sink end of a feed.
1395
1396 Each operator expects to find a call to a variadic receiver on its
1397 "sharp" end, and a list of values on its "blunt" end:
1398
1399 grep { $_ % 2 } <== @data;
1400
1401 @data ==> grep { $_ % 2 };
1402
1403 It binds the (potentially lazy) list from the blunt end to the slurpy
1404 parameter(s) of the receiver on the sharp end. In the case of a receiver
1405 that is a variadic function, the feed is received as part of its slurpy list.
1406 So both of the calls above are equivalent to:
1407
1408 grep { $_ % 2 }, @data;
1409
1410 Note that all such feeds (and indeed all lazy argument lists) supply
1411 an implicit promise that the code producing the lists may execute
1412 in parallel with the code receiving the lists. (Feeds, hyperops,
1413 and junctions all have this promise of parallelizability in common,
1414 but differ in interface. Code which violates these promises is
038dc96 add C<> tags, fix typos, fix out-of-date \$args to |$args, use Callab…
jdlugosz authored
1415 erroneous, and will produce undefined results when parallelized.)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1416
1417 However, feeds go a bit further than ordinary lazy lists in enforcing
1418 the parallel discipline: they explicitly treat the blunt end as a
1419 cloned closure that starts a subthread (presumably cooperative). The only variables shared
1420 by the inner scope with the outer scope are those lexical variables
1421 declared in the outer scope that are visible at the time the closure is
1422 cloned and the subthread spawned. Use of such shared variables will
1423 automatically be subject to transactional protection (and associated
1424 overhead). Package variables are not cloned unless predeclared
1425 as lexical names with C<our>. Variables declared within the blunt
1426 end are not visible outside, and in fact it is illegal to declare a
1427 lexical on the blunt end that is not enclosed in curlies somehow.
1428
1429 Because feeds are defined as lazy pipes, a chain of feeds may not begin
1430 and end with the same array without some kind of eager sequence point.
1431 That is, this isn't guaranteed to work:
1432
1433 @data <== grep { $_ % 2 } <== @data;
1434
1435 either of these do:
1436
1437 @data <== grep { $_ % 2 } <== eager @data;
1438 @data <== eager grep { $_ % 2 } <== @data;
1439
1440 Conjecture: if the cloning process eagerly duplicates C<@data>, it could
1441 be forced to work. Not clear if this is desirable, since ordinary clones
1442 just clone the container, not the value.
1443
1444 Leftward feeds are a convenient way of explicitly indicating the typical
1445 right-to-left flow of data through a chain of operations:
1446
1447 @oddsquares = map { $_**2 }, sort grep { $_ % 2 }, @nums;
1448
1449 # perhaps more clearly written as...
1450
1451 @oddsquares = do {
1452 map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums;
1453 }
1454
1455 Rightward feeds are a convenient way of reversing the normal data flow in a
1456 chain of operations, to make it read left-to-right:
1457
1458 @oddsquares = do {
1459 @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 };
1460 }
1461
1462 Note that something like the C<do> is necessary because feeds operate
1463 at the statement level. Parens would also work, since a statement is
1464 expected inside:
1465
1466 @oddsquares = (
1467 @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 };
1468 );
1469
1470 But as described below, you can also just write:
1471
1472 @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 } ==> @oddsquares;
1473
1474 If the operand on the sharp end of a feed is not a call to a variadic
1475 operation, it must be something else that can be interpreted as a list
1476 receiver, or a scalar expression that can be evaluated to produce an
1477 object that does the C<KitchenSink> role, such as an C<IO> object.
1478 Such an object provides C<.clear> and C<.push> methods that will
1479 be called as appropriate to send data. (Note that an C<IO> object
1480 used as a sink will force eager evaluation on its pipeline, so the
1481 next statement is guaranteed not to run till the file is closed.
1482 In contrast, an C<Array> object used as a sink turns into a lazy
1483 array.)
1484
1485 Any non-variadic object (such as an C<Array> or C<IO> object) used as a filter
1486 between two feeds is treated specially as a I<tap> that merely captures
1487 data I<en passant>. You can safely install such a tap in an extended pipeline
1488 without changing the semantics. An C<IO> object used as a tap does not
1489 force eager evaluation since the eagerness is controlled instead by the
1490 downstream feed.
1491
1492 Any prefix list operator is considered a variadic operation, so ordinarily
1493 a list operator adds any feed input to the end of its list.
1494 But sometimes you want to interpolate elsewhere, so any contextualizer
1495 with C<*> as an argument may be used to indicate the target of a
1496 feed without the use of a temporary array:
1497
1498 foo() ==> say @(*), " is what I meant";
9eb1b35 [S06] more @@ clobberation.
lwall authored
1499 bar() ==> @(*).baz();
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1500
1501 Likewise, an C<Array> used as a tap may be distinguished from an C<Array> used
1502 as a translation function:
1503
1504 numbers() ==> @array ==> bar() # tap
1505 numbers() ==> @array[@(*)] ==> bar() # translation
1506
1507 To append multiple sources to the next sink, double the angle:
1508
9eb1b35 [S06] more @@ clobberation.
lwall authored
1509 my $sink;
1510 0..* ==> $sink;
1511 'a'..* ==>> $sink;
1512 pidigits() ==>> $sink;
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1513
1514 # outputs "(0, 'a', 3)\n"...
9eb1b35 [S06] more @@ clobberation.
lwall authored
1515 for $sink.zip { .perl.say }
1516
1517 Each such append adds another slice element (that is, a parcel), to
1518 the sink. (The original feed also created a parcel.)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1519
1520 You may use a variable (or variable declaration) as a receiver, in
1521 which case the list value is bound as the "todo" of the variable.
1522 (The append form binds addition todos to the receiver's todo list.)
1523 Do not think of it as an assignment, nor as an ordinary binding.
1524 Think of it as iterator creation. In the case of a scalar variable,
1525 that variable contains the newly created iterator itself. In the case
1526 of an array, the new iterator is installed as the method for extending
1527 the array. As with assignment, the old todo list is clobbered; use the
9eb1b35 [S06] more @@ clobberation.
lwall authored
1528 append form to avoid that and get push semantics. In any case, feeding
1529 an array always flattens. You must use the scalar form to preserve
1530 slice information.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1531
1532 In general you can simply think of a receiver array as representing
1533 the results of the chain, so you can equivalently write any of:
1534
1535 my @oddsquares <== map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums;
1536
1537 my @oddsquares
1538 <== map { $_**2 }
1539 <== sort
1540 <== grep { $_ % 2 }
1541 <== @nums;
1542
1543 @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 } ==> my @oddsquares;
1544
1545 @nums
1546 ==> grep { $_ % 2 }
1547 ==> sort
1548 ==> map { $_**2 }
1549 ==> my @oddsquares;
1550
1551 Since the feed iterator is bound into the final variable, the variable
1552 can be just as lazy as the feed that is producing the values.
1553
1554 When feeds are bound to arrays with "push" semantics, you can have
1555 a receiver for multiple feeds:
1556
1557 my @foo;
1558 0..2 ==> @foo;
1559 'a'..'c' ==>> @foo;
1560 say @foo; # 0,1,2,'a','b','c'
1561
1562 Note how the feeds are concatenated in C<@foo> so that C<@foo>
1563 is a list of 6 elements. This is the default behavior. However,
1564 sometimes you want to capture the outputs as a list of two iterators,
1565 namely the two iterators that represent the two input feeds. You can
9eb1b35 [S06] more @@ clobberation.
lwall authored
1566 get at those two iterators by using a scalar instead, which
1567 will preserve the slice structure, which can be fed to any operation
1568 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
1569
9eb1b35 [S06] more @@ clobberation.
lwall authored
1570 0..* ==> $foo;
1571 'a'..* ==>> $foo;
1572 pidigits() ==>> $foo;
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1573
9eb1b35 [S06] more @@ clobberation.
lwall authored
1574 for $foo.zip { .say }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1575
1576 [0,'a',3]
1577 [1,'b',1]
1578 [2,'c',4]
1579 [3,'d',1]
1580 [4,'e',5]
1581 [5,'f',9]
1582 ...
1583
9eb1b35 [S06] more @@ clobberation.
lwall authored
1584 Here C<$foo> is a list of three parcels, so
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1585
9eb1b35 [S06] more @@ clobberation.
lwall authored
1586 $foo.zip
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1587
1588 is equivalent to
1589
9eb1b35 [S06] more @@ clobberation.
lwall authored
1590 my (@a,@b,@c) := |$foo;
1591 zip(@a; @b; @c)
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1592
1593 A named receiver array is useful when you wish to feed into an
1594 expression that is not an ordinary list operator, and you wish to be
1595 clear where the feed's destination is supposed to be:
1596
1597 picklist() ==> my @baz;
1598 my @foo = @bar[@baz];
1599
1600 Various contexts may or may not be expecting multi-dimensional slices
9eb1b35 [S06] more @@ clobberation.
lwall authored
1601 or feeds. By default, ordinary arrays are flattened in slurpy context, that is, they
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1602 have "list" semantics. If you say
1603
63a0d61 @TimToady Remove notion of stacked feeds
TimToady authored
1604 zip(0..2; 'a'..'c') ==> my @tmp;
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1605 for @tmp { .say }
1606
45ca8c8 @patch fix typos
patch authored
1607 then you get 0,1,2,'a','b','c'. If you have a multidimensional array, you
9eb1b35 [S06] more @@ clobberation.
lwall authored
1608 can ask for flattening semantics explicitly with C<flat>:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1609
63a0d61 @TimToady Remove notion of stacked feeds
TimToady authored
1610 zip(0..2; 'a'..'c') ==> my $tmp;
9eb1b35 [S06] more @@ clobberation.
lwall authored
1611 for $tmp.flat { .say }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1612
1613 As we saw earlier, "zip" produces an interleaved result by taking one element
1614 from each list in turn, so
1615
63a0d61 @TimToady Remove notion of stacked feeds
TimToady authored
1616 zip(0..2; 'a'..'c') ==> my $tmp;
9eb1b35 [S06] more @@ clobberation.
lwall authored
1617 for $tmp.zip { .say }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1618
1619 produces 0,'a',1,'b',2,'c'.
1620
9eb1b35 [S06] more @@ clobberation.
lwall authored
1621 If you want the zip's result as a list of subarrays, then you need to put
b962f00 @TimToady refine tree contexts; slice context -> lol context
TimToady authored
1622 the zip itself into a "chunky" C<LoL> context instead:
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1623
63a0d61 @TimToady Remove notion of stacked feeds
TimToady authored
1624 zip(0..2; 'a'..'c') ==> my $tmp;
b962f00 @TimToady refine tree contexts; slice context -> lol context
TimToady authored
1625 for $tmp.zip.lol { .say }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1626
b962f00 @TimToady refine tree contexts; slice context -> lol context
TimToady authored
1627 This produces two values on each line. But usually you want the flat
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1628 form so you can just bind it directly to a signature:
1629
9eb1b35 [S06] more @@ clobberation.
lwall authored
1630 for $tmp.zip -> $i, $a { say "$i: $a" }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1631
1632 Otherwise you'd have to say this:
1633
b962f00 @TimToady refine tree contexts; slice context -> lol context
TimToady authored
1634 for $tmp.zip.lol -> [$i, $a] { say "$i: $a" }
9eb1b35 [S06] more @@ clobberation.
lwall authored
1635
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1636 Note that with the current definition, the order of feeds is preserved
1637 left to right in general regardless of the position of the receiver.
1638
1639 So
1640
9eb1b35 [S06] more @@ clobberation.
lwall authored
1641 ('a'..*; 0..*) ==> $feed;
1642 for $feed.zip <== @foo) -> $a, $i, $x { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1643
1644 is the same as
1645
9eb1b35 [S06] more @@ clobberation.
lwall authored
1646 'a'..* ==> $feed;
1647 0..* ==>> $feed;
1648 for $feed.zip <== @foo) -> $a, $i, $x { ... }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1649
1650 which is the same as
1651
1652 for zip('a'..*; 0..*; @foo) -> $a, $i, $x { ... }
1653
1654 Also note that these come out to be identical for ordinary arrays:
1655
1656 @foo.zip
1657 @foo.cat
1658
1659 =head2 Closure parameters
1660
1661 Parameters declared with the C<&> sigil take blocks, closures, or
1662 subroutines as their arguments. Closure parameters can be required,
1663 optional, named, or slurpy.
1664
1665 sub limited_grep (Int $count, &block, *@list) {...}
1666
1667 # and later...
1668
1669 @first_three = limited_grep 3, {$_<10}, @data;
1670
1671 (The comma is required after the closure.)
1672
1673 Within the subroutine, the closure parameter can be used like any other
1674 lexically scoped subroutine:
1675
1676 sub limited_grep (Int $count, &block, *@list) {
1677 ...
1678 if block($nextelem) {...}
1679 ...
1680 }
1681
1682 The closure parameter can have its own signature in a type specification written
1683 with C<:(...)>:
1684
1685 sub limited_Dog_grep ($count, &block:(Dog), Dog *@list) {...}
1686
1687 and even a return type:
1688
1689 sub limited_Dog_grep ($count, &block:(Dog --> Bool), Dog *@list) {...}
1690
1691 When an argument is passed to a closure parameter that has this kind of
1692 signature, the argument must be a C<Code> object with a compatible
1693 parameter list and return type.
1694
55a537b [S06]
lwall authored
1695 =head2 En passant type capture
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1696
1697 Unlike normal parameters, type parameters often come in piggybacked
1698 on the actual value as "kind", and you'd like a way to capture both
55a537b [S06]
lwall authored
1699 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
1700 an object is allowed to be. An object is not officially allowed
1701 to take on a constrained or contravariant type.) A type variable
1702 can be used anywhere a type name can, but instead of asserting that
1703 the value must conform to a particular type, it captures the
1704 actual "kind" of the object and also declares a package/type name
1705 by which you can refer to that kind later in the signature or body.
55a537b [S06]
lwall authored
1706 In addition, it captures the nominal typing of any associated nominal
1707 type.
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1708 For instance, if you wanted to match any two Dogs as long as they
1709 were of the same kind, you can say:
1710
1711 sub matchedset (Dog ::T $fido, T $spot) {...}
1712
55a537b [S06]
lwall authored
1713 This actually turns into something more like
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1714
55a537b [S06]
lwall authored
1715 sub matchedset (Dog ::T $fido, Dog $spot where T) {...}
1716
1717 Note that C<::T> is not required to contain C<Dog>, only
1718 a type that is compatible with C<Dog>. Note also that the nominal
1719 type, C<Dog>, is also included in the meaning of C<T>, along
1720 with the notion that the actual type must match the storage
1721 type of C<$fido>.
1722
1723 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
1724 short for "sub". Just as C<&> can be used to name any kind of code,
1725 so too C<::> can be used to name any kind of type. Both of them insert
1726 a bare identifier into the symbol table, though they fill different syntactic
1727 spots.
1728
1729 Note that it is not required to capture the object associated with the
1730 class unless you want it. The sub above could be written as
1731
1732 sub matchedset (Dog ::T, T) {...}
1733
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
1734 if we're not interested in C<$fido> or C<$spot>. Or just
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1735
1736 sub matchedset (::T, T) {...}
1737
55a537b [S06]
lwall authored
1738 if we don't care about anything but the matching. Note here that
1739 the second parameter may be more derived than the first. If you
1740 need them to be identical, you must say something like
1741
1742 sub matchedset (::T, $ where { $_.WHAT === T }
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1743
1744 =head2 Unpacking array parameters
1745
1746 Instead of specifying an array parameter as an array:
1747
1748 sub quicksort (@data, $reverse?, $inplace?) {
1749 my $pivot := shift @data;
1750 ...
1751 }
1752
1753 it may be broken up into components in the signature, by
1754 specifying the parameter as if it were an anonymous array of
1755 parameters:
1756
1757 sub quicksort ([$pivot, *@data], $reverse?, $inplace?) {
1758 ...
1759 }
1760
1761 This subroutine still expects an array as its first argument, just like
1762 the first version.
1763
1764 =head2 Unpacking a single list argument
1765
1766 To match the first element of the slurpy list, use a "slurpy" scalar:
1767
1768 sub quicksort (:$reverse, :$inplace, *$pivot, *@data)
1769
1770 =head2 Unpacking tree node parameters
1771
1772 You can unpack hash values and tree nodes in various dwimmy ways by enclosing the bindings
1773 of child nodes and attributes in parentheses following the declaration of
1774 the node itself:
1775
1776 sub traverse ( BinTree $top ( $left, $right ) ) {
1777 traverse($left);
1778 traverse($right);
1779 }
1780
1781 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 Callab…
jdlugosz authored
1782 and right nodes of the tree. If C<$top> is an ordinary object, it binds
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1783 the C<$top.left> and C<$top.right> attributes. If it's a hash,
1784 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 Callab…
jdlugosz authored
1785 signature type and $top is a C<Capture> (argument list) object, the child types
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1786 of the signature are applied to the actual arguments in the argument
1787 list object. (Signature types have the benefit that you can view
1788 them inside-out as constructors with positional arguments, such that
1789 the transformations can be reversible.)
1790
1791 However, the full power of signatures can be applied to pattern match
1792 just about any argument or set of arguments, even though in some cases
1793 the reverse transformation is not derivable. For instance, to bind to
1794 an array of children named C<.kids> or C<< .<kids> >>, use something
1795 like:
1796
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
1797 proto traverse ($) {*}
16b8335 [Spec] undelete some accidentally deleted history
lwall authored
1798 multi traverse ( NAry $top ( :kids [$eldest, *@siblings] ) ) {
1799 traverse($eldest);
1800 traverse(:kids(@siblings)); # (binds @siblings to $top)
1801 }
1802 multi traverse ( $leaf ) {...}
1803
1804 The second candidate is called only if the parameter cannot be bound to
038dc96