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