This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlfaq update from Tom Christiansen
[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
f86cebdf 49Any arguments passed to the routine come in as the array C<@_>. Thus if you
cb1a09d0 50called a function with two arguments, those would be stored in C<$_[0]>
f86cebdf 51and C<$_[1]>. The array C<@_> is a local array, but its elements are
3fe9a6f1
PP
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
f86cebdf 58it was assigned to.) Note that assigning to the whole array C<@_> removes
3fe9a6f1
PP
59the aliasing, and does not update any arguments.
60
61The return value of the subroutine is the value of the last expression
f86cebdf 62evaluated. Alternatively, a C<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
f86cebdf 72assign to a C<my()> list of these. Any variables you use in the function
cb1a09d0 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
f86cebdf 122do in-place modifications of C<@_> 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
f86cebdf 135It would be much safer if the C<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
f86cebdf 148real scalars or arrays. Perl will see everything as one big long flat C<@_>
cb1a09d0 149parameter list. This is one of the ways where Perl's simple
f86cebdf
GS
150argument-passing style shines. The C<upcase()> function would work perfectly
151well without changing the C<upcase()> definition even if we fed it things
cb1a09d0
AD
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
f86cebdf
GS
162flat. So all you have managed to do here is stored everything in C<@a> and
163made C<@b> an empty list. See L<Pass by Reference> for alternatives.
cb1a09d0 164
f86cebdf 165A subroutine may be called using the "C<&>" prefix. The "C<&>" is optional
5f05dabc 166in modern Perls, and so are the parentheses if the subroutine has been
f86cebdf 167predeclared. (Note, however, that the "C<&>" is I<NOT> optional when
5f05dabc 168you're just naming the subroutine, such as when it's used as an
f86cebdf 169argument to C<defined()> or C<undef()>. Nor is it optional when you want to
5f05dabc
PP
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
f86cebdf
GS
175the "C<&>" form, the argument list is optional, and if omitted, no C<@_> array is
176set up for the subroutine: the C<@_> array at the time of the call is
cb1a09d0
AD
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
f86cebdf 189Not only does the "C<&>" form make the argument list optional, but it also
c07a80fd
PP
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,
f86cebdf
GS
198pre-defined things are C<BEGIN>, C<END>, C<AUTOLOAD>, and C<DESTROY>--plus all the
199functions mentioned in L<perltie>. The 5.005 release adds C<INIT>
5a964f20
TC
200to this list.
201
b687b08b 202=head2 Private Variables via my()
cb1a09d0
AD
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
f86cebdf 211A "C<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 216Only alphanumeric identifiers may be lexically scoped--magical
f86cebdf 217builtins like C<$/> must currently be C<local>ize with "C<local>" instead.
cb1a09d0 218
f86cebdf
GS
219Unlike dynamic variables created by the "C<local>" operator, lexical
220variables declared with "C<my>" are totally hidden from the outside world,
cb1a09d0
AD
221including any called subroutines (even if it's the same subroutine called
222from itself or elsewhere--every call gets its own copy).
223
f86cebdf 224This doesn't mean that a C<my()> variable declared in a statically
5a964f20 225I<enclosing> lexical scope would be invisible. Only the dynamic scopes
f86cebdf
GS
226are cut off. For example, the C<bumpx()> function below has access to the
227lexical C<$x> variable because both the my and the sub occurred at the same
5a964f20
TC
228scope, presumably the file scope.
229
230 my $x = 10;
231 sub bumpx { $x++ }
232
f86cebdf 233(An C<eval()>, however, can see the lexical variables of the scope it is
cb1a09d0 234being evaluated in so long as the names aren't hidden by declarations within
f86cebdf 235the C<eval()> itself. See L<perlref>.)
cb1a09d0 236
f86cebdf 237The parameter list to C<my()> may be assigned to if desired, which allows you
cb1a09d0
AD
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 252
f86cebdf
GS
253The "C<my>" is simply a modifier on something you might assign to. So when
254you do assign to the variables in its argument list, the "C<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
f86cebdf 278can be used to initialize the new $x with the value of the old C<$x>, and
cb1a09d0
AD
279the expression
280
281 my $x = 123 and $x == 123
282
f86cebdf 283is false unless the old C<$x> happened to have the value C<123>.
cb1a09d0 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
f86cebdf 295the scope of C<$line> extends from its declaration throughout the rest of
55497cff
PP
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
f86cebdf 308the scope of C<$answer> extends from its declaration throughout the rest
55497cff
PP
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 317(in the manner of C<local>; see below). However, if the index
f86cebdf 318variable is prefixed with the keyword "C<my>", then it is lexically
55497cff
PP
319scoped instead. Thus in the loop
320
321 for my $i (1, 2, 3) {
322 some_function();
323 }
324
f86cebdf
GS
325the scope of C<$i> extends to the end of the loop, but not beyond it, and
326so the value of C<$i> is unavailable in C<some_function()>.
55497cff 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
f86cebdf 337otherwise. An inner block may countermand this with S<"C<no strict 'vars'>">.
cb1a09d0 338
f86cebdf 339A C<my()> has both a compile-time and a run-time effect. At compile time,
cb1a09d0 340the compiler takes notice of it; the principle usefulness of this is to
f86cebdf 341quiet S<"C<use strict 'vars'>">. The actual initialization is delayed until
7bac28a0
PP
342run time, so it gets executed appropriately; every time through a loop,
343for example.
cb1a09d0 344
f86cebdf 345Variables declared with "C<my>" are not part of any package and are therefore
cb1a09d0
AD
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)
f86cebdf 353are still accessible using the fully qualified C<::> notation even while a
cb1a09d0
AD
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
f86cebdf 361That will print out C<20> and C<10>.
cb1a09d0 362
f86cebdf 363You may declare "C<my>" variables at the outermost scope of a file to hide
5a964f20 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 366requires the use of a closure (anonymous function with lexical access).
f86cebdf 367If a block (such as an C<eval()>, function, or C<package>) wants to create
5a964f20
TC
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 377any package's symbol table. Remember that it's not I<REALLY> called
f86cebdf 378C<$some_pack::secret_version> or anything; it's just C<$secret_version>,
cb1a09d0
AD
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
c2611fb3 384=head2 Persistent Private Variables
5a964f20
TC
385
386Just because a lexical variable is lexically (also called statically)
f86cebdf 387scoped to its enclosing block, C<eval>, or C<do> FILE, this doesn't mean that
5a964f20
TC
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
f86cebdf 418all in the main program, you'll need to arrange for the C<my()>
cb1a09d0 419to be executed early, either by putting the whole block above
f86cebdf 420your main program, or more likely, placing merely a C<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 430
f86cebdf 431See L<perlmod/"Package Constructors and Destructors"> about the C<BEGIN> function.
cb1a09d0 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
f86cebdf 441B<NOTE>: In general, you should be using "C<my>" instead of "C<local>", because
6d28dffb 442it's faster and safer. Exceptions to this include the global punctuation
cb1a09d0 443variables, filehandles and formats, and direct manipulation of the Perl
f86cebdf 444symbol table itself. Format variables often use "C<local>" though, as do
cb1a09d0
AD
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
f86cebdf
GS
461A C<local()> modifies its listed variables to be "local" to the enclosing
462block, C<eval>, or C<do FILE>--and to I<any subroutine called from within that block>.
463A C<local()> just gives temporary values to global (meaning package)
464variables. It does B<not> create a local variable. This is known as
465dynamic scoping. Lexical scoping is done with "C<my>", which works more
5a964f20 466like C's auto declarations.
cb1a09d0 467
f86cebdf 468If more than one variable is given to C<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
f86cebdf 493Because C<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
f86cebdf
GS
499A C<local> is simply a modifier on an lvalue expression. When you assign to
500a C<local>ized variable, the C<local> doesn't change whether its list is viewed
cb1a09d0
AD
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 547It's also worth taking a moment to explain what happens when you
f86cebdf
GS
548C<local>ize a member of a composite type (i.e. an array or hash element).
549In this case, the element is C<local>ized I<by name>. This means that
6ee623d5
GS
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
7185e5cc
GS
584Note also that when you C<local>ize a member of a composite type that
585B<does not exist previously>, the value is treated as though it were
586in an lvalue context, i.e., it is first created and then C<local>ized.
587The consequence of this is that the hash or array is in fact permanently
588modified. For instance, if you say
589
590 %hash = ( 'This' => 'is', 'a' => 'test' );
591 @ary = ( 0..5 );
592 {
593 local($ary[8]) = 0;
594 local($hash{'b'}) = 'whatever';
595 }
596 printf "%%hash has now %d keys, \@ary %d elements.\n",
597 scalar(keys(%hash)), scalar(@ary);
598
599Perl will print
600
601 %hash has now 3 keys, @ary 9 elements.
602
603The above behavior of local() on non-existent members of composite
604types is subject to change in future.
605
cb1a09d0
AD
606=head2 Passing Symbol Table Entries (typeglobs)
607
608[Note: The mechanism described in this section was originally the only
609way to simulate pass-by-reference in older versions of Perl. While it
610still works fine in modern versions, the new reference mechanism is
611generally easier to work with. See below.]
a0d0e21e
LW
612
613Sometimes you don't want to pass the value of an array to a subroutine
614but rather the name of it, so that the subroutine can modify the global
615copy of it rather than working with a local copy. In perl you can
cb1a09d0 616refer to all objects of a particular name by prefixing the name
5f05dabc 617with a star: C<*foo>. This is often known as a "typeglob", because the
a0d0e21e
LW
618star on the front can be thought of as a wildcard match for all the
619funny prefix characters on variables and subroutines and such.
620
55497cff 621When evaluated, the typeglob produces a scalar value that represents
5f05dabc 622all the objects of that name, including any filehandle, format, or
a0d0e21e 623subroutine. When assigned to, it causes the name mentioned to refer to
f86cebdf 624whatever "C<*>" value was assigned to it. Example:
a0d0e21e
LW
625
626 sub doubleary {
627 local(*someary) = @_;
628 foreach $elem (@someary) {
629 $elem *= 2;
630 }
631 }
632 doubleary(*foo);
633 doubleary(*bar);
634
635Note that scalars are already passed by reference, so you can modify
636scalar arguments without using this mechanism by referring explicitly
1fef88e7 637to C<$_[0]> etc. You can modify all the elements of an array by passing
f86cebdf
GS
638all the elements as scalars, but you have to use the C<*> mechanism (or
639the equivalent reference mechanism) to C<push>, C<pop>, or change the size of
a0d0e21e
LW
640an array. It will certainly be faster to pass the typeglob (or reference).
641
642Even if you don't want to modify an array, this mechanism is useful for
5f05dabc 643passing multiple arrays in a single LIST, because normally the LIST
a0d0e21e 644mechanism will merge all the array values so that you can't extract out
55497cff 645the individual arrays. For more on typeglobs, see
2ae324a7 646L<perldata/"Typeglobs and Filehandles">.
cb1a09d0 647
5a964f20
TC
648=head2 When to Still Use local()
649
f86cebdf
GS
650Despite the existence of C<my()>, there are still three places where the
651C<local()> operator still shines. In fact, in these three places, you
5a964f20
TC
652I<must> use C<local> instead of C<my>.
653
654=over
655
f86cebdf 656=item 1. You need to give a global variable a temporary value, especially C<$_>.
5a964f20 657
f86cebdf
GS
658The global variables, like C<@ARGV> or the punctuation variables, must be
659C<local>ized with C<local()>. This block reads in F</etc/motd>, and splits
5a964f20 660it up into chunks separated by lines of equal signs, which are placed
f86cebdf 661in C<@Fields>.
5a964f20
TC
662
663 {
664 local @ARGV = ("/etc/motd");
665 local $/ = undef;
666 local $_ = <>;
667 @Fields = split /^\s*=+\s*$/;
668 }
669
f86cebdf 670It particular, it's important to C<local>ize C<$_> in any routine that assigns
5a964f20
TC
671to it. Look out for implicit assignments in C<while> conditionals.
672
673=item 2. You need to create a local file or directory handle or a local function.
674
f86cebdf
GS
675A function that needs a filehandle of its own must use C<local()> uses
676C<local()> on complete typeglob. This can be used to create new symbol
5a964f20
TC
677table entries:
678
679 sub ioqueue {
680 local (*READER, *WRITER); # not my!
681 pipe (READER, WRITER); or die "pipe: $!";
682 return (*READER, *WRITER);
683 }
684 ($head, $tail) = ioqueue();
685
686See the Symbol module for a way to create anonymous symbol table
687entries.
688
689Because assignment of a reference to a typeglob creates an alias, this
690can be used to create what is effectively a local function, or at least,
691a local alias.
692
693 {
f86cebdf
GS
694 local *grow = \&shrink; # only until this block exists
695 grow(); # really calls shrink()
696 move(); # if move() grow()s, it shrink()s too
5a964f20 697 }
f86cebdf 698 grow(); # get the real grow() again
5a964f20
TC
699
700See L<perlref/"Function Templates"> for more about manipulating
701functions by name in this way.
702
703=item 3. You want to temporarily change just one element of an array or hash.
704
f86cebdf 705You can C<local>ize just one element of an aggregate. Usually this
5a964f20
TC
706is done on dynamics:
707
708 {
709 local $SIG{INT} = 'IGNORE';
710 funct(); # uninterruptible
711 }
712 # interruptibility automatically restored here
713
714But it also works on lexically declared aggregates. Prior to 5.005,
715this operation could on occasion misbehave.
716
717=back
718
cb1a09d0
AD
719=head2 Pass by Reference
720
55497cff
PP
721If you want to pass more than one array or hash into a function--or
722return them from it--and have them maintain their integrity, then
723you're going to have to use an explicit pass-by-reference. Before you
724do that, you need to understand references as detailed in L<perlref>.
c07a80fd 725This section may not make much sense to you otherwise.
cb1a09d0
AD
726
727Here are a few simple examples. First, let's pass in several
f86cebdf 728arrays to a function and have it C<pop> all of then, return a new
cb1a09d0
AD
729list of all their former last elements:
730
731 @tailings = popmany ( \@a, \@b, \@c, \@d );
732
733 sub popmany {
734 my $aref;
735 my @retlist = ();
736 foreach $aref ( @_ ) {
737 push @retlist, pop @$aref;
54310121 738 }
cb1a09d0 739 return @retlist;
54310121 740 }
cb1a09d0 741
54310121 742Here's how you might write a function that returns a
cb1a09d0
AD
743list of keys occurring in all the hashes passed to it:
744
54310121 745 @common = inter( \%foo, \%bar, \%joe );
cb1a09d0
AD
746 sub inter {
747 my ($k, $href, %seen); # locals
748 foreach $href (@_) {
749 while ( $k = each %$href ) {
750 $seen{$k}++;
54310121
PP
751 }
752 }
cb1a09d0 753 return grep { $seen{$_} == @_ } keys %seen;
54310121 754 }
cb1a09d0 755
5f05dabc 756So far, we're using just the normal list return mechanism.
54310121
PP
757What happens if you want to pass or return a hash? Well,
758if you're using only one of them, or you don't mind them
cb1a09d0 759concatenating, then the normal calling convention is ok, although
54310121 760a little expensive.
cb1a09d0
AD
761
762Where people get into trouble is here:
763
764 (@a, @b) = func(@c, @d);
765or
766 (%a, %b) = func(%c, %d);
767
f86cebdf
GS
768That syntax simply won't work. It sets just C<@a> or C<%a> and clears the C<@b> or
769C<%b>. Plus the function didn't get passed into two separate arrays or
770hashes: it got one long list in C<@_>, as always.
cb1a09d0
AD
771
772If you can arrange for everyone to deal with this through references, it's
773cleaner code, although not so nice to look at. Here's a function that
774takes two array references as arguments, returning the two array elements
775in order of how many elements they have in them:
776
777 ($aref, $bref) = func(\@c, \@d);
778 print "@$aref has more than @$bref\n";
779 sub func {
780 my ($cref, $dref) = @_;
781 if (@$cref > @$dref) {
782 return ($cref, $dref);
783 } else {
c07a80fd 784 return ($dref, $cref);
54310121
PP
785 }
786 }
cb1a09d0
AD
787
788It turns out that you can actually do this also:
789
790 (*a, *b) = func(\@c, \@d);
791 print "@a has more than @b\n";
792 sub func {
793 local (*c, *d) = @_;
794 if (@c > @d) {
795 return (\@c, \@d);
796 } else {
797 return (\@d, \@c);
54310121
PP
798 }
799 }
cb1a09d0
AD
800
801Here we're using the typeglobs to do symbol table aliasing. It's
f86cebdf
GS
802a tad subtle, though, and also won't work if you're using C<my()>
803variables, because only globals (well, and C<local()>s) are in the symbol table.
5f05dabc
PP
804
805If you're passing around filehandles, you could usually just use the bare
f86cebdf
GS
806typeglob, like C<*STDOUT>, but typeglobs references would be better because
807they'll still work properly under S<C<use strict 'refs'>>. For example:
5f05dabc
PP
808
809 splutter(\*STDOUT);
810 sub splutter {
811 my $fh = shift;
812 print $fh "her um well a hmmm\n";
813 }
814
815 $rec = get_rec(\*STDIN);
816 sub get_rec {
817 my $fh = shift;
818 return scalar <$fh>;
819 }
820
f86cebdf 821Another way to do this is using C<*HANDLE{IO}>, see L<perlref> for usage
5f05dabc
PP
822and caveats.
823
824If you're planning on generating new filehandles, you could do this:
825
826 sub openit {
827 my $name = shift;
828 local *FH;
e05a3a1e 829 return open (FH, $path) ? *FH : undef;
54310121 830 }
5f05dabc
PP
831
832Although that will actually produce a small memory leak. See the bottom
f86cebdf 833of L<perlfunc/open()> for a somewhat cleaner way using the C<IO::Handle>
5f05dabc 834package.
cb1a09d0 835
cb1a09d0
AD
836=head2 Prototypes
837
838As of the 5.002 release of perl, if you declare
839
840 sub mypush (\@@)
841
f86cebdf 842then C<mypush()> takes arguments exactly like C<push()> does. The declaration
c07a80fd 843of the function to be called must be visible at compile time. The prototype
5f05dabc 844affects only the interpretation of new-style calls to the function, where
c07a80fd
PP
845new-style is defined as not using the C<&> character. In other words,
846if you call it like a builtin function, then it behaves like a builtin
847function. If you call it like an old-fashioned subroutine, then it
848behaves like an old-fashioned subroutine. It naturally falls out from
849this rule that prototypes have no influence on subroutine references
4536e65d
MJD
850like C<\&foo> or on indirect subroutine calls like C<&{$subref}> or
851C<$subref-E<gt>()>.
c07a80fd
PP
852
853Method calls are not influenced by prototypes either, because the
5f05dabc 854function to be called is indeterminate at compile time, because it depends
c07a80fd 855on inheritance.
cb1a09d0 856
5f05dabc 857Because the intent is primarily to let you define subroutines that work
c07a80fd
PP
858like builtin commands, here are the prototypes for some other functions
859that parse almost exactly like the corresponding builtins.
cb1a09d0
AD
860
861 Declared as Called as
862
f86cebdf
GS
863 sub mylink ($$) mylink $old, $new
864 sub myvec ($$$) myvec $var, $offset, 1
865 sub myindex ($$;$) myindex &getstring, "substr"
866 sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off
867 sub myreverse (@) myreverse $a, $b, $c
868 sub myjoin ($@) myjoin ":", $a, $b, $c
869 sub mypop (\@) mypop @array
870 sub mysplice (\@$$@) mysplice @array, @array, 0, @pushme
871 sub mykeys (\%) mykeys %{$hashref}
872 sub myopen (*;$) myopen HANDLE, $name
873 sub mypipe (**) mypipe READHANDLE, WRITEHANDLE
874 sub mygrep (&@) mygrep { /foo/ } $a, $b, $c
875 sub myrand ($) myrand 42
876 sub mytime () mytime
cb1a09d0 877
c07a80fd 878Any backslashed prototype character represents an actual argument
6e47f808
PP
879that absolutely must start with that character. The value passed
880to the subroutine (as part of C<@_>) will be a reference to the
881actual argument given in the subroutine call, obtained by applying
882C<\> to that argument.
c07a80fd
PP
883
884Unbackslashed prototype characters have special meanings. Any
f86cebdf
GS
885unbackslashed C<@> or C<%> eats all the rest of the arguments, and forces
886list context. An argument represented by C<$> forces scalar context. An
887C<&> requires an anonymous subroutine, which, if passed as the first
888argument, does not require the "C<sub>" keyword or a subsequent comma. A
648ca4f7
GS
889C<*> allows the subroutine to accept a bareword, constant, scalar expression,
890typeglob, or a reference to a typeglob in that slot. The value will be
891available to the subroutine either as a simple scalar, or (in the latter
892two cases) as a reference to the typeglob.
c07a80fd
PP
893
894A semicolon separates mandatory arguments from optional arguments.
f86cebdf 895(It is redundant before C<@> or C<%>.)
cb1a09d0 896
c07a80fd 897Note how the last three examples above are treated specially by the parser.
f86cebdf
GS
898C<mygrep()> is parsed as a true list operator, C<myrand()> is parsed as a
899true unary operator with unary precedence the same as C<rand()>, and
900C<mytime()> is truly without arguments, just like C<time()>. That is, if you
cb1a09d0
AD
901say
902
903 mytime +2;
904
f86cebdf 905you'll get C<mytime() + 2>, not C<mytime(2)>, which is how it would be parsed
cb1a09d0
AD
906without the prototype.
907
f86cebdf 908The interesting thing about C<&> is that you can generate new syntax with it:
cb1a09d0 909
6d28dffb 910 sub try (&@) {
cb1a09d0
AD
911 my($try,$catch) = @_;
912 eval { &$try };
913 if ($@) {
914 local $_ = $@;
915 &$catch;
916 }
917 }
55497cff 918 sub catch (&) { $_[0] }
cb1a09d0
AD
919
920 try {
921 die "phooey";
922 } catch {
923 /phooey/ and print "unphooey\n";
924 };
925
f86cebdf
GS
926That prints C<"unphooey">. (Yes, there are still unresolved
927issues having to do with the visibility of C<@_>. I'm ignoring that
928question for the moment. (But note that if we make C<@_> lexically
cb1a09d0 929scoped, those anonymous subroutines can act like closures... (Gee,
5f05dabc 930is this sounding a little Lispish? (Never mind.))))
cb1a09d0 931
f86cebdf 932And here's a reimplementation of C<grep>:
cb1a09d0
AD
933
934 sub mygrep (&@) {
935 my $code = shift;
936 my @result;
937 foreach $_ (@_) {
6e47f808 938 push(@result, $_) if &$code;
cb1a09d0
AD
939 }
940 @result;
941 }
a0d0e21e 942
cb1a09d0
AD
943Some folks would prefer full alphanumeric prototypes. Alphanumerics have
944been intentionally left out of prototypes for the express purpose of
945someday in the future adding named, formal parameters. The current
946mechanism's main goal is to let module writers provide better diagnostics
947for module users. Larry feels the notation quite understandable to Perl
948programmers, and that it will not intrude greatly upon the meat of the
949module, nor make it harder to read. The line noise is visually
950encapsulated into a small pill that's easy to swallow.
951
952It's probably best to prototype new functions, not retrofit prototyping
953into older ones. That's because you must be especially careful about
954silent impositions of differing list versus scalar contexts. For example,
955if you decide that a function should take just one parameter, like this:
956
957 sub func ($) {
958 my $n = shift;
959 print "you gave me $n\n";
54310121 960 }
cb1a09d0
AD
961
962and someone has been calling it with an array or expression
963returning a list:
964
965 func(@foo);
966 func( split /:/ );
967
f86cebdf
GS
968Then you've just supplied an automatic C<scalar()> in front of their
969argument, which can be more than a bit surprising. The old C<@foo>
cb1a09d0 970which used to hold one thing doesn't get passed in. Instead,
f86cebdf
GS
971the C<func()> now gets passed in C<1>, that is, the number of elements
972in C<@foo>. And the C<split()> gets called in a scalar context and
973starts scribbling on your C<@_> parameter list.
cb1a09d0 974
5f05dabc 975This is all very powerful, of course, and should be used only in moderation
54310121 976to make the world a better place.
44a8e56a
PP
977
978=head2 Constant Functions
979
980Functions with a prototype of C<()> are potential candidates for
54310121
PP
981inlining. If the result after optimization and constant folding is
982either a constant or a lexically-scoped scalar which has no other
983references, then it will be used in place of function calls made
984without C<&> or C<do>. Calls made using C<&> or C<do> are never
f86cebdf 985inlined. (See F<constant.pm> for an easy way to declare most
54310121 986constants.)
44a8e56a 987
5a964f20 988The following functions would all be inlined:
44a8e56a 989
699e6cd4
TP
990 sub pi () { 3.14159 } # Not exact, but close.
991 sub PI () { 4 * atan2 1, 1 } # As good as it gets,
992 # and it's inlined, too!
44a8e56a
PP
993 sub ST_DEV () { 0 }
994 sub ST_INO () { 1 }
995
996 sub FLAG_FOO () { 1 << 8 }
997 sub FLAG_BAR () { 1 << 9 }
998 sub FLAG_MASK () { FLAG_FOO | FLAG_BAR }
54310121
PP
999
1000 sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) }
44a8e56a
PP
1001 sub BAZ_VAL () {
1002 if (OPT_BAZ) {
1003 return 23;
1004 }
1005 else {
1006 return 42;
1007 }
1008 }
cb1a09d0 1009
54310121
PP
1010 sub N () { int(BAZ_VAL) / 3 }
1011 BEGIN {
1012 my $prod = 1;
1013 for (1..N) { $prod *= $_ }
1014 sub N_FACTORIAL () { $prod }
1015 }
1016
5a964f20 1017If you redefine a subroutine that was eligible for inlining, you'll get
4cee8e80
CS
1018a mandatory warning. (You can use this warning to tell whether or not a
1019particular subroutine is considered constant.) The warning is
1020considered severe enough not to be optional because previously compiled
1021invocations of the function will still be using the old value of the
1022function. If you need to be able to redefine the subroutine you need to
1023ensure that it isn't inlined, either by dropping the C<()> prototype
1024(which changes the calling semantics, so beware) or by thwarting the
1025inlining mechanism in some other way, such as
1026
4cee8e80 1027 sub not_inlined () {
54310121 1028 23 if $];
4cee8e80
CS
1029 }
1030
cb1a09d0 1031=head2 Overriding Builtin Functions
a0d0e21e 1032
5f05dabc
PP
1033Many builtin functions may be overridden, though this should be tried
1034only occasionally and for good reason. Typically this might be
a0d0e21e
LW
1035done by a package attempting to emulate missing builtin functionality
1036on a non-Unix system.
1037
5f05dabc 1038Overriding may be done only by importing the name from a
a0d0e21e 1039module--ordinary predeclaration isn't good enough. However, the
54310121 1040C<subs> pragma (compiler directive) lets you, in effect, predeclare subs
a0d0e21e
LW
1041via the import syntax, and these names may then override the builtin ones:
1042
1043 use subs 'chdir', 'chroot', 'chmod', 'chown';
1044 chdir $somewhere;
1045 sub chdir { ... }
1046
fb73857a
PP
1047To unambiguously refer to the builtin form, one may precede the
1048builtin name with the special package qualifier C<CORE::>. For example,
1049saying C<CORE::open()> will always refer to the builtin C<open()>, even
1050if the current package has imported some other subroutine called
1051C<&open()> from elsewhere.
1052
f86cebdf
GS
1053Library modules should not in general export builtin names like "C<open>"
1054or "C<chdir>" as part of their default C<@EXPORT> list, because these may
a0d0e21e 1055sneak into someone else's namespace and change the semantics unexpectedly.
f86cebdf 1056Instead, if the module adds the name to the C<@EXPORT_OK> list, then it's
a0d0e21e
LW
1057possible for a user to import the name explicitly, but not implicitly.
1058That is, they could say
1059
1060 use Module 'open';
1061
f86cebdf 1062and it would import the C<open> override, but if they said
a0d0e21e
LW
1063
1064 use Module;
1065
1066they would get the default imports without the overrides.
1067
95d94a4f
GS
1068The foregoing mechanism for overriding builtins is restricted, quite
1069deliberately, to the package that requests the import. There is a second
1070method that is sometimes applicable when you wish to override a builtin
1071everywhere, without regard to namespace boundaries. This is achieved by
1072importing a sub into the special namespace C<CORE::GLOBAL::>. Here is an
1073example that quite brazenly replaces the C<glob> operator with something
1074that understands regular expressions.
1075
1076 package REGlob;
1077 require Exporter;
1078 @ISA = 'Exporter';
1079 @EXPORT_OK = 'glob';
1080
1081 sub import {
1082 my $pkg = shift;
1083 return unless @_;
1084 my $sym = shift;
1085 my $where = ($sym =~ s/^GLOBAL_// ? 'CORE::GLOBAL' : caller(0));
1086 $pkg->export($where, $sym, @_);
1087 }
1088
1089 sub glob {
1090 my $pat = shift;
1091 my @got;
1092 local(*D);
227a8b4b 1093 if (opendir D, '.') { @got = grep /$pat/, readdir D; closedir D; }
95d94a4f
GS
1094 @got;
1095 }
1096 1;
1097
1098And here's how it could be (ab)used:
1099
1100 #use REGlob 'GLOBAL_glob'; # override glob() in ALL namespaces
1101 package Foo;
1102 use REGlob 'glob'; # override glob() in Foo:: only
1103 print for <^[a-z_]+\.pm\$>; # show all pragmatic modules
1104
1105Note that the initial comment shows a contrived, even dangerous example.
1106By overriding C<glob> globally, you would be forcing the new (and
1107subversive) behavior for the C<glob> operator for B<every> namespace,
1108without the complete cognizance or cooperation of the modules that own
1109those namespaces. Naturally, this should be done with extreme caution--if
1110it must be done at all.
1111
1112The C<REGlob> example above does not implement all the support needed to
1113cleanly override perl's C<glob> operator. The builtin C<glob> has
1114different behaviors depending on whether it appears in a scalar or list
1115context, but our C<REGlob> doesn't. Indeed, many perl builtins have such
1116context sensitive behaviors, and these must be adequately supported by
1117a properly written override. For a fully functional example of overriding
1118C<glob>, study the implementation of C<File::DosGlob> in the standard
1119library.
1120
fb73857a 1121
a0d0e21e
LW
1122=head2 Autoloading
1123
1124If you call a subroutine that is undefined, you would ordinarily get an
1125immediate fatal error complaining that the subroutine doesn't exist.
1126(Likewise for subroutines being used as methods, when the method
5a964f20 1127doesn't exist in any base class of the class package.) If,
a0d0e21e
LW
1128however, there is an C<AUTOLOAD> subroutine defined in the package or
1129packages that were searched for the original subroutine, then that
1130C<AUTOLOAD> subroutine is called with the arguments that would have been
1131passed to the original subroutine. The fully qualified name of the
f86cebdf 1132original subroutine magically appears in the C<$AUTOLOAD> variable in the
a0d0e21e
LW
1133same package as the C<AUTOLOAD> routine. The name is not passed as an
1134ordinary argument because, er, well, just because, that's why...
1135
1136Most C<AUTOLOAD> routines will load in a definition for the subroutine in
1137question using eval, and then execute that subroutine using a special
1138form of "goto" that erases the stack frame of the C<AUTOLOAD> routine
1139without a trace. (See the standard C<AutoLoader> module, for example.)
1140But an C<AUTOLOAD> routine can also just emulate the routine and never
cb1a09d0 1141define it. For example, let's pretend that a function that wasn't defined
f86cebdf 1142should just call C<system()> with those arguments. All you'd do is this:
cb1a09d0
AD
1143
1144 sub AUTOLOAD {
1145 my $program = $AUTOLOAD;
1146 $program =~ s/.*:://;
1147 system($program, @_);
54310121 1148 }
cb1a09d0 1149 date();
6d28dffb 1150 who('am', 'i');
cb1a09d0
AD
1151 ls('-l');
1152
54310121 1153In fact, if you predeclare the functions you want to call that way, you don't
cb1a09d0
AD
1154even need the parentheses:
1155
1156 use subs qw(date who ls);
1157 date;
1158 who "am", "i";
1159 ls -l;
1160
1161A more complete example of this is the standard Shell module, which
a0d0e21e
LW
1162can treat undefined subroutine calls as calls to Unix programs.
1163
cb1a09d0 1164Mechanisms are available for modules writers to help split the modules
6d28dffb
PP
1165up into autoloadable files. See the standard AutoLoader module
1166described in L<AutoLoader> and in L<AutoSplit>, the standard
1167SelfLoader modules in L<SelfLoader>, and the document on adding C
1168functions to perl code in L<perlxs>.
cb1a09d0
AD
1169
1170=head1 SEE ALSO
a0d0e21e 1171
5a964f20
TC
1172See L<perlref> for more about references and closures. See L<perlxs> if
1173you'd like to learn about calling C subroutines from perl. See L<perlmod>
1174to learn about bundling up your functions in separate files.