This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
initialisation of simple aggregate state variables
[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
63ccd0da 18 sub NAME(SIG) BLOCK # with a signature instead
09bef843
SB
19 sub NAME : ATTRS BLOCK # with attributes
20 sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes
63ccd0da 21 sub NAME(SIG) : ATTRS BLOCK # with a signature and attributes
a0d0e21e 22
748a9306 23To define an anonymous subroutine at runtime:
d74e8afc 24X<subroutine, anonymous>
748a9306 25
09bef843
SB
26 $subref = sub BLOCK; # no proto
27 $subref = sub (PROTO) BLOCK; # with proto
63ccd0da 28 $subref = sub (SIG) BLOCK; # with signature
09bef843
SB
29 $subref = sub : ATTRS BLOCK; # with attributes
30 $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes
63ccd0da 31 $subref = sub (SIG) : ATTRS BLOCK; # with signature and attributes
748a9306 32
a0d0e21e 33To import subroutines:
d74e8afc 34X<import>
a0d0e21e 35
19799a22 36 use MODULE qw(NAME1 NAME2 NAME3);
a0d0e21e
LW
37
38To call subroutines:
d74e8afc 39X<subroutine, call> X<call>
a0d0e21e 40
5f05dabc 41 NAME(LIST); # & is optional with parentheses.
54310121 42 NAME LIST; # Parentheses optional if predeclared/imported.
19799a22 43 &NAME(LIST); # Circumvent prototypes.
5a964f20 44 &NAME; # Makes current @_ visible to called subroutine.
a0d0e21e
LW
45
46=head1 DESCRIPTION
47
19799a22
GS
48Like many languages, Perl provides for user-defined subroutines.
49These may be located anywhere in the main program, loaded in from
50other files via the C<do>, C<require>, or C<use> keywords, or
be3174d2 51generated on the fly using C<eval> or anonymous subroutines.
19799a22
GS
52You can even call a function indirectly using a variable containing
53its name or a CODE reference.
cb1a09d0
AD
54
55The Perl model for function call and return values is simple: all
56functions are passed as parameters one single flat list of scalars, and
57all functions likewise return to their caller one single flat list of
58scalars. Any arrays or hashes in these call and return lists will
59collapse, losing their identities--but you may always use
60pass-by-reference instead to avoid this. Both call and return lists may
61contain as many or as few scalar elements as you'd like. (Often a
62function without an explicit return statement is called a subroutine, but
19799a22 63there's really no difference from Perl's perspective.)
d74e8afc 64X<subroutine, parameter> X<parameter>
19799a22 65
30d9c59b
Z
66Any arguments passed in show up in the array C<@_>.
67(They may also show up in lexical variables introduced by a signature;
68see L</Signatures> below.) Therefore, if
19799a22
GS
69you called a function with two arguments, those would be stored in
70C<$_[0]> and C<$_[1]>. The array C<@_> is a local array, but its
71elements are aliases for the actual scalar parameters. In particular,
72if an element C<$_[0]> is updated, the corresponding argument is
73updated (or an error occurs if it is not updatable). If an argument
74is an array or hash element which did not exist when the function
75was called, that element is created only when (and if) it is modified
76or a reference to it is taken. (Some earlier versions of Perl
77created the element whether or not the element was assigned to.)
78Assigning to the whole array C<@_> removes that aliasing, and does
79not update any arguments.
d74e8afc 80X<subroutine, argument> X<argument> X<@_>
19799a22 81
dbb128be
XN
82A C<return> statement may be used to exit a subroutine, optionally
83specifying the returned value, which will be evaluated in the
84appropriate context (list, scalar, or void) depending on the context of
85the subroutine call. If you specify no return value, the subroutine
86returns an empty list in list context, the undefined value in scalar
87context, or nothing in void context. If you return one or more
88aggregates (arrays and hashes), these will be flattened together into
89one large indistinguishable list.
90
91If no C<return> is found and if the last statement is an expression, its
b77865f5
FC
92value is returned. If the last statement is a loop control structure
93like a C<foreach> or a C<while>, the returned value is unspecified. The
9a989771 94empty sub returns the empty list.
d74e8afc 95X<subroutine, return value> X<return value> X<return>
19799a22 96
30d9c59b 97Aside from an experimental facility (see L</Signatures> below),
19799a22
GS
98Perl does not have named formal parameters. In practice all you
99do is assign to a C<my()> list of these. Variables that aren't
100declared to be private are global variables. For gory details
5a0de581
LM
101on creating private variables, see L</"Private Variables via my()">
102and L</"Temporary Values via local()">. To create protected
19799a22
GS
103environments for a set of functions in a separate package (and
104probably a separate file), see L<perlmod/"Packages">.
d74e8afc 105X<formal parameter> X<parameter, formal>
a0d0e21e
LW
106
107Example:
108
cb1a09d0
AD
109 sub max {
110 my $max = shift(@_);
a0d0e21e
LW
111 foreach $foo (@_) {
112 $max = $foo if $max < $foo;
113 }
cb1a09d0 114 return $max;
a0d0e21e 115 }
cb1a09d0 116 $bestday = max($mon,$tue,$wed,$thu,$fri);
a0d0e21e
LW
117
118Example:
119
120 # get a line, combining continuation lines
121 # that start with whitespace
122
123 sub get_line {
19799a22 124 $thisline = $lookahead; # global variables!
54310121 125 LINE: while (defined($lookahead = <STDIN>)) {
a0d0e21e
LW
126 if ($lookahead =~ /^[ \t]/) {
127 $thisline .= $lookahead;
128 }
129 else {
130 last LINE;
131 }
132 }
19799a22 133 return $thisline;
a0d0e21e
LW
134 }
135
136 $lookahead = <STDIN>; # get first line
19799a22 137 while (defined($line = get_line())) {
a0d0e21e
LW
138 ...
139 }
140
09bef843 141Assigning to a list of private variables to name your arguments:
a0d0e21e
LW
142
143 sub maybeset {
144 my($key, $value) = @_;
cb1a09d0 145 $Foo{$key} = $value unless $Foo{$key};
a0d0e21e
LW
146 }
147
19799a22
GS
148Because the assignment copies the values, this also has the effect
149of turning call-by-reference into call-by-value. Otherwise a
150function is free to do in-place modifications of C<@_> and change
151its caller's values.
d74e8afc 152X<call-by-reference> X<call-by-value>
cb1a09d0
AD
153
154 upcase_in($v1, $v2); # this changes $v1 and $v2
155 sub upcase_in {
54310121
PP
156 for (@_) { tr/a-z/A-Z/ }
157 }
cb1a09d0
AD
158
159You aren't allowed to modify constants in this way, of course. If an
160argument were actually literal and you tried to change it, you'd take a
161(presumably fatal) exception. For example, this won't work:
d74e8afc 162X<call-by-reference> X<call-by-value>
cb1a09d0
AD
163
164 upcase_in("frederick");
165
f86cebdf 166It would be much safer if the C<upcase_in()> function
cb1a09d0
AD
167were written to return a copy of its parameters instead
168of changing them in place:
169
19799a22 170 ($v3, $v4) = upcase($v1, $v2); # this doesn't change $v1 and $v2
cb1a09d0 171 sub upcase {
54310121 172 return unless defined wantarray; # void context, do nothing
cb1a09d0 173 my @parms = @_;
54310121 174 for (@parms) { tr/a-z/A-Z/ }
c07a80fd 175 return wantarray ? @parms : $parms[0];
54310121 176 }
cb1a09d0 177
19799a22 178Notice how this (unprototyped) function doesn't care whether it was
a2293a43 179passed real scalars or arrays. Perl sees all arguments as one big,
19799a22
GS
180long, flat parameter list in C<@_>. This is one area where
181Perl's simple argument-passing style shines. The C<upcase()>
182function would work perfectly well without changing the C<upcase()>
183definition even if we fed it things like this:
cb1a09d0
AD
184
185 @newlist = upcase(@list1, @list2);
186 @newlist = upcase( split /:/, $var );
187
188Do not, however, be tempted to do this:
189
190 (@a, @b) = upcase(@list1, @list2);
191
19799a22
GS
192Like the flattened incoming parameter list, the return list is also
193flattened on return. So all you have managed to do here is stored
17b63f68 194everything in C<@a> and made C<@b> empty. See
5a0de581 195L</Pass by Reference> for alternatives.
19799a22
GS
196
197A subroutine may be called using an explicit C<&> prefix. The
198C<&> is optional in modern Perl, as are parentheses if the
199subroutine has been predeclared. The C<&> is I<not> optional
200when just naming the subroutine, such as when it's used as
201an argument to defined() or undef(). Nor is it optional when you
202want to do an indirect subroutine call with a subroutine name or
203reference using the C<&$subref()> or C<&{$subref}()> constructs,
c47ff5f1 204although the C<< $subref->() >> notation solves that problem.
19799a22 205See L<perlref> for more about all that.
d74e8afc 206X<&>
19799a22
GS
207
208Subroutines may be called recursively. If a subroutine is called
209using the C<&> form, the argument list is optional, and if omitted,
210no C<@_> array is set up for the subroutine: the C<@_> array at the
211time of the call is visible to subroutine instead. This is an
212efficiency mechanism that new users may wish to avoid.
d74e8afc 213X<recursion>
a0d0e21e
LW
214
215 &foo(1,2,3); # pass three arguments
216 foo(1,2,3); # the same
217
218 foo(); # pass a null list
219 &foo(); # the same
a0d0e21e 220
cb1a09d0 221 &foo; # foo() get current args, like foo(@_) !!
54310121 222 foo; # like foo() IFF sub foo predeclared, else "foo"
cb1a09d0 223
19799a22
GS
224Not only does the C<&> form make the argument list optional, it also
225disables any prototype checking on arguments you do provide. This
c07a80fd 226is partly for historical reasons, and partly for having a convenient way
9688be67 227to cheat if you know what you're doing. See L</Prototypes> below.
d74e8afc 228X<&>
c07a80fd 229
977616ef
RS
230Since Perl 5.16.0, the C<__SUB__> token is available under C<use feature
231'current_sub'> and C<use 5.16.0>. It will evaluate to a reference to the
906024c7
FC
232currently-running sub, which allows for recursive calls without knowing
233your subroutine's name.
977616ef
RS
234
235 use 5.16.0;
236 my $factorial = sub {
237 my ($x) = @_;
238 return 1 if $x == 1;
239 return($x * __SUB__->( $x - 1 ) );
240 };
241
89d1beed 242The behavior of C<__SUB__> within a regex code block (such as C</(?{...})/>)
a453e28a
DM
243is subject to change.
244
ac90fb77
EM
245Subroutines whose names are in all upper case are reserved to the Perl
246core, as are modules whose names are in all lower case. A subroutine in
247all capitals is a loosely-held convention meaning it will be called
248indirectly by the run-time system itself, usually due to a triggered event.
bf5513e0 249Subroutines whose name start with a left parenthesis are also reserved the
b77865f5 250same way. The following is a list of some subroutines that currently do
bf5513e0
ZA
251special, pre-defined things.
252
253=over
254
255=item documented later in this document
256
257C<AUTOLOAD>
258
259=item documented in L<perlmod>
260
8b7906d1 261C<CLONE>, C<CLONE_SKIP>
bf5513e0
ZA
262
263=item documented in L<perlobj>
264
8b7906d1 265C<DESTROY>, C<DOES>
bf5513e0
ZA
266
267=item documented in L<perltie>
268
269C<BINMODE>, C<CLEAR>, C<CLOSE>, C<DELETE>, C<DESTROY>, C<EOF>, C<EXISTS>,
270C<EXTEND>, C<FETCH>, C<FETCHSIZE>, C<FILENO>, C<FIRSTKEY>, C<GETC>,
271C<NEXTKEY>, C<OPEN>, C<POP>, C<PRINT>, C<PRINTF>, C<PUSH>, C<READ>,
272C<READLINE>, C<SCALAR>, C<SEEK>, C<SHIFT>, C<SPLICE>, C<STORE>,
273C<STORESIZE>, C<TELL>, C<TIEARRAY>, C<TIEHANDLE>, C<TIEHASH>,
274C<TIESCALAR>, C<UNSHIFT>, C<UNTIE>, C<WRITE>
275
276=item documented in L<PerlIO::via>
277
278C<BINMODE>, C<CLEARERR>, C<CLOSE>, C<EOF>, C<ERROR>, C<FDOPEN>, C<FILENO>,
279C<FILL>, C<FLUSH>, C<OPEN>, C<POPPED>, C<PUSHED>, C<READ>, C<SEEK>,
280C<SETLINEBUF>, C<SYSOPEN>, C<TELL>, C<UNREAD>, C<UTF8>, C<WRITE>
281
ec2eb8a9
TC
282=item documented in L<perlfunc>
283
284L<< C<import> | perlfunc/use >>, L<< C<unimport> | perlfunc/use >>,
285L<< C<INC> | perlfunc/require >>
286
287=item documented in L<UNIVERSAL>
288
289C<VERSION>
290
291=item documented in L<perldebguts>
292
293C<DB::DB>, C<DB::sub>, C<DB::lsub>, C<DB::goto>, C<DB::postponed>
294
bf5513e0
ZA
295=item undocumented, used internally by the L<overload> feature
296
297any starting with C<(>
298
299=back
ac90fb77 300
3c10abe3
AG
301The C<BEGIN>, C<UNITCHECK>, C<CHECK>, C<INIT> and C<END> subroutines
302are not so much subroutines as named special code blocks, of which you
303can have more than one in a package, and which you can B<not> call
304explicitly. See L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END">
5a964f20 305
30d9c59b
Z
306=head2 Signatures
307
308B<WARNING>: Subroutine signatures are experimental. The feature may be
309modified or removed in future versions of Perl.
310
311Perl has an experimental facility to allow a subroutine's formal
312parameters to be introduced by special syntax, separate from the
313procedural code of the subroutine body. The formal parameter list
314is known as a I<signature>. The facility must be enabled first by a
315pragmatic declaration, C<use feature 'signatures'>, and it will produce
316a warning unless the "experimental::signatures" warnings category is
317disabled.
318
319The signature is part of a subroutine's body. Normally the body of a
320subroutine is simply a braced block of code. When using a signature,
fa14274e 321the signature is a parenthesised list that goes immediately after
55121b6b
RS
322the subroutine name (or, for anonymous subroutines, immediately after
323the C<sub> keyword). The signature declares lexical variables that are
30d9c59b
Z
324in scope for the block. When the subroutine is called, the signature
325takes control first. It populates the signature variables from the
326list of arguments that were passed. If the argument list doesn't meet
327the requirements of the signature, then it will throw an exception.
328When the signature processing is complete, control passes to the block.
329
330Positional parameters are handled by simply naming scalar variables in
331the signature. For example,
332
333 sub foo ($left, $right) {
334 return $left + $right;
335 }
336
337takes two positional parameters, which must be filled at runtime by
338two arguments. By default the parameters are mandatory, and it is
339not permitted to pass more arguments than expected. So the above is
340equivalent to
341
342 sub foo {
343 die "Too many arguments for subroutine" unless @_ <= 2;
344 die "Too few arguments for subroutine" unless @_ >= 2;
345 my $left = $_[0];
346 my $right = $_[1];
347 return $left + $right;
348 }
349
350An argument can be ignored by omitting the main part of the name from
351a parameter declaration, leaving just a bare C<$> sigil. For example,
352
353 sub foo ($first, $, $third) {
354 return "first=$first, third=$third";
355 }
356
357Although the ignored argument doesn't go into a variable, it is still
358mandatory for the caller to pass it.
359
360A positional parameter is made optional by giving a default value,
361separated from the parameter name by C<=>:
362
363 sub foo ($left, $right = 0) {
364 return $left + $right;
365 }
366
367The above subroutine may be called with either one or two arguments.
368The default value expression is evaluated when the subroutine is called,
369so it may provide different default values for different calls. It is
370only evaluated if the argument was actually omitted from the call.
371For example,
372
373 my $auto_id = 0;
374 sub foo ($thing, $id = $auto_id++) {
375 print "$thing has ID $id";
376 }
377
378automatically assigns distinct sequential IDs to things for which no
379ID was supplied by the caller. A default value expression may also
380refer to parameters earlier in the signature, making the default for
381one parameter vary according to the earlier parameters. For example,
382
383 sub foo ($first_name, $surname, $nickname = $first_name) {
384 print "$first_name $surname is known as \"$nickname\"";
385 }
386
387An optional parameter can be nameless just like a mandatory parameter.
388For example,
389
390 sub foo ($thing, $ = 1) {
391 print $thing;
392 }
393
394The parameter's default value will still be evaluated if the corresponding
395argument isn't supplied, even though the value won't be stored anywhere.
396This is in case evaluating it has important side effects. However, it
397will be evaluated in void context, so if it doesn't have side effects
398and is not trivial it will generate a warning if the "void" warning
399category is enabled. If a nameless optional parameter's default value
400is not important, it may be omitted just as the parameter's name was:
401
402 sub foo ($thing, $=) {
403 print $thing;
404 }
405
406Optional positional parameters must come after all mandatory positional
407parameters. (If there are no mandatory positional parameters then an
408optional positional parameters can be the first thing in the signature.)
409If there are multiple optional positional parameters and not enough
410arguments are supplied to fill them all, they will be filled from left
411to right.
412
413After positional parameters, additional arguments may be captured in a
414slurpy parameter. The simplest form of this is just an array variable:
415
416 sub foo ($filter, @inputs) {
417 print $filter->($_) foreach @inputs;
418 }
419
420With a slurpy parameter in the signature, there is no upper limit on how
421many arguments may be passed. A slurpy array parameter may be nameless
422just like a positional parameter, in which case its only effect is to
423turn off the argument limit that would otherwise apply:
424
425 sub foo ($thing, @) {
426 print $thing;
427 }
428
429A slurpy parameter may instead be a hash, in which case the arguments
430available to it are interpreted as alternating keys and values.
431There must be as many keys as values: if there is an odd argument then
432an exception will be thrown. Keys will be stringified, and if there are
433duplicates then the later instance takes precedence over the earlier,
434as with standard hash construction.
435
436 sub foo ($filter, %inputs) {
437 print $filter->($_, $inputs{$_}) foreach sort keys %inputs;
438 }
439
440A slurpy hash parameter may be nameless just like other kinds of
441parameter. It still insists that the number of arguments available to
442it be even, even though they're not being put into a variable.
443
444 sub foo ($thing, %) {
445 print $thing;
446 }
447
448A slurpy parameter, either array or hash, must be the last thing in the
449signature. It may follow mandatory and optional positional parameters;
450it may also be the only thing in the signature. Slurpy parameters cannot
451have default values: if no arguments are supplied for them then you get
452an empty array or empty hash.
453
454A signature may be entirely empty, in which case all it does is check
455that the caller passed no arguments:
456
457 sub foo () {
458 return 123;
459 }
460
8c13e946
RS
461When using a signature, the arguments are still available in the special
462array variable C<@_>, in addition to the lexical variables of the
463signature. There is a difference between the two ways of accessing the
30d9c59b
Z
464arguments: C<@_> I<aliases> the arguments, but the signature variables
465get I<copies> of the arguments. So writing to a signature variable
466only changes that variable, and has no effect on the caller's variables,
467but writing to an element of C<@_> modifies whatever the caller used to
468supply that argument.
469
470There is a potential syntactic ambiguity between signatures and prototypes
471(see L</Prototypes>), because both start with an opening parenthesis and
472both can appear in some of the same places, such as just after the name
473in a subroutine declaration. For historical reasons, when signatures
474are not enabled, any opening parenthesis in such a context will trigger
475very forgiving prototype parsing. Most signatures will be interpreted
476as prototypes in those circumstances, but won't be valid prototypes.
477(A valid prototype cannot contain any alphabetic character.) This will
478lead to somewhat confusing error messages.
479
480To avoid ambiguity, when signatures are enabled the special syntax
481for prototypes is disabled. There is no attempt to guess whether a
482parenthesised group was intended to be a prototype or a signature.
483To give a subroutine a prototype under these circumstances, use a
484L<prototype attribute|attributes/Built-in Attributes>. For example,
485
486 sub foo :prototype($) { $_[0] }
487
488It is entirely possible for a subroutine to have both a prototype and
489a signature. They do different jobs: the prototype affects compilation
490of calls to the subroutine, and the signature puts argument values into
491lexical variables at runtime. You can therefore write
492
71917f62 493 sub foo ($left, $right) : prototype($$) {
30d9c59b
Z
494 return $left + $right;
495 }
496
71917f62
PM
497The prototype attribute, and any other attributes, come after
498the signature.
30d9c59b 499
b687b08b 500=head2 Private Variables via my()
d74e8afc
ITB
501X<my> X<variable, lexical> X<lexical> X<lexical variable> X<scope, lexical>
502X<lexical scope> X<attributes, my>
cb1a09d0
AD
503
504Synopsis:
505
506 my $foo; # declare $foo lexically local
507 my (@wid, %get); # declare list of variables local
508 my $foo = "flurp"; # declare $foo lexical, and init it
509 my @oof = @bar; # declare @oof lexical, and init it
09bef843
SB
510 my $x : Foo = $y; # similar, with an attribute applied
511
a0ae32d3
JH
512B<WARNING>: The use of attribute lists on C<my> declarations is still
513evolving. The current semantics and interface are subject to change.
514See L<attributes> and L<Attribute::Handlers>.
cb1a09d0 515
19799a22 516The C<my> operator declares the listed variables to be lexically
f185f654
KW
517confined to the enclosing block, conditional
518(C<if>/C<unless>/C<elsif>/C<else>), loop
519(C<for>/C<foreach>/C<while>/C<until>/C<continue>), subroutine, C<eval>,
520or C<do>/C<require>/C<use>'d file. If more than one value is listed, the
19799a22
GS
521list must be placed in parentheses. All listed elements must be
522legal lvalues. Only alphanumeric identifiers may be lexically
325192b1 523scoped--magical built-ins like C<$/> must currently be C<local>ized
19799a22
GS
524with C<local> instead.
525
526Unlike dynamic variables created by the C<local> operator, lexical
527variables declared with C<my> are totally hidden from the outside
528world, including any called subroutines. This is true if it's the
529same subroutine called from itself or elsewhere--every call gets
530its own copy.
d74e8afc 531X<local>
19799a22
GS
532
533This doesn't mean that a C<my> variable declared in a statically
534enclosing lexical scope would be invisible. Only dynamic scopes
535are cut off. For example, the C<bumpx()> function below has access
536to the lexical $x variable because both the C<my> and the C<sub>
537occurred at the same scope, presumably file scope.
5a964f20
TC
538
539 my $x = 10;
540 sub bumpx { $x++ }
541
19799a22
GS
542An C<eval()>, however, can see lexical variables of the scope it is
543being evaluated in, so long as the names aren't hidden by declarations within
544the C<eval()> itself. See L<perlref>.
d74e8afc 545X<eval, scope of>
cb1a09d0 546
19799a22 547The parameter list to my() may be assigned to if desired, which allows you
cb1a09d0
AD
548to initialize your variables. (If no initializer is given for a
549particular variable, it is created with the undefined value.) Commonly
19799a22 550this is used to name input parameters to a subroutine. Examples:
cb1a09d0
AD
551
552 $arg = "fred"; # "global" variable
553 $n = cube_root(27);
554 print "$arg thinks the root is $n\n";
555 fred thinks the root is 3
556
557 sub cube_root {
558 my $arg = shift; # name doesn't matter
559 $arg **= 1/3;
560 return $arg;
54310121 561 }
cb1a09d0 562
19799a22
GS
563The C<my> is simply a modifier on something you might assign to. So when
564you do assign to variables in its argument list, C<my> doesn't
6cc33c6d 565change whether those variables are viewed as a scalar or an array. So
cb1a09d0 566
5a964f20 567 my ($foo) = <STDIN>; # WRONG?
cb1a09d0
AD
568 my @FOO = <STDIN>;
569
5f05dabc 570both supply a list context to the right-hand side, while
cb1a09d0
AD
571
572 my $foo = <STDIN>;
573
5f05dabc 574supplies a scalar context. But the following declares only one variable:
748a9306 575
5a964f20 576 my $foo, $bar = 1; # WRONG
748a9306 577
cb1a09d0 578That has the same effect as
748a9306 579
cb1a09d0
AD
580 my $foo;
581 $bar = 1;
a0d0e21e 582
cb1a09d0
AD
583The declared variable is not introduced (is not visible) until after
584the current statement. Thus,
585
586 my $x = $x;
587
19799a22 588can be used to initialize a new $x with the value of the old $x, and
cb1a09d0
AD
589the expression
590
591 my $x = 123 and $x == 123
592
19799a22 593is false unless the old $x happened to have the value C<123>.
cb1a09d0 594
55497cff
PP
595Lexical scopes of control structures are not bounded precisely by the
596braces that delimit their controlled blocks; control expressions are
19799a22 597part of that scope, too. Thus in the loop
55497cff 598
19799a22 599 while (my $line = <>) {
55497cff
PP
600 $line = lc $line;
601 } continue {
602 print $line;
603 }
604
19799a22 605the scope of $line extends from its declaration throughout the rest of
55497cff
PP
606the loop construct (including the C<continue> clause), but not beyond
607it. Similarly, in the conditional
608
609 if ((my $answer = <STDIN>) =~ /^yes$/i) {
610 user_agrees();
611 } elsif ($answer =~ /^no$/i) {
612 user_disagrees();
613 } else {
614 chomp $answer;
615 die "'$answer' is neither 'yes' nor 'no'";
616 }
617
19799a22
GS
618the scope of $answer extends from its declaration through the rest
619of that conditional, including any C<elsif> and C<else> clauses,
96090e4f 620but not beyond it. See L<perlsyn/"Simple Statements"> for information
457b36cb 621on the scope of variables in statements with modifiers.
55497cff 622
5f05dabc 623The C<foreach> loop defaults to scoping its index variable dynamically
19799a22
GS
624in the manner of C<local>. However, if the index variable is
625prefixed with the keyword C<my>, or if there is already a lexical
626by that name in scope, then a new lexical is created instead. Thus
627in the loop
d74e8afc 628X<foreach> X<for>
55497cff
PP
629
630 for my $i (1, 2, 3) {
631 some_function();
632 }
633
19799a22
GS
634the scope of $i extends to the end of the loop, but not beyond it,
635rendering the value of $i inaccessible within C<some_function()>.
d74e8afc 636X<foreach> X<for>
55497cff 637
cb1a09d0 638Some users may wish to encourage the use of lexically scoped variables.
19799a22
GS
639As an aid to catching implicit uses to package variables,
640which are always global, if you say
cb1a09d0
AD
641
642 use strict 'vars';
643
19799a22
GS
644then any variable mentioned from there to the end of the enclosing
645block must either refer to a lexical variable, be predeclared via
77ca0c92 646C<our> or C<use vars>, or else must be fully qualified with the package name.
19799a22
GS
647A compilation error results otherwise. An inner block may countermand
648this with C<no strict 'vars'>.
649
650A C<my> has both a compile-time and a run-time effect. At compile
8593bda5 651time, the compiler takes notice of it. The principal usefulness
19799a22
GS
652of this is to quiet C<use strict 'vars'>, but it is also essential
653for generation of closures as detailed in L<perlref>. Actual
654initialization is delayed until run time, though, so it gets executed
655at the appropriate time, such as each time through a loop, for
656example.
657
658Variables declared with C<my> are not part of any package and are therefore
cb1a09d0
AD
659never fully qualified with the package name. In particular, you're not
660allowed to try to make a package variable (or other global) lexical:
661
662 my $pack::var; # ERROR! Illegal syntax
cb1a09d0
AD
663
664In fact, a dynamic variable (also known as package or global variables)
f86cebdf 665are still accessible using the fully qualified C<::> notation even while a
cb1a09d0
AD
666lexical of the same name is also visible:
667
668 package main;
669 local $x = 10;
670 my $x = 20;
671 print "$x and $::x\n";
672
f86cebdf 673That will print out C<20> and C<10>.
cb1a09d0 674
19799a22
GS
675You may declare C<my> variables at the outermost scope of a file
676to hide any such identifiers from the world outside that file. This
677is similar in spirit to C's static variables when they are used at
678the file level. To do this with a subroutine requires the use of
679a closure (an anonymous function that accesses enclosing lexicals).
680If you want to create a private subroutine that cannot be called
681from outside that block, it can declare a lexical variable containing
682an anonymous sub reference:
cb1a09d0
AD
683
684 my $secret_version = '1.001-beta';
685 my $secret_sub = sub { print $secret_version };
686 &$secret_sub();
687
688As long as the reference is never returned by any function within the
5f05dabc 689module, no outside module can see the subroutine, because its name is not in
cb1a09d0 690any package's symbol table. Remember that it's not I<REALLY> called
19799a22 691C<$some_pack::secret_version> or anything; it's just $secret_version,
cb1a09d0
AD
692unqualified and unqualifiable.
693
19799a22
GS
694This does not work with object methods, however; all object methods
695have to be in the symbol table of some package to be found. See
696L<perlref/"Function Templates"> for something of a work-around to
697this.
cb1a09d0 698
c2611fb3 699=head2 Persistent Private Variables
ba1f8e91
RGS
700X<state> X<state variable> X<static> X<variable, persistent> X<variable, static> X<closure>
701
702There are two ways to build persistent private variables in Perl 5.10.
b77865f5 703First, you can simply use the C<state> feature. Or, you can use closures,
ba1f8e91
RGS
704if you want to stay compatible with releases older than 5.10.
705
706=head3 Persistent variables via state()
707
9d42615f 708Beginning with Perl 5.10.0, you can declare variables with the C<state>
4a904372 709keyword in place of C<my>. For that to work, though, you must have
ba1f8e91 710enabled that feature beforehand, either by using the C<feature> pragma, or
4a904372 711by using C<-E> on one-liners (see L<feature>). Beginning with Perl 5.16,
47d235f1 712the C<CORE::state> form does not require the
4a904372 713C<feature> pragma.
ba1f8e91 714
ad0cc46c
FC
715The C<state> keyword creates a lexical variable (following the same scoping
716rules as C<my>) that persists from one subroutine call to the next. If a
717state variable resides inside an anonymous subroutine, then each copy of
718the subroutine has its own copy of the state variable. However, the value
719of the state variable will still persist between calls to the same copy of
720the anonymous subroutine. (Don't forget that C<sub { ... }> creates a new
721subroutine each time it is executed.)
722
ba1f8e91
RGS
723For example, the following code maintains a private counter, incremented
724each time the gimme_another() function is called:
725
726 use feature 'state';
727 sub gimme_another { state $x; return ++$x }
728
ad0cc46c
FC
729And this example uses anonymous subroutines to create separate counters:
730
731 use feature 'state';
732 sub create_counter {
733 return sub { state $x; return ++$x }
734 }
735
ba1f8e91
RGS
736Also, since C<$x> is lexical, it can't be reached or modified by any Perl
737code outside.
738
f99042c8 739When combined with variable declaration, simple assignment to C<state>
f292fc7a
RS
740variables (as in C<state $x = 42>) is executed only the first time. When such
741statements are evaluated subsequent times, the assignment is ignored. The
f99042c8
Z
742behavior of assignment to C<state> declarations where the left hand side
743of the assignment involves any parentheses is currently undefined.
ba1f8e91
RGS
744
745=head3 Persistent variables with closures
5a964f20
TC
746
747Just because a lexical variable is lexically (also called statically)
f86cebdf 748scoped to its enclosing block, C<eval>, or C<do> FILE, this doesn't mean that
5a964f20
TC
749within a function it works like a C static. It normally works more
750like a C auto, but with implicit garbage collection.
751
752Unlike local variables in C or C++, Perl's lexical variables don't
753necessarily get recycled just because their scope has exited.
754If something more permanent is still aware of the lexical, it will
755stick around. So long as something else references a lexical, that
756lexical won't be freed--which is as it should be. You wouldn't want
757memory being free until you were done using it, or kept around once you
758were done. Automatic garbage collection takes care of this for you.
759
760This means that you can pass back or save away references to lexical
761variables, whereas to return a pointer to a C auto is a grave error.
762It also gives us a way to simulate C's function statics. Here's a
763mechanism for giving a function private variables with both lexical
764scoping and a static lifetime. If you do want to create something like
765C's static variables, just enclose the whole function in an extra block,
766and put the static variable outside the function but in the block.
cb1a09d0
AD
767
768 {
54310121 769 my $secret_val = 0;
cb1a09d0
AD
770 sub gimme_another {
771 return ++$secret_val;
54310121
PP
772 }
773 }
cb1a09d0
AD
774 # $secret_val now becomes unreachable by the outside
775 # world, but retains its value between calls to gimme_another
776
54310121 777If this function is being sourced in from a separate file
cb1a09d0 778via C<require> or C<use>, then this is probably just fine. If it's
19799a22 779all in the main program, you'll need to arrange for the C<my>
cb1a09d0 780to be executed early, either by putting the whole block above
f86cebdf 781your main program, or more likely, placing merely a C<BEGIN>
ac90fb77 782code block around it to make sure it gets executed before your program
cb1a09d0
AD
783starts to run:
784
ac90fb77 785 BEGIN {
54310121 786 my $secret_val = 0;
cb1a09d0
AD
787 sub gimme_another {
788 return ++$secret_val;
54310121
PP
789 }
790 }
cb1a09d0 791
3c10abe3
AG
792See L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END"> about the
793special triggered code blocks, C<BEGIN>, C<UNITCHECK>, C<CHECK>,
794C<INIT> and C<END>.
cb1a09d0 795
19799a22
GS
796If declared at the outermost scope (the file scope), then lexicals
797work somewhat like C's file statics. They are available to all
798functions in that same file declared below them, but are inaccessible
799from outside that file. This strategy is sometimes used in modules
800to create private variables that the whole module can see.
5a964f20 801
cb1a09d0 802=head2 Temporary Values via local()
d74e8afc
ITB
803X<local> X<scope, dynamic> X<dynamic scope> X<variable, local>
804X<variable, temporary>
cb1a09d0 805
19799a22 806B<WARNING>: In general, you should be using C<my> instead of C<local>, because
6d28dffb 807it's faster and safer. Exceptions to this include the global punctuation
325192b1
RGS
808variables, global filehandles and formats, and direct manipulation of the
809Perl symbol table itself. C<local> is mostly used when the current value
810of a variable must be visible to called subroutines.
cb1a09d0
AD
811
812Synopsis:
813
325192b1
RGS
814 # localization of values
815
555bd962
BG
816 local $foo; # make $foo dynamically local
817 local (@wid, %get); # make list of variables local
818 local $foo = "flurp"; # make $foo dynamic, and init it
819 local @oof = @bar; # make @oof dynamic, and init it
325192b1 820
555bd962
BG
821 local $hash{key} = "val"; # sets a local value for this hash entry
822 delete local $hash{key}; # delete this entry for the current block
823 local ($cond ? $v1 : $v2); # several types of lvalues support
824 # localization
325192b1
RGS
825
826 # localization of symbols
cb1a09d0 827
555bd962
BG
828 local *FH; # localize $FH, @FH, %FH, &FH ...
829 local *merlyn = *randal; # now $merlyn is really $randal, plus
830 # @merlyn is really @randal, etc
831 local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal
832 local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc
cb1a09d0 833
19799a22
GS
834A C<local> modifies its listed variables to be "local" to the
835enclosing block, C<eval>, or C<do FILE>--and to I<any subroutine
836called from within that block>. A C<local> just gives temporary
837values to global (meaning package) variables. It does I<not> create
838a local variable. This is known as dynamic scoping. Lexical scoping
839is done with C<my>, which works more like C's auto declarations.
cb1a09d0 840
ceb12f1f 841Some types of lvalues can be localized as well: hash and array elements
325192b1
RGS
842and slices, conditionals (provided that their result is always
843localizable), and symbolic references. As for simple variables, this
844creates new, dynamically scoped values.
845
846If more than one variable or expression is given to C<local>, they must be
847placed in parentheses. This operator works
cb1a09d0 848by saving the current values of those variables in its argument list on a
5f05dabc 849hidden stack and restoring them upon exiting the block, subroutine, or
cb1a09d0
AD
850eval. This means that called subroutines can also reference the local
851variable, but not the global one. The argument list may be assigned to if
852desired, which allows you to initialize your local variables. (If no
853initializer is given for a particular variable, it is created with an
325192b1 854undefined value.)
cb1a09d0 855
19799a22 856Because C<local> is a run-time operator, it gets executed each time
325192b1
RGS
857through a loop. Consequently, it's more efficient to localize your
858variables outside the loop.
859
860=head3 Grammatical note on local()
d74e8afc 861X<local, context>
cb1a09d0 862
f86cebdf
GS
863A C<local> is simply a modifier on an lvalue expression. When you assign to
864a C<local>ized variable, the C<local> doesn't change whether its list is viewed
cb1a09d0
AD
865as a scalar or an array. So
866
867 local($foo) = <STDIN>;
868 local @FOO = <STDIN>;
869
5f05dabc 870both supply a list context to the right-hand side, while
cb1a09d0
AD
871
872 local $foo = <STDIN>;
873
874supplies a scalar context.
875
325192b1 876=head3 Localization of special variables
d74e8afc 877X<local, special variable>
3e3baf6d 878
325192b1
RGS
879If you localize a special variable, you'll be giving a new value to it,
880but its magic won't go away. That means that all side-effects related
881to this magic still work with the localized value.
3e3baf6d 882
325192b1
RGS
883This feature allows code like this to work :
884
885 # Read the whole contents of FILE in $slurp
886 { local $/ = undef; $slurp = <FILE>; }
887
888Note, however, that this restricts localization of some values ; for
9d42615f 889example, the following statement dies, as of perl 5.10.0, with an error
325192b1
RGS
890I<Modification of a read-only value attempted>, because the $1 variable is
891magical and read-only :
892
893 local $1 = 2;
894
658a9f31
JD
895One exception is the default scalar variable: starting with perl 5.14
896C<local($_)> will always strip all magic from $_, to make it possible
897to safely reuse $_ in a subroutine.
325192b1
RGS
898
899B<WARNING>: Localization of tied arrays and hashes does not currently
900work as described.
fd5a896a 901This will be fixed in a future release of Perl; in the meantime, avoid
89d1beed 902code that relies on any particular behavior of localising tied arrays
fd5a896a 903or hashes (localising individual elements is still okay).
325192b1 904See L<perl58delta/"Localising Tied Arrays and Hashes Is Broken"> for more
fd5a896a 905details.
d74e8afc 906X<local, tie>
fd5a896a 907
325192b1 908=head3 Localization of globs
d74e8afc 909X<local, glob> X<glob>
3e3baf6d 910
325192b1
RGS
911The construct
912
913 local *name;
914
915creates a whole new symbol table entry for the glob C<name> in the
916current package. That means that all variables in its glob slot ($name,
917@name, %name, &name, and the C<name> filehandle) are dynamically reset.
918
919This implies, among other things, that any magic eventually carried by
920those variables is locally lost. In other words, saying C<local */>
921will not have any effect on the internal value of the input record
922separator.
923
325192b1 924=head3 Localization of elements of composite types
d74e8afc 925X<local, composite type element> X<local, array element> X<local, hash element>
3e3baf6d 926
6ee623d5 927It's also worth taking a moment to explain what happens when you
f86cebdf 928C<local>ize a member of a composite type (i.e. an array or hash element).
b77865f5 929In this case, the element is C<local>ized I<by name>. This means that
6ee623d5
GS
930when the scope of the C<local()> ends, the saved value will be
931restored to the hash element whose key was named in the C<local()>, or
932the array element whose index was named in the C<local()>. If that
933element was deleted while the C<local()> was in effect (e.g. by a
934C<delete()> from a hash or a C<shift()> of an array), it will spring
935back into existence, possibly extending an array and filling in the
936skipped elements with C<undef>. For instance, if you say
937
938 %hash = ( 'This' => 'is', 'a' => 'test' );
939 @ary = ( 0..5 );
940 {
941 local($ary[5]) = 6;
942 local($hash{'a'}) = 'drill';
943 while (my $e = pop(@ary)) {
944 print "$e . . .\n";
945 last unless $e > 3;
946 }
947 if (@ary) {
948 $hash{'only a'} = 'test';
949 delete $hash{'a'};
950 }
951 }
952 print join(' ', map { "$_ $hash{$_}" } sort keys %hash),".\n";
953 print "The array has ",scalar(@ary)," elements: ",
954 join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\n";
955
956Perl will print
957
958 6 . . .
959 4 . . .
960 3 . . .
961 This is a test only a test.
962 The array has 6 elements: 0, 1, 2, undef, undef, 5
963
19799a22 964The behavior of local() on non-existent members of composite
7185e5cc
GS
965types is subject to change in future.
966
d361fafa
VP
967=head3 Localized deletion of elements of composite types
968X<delete> X<local, composite type element> X<local, array element> X<local, hash element>
969
970You can use the C<delete local $array[$idx]> and C<delete local $hash{key}>
971constructs to delete a composite type entry for the current block and restore
b77865f5 972it when it ends. They return the array/hash value before the localization,
d361fafa
VP
973which means that they are respectively equivalent to
974
975 do {
976 my $val = $array[$idx];
977 local $array[$idx];
978 delete $array[$idx];
979 $val
980 }
981
982and
983
984 do {
985 my $val = $hash{key};
986 local $hash{key};
987 delete $hash{key};
988 $val
989 }
990
b77865f5
FC
991except that for those the C<local> is
992scoped to the C<do> block. Slices are
d361fafa
VP
993also accepted.
994
995 my %hash = (
996 a => [ 7, 8, 9 ],
997 b => 1,
998 )
999
1000 {
1001 my $a = delete local $hash{a};
1002 # $a is [ 7, 8, 9 ]
1003 # %hash is (b => 1)
1004
1005 {
1006 my @nums = delete local @$a[0, 2]
1007 # @nums is (7, 9)
1008 # $a is [ undef, 8 ]
1009
1010 $a[0] = 999; # will be erased when the scope ends
1011 }
1012 # $a is back to [ 7, 8, 9 ]
1013
1014 }
1015 # %hash is back to its original state
1016
cd06dffe 1017=head2 Lvalue subroutines
d74e8afc 1018X<lvalue> X<subroutine, lvalue>
cd06dffe 1019
cd06dffe
GS
1020It is possible to return a modifiable value from a subroutine.
1021To do this, you have to declare the subroutine to return an lvalue.
1022
1023 my $val;
1024 sub canmod : lvalue {
4a904372 1025 $val; # or: return $val;
cd06dffe
GS
1026 }
1027 sub nomod {
1028 $val;
1029 }
1030
1031 canmod() = 5; # assigns to $val
1032 nomod() = 5; # ERROR
1033
1034The scalar/list context for the subroutine and for the right-hand
1035side of assignment is determined as if the subroutine call is replaced
b77865f5 1036by a scalar. For example, consider:
cd06dffe
GS
1037
1038 data(2,3) = get_data(3,4);
1039
1040Both subroutines here are called in a scalar context, while in:
1041
1042 (data(2,3)) = get_data(3,4);
1043
1044and in:
1045
1046 (data(2),data(3)) = get_data(3,4);
1047
1048all the subroutines are called in a list context.
1049
771cc755 1050Lvalue subroutines are convenient, but you have to keep in mind that,
b77865f5 1051when used with objects, they may violate encapsulation. A normal
771cc755 1052mutator can check the supplied argument before setting the attribute
b77865f5 1053it is protecting, an lvalue subroutine cannot. If you require any
771cc755
JV
1054special processing when storing and retrieving the values, consider
1055using the CPAN module Sentinel or something similar.
e6a32221 1056
ca40957e
FC
1057=head2 Lexical Subroutines
1058X<my sub> X<state sub> X<our sub> X<subroutine, lexical>
1059
ca40957e
FC
1060Beginning with Perl 5.18, you can declare a private subroutine with C<my>
1061or C<state>. As with state variables, the C<state> keyword is only
1062available under C<use feature 'state'> or C<use 5.010> or higher.
1063
06c4bad0
FC
1064Prior to Perl 5.26, lexical subroutines were deemed experimental and were
1065available only under the C<use feature 'lexical_subs'> pragma. They also
1066produced a warning unless the "experimental::lexical_subs" warnings
1067category was disabled.
1068
ca40957e
FC
1069These subroutines are only visible within the block in which they are
1070declared, and only after that declaration:
1071
06c4bad0
FC
1072 # Include these two lines if your code is intended to run under Perl
1073 # versions earlier than 5.26.
f1d34ca8 1074 no warnings "experimental::lexical_subs";
ca40957e
FC
1075 use feature 'lexical_subs';
1076
67bf5a37 1077 foo(); # calls the package/global subroutine
ca40957e 1078 state sub foo {
67bf5a37 1079 foo(); # also calls the package subroutine
ca40957e 1080 }
67bf5a37
LM
1081 foo(); # calls "state" sub
1082 my $ref = \&foo; # take a reference to "state" sub
ca40957e
FC
1083
1084 my sub bar { ... }
67bf5a37 1085 bar(); # calls "my" sub
ca40957e 1086
67bf5a37 1087You can't (directly) write a recursive lexical subroutine:
ca40957e 1088
67bf5a37
LM
1089 # WRONG
1090 my sub baz {
1091 baz();
ca40957e
FC
1092 }
1093
67bf5a37
LM
1094This example fails because C<baz()> refers to the package/global subroutine
1095C<baz>, not the lexical subroutine currently being defined.
1096
1097The solution is to use L<C<__SUB__>|perlfunc/__SUB__>:
1098
1099 my sub baz {
1100 __SUB__->(); # calls itself
1101 }
1102
1103It is possible to predeclare a lexical subroutine. The C<sub foo {...}>
1104subroutine definition syntax respects any previous C<my sub;> or C<state sub;>
1105declaration. Using this to define recursive subroutines is a bad idea,
1106however:
1107
1108 my sub baz; # predeclaration
1109 sub baz { # define the "my" sub
1110 baz(); # WRONG: calls itself, but leaks memory
1111 }
1112
1113Just like C<< my $f; $f = sub { $f->() } >>, this example leaks memory. The
1114name C<baz> is a reference to the subroutine, and the subroutine uses the name
1115C<baz>; they keep each other alive (see L<perlref/Circular References>).
1116
ca40957e
FC
1117=head3 C<state sub> vs C<my sub>
1118
1119What is the difference between "state" subs and "my" subs? Each time that
1120execution enters a block when "my" subs are declared, a new copy of each
1121sub is created. "State" subroutines persist from one execution of the
1122containing block to the next.
1123
1124So, in general, "state" subroutines are faster. But "my" subs are
1125necessary if you want to create closures:
1126
ca40957e
FC
1127 sub whatever {
1128 my $x = shift;
1129 my sub inner {
1130 ... do something with $x ...
1131 }
1132 inner();
1133 }
1134
1135In this example, a new C<$x> is created when C<whatever> is called, and
1136also a new C<inner>, which can see the new C<$x>. A "state" sub will only
1137see the C<$x> from the first call to C<whatever>.
1138
1139=head3 C<our> subroutines
1140
1141Like C<our $variable>, C<our sub> creates a lexical alias to the package
1142subroutine of the same name.
1143
1144The two main uses for this are to switch back to using the package sub
1145inside an inner scope:
1146
ca40957e
FC
1147 sub foo { ... }
1148
1149 sub bar {
1150 my sub foo { ... }
1151 {
1152 # need to use the outer foo here
1153 our sub foo;
1154 foo();
1155 }
1156 }
1157
1158and to make a subroutine visible to other packages in the same scope:
1159
1160 package MySneakyModule;
1161
ca40957e
FC
1162 our sub do_something { ... }
1163
1164 sub do_something_with_caller {
1165 package DB;
1166 () = caller 1; # sets @DB::args
1167 do_something(@args); # uses MySneakyModule::do_something
1168 }
1169
cb1a09d0 1170=head2 Passing Symbol Table Entries (typeglobs)
d74e8afc 1171X<typeglob> X<*>
cb1a09d0 1172
19799a22
GS
1173B<WARNING>: The mechanism described in this section was originally
1174the only way to simulate pass-by-reference in older versions of
1175Perl. While it still works fine in modern versions, the new reference
1176mechanism is generally easier to work with. See below.
a0d0e21e
LW
1177
1178Sometimes you don't want to pass the value of an array to a subroutine
1179but rather the name of it, so that the subroutine can modify the global
1180copy of it rather than working with a local copy. In perl you can
cb1a09d0 1181refer to all objects of a particular name by prefixing the name
5f05dabc 1182with a star: C<*foo>. This is often known as a "typeglob", because the
a0d0e21e
LW
1183star on the front can be thought of as a wildcard match for all the
1184funny prefix characters on variables and subroutines and such.
1185
55497cff 1186When evaluated, the typeglob produces a scalar value that represents
5f05dabc 1187all the objects of that name, including any filehandle, format, or
a0d0e21e 1188subroutine. When assigned to, it causes the name mentioned to refer to
19799a22 1189whatever C<*> value was assigned to it. Example:
a0d0e21e
LW
1190
1191 sub doubleary {
1192 local(*someary) = @_;
1193 foreach $elem (@someary) {
1194 $elem *= 2;
1195 }
1196 }
1197 doubleary(*foo);
1198 doubleary(*bar);
1199
19799a22 1200Scalars are already passed by reference, so you can modify
a0d0e21e 1201scalar arguments without using this mechanism by referring explicitly
1fef88e7 1202to C<$_[0]> etc. You can modify all the elements of an array by passing
f86cebdf
GS
1203all the elements as scalars, but you have to use the C<*> mechanism (or
1204the equivalent reference mechanism) to C<push>, C<pop>, or change the size of
a0d0e21e
LW
1205an array. It will certainly be faster to pass the typeglob (or reference).
1206
1207Even if you don't want to modify an array, this mechanism is useful for
5f05dabc 1208passing multiple arrays in a single LIST, because normally the LIST
a0d0e21e 1209mechanism will merge all the array values so that you can't extract out
55497cff 1210the individual arrays. For more on typeglobs, see
2ae324a7 1211L<perldata/"Typeglobs and Filehandles">.
cb1a09d0 1212
5a964f20 1213=head2 When to Still Use local()
d74e8afc 1214X<local> X<variable, local>
5a964f20 1215
19799a22
GS
1216Despite the existence of C<my>, there are still three places where the
1217C<local> operator still shines. In fact, in these three places, you
5a964f20
TC
1218I<must> use C<local> instead of C<my>.
1219
13a2d996 1220=over 4
5a964f20 1221
551e1d92
RB
1222=item 1.
1223
1224You need to give a global variable a temporary value, especially $_.
5a964f20 1225
f86cebdf
GS
1226The global variables, like C<@ARGV> or the punctuation variables, must be
1227C<local>ized with C<local()>. This block reads in F</etc/motd>, and splits
5a964f20 1228it up into chunks separated by lines of equal signs, which are placed
f86cebdf 1229in C<@Fields>.
5a964f20
TC
1230
1231 {
1232 local @ARGV = ("/etc/motd");
1233 local $/ = undef;
1234 local $_ = <>;
1235 @Fields = split /^\s*=+\s*$/;
1236 }
1237
19799a22 1238It particular, it's important to C<local>ize $_ in any routine that assigns
5a964f20
TC
1239to it. Look out for implicit assignments in C<while> conditionals.
1240
551e1d92
RB
1241=item 2.
1242
1243You need to create a local file or directory handle or a local function.
5a964f20 1244
09bef843
SB
1245A function that needs a filehandle of its own must use
1246C<local()> on a complete typeglob. This can be used to create new symbol
5a964f20
TC
1247table entries:
1248
1249 sub ioqueue {
1250 local (*READER, *WRITER); # not my!
17b63f68 1251 pipe (READER, WRITER) or die "pipe: $!";
5a964f20
TC
1252 return (*READER, *WRITER);
1253 }
1254 ($head, $tail) = ioqueue();
1255
1256See the Symbol module for a way to create anonymous symbol table
1257entries.
1258
1259Because assignment of a reference to a typeglob creates an alias, this
1260can be used to create what is effectively a local function, or at least,
1261a local alias.
1262
1263 {
4a46e268 1264 local *grow = \&shrink; # only until this block exits
555bd962
BG
1265 grow(); # really calls shrink()
1266 move(); # if move() grow()s, it shrink()s too
5a964f20 1267 }
555bd962 1268 grow(); # get the real grow() again
5a964f20
TC
1269
1270See L<perlref/"Function Templates"> for more about manipulating
1271functions by name in this way.
1272
551e1d92
RB
1273=item 3.
1274
1275You want to temporarily change just one element of an array or hash.
5a964f20 1276
f86cebdf 1277You can C<local>ize just one element of an aggregate. Usually this
5a964f20
TC
1278is done on dynamics:
1279
1280 {
1281 local $SIG{INT} = 'IGNORE';
1282 funct(); # uninterruptible
1283 }
1284 # interruptibility automatically restored here
1285
9d42615f 1286But it also works on lexically declared aggregates.
5a964f20
TC
1287
1288=back
1289
cb1a09d0 1290=head2 Pass by Reference
d74e8afc 1291X<pass by reference> X<pass-by-reference> X<reference>
cb1a09d0 1292
55497cff
PP
1293If you want to pass more than one array or hash into a function--or
1294return them from it--and have them maintain their integrity, then
1295you're going to have to use an explicit pass-by-reference. Before you
1296do that, you need to understand references as detailed in L<perlref>.
c07a80fd 1297This section may not make much sense to you otherwise.
cb1a09d0 1298
19799a22
GS
1299Here are a few simple examples. First, let's pass in several arrays
1300to a function and have it C<pop> all of then, returning a new list
1301of all their former last elements:
cb1a09d0
AD
1302
1303 @tailings = popmany ( \@a, \@b, \@c, \@d );
1304
1305 sub popmany {
1306 my $aref;
8b7906d1 1307 my @retlist;
cb1a09d0
AD
1308 foreach $aref ( @_ ) {
1309 push @retlist, pop @$aref;
54310121 1310 }
cb1a09d0 1311 return @retlist;
54310121 1312 }
cb1a09d0 1313
54310121 1314Here's how you might write a function that returns a
cb1a09d0
AD
1315list of keys occurring in all the hashes passed to it:
1316
54310121 1317 @common = inter( \%foo, \%bar, \%joe );
cb1a09d0
AD
1318 sub inter {
1319 my ($k, $href, %seen); # locals
1320 foreach $href (@_) {
1321 while ( $k = each %$href ) {
1322 $seen{$k}++;
54310121
PP
1323 }
1324 }
cb1a09d0 1325 return grep { $seen{$_} == @_ } keys %seen;
54310121 1326 }
cb1a09d0 1327
5f05dabc 1328So far, we're using just the normal list return mechanism.
54310121
PP
1329What happens if you want to pass or return a hash? Well,
1330if you're using only one of them, or you don't mind them
cb1a09d0 1331concatenating, then the normal calling convention is ok, although
54310121 1332a little expensive.
cb1a09d0
AD
1333
1334Where people get into trouble is here:
1335
1336 (@a, @b) = func(@c, @d);
1337or
1338 (%a, %b) = func(%c, %d);
1339
19799a22
GS
1340That syntax simply won't work. It sets just C<@a> or C<%a> and
1341clears the C<@b> or C<%b>. Plus the function didn't get passed
1342into two separate arrays or hashes: it got one long list in C<@_>,
1343as always.
cb1a09d0
AD
1344
1345If you can arrange for everyone to deal with this through references, it's
1346cleaner code, although not so nice to look at. Here's a function that
1347takes two array references as arguments, returning the two array elements
1348in order of how many elements they have in them:
1349
1350 ($aref, $bref) = func(\@c, \@d);
1351 print "@$aref has more than @$bref\n";
1352 sub func {
1353 my ($cref, $dref) = @_;
1354 if (@$cref > @$dref) {
1355 return ($cref, $dref);
1356 } else {
c07a80fd 1357 return ($dref, $cref);
54310121
PP
1358 }
1359 }
cb1a09d0
AD
1360
1361It turns out that you can actually do this also:
1362
1363 (*a, *b) = func(\@c, \@d);
1364 print "@a has more than @b\n";
1365 sub func {
1366 local (*c, *d) = @_;
1367 if (@c > @d) {
1368 return (\@c, \@d);
1369 } else {
1370 return (\@d, \@c);
54310121
PP
1371 }
1372 }
cb1a09d0
AD
1373
1374Here we're using the typeglobs to do symbol table aliasing. It's
19799a22 1375a tad subtle, though, and also won't work if you're using C<my>
09bef843 1376variables, because only globals (even in disguise as C<local>s)
19799a22 1377are in the symbol table.
5f05dabc
PP
1378
1379If you're passing around filehandles, you could usually just use the bare
19799a22
GS
1380typeglob, like C<*STDOUT>, but typeglobs references work, too.
1381For example:
5f05dabc
PP
1382
1383 splutter(\*STDOUT);
1384 sub splutter {
1385 my $fh = shift;
1386 print $fh "her um well a hmmm\n";
1387 }
1388
1389 $rec = get_rec(\*STDIN);
1390 sub get_rec {
1391 my $fh = shift;
1392 return scalar <$fh>;
1393 }
1394
19799a22
GS
1395If you're planning on generating new filehandles, you could do this.
1396Notice to pass back just the bare *FH, not its reference.
5f05dabc
PP
1397
1398 sub openit {
19799a22 1399 my $path = shift;
5f05dabc 1400 local *FH;
e05a3a1e 1401 return open (FH, $path) ? *FH : undef;
54310121 1402 }
5f05dabc 1403
cb1a09d0 1404=head2 Prototypes
d74e8afc 1405X<prototype> X<subroutine, prototype>
cb1a09d0 1406
19799a22 1407Perl supports a very limited kind of compile-time argument checking
eedb00fa
PM
1408using function prototyping. This can be declared in either the PROTO
1409section or with a L<prototype attribute|attributes/Built-in Attributes>.
30d9c59b 1410If you declare either of
cb1a09d0 1411
26230909
AC
1412 sub mypush (\@@)
1413 sub mypush :prototype(\@@)
30d9c59b
Z
1414
1415then C<mypush()> takes arguments exactly like C<push()> does.
1416
1417If subroutine signatures are enabled (see L</Signatures>), then
1418the shorter PROTO syntax is unavailable, because it would clash with
1419signatures. In that case, a prototype can only be declared in the form
1420of an attribute.
cb1a09d0 1421
30d9c59b 1422The
19799a22
GS
1423function declaration must be visible at compile time. The prototype
1424affects only interpretation of new-style calls to the function,
1425where new-style is defined as not using the C<&> character. In
1426other words, if you call it like a built-in function, then it behaves
1427like a built-in function. If you call it like an old-fashioned
1428subroutine, then it behaves like an old-fashioned subroutine. It
1429naturally falls out from this rule that prototypes have no influence
1430on subroutine references like C<\&foo> or on indirect subroutine
c47ff5f1 1431calls like C<&{$subref}> or C<< $subref->() >>.
c07a80fd
PP
1432
1433Method calls are not influenced by prototypes either, because the
19799a22
GS
1434function to be called is indeterminate at compile time, since
1435the exact code called depends on inheritance.
cb1a09d0 1436
19799a22
GS
1437Because the intent of this feature is primarily to let you define
1438subroutines that work like built-in functions, here are prototypes
1439for some other functions that parse almost exactly like the
1440corresponding built-in.
cb1a09d0 1441
555bd962
BG
1442 Declared as Called as
1443
1444 sub mylink ($$) mylink $old, $new
1445 sub myvec ($$$) myvec $var, $offset, 1
1446 sub myindex ($$;$) myindex &getstring, "substr"
1447 sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off
1448 sub myreverse (@) myreverse $a, $b, $c
1449 sub myjoin ($@) myjoin ":", $a, $b, $c
26230909
AC
1450 sub mypop (\@) mypop @array
1451 sub mysplice (\@$$@) mysplice @array, 0, 2, @pushme
1452 sub mykeys (\[%@]) mykeys %{$hashref}
555bd962
BG
1453 sub myopen (*;$) myopen HANDLE, $name
1454 sub mypipe (**) mypipe READHANDLE, WRITEHANDLE
1455 sub mygrep (&@) mygrep { /foo/ } $a, $b, $c
1456 sub myrand (;$) myrand 42
1457 sub mytime () mytime
cb1a09d0 1458
c07a80fd 1459Any backslashed prototype character represents an actual argument
ae7a3cfa 1460that must start with that character (optionally preceded by C<my>,
b91b7d1a
FC
1461C<our> or C<local>), with the exception of C<$>, which will
1462accept any scalar lvalue expression, such as C<$foo = 7> or
b77865f5 1463C<< my_function()->[0] >>. The value passed as part of C<@_> will be a
ae7a3cfa
FC
1464reference to the actual argument given in the subroutine call,
1465obtained by applying C<\> to that argument.
c07a80fd 1466
c035a075 1467You can use the C<\[]> backslash group notation to specify more than one
b77865f5 1468allowed argument type. For example:
5b794e05
JH
1469
1470 sub myref (\[$@%&*])
1471
1472will allow calling myref() as
1473
1474 myref $var
1475 myref @array
1476 myref %hash
1477 myref &sub
1478 myref *glob
1479
1480and the first argument of myref() will be a reference to
1481a scalar, an array, a hash, a code, or a glob.
1482
c07a80fd 1483Unbackslashed prototype characters have special meanings. Any
19799a22 1484unbackslashed C<@> or C<%> eats all remaining arguments, and forces
f86cebdf
GS
1485list context. An argument represented by C<$> forces scalar context. An
1486C<&> requires an anonymous subroutine, which, if passed as the first
0df79f0c
GS
1487argument, does not require the C<sub> keyword or a subsequent comma.
1488
1489A C<*> allows the subroutine to accept a bareword, constant, scalar expression,
648ca4f7
GS
1490typeglob, or a reference to a typeglob in that slot. The value will be
1491available to the subroutine either as a simple scalar, or (in the latter
0df79f0c
GS
1492two cases) as a reference to the typeglob. If you wish to always convert
1493such arguments to a typeglob reference, use Symbol::qualify_to_ref() as
1494follows:
1495
1496 use Symbol 'qualify_to_ref';
1497
1498 sub foo (*) {
1499 my $fh = qualify_to_ref(shift, caller);
1500 ...
1501 }
c07a80fd 1502
c035a075
DG
1503The C<+> prototype is a special alternative to C<$> that will act like
1504C<\[@%]> when given a literal array or hash variable, but will otherwise
1505force scalar context on the argument. This is useful for functions which
1506should accept either a literal array or an array reference as the argument:
1507
cba5a3b0 1508 sub mypush (+@) {
c035a075
DG
1509 my $aref = shift;
1510 die "Not an array or arrayref" unless ref $aref eq 'ARRAY';
1511 push @$aref, @_;
1512 }
1513
1514When using the C<+> prototype, your function must check that the argument
1515is of an acceptable type.
1516
859a4967 1517A semicolon (C<;>) separates mandatory arguments from optional arguments.
19799a22 1518It is redundant before C<@> or C<%>, which gobble up everything else.
cb1a09d0 1519
34daab0f
RGS
1520As the last character of a prototype, or just before a semicolon, a C<@>
1521or a C<%>, you can use C<_> in place of C<$>: if this argument is not
1522provided, C<$_> will be used instead.
859a4967 1523
19799a22
GS
1524Note how the last three examples in the table above are treated
1525specially by the parser. C<mygrep()> is parsed as a true list
1526operator, C<myrand()> is parsed as a true unary operator with unary
1527precedence the same as C<rand()>, and C<mytime()> is truly without
1528arguments, just like C<time()>. That is, if you say
cb1a09d0
AD
1529
1530 mytime +2;
1531
f86cebdf 1532you'll get C<mytime() + 2>, not C<mytime(2)>, which is how it would be parsed
3a8944db
FC
1533without a prototype. If you want to force a unary function to have the
1534same precedence as a list operator, add C<;> to the end of the prototype:
1535
1536 sub mygetprotobynumber($;);
1537 mygetprotobynumber $a > $b; # parsed as mygetprotobynumber($a > $b)
cb1a09d0 1538
19799a22
GS
1539The interesting thing about C<&> is that you can generate new syntax with it,
1540provided it's in the initial position:
d74e8afc 1541X<&>
cb1a09d0 1542
6d28dffb 1543 sub try (&@) {
cb1a09d0
AD
1544 my($try,$catch) = @_;
1545 eval { &$try };
1546 if ($@) {
1547 local $_ = $@;
1548 &$catch;
1549 }
1550 }
55497cff 1551 sub catch (&) { $_[0] }
cb1a09d0
AD
1552
1553 try {
1554 die "phooey";
1555 } catch {
1556 /phooey/ and print "unphooey\n";
1557 };
1558
f86cebdf 1559That prints C<"unphooey">. (Yes, there are still unresolved
19799a22 1560issues having to do with visibility of C<@_>. I'm ignoring that
f86cebdf 1561question for the moment. (But note that if we make C<@_> lexically
cb1a09d0 1562scoped, those anonymous subroutines can act like closures... (Gee,
5f05dabc 1563is this sounding a little Lispish? (Never mind.))))
cb1a09d0 1564
19799a22 1565And here's a reimplementation of the Perl C<grep> operator:
d74e8afc 1566X<grep>
cb1a09d0
AD
1567
1568 sub mygrep (&@) {
1569 my $code = shift;
1570 my @result;
1571 foreach $_ (@_) {
6e47f808 1572 push(@result, $_) if &$code;
cb1a09d0
AD
1573 }
1574 @result;
1575 }
a0d0e21e 1576
cb1a09d0
AD
1577Some folks would prefer full alphanumeric prototypes. Alphanumerics have
1578been intentionally left out of prototypes for the express purpose of
1579someday in the future adding named, formal parameters. The current
1580mechanism's main goal is to let module writers provide better diagnostics
1581for module users. Larry feels the notation quite understandable to Perl
1582programmers, and that it will not intrude greatly upon the meat of the
1583module, nor make it harder to read. The line noise is visually
1584encapsulated into a small pill that's easy to swallow.
1585
420cdfc1
ST
1586If you try to use an alphanumeric sequence in a prototype you will
1587generate an optional warning - "Illegal character in prototype...".
1588Unfortunately earlier versions of Perl allowed the prototype to be
1589used as long as its prefix was a valid prototype. The warning may be
1590upgraded to a fatal error in a future version of Perl once the
1591majority of offending code is fixed.
1592
cb1a09d0
AD
1593It's probably best to prototype new functions, not retrofit prototyping
1594into older ones. That's because you must be especially careful about
1595silent impositions of differing list versus scalar contexts. For example,
1596if you decide that a function should take just one parameter, like this:
1597
1598 sub func ($) {
1599 my $n = shift;
1600 print "you gave me $n\n";
54310121 1601 }
cb1a09d0
AD
1602
1603and someone has been calling it with an array or expression
1604returning a list:
1605
1606 func(@foo);
f2606479 1607 func( $text =~ /\w+/g );
cb1a09d0 1608
19799a22 1609Then you've just supplied an automatic C<scalar> in front of their
f86cebdf 1610argument, which can be more than a bit surprising. The old C<@foo>
cb1a09d0 1611which used to hold one thing doesn't get passed in. Instead,
19799a22 1612C<func()> now gets passed in a C<1>; that is, the number of elements
f2606479
LM
1613in C<@foo>. And the C<m//g> gets called in scalar context so instead of a
1614list of words it returns a boolean result and advances C<pos($text)>. Ouch!
cb1a09d0 1615
eb40d2ca
PM
1616If a sub has both a PROTO and a BLOCK, the prototype is not applied
1617until after the BLOCK is completely defined. This means that a recursive
1618function with a prototype has to be predeclared for the prototype to take
1619effect, like so:
1620
1621 sub foo($$);
1622 sub foo($$) {
1623 foo 1, 2;
1624 }
1625
5f05dabc 1626This is all very powerful, of course, and should be used only in moderation
54310121 1627to make the world a better place.
44a8e56a
PP
1628
1629=head2 Constant Functions
d74e8afc 1630X<constant>
44a8e56a
PP
1631
1632Functions with a prototype of C<()> are potential candidates for
19799a22
GS
1633inlining. If the result after optimization and constant folding
1634is either a constant or a lexically-scoped scalar which has no other
54310121 1635references, then it will be used in place of function calls made
19799a22
GS
1636without C<&>. Calls made using C<&> are never inlined. (See
1637F<constant.pm> for an easy way to declare most constants.)
44a8e56a 1638
5a964f20 1639The following functions would all be inlined:
44a8e56a 1640
699e6cd4
TP
1641 sub pi () { 3.14159 } # Not exact, but close.
1642 sub PI () { 4 * atan2 1, 1 } # As good as it gets,
1643 # and it's inlined, too!
44a8e56a
PP
1644 sub ST_DEV () { 0 }
1645 sub ST_INO () { 1 }
1646
1647 sub FLAG_FOO () { 1 << 8 }
1648 sub FLAG_BAR () { 1 << 9 }
1649 sub FLAG_MASK () { FLAG_FOO | FLAG_BAR }
54310121
PP
1650
1651 sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) }
88267271 1652
1653 sub N () { int(OPT_BAZ) / 3 }
1654
1655 sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO }
d3c633ba 1656 sub FOO_SET2 () { if (FLAG_MASK & FLAG_FOO) { 1 } }
88267271 1657
d3c633ba
FC
1658(Be aware that the last example was not always inlined in Perl 5.20 and
1659earlier, which did not behave consistently with subroutines containing
1660inner scopes.) You can countermand inlining by using an explicit
1661C<return>:
88267271 1662
1663 sub baz_val () {
44a8e56a
PP
1664 if (OPT_BAZ) {
1665 return 23;
1666 }
1667 else {
1668 return 42;
1669 }
1670 }
d3c633ba 1671 sub bonk_val () { return 12345 }
cb1a09d0 1672
fe39f0d5
AB
1673As alluded to earlier you can also declare inlined subs dynamically at
1674BEGIN time if their body consists of a lexically-scoped scalar which
b77865f5 1675has no other references. Only the first example here will be inlined:
fe39f0d5
AB
1676
1677 BEGIN {
1678 my $var = 1;
1679 no strict 'refs';
1680 *INLINED = sub () { $var };
1681 }
1682
1683 BEGIN {
1684 my $var = 1;
1685 my $ref = \$var;
1686 no strict 'refs';
1687 *NOT_INLINED = sub () { $var };
1688 }
1689
1690A not so obvious caveat with this (see [RT #79908]) is that the
1691variable will be immediately inlined, and will stop behaving like a
1692normal lexical variable, e.g. this will print C<79907>, not C<79908>:
1693
1694 BEGIN {
1695 my $x = 79907;
1696 *RT_79908 = sub () { $x };
1697 $x++;
1698 }
1699 print RT_79908(); # prints 79907
1700
d3c633ba
FC
1701As of Perl 5.22, this buggy behavior, while preserved for backward
1702compatibility, is detected and emits a deprecation warning. If you want
1703the subroutine to be inlined (with no warning), make sure the variable is
1704not used in a context where it could be modified aside from where it is
1705declared.
1706
1707 # Fine, no warning
1708 BEGIN {
1709 my $x = 54321;
1710 *INLINED = sub () { $x };
1711 }
1712 # Warns. Future Perl versions will stop inlining it.
1713 BEGIN {
1714 my $x;
1715 $x = 54321;
1716 *ALSO_INLINED = sub () { $x };
1717 }
1718
99734069
FC
1719Perl 5.22 also introduces the experimental "const" attribute as an
1720alternative. (Disable the "experimental::const_attr" warnings if you want
1721to use it.) When applied to an anonymous subroutine, it forces the sub to
1722be called when the C<sub> expression is evaluated. The return value is
1723captured and turned into a constant subroutine:
1724
1725 my $x = 54321;
1726 *INLINED = sub : const { $x };
1727 $x++;
1728
1729The return value of C<INLINED> in this example will always be 54321,
1730regardless of later modifications to $x. You can also put any arbitrary
1731code inside the sub, at it will be executed immediately and its return
1732value captured the same way.
1733
fe39f0d5
AB
1734If you really want a subroutine with a C<()> prototype that returns a
1735lexical variable you can easily force it to not be inlined by adding
1736an explicit C<return>:
1737
1738 BEGIN {
1739 my $x = 79907;
1740 *RT_79908 = sub () { return $x };
1741 $x++;
1742 }
1743 print RT_79908(); # prints 79908
1744
1745The easiest way to tell if a subroutine was inlined is by using
d3c633ba 1746L<B::Deparse>. Consider this example of two subroutines returning
fe39f0d5
AB
1747C<1>, one with a C<()> prototype causing it to be inlined, and one
1748without (with deparse output truncated for clarity):
1749
cb07e2f2
KW
1750 $ perl -MO=Deparse -le 'sub ONE { 1 } if (ONE) { print ONE if ONE }'
1751 sub ONE {
1752 1;
1753 }
1754 if (ONE ) {
1755 print ONE() if ONE ;
1756 }
1757 $ perl -MO=Deparse -le 'sub ONE () { 1 } if (ONE) { print ONE if ONE }'
1758 sub ONE () { 1 }
1759 do {
1760 print 1
1761 };
fe39f0d5
AB
1762
1763If you redefine a subroutine that was eligible for inlining, you'll
b77865f5 1764get a warning by default. You can use this warning to tell whether or
fe39f0d5
AB
1765not a particular subroutine is considered inlinable, since it's
1766different than the warning for overriding non-inlined subroutines:
1767
1768 $ perl -e 'sub one () {1} sub one () {2}'
1769 Constant subroutine one redefined at -e line 1.
1770 $ perl -we 'sub one {1} sub one {2}'
1771 Subroutine one redefined at -e line 1.
1772
1773The warning is considered severe enough not to be affected by the
1774B<-w> switch (or its absence) because previously compiled invocations
1775of the function will still be using the old value of the function. If
1776you need to be able to redefine the subroutine, you need to ensure
1777that it isn't inlined, either by dropping the C<()> prototype (which
1778changes calling semantics, so beware) or by thwarting the inlining
d3c633ba
FC
1779mechanism in some other way, e.g. by adding an explicit C<return>, as
1780mentioned above:
fe39f0d5
AB
1781
1782 sub not_inlined () { return 23 }
4cee8e80 1783
19799a22 1784=head2 Overriding Built-in Functions
d74e8afc 1785X<built-in> X<override> X<CORE> X<CORE::GLOBAL>
a0d0e21e 1786
19799a22 1787Many built-in functions may be overridden, though this should be tried
5f05dabc 1788only occasionally and for good reason. Typically this might be
19799a22 1789done by a package attempting to emulate missing built-in functionality
a0d0e21e
LW
1790on a non-Unix system.
1791
163e3a99
JP
1792Overriding may be done only by importing the name from a module at
1793compile time--ordinary predeclaration isn't good enough. However, the
19799a22
GS
1794C<use subs> pragma lets you, in effect, predeclare subs
1795via the import syntax, and these names may then override built-in ones:
a0d0e21e
LW
1796
1797 use subs 'chdir', 'chroot', 'chmod', 'chown';
1798 chdir $somewhere;
1799 sub chdir { ... }
1800
19799a22
GS
1801To unambiguously refer to the built-in form, precede the
1802built-in name with the special package qualifier C<CORE::>. For example,
1803saying C<CORE::open()> always refers to the built-in C<open()>, even
fb73857a 1804if the current package has imported some other subroutine called
19799a22 1805C<&open()> from elsewhere. Even though it looks like a regular
4aaa4757
FC
1806function call, it isn't: the CORE:: prefix in that case is part of Perl's
1807syntax, and works for any keyword, regardless of what is in the CORE
1808package. Taking a reference to it, that is, C<\&CORE::open>, only works
1809for some keywords. See L<CORE>.
fb73857a 1810
19799a22
GS
1811Library modules should not in general export built-in names like C<open>
1812or C<chdir> as part of their default C<@EXPORT> list, because these may
a0d0e21e 1813sneak into someone else's namespace and change the semantics unexpectedly.
19799a22 1814Instead, if the module adds that name to C<@EXPORT_OK>, then it's
a0d0e21e
LW
1815possible for a user to import the name explicitly, but not implicitly.
1816That is, they could say
1817
1818 use Module 'open';
1819
19799a22 1820and it would import the C<open> override. But if they said
a0d0e21e
LW
1821
1822 use Module;
1823
19799a22 1824they would get the default imports without overrides.
a0d0e21e 1825
19799a22 1826The foregoing mechanism for overriding built-in is restricted, quite
95d94a4f 1827deliberately, to the package that requests the import. There is a second
19799a22 1828method that is sometimes applicable when you wish to override a built-in
95d94a4f
GS
1829everywhere, without regard to namespace boundaries. This is achieved by
1830importing a sub into the special namespace C<CORE::GLOBAL::>. Here is an
1831example that quite brazenly replaces the C<glob> operator with something
1832that understands regular expressions.
1833
1834 package REGlob;
1835 require Exporter;
1836 @ISA = 'Exporter';
1837 @EXPORT_OK = 'glob';
1838
1839 sub import {
1840 my $pkg = shift;
1841 return unless @_;
1842 my $sym = shift;
1843 my $where = ($sym =~ s/^GLOBAL_// ? 'CORE::GLOBAL' : caller(0));
1844 $pkg->export($where, $sym, @_);
1845 }
1846
1847 sub glob {
1848 my $pat = shift;
1849 my @got;
7b815c67
RGS
1850 if (opendir my $d, '.') {
1851 @got = grep /$pat/, readdir $d;
1852 closedir $d;
19799a22
GS
1853 }
1854 return @got;
95d94a4f
GS
1855 }
1856 1;
1857
1858And here's how it could be (ab)used:
1859
1860 #use REGlob 'GLOBAL_glob'; # override glob() in ALL namespaces
1861 package Foo;
1862 use REGlob 'glob'; # override glob() in Foo:: only
1863 print for <^[a-z_]+\.pm\$>; # show all pragmatic modules
1864
19799a22 1865The initial comment shows a contrived, even dangerous example.
95d94a4f 1866By overriding C<glob> globally, you would be forcing the new (and
19799a22 1867subversive) behavior for the C<glob> operator for I<every> namespace,
95d94a4f
GS
1868without the complete cognizance or cooperation of the modules that own
1869those namespaces. Naturally, this should be done with extreme caution--if
1870it must be done at all.
1871
1872The C<REGlob> example above does not implement all the support needed to
19799a22 1873cleanly override perl's C<glob> operator. The built-in C<glob> has
95d94a4f 1874different behaviors depending on whether it appears in a scalar or list
19799a22 1875context, but our C<REGlob> doesn't. Indeed, many perl built-in have such
95d94a4f
GS
1876context sensitive behaviors, and these must be adequately supported by
1877a properly written override. For a fully functional example of overriding
1878C<glob>, study the implementation of C<File::DosGlob> in the standard
1879library.
1880
77bc9082
RGS
1881When you override a built-in, your replacement should be consistent (if
1882possible) with the built-in native syntax. You can achieve this by using
1883a suitable prototype. To get the prototype of an overridable built-in,
1884use the C<prototype> function with an argument of C<"CORE::builtin_name">
1885(see L<perlfunc/prototype>).
1886
1887Note however that some built-ins can't have their syntax expressed by a
1888prototype (such as C<system> or C<chomp>). If you override them you won't
1889be able to fully mimic their original syntax.
1890
fe854a6f 1891The built-ins C<do>, C<require> and C<glob> can also be overridden, but due
77bc9082
RGS
1892to special magic, their original syntax is preserved, and you don't have
1893to define a prototype for their replacements. (You can't override the
1894C<do BLOCK> syntax, though).
1895
1896C<require> has special additional dark magic: if you invoke your
1897C<require> replacement as C<require Foo::Bar>, it will actually receive
1898the argument C<"Foo/Bar.pm"> in @_. See L<perlfunc/require>.
1899
1900And, as you'll have noticed from the previous example, if you override
593b9c14 1901C<glob>, the C<< <*> >> glob operator is overridden as well.
77bc9082 1902
9b3023bc 1903In a similar fashion, overriding the C<readline> function also overrides
b77865f5 1904the equivalent I/O operator C<< <FILEHANDLE> >>. Also, overriding
e3f73d4e 1905C<readpipe> also overrides the operators C<``> and C<qx//>.
9b3023bc 1906
fe854a6f 1907Finally, some built-ins (e.g. C<exists> or C<grep>) can't be overridden.
77bc9082 1908
a0d0e21e 1909=head2 Autoloading
d74e8afc 1910X<autoloading> X<AUTOLOAD>
a0d0e21e 1911
19799a22
GS
1912If you call a subroutine that is undefined, you would ordinarily
1913get an immediate, fatal error complaining that the subroutine doesn't
1914exist. (Likewise for subroutines being used as methods, when the
1915method doesn't exist in any base class of the class's package.)
1916However, if an C<AUTOLOAD> subroutine is defined in the package or
1917packages used to locate the original subroutine, then that
1918C<AUTOLOAD> subroutine is called with the arguments that would have
1919been passed to the original subroutine. The fully qualified name
1920of the original subroutine magically appears in the global $AUTOLOAD
1921variable of the same package as the C<AUTOLOAD> routine. The name
1922is not passed as an ordinary argument because, er, well, just
593b9c14 1923because, that's why. (As an exception, a method call to a nonexistent
80ee23cd 1924C<import> or C<unimport> method is just skipped instead. Also, if
5b36e945
FC
1925the AUTOLOAD subroutine is an XSUB, there are other ways to retrieve the
1926subroutine name. See L<perlguts/Autoloading with XSUBs> for details.)
80ee23cd 1927
19799a22
GS
1928
1929Many C<AUTOLOAD> routines load in a definition for the requested
1930subroutine using eval(), then execute that subroutine using a special
1931form of goto() that erases the stack frame of the C<AUTOLOAD> routine
1932without a trace. (See the source to the standard module documented
1933in L<AutoLoader>, for example.) But an C<AUTOLOAD> routine can
1934also just emulate the routine and never define it. For example,
1935let's pretend that a function that wasn't defined should just invoke
1936C<system> with those arguments. All you'd do is:
cb1a09d0
AD
1937
1938 sub AUTOLOAD {
1939 my $program = $AUTOLOAD;
1940 $program =~ s/.*:://;
1941 system($program, @_);
54310121 1942 }
cb1a09d0 1943 date();
6d28dffb 1944 who('am', 'i');
cb1a09d0
AD
1945 ls('-l');
1946
19799a22
GS
1947In fact, if you predeclare functions you want to call that way, you don't
1948even need parentheses:
cb1a09d0
AD
1949
1950 use subs qw(date who ls);
1951 date;
1952 who "am", "i";
593b9c14 1953 ls '-l';
cb1a09d0 1954
13058d67 1955A more complete example of this is the Shell module on CPAN, which
19799a22 1956can treat undefined subroutine calls as calls to external programs.
a0d0e21e 1957
19799a22
GS
1958Mechanisms are available to help modules writers split their modules
1959into autoloadable files. See the standard AutoLoader module
6d28dffb
PP
1960described in L<AutoLoader> and in L<AutoSplit>, the standard
1961SelfLoader modules in L<SelfLoader>, and the document on adding C
19799a22 1962functions to Perl code in L<perlxs>.
cb1a09d0 1963
09bef843 1964=head2 Subroutine Attributes
d74e8afc 1965X<attribute> X<subroutine, attribute> X<attrs>
09bef843
SB
1966
1967A subroutine declaration or definition may have a list of attributes
1968associated with it. If such an attribute list is present, it is
0120eecf 1969broken up at space or colon boundaries and treated as though a
09bef843
SB
1970C<use attributes> had been seen. See L<attributes> for details
1971about what attributes are currently supported.
1972Unlike the limitation with the obsolescent C<use attrs>, the
1973C<sub : ATTRLIST> syntax works to associate the attributes with
1974a pre-declaration, and not just with a subroutine definition.
1975
1976The attributes must be valid as simple identifier names (without any
1977punctuation other than the '_' character). They may have a parameter
1978list appended, which is only checked for whether its parentheses ('(',')')
1979nest properly.
1980
1981Examples of valid syntax (even though the attributes are unknown):
1982
4358a253
SS
1983 sub fnord (&\%) : switch(10,foo(7,3)) : expensive;
1984 sub plugh () : Ugly('\(") :Bad;
09bef843
SB
1985 sub xyzzy : _5x5 { ... }
1986
1987Examples of invalid syntax:
1988
4358a253
SS
1989 sub fnord : switch(10,foo(); # ()-string not balanced
1990 sub snoid : Ugly('('); # ()-string not balanced
1991 sub xyzzy : 5x5; # "5x5" not a valid identifier
1992 sub plugh : Y2::north; # "Y2::north" not a simple identifier
1993 sub snurt : foo + bar; # "+" not a colon or space
09bef843
SB
1994
1995The attribute list is passed as a list of constant strings to the code
1996which associates them with the subroutine. In particular, the second example
1997of valid syntax above currently looks like this in terms of how it's
1998parsed and invoked:
1999
2000 use attributes __PACKAGE__, \&plugh, q[Ugly('\(")], 'Bad';
2001
2002For further details on attribute lists and their manipulation,
a0ae32d3 2003see L<attributes> and L<Attribute::Handlers>.
09bef843 2004
cb1a09d0 2005=head1 SEE ALSO
a0d0e21e 2006
19799a22
GS
2007See L<perlref/"Function Templates"> for more about references and closures.
2008See L<perlxs> if you'd like to learn about calling C subroutines from Perl.
a2293a43 2009See L<perlembed> if you'd like to learn about calling Perl subroutines from C.
19799a22
GS
2010See L<perlmod> to learn about bundling up your functions in separate files.
2011See L<perlmodlib> to learn what library modules come standard on your system.
82e1c0d9 2012See L<perlootut> to learn how to make object method calls.