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