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