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