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