Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
3 | perlsub - Perl subroutines |
4 | |
5 | =head1 SYNOPSIS |
6 | |
7 | To declare subroutines: |
8 | |
cb1a09d0 |
9 | sub NAME; # A "forward" declaration. |
10 | sub NAME(PROTO); # ditto, but with prototypes |
11 | |
12 | sub NAME BLOCK # A declaration and a definition. |
13 | sub NAME(PROTO) BLOCK # ditto, but with prototypes |
a0d0e21e |
14 | |
748a9306 |
15 | To define an anonymous subroutine at runtime: |
16 | |
17 | $subref = sub BLOCK; |
18 | |
a0d0e21e |
19 | To import subroutines: |
20 | |
21 | use PACKAGE qw(NAME1 NAME2 NAME3); |
22 | |
23 | To call subroutines: |
24 | |
5f05dabc |
25 | NAME(LIST); # & is optional with parentheses. |
54310121 |
26 | NAME LIST; # Parentheses optional if predeclared/imported. |
cb1a09d0 |
27 | &NAME; # Passes current @_ to subroutine. |
a0d0e21e |
28 | |
29 | =head1 DESCRIPTION |
30 | |
cb1a09d0 |
31 | Like many languages, Perl provides for user-defined subroutines. These |
32 | may be located anywhere in the main program, loaded in from other files |
33 | via the C<do>, C<require>, or C<use> keywords, or even generated on the |
34 | fly using C<eval> or anonymous subroutines (closures). You can even call |
c07a80fd |
35 | a function indirectly using a variable containing its name or a CODE reference |
36 | to it, as in C<$var = \&function>. |
cb1a09d0 |
37 | |
38 | The Perl model for function call and return values is simple: all |
39 | functions are passed as parameters one single flat list of scalars, and |
40 | all functions likewise return to their caller one single flat list of |
41 | scalars. Any arrays or hashes in these call and return lists will |
42 | collapse, losing their identities--but you may always use |
43 | pass-by-reference instead to avoid this. Both call and return lists may |
44 | contain as many or as few scalar elements as you'd like. (Often a |
45 | function without an explicit return statement is called a subroutine, but |
46 | there's really no difference from the language's perspective.) |
47 | |
48 | Any arguments passed to the routine come in as the array @_. Thus if you |
49 | called a function with two arguments, those would be stored in C<$_[0]> |
3fe9a6f1 |
50 | and C<$_[1]>. The array @_ is a local array, but its elements are |
51 | aliases for the actual scalar parameters. In particular, if an element |
52 | C<$_[0]> is updated, the corresponding argument is updated (or an error |
53 | occurs if it is not updatable). If an argument is an array or hash |
54 | element which did not exist when the function was called, that element is |
55 | created only when (and if) it is modified or if a reference to it is |
56 | taken. (Some earlier versions of Perl created the element whether or not |
57 | it was assigned to.) Note that assigning to the whole array @_ removes |
58 | the aliasing, and does not update any arguments. |
59 | |
60 | The return value of the subroutine is the value of the last expression |
54310121 |
61 | evaluated. Alternatively, a return statement may be used exit the |
62 | subroutine, optionally specifying the returned value, which will be |
63 | evaluated in the appropriate context (list, scalar, or void) depending |
64 | on the context of the subroutine call. If you specify no return value, |
65 | the subroutine will return an empty list in a list context, an undefined |
66 | value in a scalar context, or nothing in a void context. If you return |
67 | one or more arrays and/or hashes, these will be flattened together into |
68 | one large indistinguishable list. |
cb1a09d0 |
69 | |
70 | Perl does not have named formal parameters, but in practice all you do is |
71 | assign to a my() list of these. Any variables you use in the function |
72 | that aren't declared private are global variables. For the gory details |
1fef88e7 |
73 | on creating private variables, see |
6d28dffb |
74 | L<"Private Variables via my()"> and L<"Temporary Values via local()">. |
75 | To create protected environments for a set of functions in a separate |
76 | package (and probably a separate file), see L<perlmod/"Packages">. |
a0d0e21e |
77 | |
78 | Example: |
79 | |
cb1a09d0 |
80 | sub max { |
81 | my $max = shift(@_); |
a0d0e21e |
82 | foreach $foo (@_) { |
83 | $max = $foo if $max < $foo; |
84 | } |
cb1a09d0 |
85 | return $max; |
a0d0e21e |
86 | } |
cb1a09d0 |
87 | $bestday = max($mon,$tue,$wed,$thu,$fri); |
a0d0e21e |
88 | |
89 | Example: |
90 | |
91 | # get a line, combining continuation lines |
92 | # that start with whitespace |
93 | |
94 | sub get_line { |
cb1a09d0 |
95 | $thisline = $lookahead; # GLOBAL VARIABLES!! |
54310121 |
96 | LINE: while (defined($lookahead = <STDIN>)) { |
a0d0e21e |
97 | if ($lookahead =~ /^[ \t]/) { |
98 | $thisline .= $lookahead; |
99 | } |
100 | else { |
101 | last LINE; |
102 | } |
103 | } |
104 | $thisline; |
105 | } |
106 | |
107 | $lookahead = <STDIN>; # get first line |
108 | while ($_ = get_line()) { |
109 | ... |
110 | } |
111 | |
112 | Use array assignment to a local list to name your formal arguments: |
113 | |
114 | sub maybeset { |
115 | my($key, $value) = @_; |
cb1a09d0 |
116 | $Foo{$key} = $value unless $Foo{$key}; |
a0d0e21e |
117 | } |
118 | |
cb1a09d0 |
119 | This also has the effect of turning call-by-reference into call-by-value, |
5f05dabc |
120 | because the assignment copies the values. Otherwise a function is free to |
1fef88e7 |
121 | do in-place modifications of @_ and change its caller's values. |
cb1a09d0 |
122 | |
123 | upcase_in($v1, $v2); # this changes $v1 and $v2 |
124 | sub upcase_in { |
54310121 |
125 | for (@_) { tr/a-z/A-Z/ } |
126 | } |
cb1a09d0 |
127 | |
128 | You aren't allowed to modify constants in this way, of course. If an |
129 | argument were actually literal and you tried to change it, you'd take a |
130 | (presumably fatal) exception. For example, this won't work: |
131 | |
132 | upcase_in("frederick"); |
133 | |
54310121 |
134 | It would be much safer if the upcase_in() function |
cb1a09d0 |
135 | were written to return a copy of its parameters instead |
136 | of changing them in place: |
137 | |
138 | ($v3, $v4) = upcase($v1, $v2); # this doesn't |
139 | sub upcase { |
54310121 |
140 | return unless defined wantarray; # void context, do nothing |
cb1a09d0 |
141 | my @parms = @_; |
54310121 |
142 | for (@parms) { tr/a-z/A-Z/ } |
c07a80fd |
143 | return wantarray ? @parms : $parms[0]; |
54310121 |
144 | } |
cb1a09d0 |
145 | |
146 | Notice how this (unprototyped) function doesn't care whether it was passed |
147 | real scalars or arrays. Perl will see everything as one big long flat @_ |
148 | parameter list. This is one of the ways where Perl's simple |
149 | argument-passing style shines. The upcase() function would work perfectly |
150 | well without changing the upcase() definition even if we fed it things |
151 | like this: |
152 | |
153 | @newlist = upcase(@list1, @list2); |
154 | @newlist = upcase( split /:/, $var ); |
155 | |
156 | Do not, however, be tempted to do this: |
157 | |
158 | (@a, @b) = upcase(@list1, @list2); |
159 | |
160 | Because like its flat incoming parameter list, the return list is also |
161 | flat. So all you have managed to do here is stored everything in @a and |
162 | made @b an empty list. See L</"Pass by Reference"> for alternatives. |
163 | |
5f05dabc |
164 | A subroutine may be called using the "&" prefix. The "&" is optional |
165 | in modern Perls, and so are the parentheses if the subroutine has been |
54310121 |
166 | predeclared. (Note, however, that the "&" is I<NOT> optional when |
5f05dabc |
167 | you're just naming the subroutine, such as when it's used as an |
168 | argument to defined() or undef(). Nor is it optional when you want to |
169 | do an indirect subroutine call with a subroutine name or reference |
170 | using the C<&$subref()> or C<&{$subref}()> constructs. See L<perlref> |
171 | for more on that.) |
a0d0e21e |
172 | |
173 | Subroutines may be called recursively. If a subroutine is called using |
cb1a09d0 |
174 | the "&" form, the argument list is optional, and if omitted, no @_ array is |
175 | set up for the subroutine: the @_ array at the time of the call is |
176 | visible to subroutine instead. This is an efficiency mechanism that |
177 | new users may wish to avoid. |
a0d0e21e |
178 | |
179 | &foo(1,2,3); # pass three arguments |
180 | foo(1,2,3); # the same |
181 | |
182 | foo(); # pass a null list |
183 | &foo(); # the same |
a0d0e21e |
184 | |
cb1a09d0 |
185 | &foo; # foo() get current args, like foo(@_) !! |
54310121 |
186 | foo; # like foo() IFF sub foo predeclared, else "foo" |
cb1a09d0 |
187 | |
c07a80fd |
188 | Not only does the "&" form make the argument list optional, but it also |
189 | disables any prototype checking on the arguments you do provide. This |
190 | is partly for historical reasons, and partly for having a convenient way |
191 | to cheat if you know what you're doing. See the section on Prototypes below. |
192 | |
cb1a09d0 |
193 | =head2 Private Variables via my() |
194 | |
195 | Synopsis: |
196 | |
197 | my $foo; # declare $foo lexically local |
198 | my (@wid, %get); # declare list of variables local |
199 | my $foo = "flurp"; # declare $foo lexical, and init it |
200 | my @oof = @bar; # declare @oof lexical, and init it |
201 | |
202 | A "my" declares the listed variables to be confined (lexically) to the |
55497cff |
203 | enclosing block, conditional (C<if/unless/elsif/else>), loop |
204 | (C<for/foreach/while/until/continue>), subroutine, C<eval>, or |
205 | C<do/require/use>'d file. If more than one value is listed, the list |
5f05dabc |
206 | must be placed in parentheses. All listed elements must be legal lvalues. |
55497cff |
207 | Only alphanumeric identifiers may be lexically scoped--magical |
208 | builtins like $/ must currently be localized with "local" instead. |
cb1a09d0 |
209 | |
210 | Unlike dynamic variables created by the "local" statement, lexical |
211 | variables declared with "my" are totally hidden from the outside world, |
212 | including any called subroutines (even if it's the same subroutine called |
213 | from itself or elsewhere--every call gets its own copy). |
214 | |
215 | (An eval(), however, can see the lexical variables of the scope it is |
216 | being evaluated in so long as the names aren't hidden by declarations within |
217 | the eval() itself. See L<perlref>.) |
218 | |
219 | The parameter list to my() may be assigned to if desired, which allows you |
220 | to initialize your variables. (If no initializer is given for a |
221 | particular variable, it is created with the undefined value.) Commonly |
222 | this is used to name the parameters to a subroutine. Examples: |
223 | |
224 | $arg = "fred"; # "global" variable |
225 | $n = cube_root(27); |
226 | print "$arg thinks the root is $n\n"; |
227 | fred thinks the root is 3 |
228 | |
229 | sub cube_root { |
230 | my $arg = shift; # name doesn't matter |
231 | $arg **= 1/3; |
232 | return $arg; |
54310121 |
233 | } |
cb1a09d0 |
234 | |
235 | The "my" is simply a modifier on something you might assign to. So when |
236 | you do assign to the variables in its argument list, the "my" doesn't |
237 | change whether those variables is viewed as a scalar or an array. So |
238 | |
239 | my ($foo) = <STDIN>; |
240 | my @FOO = <STDIN>; |
241 | |
5f05dabc |
242 | both supply a list context to the right-hand side, while |
cb1a09d0 |
243 | |
244 | my $foo = <STDIN>; |
245 | |
5f05dabc |
246 | supplies a scalar context. But the following declares only one variable: |
748a9306 |
247 | |
cb1a09d0 |
248 | my $foo, $bar = 1; |
748a9306 |
249 | |
cb1a09d0 |
250 | That has the same effect as |
748a9306 |
251 | |
cb1a09d0 |
252 | my $foo; |
253 | $bar = 1; |
a0d0e21e |
254 | |
cb1a09d0 |
255 | The declared variable is not introduced (is not visible) until after |
256 | the current statement. Thus, |
257 | |
258 | my $x = $x; |
259 | |
54310121 |
260 | can be used to initialize the new $x with the value of the old $x, and |
cb1a09d0 |
261 | the expression |
262 | |
263 | my $x = 123 and $x == 123 |
264 | |
265 | is false unless the old $x happened to have the value 123. |
266 | |
55497cff |
267 | Lexical scopes of control structures are not bounded precisely by the |
268 | braces that delimit their controlled blocks; control expressions are |
269 | part of the scope, too. Thus in the loop |
270 | |
54310121 |
271 | while (defined(my $line = <>)) { |
55497cff |
272 | $line = lc $line; |
273 | } continue { |
274 | print $line; |
275 | } |
276 | |
277 | the scope of $line extends from its declaration throughout the rest of |
278 | the loop construct (including the C<continue> clause), but not beyond |
279 | it. Similarly, in the conditional |
280 | |
281 | if ((my $answer = <STDIN>) =~ /^yes$/i) { |
282 | user_agrees(); |
283 | } elsif ($answer =~ /^no$/i) { |
284 | user_disagrees(); |
285 | } else { |
286 | chomp $answer; |
287 | die "'$answer' is neither 'yes' nor 'no'"; |
288 | } |
289 | |
290 | the scope of $answer extends from its declaration throughout the rest |
291 | of the conditional (including C<elsif> and C<else> clauses, if any), |
292 | but not beyond it. |
293 | |
294 | (None of the foregoing applies to C<if/unless> or C<while/until> |
295 | modifiers appended to simple statements. Such modifiers are not |
296 | control structures and have no effect on scoping.) |
297 | |
5f05dabc |
298 | The C<foreach> loop defaults to scoping its index variable dynamically |
55497cff |
299 | (in the manner of C<local>; see below). However, if the index |
300 | variable is prefixed with the keyword "my", then it is lexically |
301 | scoped instead. Thus in the loop |
302 | |
303 | for my $i (1, 2, 3) { |
304 | some_function(); |
305 | } |
306 | |
307 | the scope of $i extends to the end of the loop, but not beyond it, and |
308 | so the value of $i is unavailable in some_function(). |
309 | |
cb1a09d0 |
310 | Some users may wish to encourage the use of lexically scoped variables. |
311 | As an aid to catching implicit references to package variables, |
312 | if you say |
313 | |
314 | use strict 'vars'; |
315 | |
316 | then any variable reference from there to the end of the enclosing |
317 | block must either refer to a lexical variable, or must be fully |
318 | qualified with the package name. A compilation error results |
319 | otherwise. An inner block may countermand this with S<"no strict 'vars'">. |
320 | |
321 | A my() has both a compile-time and a run-time effect. At compile time, |
322 | the compiler takes notice of it; the principle usefulness of this is to |
323 | quiet C<use strict 'vars'>. The actual initialization doesn't happen |
324 | until run time, so gets executed every time through a loop. |
325 | |
326 | Variables declared with "my" are not part of any package and are therefore |
327 | never fully qualified with the package name. In particular, you're not |
328 | allowed to try to make a package variable (or other global) lexical: |
329 | |
330 | my $pack::var; # ERROR! Illegal syntax |
331 | my $_; # also illegal (currently) |
332 | |
333 | In fact, a dynamic variable (also known as package or global variables) |
334 | are still accessible using the fully qualified :: notation even while a |
335 | lexical of the same name is also visible: |
336 | |
337 | package main; |
338 | local $x = 10; |
339 | my $x = 20; |
340 | print "$x and $::x\n"; |
341 | |
342 | That will print out 20 and 10. |
343 | |
5f05dabc |
344 | You may declare "my" variables at the outermost scope of a file to |
345 | hide any such identifiers totally from the outside world. This is similar |
6d28dffb |
346 | to C's static variables at the file level. To do this with a subroutine |
cb1a09d0 |
347 | requires the use of a closure (anonymous function). If a block (such as |
348 | an eval(), function, or C<package>) wants to create a private subroutine |
349 | that cannot be called from outside that block, it can declare a lexical |
350 | variable containing an anonymous sub reference: |
351 | |
352 | my $secret_version = '1.001-beta'; |
353 | my $secret_sub = sub { print $secret_version }; |
354 | &$secret_sub(); |
355 | |
356 | As long as the reference is never returned by any function within the |
5f05dabc |
357 | module, no outside module can see the subroutine, because its name is not in |
cb1a09d0 |
358 | any package's symbol table. Remember that it's not I<REALLY> called |
359 | $some_pack::secret_version or anything; it's just $secret_version, |
360 | unqualified and unqualifiable. |
361 | |
362 | This does not work with object methods, however; all object methods have |
363 | to be in the symbol table of some package to be found. |
364 | |
365 | Just because the lexical variable is lexically (also called statically) |
366 | scoped doesn't mean that within a function it works like a C static. It |
367 | normally works more like a C auto. But here's a mechanism for giving a |
368 | function private variables with both lexical scoping and a static |
369 | lifetime. If you do want to create something like C's static variables, |
370 | just enclose the whole function in an extra block, and put the |
371 | static variable outside the function but in the block. |
372 | |
373 | { |
54310121 |
374 | my $secret_val = 0; |
cb1a09d0 |
375 | sub gimme_another { |
376 | return ++$secret_val; |
54310121 |
377 | } |
378 | } |
cb1a09d0 |
379 | # $secret_val now becomes unreachable by the outside |
380 | # world, but retains its value between calls to gimme_another |
381 | |
54310121 |
382 | If this function is being sourced in from a separate file |
cb1a09d0 |
383 | via C<require> or C<use>, then this is probably just fine. If it's |
54310121 |
384 | all in the main program, you'll need to arrange for the my() |
cb1a09d0 |
385 | to be executed early, either by putting the whole block above |
54310121 |
386 | your pain program, or more likely, placing merely a BEGIN |
cb1a09d0 |
387 | sub around it to make sure it gets executed before your program |
388 | starts to run: |
389 | |
390 | sub BEGIN { |
54310121 |
391 | my $secret_val = 0; |
cb1a09d0 |
392 | sub gimme_another { |
393 | return ++$secret_val; |
54310121 |
394 | } |
395 | } |
cb1a09d0 |
396 | |
397 | See L<perlrun> about the BEGIN function. |
398 | |
399 | =head2 Temporary Values via local() |
400 | |
401 | B<NOTE>: In general, you should be using "my" instead of "local", because |
6d28dffb |
402 | it's faster and safer. Exceptions to this include the global punctuation |
cb1a09d0 |
403 | variables, filehandles and formats, and direct manipulation of the Perl |
404 | symbol table itself. Format variables often use "local" though, as do |
405 | other variables whose current value must be visible to called |
406 | subroutines. |
407 | |
408 | Synopsis: |
409 | |
410 | local $foo; # declare $foo dynamically local |
411 | local (@wid, %get); # declare list of variables local |
412 | local $foo = "flurp"; # declare $foo dynamic, and init it |
413 | local @oof = @bar; # declare @oof dynamic, and init it |
414 | |
415 | local *FH; # localize $FH, @FH, %FH, &FH ... |
416 | local *merlyn = *randal; # now $merlyn is really $randal, plus |
417 | # @merlyn is really @randal, etc |
418 | local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal |
54310121 |
419 | local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc |
cb1a09d0 |
420 | |
421 | A local() modifies its listed variables to be local to the enclosing |
5f05dabc |
422 | block, (or subroutine, C<eval{}>, or C<do>) and I<any called from |
cb1a09d0 |
423 | within that block>. A local() just gives temporary values to global |
424 | (meaning package) variables. This is known as dynamic scoping. Lexical |
425 | scoping is done with "my", which works more like C's auto declarations. |
426 | |
427 | If more than one variable is given to local(), they must be placed in |
5f05dabc |
428 | parentheses. All listed elements must be legal lvalues. This operator works |
cb1a09d0 |
429 | by saving the current values of those variables in its argument list on a |
5f05dabc |
430 | hidden stack and restoring them upon exiting the block, subroutine, or |
cb1a09d0 |
431 | eval. This means that called subroutines can also reference the local |
432 | variable, but not the global one. The argument list may be assigned to if |
433 | desired, which allows you to initialize your local variables. (If no |
434 | initializer is given for a particular variable, it is created with an |
435 | undefined value.) Commonly this is used to name the parameters to a |
436 | subroutine. Examples: |
437 | |
438 | for $i ( 0 .. 9 ) { |
439 | $digits{$i} = $i; |
54310121 |
440 | } |
cb1a09d0 |
441 | # assume this function uses global %digits hash |
54310121 |
442 | parse_num(); |
cb1a09d0 |
443 | |
444 | # now temporarily add to %digits hash |
445 | if ($base12) { |
446 | # (NOTE: not claiming this is efficient!) |
447 | local %digits = (%digits, 't' => 10, 'e' => 11); |
448 | parse_num(); # parse_num gets this new %digits! |
449 | } |
450 | # old %digits restored here |
451 | |
1fef88e7 |
452 | Because local() is a run-time command, it gets executed every time |
cb1a09d0 |
453 | through a loop. In releases of Perl previous to 5.0, this used more stack |
454 | storage each time until the loop was exited. Perl now reclaims the space |
455 | each time through, but it's still more efficient to declare your variables |
456 | outside the loop. |
457 | |
458 | A local is simply a modifier on an lvalue expression. When you assign to |
459 | a localized variable, the local doesn't change whether its list is viewed |
460 | as a scalar or an array. So |
461 | |
462 | local($foo) = <STDIN>; |
463 | local @FOO = <STDIN>; |
464 | |
5f05dabc |
465 | both supply a list context to the right-hand side, while |
cb1a09d0 |
466 | |
467 | local $foo = <STDIN>; |
468 | |
469 | supplies a scalar context. |
470 | |
471 | =head2 Passing Symbol Table Entries (typeglobs) |
472 | |
473 | [Note: The mechanism described in this section was originally the only |
474 | way to simulate pass-by-reference in older versions of Perl. While it |
475 | still works fine in modern versions, the new reference mechanism is |
476 | generally easier to work with. See below.] |
a0d0e21e |
477 | |
478 | Sometimes you don't want to pass the value of an array to a subroutine |
479 | but rather the name of it, so that the subroutine can modify the global |
480 | copy of it rather than working with a local copy. In perl you can |
cb1a09d0 |
481 | refer to all objects of a particular name by prefixing the name |
5f05dabc |
482 | with a star: C<*foo>. This is often known as a "typeglob", because the |
a0d0e21e |
483 | star on the front can be thought of as a wildcard match for all the |
484 | funny prefix characters on variables and subroutines and such. |
485 | |
55497cff |
486 | When evaluated, the typeglob produces a scalar value that represents |
5f05dabc |
487 | all the objects of that name, including any filehandle, format, or |
a0d0e21e |
488 | subroutine. When assigned to, it causes the name mentioned to refer to |
489 | whatever "*" value was assigned to it. Example: |
490 | |
491 | sub doubleary { |
492 | local(*someary) = @_; |
493 | foreach $elem (@someary) { |
494 | $elem *= 2; |
495 | } |
496 | } |
497 | doubleary(*foo); |
498 | doubleary(*bar); |
499 | |
500 | Note that scalars are already passed by reference, so you can modify |
501 | scalar arguments without using this mechanism by referring explicitly |
1fef88e7 |
502 | to C<$_[0]> etc. You can modify all the elements of an array by passing |
a0d0e21e |
503 | all the elements as scalars, but you have to use the * mechanism (or |
5f05dabc |
504 | the equivalent reference mechanism) to push, pop, or change the size of |
a0d0e21e |
505 | an array. It will certainly be faster to pass the typeglob (or reference). |
506 | |
507 | Even if you don't want to modify an array, this mechanism is useful for |
5f05dabc |
508 | passing multiple arrays in a single LIST, because normally the LIST |
a0d0e21e |
509 | mechanism will merge all the array values so that you can't extract out |
55497cff |
510 | the individual arrays. For more on typeglobs, see |
2ae324a7 |
511 | L<perldata/"Typeglobs and Filehandles">. |
cb1a09d0 |
512 | |
513 | =head2 Pass by Reference |
514 | |
55497cff |
515 | If you want to pass more than one array or hash into a function--or |
516 | return them from it--and have them maintain their integrity, then |
517 | you're going to have to use an explicit pass-by-reference. Before you |
518 | do that, you need to understand references as detailed in L<perlref>. |
c07a80fd |
519 | This section may not make much sense to you otherwise. |
cb1a09d0 |
520 | |
521 | Here are a few simple examples. First, let's pass in several |
522 | arrays to a function and have it pop all of then, return a new |
523 | list of all their former last elements: |
524 | |
525 | @tailings = popmany ( \@a, \@b, \@c, \@d ); |
526 | |
527 | sub popmany { |
528 | my $aref; |
529 | my @retlist = (); |
530 | foreach $aref ( @_ ) { |
531 | push @retlist, pop @$aref; |
54310121 |
532 | } |
cb1a09d0 |
533 | return @retlist; |
54310121 |
534 | } |
cb1a09d0 |
535 | |
54310121 |
536 | Here's how you might write a function that returns a |
cb1a09d0 |
537 | list of keys occurring in all the hashes passed to it: |
538 | |
54310121 |
539 | @common = inter( \%foo, \%bar, \%joe ); |
cb1a09d0 |
540 | sub inter { |
541 | my ($k, $href, %seen); # locals |
542 | foreach $href (@_) { |
543 | while ( $k = each %$href ) { |
544 | $seen{$k}++; |
54310121 |
545 | } |
546 | } |
cb1a09d0 |
547 | return grep { $seen{$_} == @_ } keys %seen; |
54310121 |
548 | } |
cb1a09d0 |
549 | |
5f05dabc |
550 | So far, we're using just the normal list return mechanism. |
54310121 |
551 | What happens if you want to pass or return a hash? Well, |
552 | if you're using only one of them, or you don't mind them |
cb1a09d0 |
553 | concatenating, then the normal calling convention is ok, although |
54310121 |
554 | a little expensive. |
cb1a09d0 |
555 | |
556 | Where people get into trouble is here: |
557 | |
558 | (@a, @b) = func(@c, @d); |
559 | or |
560 | (%a, %b) = func(%c, %d); |
561 | |
5f05dabc |
562 | That syntax simply won't work. It sets just @a or %a and clears the @b or |
cb1a09d0 |
563 | %b. Plus the function didn't get passed into two separate arrays or |
564 | hashes: it got one long list in @_, as always. |
565 | |
566 | If you can arrange for everyone to deal with this through references, it's |
567 | cleaner code, although not so nice to look at. Here's a function that |
568 | takes two array references as arguments, returning the two array elements |
569 | in order of how many elements they have in them: |
570 | |
571 | ($aref, $bref) = func(\@c, \@d); |
572 | print "@$aref has more than @$bref\n"; |
573 | sub func { |
574 | my ($cref, $dref) = @_; |
575 | if (@$cref > @$dref) { |
576 | return ($cref, $dref); |
577 | } else { |
c07a80fd |
578 | return ($dref, $cref); |
54310121 |
579 | } |
580 | } |
cb1a09d0 |
581 | |
582 | It turns out that you can actually do this also: |
583 | |
584 | (*a, *b) = func(\@c, \@d); |
585 | print "@a has more than @b\n"; |
586 | sub func { |
587 | local (*c, *d) = @_; |
588 | if (@c > @d) { |
589 | return (\@c, \@d); |
590 | } else { |
591 | return (\@d, \@c); |
54310121 |
592 | } |
593 | } |
cb1a09d0 |
594 | |
595 | Here we're using the typeglobs to do symbol table aliasing. It's |
596 | a tad subtle, though, and also won't work if you're using my() |
5f05dabc |
597 | variables, because only globals (well, and local()s) are in the symbol table. |
598 | |
599 | If you're passing around filehandles, you could usually just use the bare |
600 | typeglob, like *STDOUT, but typeglobs references would be better because |
601 | they'll still work properly under C<use strict 'refs'>. For example: |
602 | |
603 | splutter(\*STDOUT); |
604 | sub splutter { |
605 | my $fh = shift; |
606 | print $fh "her um well a hmmm\n"; |
607 | } |
608 | |
609 | $rec = get_rec(\*STDIN); |
610 | sub get_rec { |
611 | my $fh = shift; |
612 | return scalar <$fh>; |
613 | } |
614 | |
615 | Another way to do this is using *HANDLE{IO}, see L<perlref> for usage |
616 | and caveats. |
617 | |
618 | If you're planning on generating new filehandles, you could do this: |
619 | |
620 | sub openit { |
621 | my $name = shift; |
622 | local *FH; |
e05a3a1e |
623 | return open (FH, $path) ? *FH : undef; |
54310121 |
624 | } |
5f05dabc |
625 | |
626 | Although that will actually produce a small memory leak. See the bottom |
627 | of L<perlfunc/open()> for a somewhat cleaner way using the IO::Handle |
628 | package. |
cb1a09d0 |
629 | |
cb1a09d0 |
630 | =head2 Prototypes |
631 | |
632 | As of the 5.002 release of perl, if you declare |
633 | |
634 | sub mypush (\@@) |
635 | |
c07a80fd |
636 | then mypush() takes arguments exactly like push() does. The declaration |
637 | of the function to be called must be visible at compile time. The prototype |
5f05dabc |
638 | affects only the interpretation of new-style calls to the function, where |
c07a80fd |
639 | new-style is defined as not using the C<&> character. In other words, |
640 | if you call it like a builtin function, then it behaves like a builtin |
641 | function. If you call it like an old-fashioned subroutine, then it |
642 | behaves like an old-fashioned subroutine. It naturally falls out from |
643 | this rule that prototypes have no influence on subroutine references |
644 | like C<\&foo> or on indirect subroutine calls like C<&{$subref}>. |
645 | |
646 | Method calls are not influenced by prototypes either, because the |
5f05dabc |
647 | function to be called is indeterminate at compile time, because it depends |
c07a80fd |
648 | on inheritance. |
cb1a09d0 |
649 | |
5f05dabc |
650 | Because the intent is primarily to let you define subroutines that work |
c07a80fd |
651 | like builtin commands, here are the prototypes for some other functions |
652 | that parse almost exactly like the corresponding builtins. |
cb1a09d0 |
653 | |
654 | Declared as Called as |
655 | |
656 | sub mylink ($$) mylink $old, $new |
657 | sub myvec ($$$) myvec $var, $offset, 1 |
658 | sub myindex ($$;$) myindex &getstring, "substr" |
659 | sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off |
660 | sub myreverse (@) myreverse $a,$b,$c |
661 | sub myjoin ($@) myjoin ":",$a,$b,$c |
662 | sub mypop (\@) mypop @array |
663 | sub mysplice (\@$$@) mysplice @array,@array,0,@pushme |
664 | sub mykeys (\%) mykeys %{$hashref} |
665 | sub myopen (*;$) myopen HANDLE, $name |
666 | sub mypipe (**) mypipe READHANDLE, WRITEHANDLE |
667 | sub mygrep (&@) mygrep { /foo/ } $a,$b,$c |
668 | sub myrand ($) myrand 42 |
669 | sub mytime () mytime |
670 | |
c07a80fd |
671 | Any backslashed prototype character represents an actual argument |
6e47f808 |
672 | that absolutely must start with that character. The value passed |
673 | to the subroutine (as part of C<@_>) will be a reference to the |
674 | actual argument given in the subroutine call, obtained by applying |
675 | C<\> to that argument. |
c07a80fd |
676 | |
677 | Unbackslashed prototype characters have special meanings. Any |
678 | unbackslashed @ or % eats all the rest of the arguments, and forces |
679 | list context. An argument represented by $ forces scalar context. An |
680 | & requires an anonymous subroutine, which, if passed as the first |
681 | argument, does not require the "sub" keyword or a subsequent comma. A |
682 | * does whatever it has to do to turn the argument into a reference to a |
683 | symbol table entry. |
684 | |
685 | A semicolon separates mandatory arguments from optional arguments. |
686 | (It is redundant before @ or %.) |
cb1a09d0 |
687 | |
c07a80fd |
688 | Note how the last three examples above are treated specially by the parser. |
cb1a09d0 |
689 | mygrep() is parsed as a true list operator, myrand() is parsed as a |
690 | true unary operator with unary precedence the same as rand(), and |
5f05dabc |
691 | mytime() is truly without arguments, just like time(). That is, if you |
cb1a09d0 |
692 | say |
693 | |
694 | mytime +2; |
695 | |
696 | you'll get mytime() + 2, not mytime(2), which is how it would be parsed |
697 | without the prototype. |
698 | |
699 | The interesting thing about & is that you can generate new syntax with it: |
700 | |
6d28dffb |
701 | sub try (&@) { |
cb1a09d0 |
702 | my($try,$catch) = @_; |
703 | eval { &$try }; |
704 | if ($@) { |
705 | local $_ = $@; |
706 | &$catch; |
707 | } |
708 | } |
55497cff |
709 | sub catch (&) { $_[0] } |
cb1a09d0 |
710 | |
711 | try { |
712 | die "phooey"; |
713 | } catch { |
714 | /phooey/ and print "unphooey\n"; |
715 | }; |
716 | |
717 | That prints "unphooey". (Yes, there are still unresolved |
718 | issues having to do with the visibility of @_. I'm ignoring that |
719 | question for the moment. (But note that if we make @_ lexically |
720 | scoped, those anonymous subroutines can act like closures... (Gee, |
5f05dabc |
721 | is this sounding a little Lispish? (Never mind.)))) |
cb1a09d0 |
722 | |
723 | And here's a reimplementation of grep: |
724 | |
725 | sub mygrep (&@) { |
726 | my $code = shift; |
727 | my @result; |
728 | foreach $_ (@_) { |
6e47f808 |
729 | push(@result, $_) if &$code; |
cb1a09d0 |
730 | } |
731 | @result; |
732 | } |
a0d0e21e |
733 | |
cb1a09d0 |
734 | Some folks would prefer full alphanumeric prototypes. Alphanumerics have |
735 | been intentionally left out of prototypes for the express purpose of |
736 | someday in the future adding named, formal parameters. The current |
737 | mechanism's main goal is to let module writers provide better diagnostics |
738 | for module users. Larry feels the notation quite understandable to Perl |
739 | programmers, and that it will not intrude greatly upon the meat of the |
740 | module, nor make it harder to read. The line noise is visually |
741 | encapsulated into a small pill that's easy to swallow. |
742 | |
743 | It's probably best to prototype new functions, not retrofit prototyping |
744 | into older ones. That's because you must be especially careful about |
745 | silent impositions of differing list versus scalar contexts. For example, |
746 | if you decide that a function should take just one parameter, like this: |
747 | |
748 | sub func ($) { |
749 | my $n = shift; |
750 | print "you gave me $n\n"; |
54310121 |
751 | } |
cb1a09d0 |
752 | |
753 | and someone has been calling it with an array or expression |
754 | returning a list: |
755 | |
756 | func(@foo); |
757 | func( split /:/ ); |
758 | |
759 | Then you've just supplied an automatic scalar() in front of their |
760 | argument, which can be more than a bit surprising. The old @foo |
761 | which used to hold one thing doesn't get passed in. Instead, |
5f05dabc |
762 | the func() now gets passed in 1, that is, the number of elements |
cb1a09d0 |
763 | in @foo. And the split() gets called in a scalar context and |
764 | starts scribbling on your @_ parameter list. |
765 | |
5f05dabc |
766 | This is all very powerful, of course, and should be used only in moderation |
54310121 |
767 | to make the world a better place. |
44a8e56a |
768 | |
769 | =head2 Constant Functions |
770 | |
771 | Functions with a prototype of C<()> are potential candidates for |
54310121 |
772 | inlining. If the result after optimization and constant folding is |
773 | either a constant or a lexically-scoped scalar which has no other |
774 | references, then it will be used in place of function calls made |
775 | without C<&> or C<do>. Calls made using C<&> or C<do> are never |
776 | inlined. (See constant.pm for an easy way to declare most |
777 | constants.) |
44a8e56a |
778 | |
779 | All of the following functions would be inlined. |
780 | |
699e6cd4 |
781 | sub pi () { 3.14159 } # Not exact, but close. |
782 | sub PI () { 4 * atan2 1, 1 } # As good as it gets, |
783 | # and it's inlined, too! |
44a8e56a |
784 | sub ST_DEV () { 0 } |
785 | sub ST_INO () { 1 } |
786 | |
787 | sub FLAG_FOO () { 1 << 8 } |
788 | sub FLAG_BAR () { 1 << 9 } |
789 | sub FLAG_MASK () { FLAG_FOO | FLAG_BAR } |
54310121 |
790 | |
791 | sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) } |
44a8e56a |
792 | sub BAZ_VAL () { |
793 | if (OPT_BAZ) { |
794 | return 23; |
795 | } |
796 | else { |
797 | return 42; |
798 | } |
799 | } |
cb1a09d0 |
800 | |
54310121 |
801 | sub N () { int(BAZ_VAL) / 3 } |
802 | BEGIN { |
803 | my $prod = 1; |
804 | for (1..N) { $prod *= $_ } |
805 | sub N_FACTORIAL () { $prod } |
806 | } |
807 | |
4cee8e80 |
808 | If you redefine a subroutine which was eligible for inlining you'll get |
809 | a mandatory warning. (You can use this warning to tell whether or not a |
810 | particular subroutine is considered constant.) The warning is |
811 | considered severe enough not to be optional because previously compiled |
812 | invocations of the function will still be using the old value of the |
813 | function. If you need to be able to redefine the subroutine you need to |
814 | ensure that it isn't inlined, either by dropping the C<()> prototype |
815 | (which changes the calling semantics, so beware) or by thwarting the |
816 | inlining mechanism in some other way, such as |
817 | |
4cee8e80 |
818 | sub not_inlined () { |
54310121 |
819 | 23 if $]; |
4cee8e80 |
820 | } |
821 | |
cb1a09d0 |
822 | =head2 Overriding Builtin Functions |
a0d0e21e |
823 | |
5f05dabc |
824 | Many builtin functions may be overridden, though this should be tried |
825 | only occasionally and for good reason. Typically this might be |
a0d0e21e |
826 | done by a package attempting to emulate missing builtin functionality |
827 | on a non-Unix system. |
828 | |
5f05dabc |
829 | Overriding may be done only by importing the name from a |
a0d0e21e |
830 | module--ordinary predeclaration isn't good enough. However, the |
54310121 |
831 | C<subs> pragma (compiler directive) lets you, in effect, predeclare subs |
a0d0e21e |
832 | via the import syntax, and these names may then override the builtin ones: |
833 | |
834 | use subs 'chdir', 'chroot', 'chmod', 'chown'; |
835 | chdir $somewhere; |
836 | sub chdir { ... } |
837 | |
838 | Library modules should not in general export builtin names like "open" |
5f05dabc |
839 | or "chdir" as part of their default @EXPORT list, because these may |
a0d0e21e |
840 | sneak into someone else's namespace and change the semantics unexpectedly. |
841 | Instead, if the module adds the name to the @EXPORT_OK list, then it's |
842 | possible for a user to import the name explicitly, but not implicitly. |
843 | That is, they could say |
844 | |
845 | use Module 'open'; |
846 | |
847 | and it would import the open override, but if they said |
848 | |
849 | use Module; |
850 | |
851 | they would get the default imports without the overrides. |
852 | |
853 | =head2 Autoloading |
854 | |
855 | If you call a subroutine that is undefined, you would ordinarily get an |
856 | immediate fatal error complaining that the subroutine doesn't exist. |
857 | (Likewise for subroutines being used as methods, when the method |
858 | doesn't exist in any of the base classes of the class package.) If, |
859 | however, there is an C<AUTOLOAD> subroutine defined in the package or |
860 | packages that were searched for the original subroutine, then that |
861 | C<AUTOLOAD> subroutine is called with the arguments that would have been |
862 | passed to the original subroutine. The fully qualified name of the |
863 | original subroutine magically appears in the $AUTOLOAD variable in the |
864 | same package as the C<AUTOLOAD> routine. The name is not passed as an |
865 | ordinary argument because, er, well, just because, that's why... |
866 | |
867 | Most C<AUTOLOAD> routines will load in a definition for the subroutine in |
868 | question using eval, and then execute that subroutine using a special |
869 | form of "goto" that erases the stack frame of the C<AUTOLOAD> routine |
870 | without a trace. (See the standard C<AutoLoader> module, for example.) |
871 | But an C<AUTOLOAD> routine can also just emulate the routine and never |
cb1a09d0 |
872 | define it. For example, let's pretend that a function that wasn't defined |
873 | should just call system() with those arguments. All you'd do is this: |
874 | |
875 | sub AUTOLOAD { |
876 | my $program = $AUTOLOAD; |
877 | $program =~ s/.*:://; |
878 | system($program, @_); |
54310121 |
879 | } |
cb1a09d0 |
880 | date(); |
6d28dffb |
881 | who('am', 'i'); |
cb1a09d0 |
882 | ls('-l'); |
883 | |
54310121 |
884 | In fact, if you predeclare the functions you want to call that way, you don't |
cb1a09d0 |
885 | even need the parentheses: |
886 | |
887 | use subs qw(date who ls); |
888 | date; |
889 | who "am", "i"; |
890 | ls -l; |
891 | |
892 | A more complete example of this is the standard Shell module, which |
a0d0e21e |
893 | can treat undefined subroutine calls as calls to Unix programs. |
894 | |
cb1a09d0 |
895 | Mechanisms are available for modules writers to help split the modules |
6d28dffb |
896 | up into autoloadable files. See the standard AutoLoader module |
897 | described in L<AutoLoader> and in L<AutoSplit>, the standard |
898 | SelfLoader modules in L<SelfLoader>, and the document on adding C |
899 | functions to perl code in L<perlxs>. |
cb1a09d0 |
900 | |
901 | =head1 SEE ALSO |
a0d0e21e |
902 | |
cb1a09d0 |
903 | See L<perlref> for more on references. See L<perlxs> if you'd |
54310121 |
904 | like to learn about calling C subroutines from perl. See |
905 | L<perlmod> to learn about bundling up your functions in |
cb1a09d0 |
906 | separate files. |