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