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