2 X<subroutine> X<function>
4 perlsub - Perl subroutines
8 To declare subroutines:
9 X<subroutine, declaration> X<sub>
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
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
21 use feature 'signatures';
22 sub NAME(SIG) BLOCK # with signature
23 sub NAME :ATTRS (SIG) BLOCK # with signature, attributes
24 sub NAME :prototype(PROTO) (SIG) BLOCK # with signature, prototype
26 To define an anonymous subroutine at runtime:
27 X<subroutine, anonymous>
29 $subref = sub BLOCK; # no proto
30 $subref = sub (PROTO) BLOCK; # with proto
31 $subref = sub : ATTRS BLOCK; # with attributes
32 $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes
34 use feature 'signatures';
35 $subref = sub (SIG) BLOCK; # with signature
36 $subref = sub : ATTRS(SIG) BLOCK; # with signature, attributes
38 To import subroutines:
41 use MODULE qw(NAME1 NAME2 NAME3);
44 X<subroutine, call> X<call>
46 NAME(LIST); # & is optional with parentheses.
47 NAME LIST; # Parentheses optional if predeclared/imported.
48 &NAME(LIST); # Circumvent prototypes.
49 &NAME; # Makes current @_ visible to called subroutine.
53 Like many languages, Perl provides for user-defined subroutines.
54 These may be located anywhere in the main program, loaded in from
55 other files via the C<do>, C<require>, or C<use> keywords, or
56 generated on the fly using C<eval> or anonymous subroutines.
57 You can even call a function indirectly using a variable containing
58 its name or a CODE reference.
60 The Perl model for function call and return values is simple: all
61 functions are passed as parameters one single flat list of scalars, and
62 all functions likewise return to their caller one single flat list of
63 scalars. Any arrays or hashes in these call and return lists will
64 collapse, losing their identities--but you may always use
65 pass-by-reference instead to avoid this. Both call and return lists may
66 contain as many or as few scalar elements as you'd like. (Often a
67 function without an explicit return statement is called a subroutine, but
68 there's really no difference from Perl's perspective.)
69 X<subroutine, parameter> X<parameter>
71 In a subroutine that does not use signatures, any arguments passed in
72 show up in the array C<@_>. Therefore, if you called a function with
73 two arguments, those would be stored in C<$_[0]> and C<$_[1]>. The
74 array C<@_> is a local array, but its elements are aliases for the
75 actual scalar parameters. In particular, if an element C<$_[0]> is
76 updated, the corresponding argument is updated (or an error occurs if it
77 is not updatable). If an argument is an array or hash element which did
78 not exist when the function was called, that element is created only
79 when (and if) it is modified or a reference to it is taken. (Some
80 earlier versions of Perl created the element whether or not the element
81 was assigned to.) Assigning to the whole array C<@_> removes that
82 aliasing, and does not update any arguments.
83 X<subroutine, argument> X<argument> X<@_>
85 In a subroutine that uses signatures (see L</Signatures> below),
86 arguments are assigned into lexical variables introduced by the
87 signature. In the current implementation of perl they are also
88 accessible in the C<@_> array in the same way as for non-signature
89 subroutines, but accessing them in this manner is now discouraged inside
90 such a signature-using subroutine.
92 A C<return> statement may be used to exit a subroutine, optionally
93 specifying the returned value, which will be evaluated in the
94 appropriate context (list, scalar, or void) depending on the context of
95 the subroutine call. If you specify no return value, the subroutine
96 returns an empty list in list context, the undefined value in scalar
97 context, or nothing in void context. If you return one or more
98 aggregates (arrays and hashes), these will be flattened together into
99 one large indistinguishable list.
101 If no C<return> is found and if the last statement is an expression, its
102 value is returned. If the last statement is a loop control structure
103 like a C<foreach> or a C<while>, the returned value is unspecified. The
104 empty sub returns the empty list.
105 X<subroutine, return value> X<return value> X<return>
107 Aside from an experimental facility (see L</Signatures> below),
108 Perl does not have named formal parameters. In practice all you
109 do is assign to a C<my()> list of these. Variables that aren't
110 declared to be private are global variables. For gory details
111 on creating private variables, see L</"Private Variables via my()">
112 and L</"Temporary Values via local()">. To create protected
113 environments for a set of functions in a separate package (and
114 probably a separate file), see L<perlmod/"Packages">.
115 X<formal parameter> X<parameter, formal>
122 $max = $foo if $max < $foo;
126 $bestday = max($mon,$tue,$wed,$thu,$fri);
130 # get a line, combining continuation lines
131 # that start with whitespace
134 $thisline = $lookahead; # global variables!
135 LINE: while (defined($lookahead = <STDIN>)) {
136 if ($lookahead =~ /^[ \t]/) {
137 $thisline .= $lookahead;
146 $lookahead = <STDIN>; # get first line
147 while (defined($line = get_line())) {
151 Assigning to a list of private variables to name your arguments:
154 my($key, $value) = @_;
155 $Foo{$key} = $value unless $Foo{$key};
158 Because the assignment copies the values, this also has the effect
159 of turning call-by-reference into call-by-value. Otherwise a
160 function is free to do in-place modifications of C<@_> and change
162 X<call-by-reference> X<call-by-value>
164 upcase_in($v1, $v2); # this changes $v1 and $v2
166 for (@_) { tr/a-z/A-Z/ }
169 You aren't allowed to modify constants in this way, of course. If an
170 argument were actually literal and you tried to change it, you'd take a
171 (presumably fatal) exception. For example, this won't work:
172 X<call-by-reference> X<call-by-value>
174 upcase_in("frederick");
176 It would be much safer if the C<upcase_in()> function
177 were written to return a copy of its parameters instead
178 of changing them in place:
180 ($v3, $v4) = upcase($v1, $v2); # this doesn't change $v1 and $v2
182 return unless defined wantarray; # void context, do nothing
184 for (@parms) { tr/a-z/A-Z/ }
185 return wantarray ? @parms : $parms[0];
188 Notice how this (unprototyped) function doesn't care whether it was
189 passed real scalars or arrays. Perl sees all arguments as one big,
190 long, flat parameter list in C<@_>. This is one area where
191 Perl's simple argument-passing style shines. The C<upcase()>
192 function would work perfectly well without changing the C<upcase()>
193 definition even if we fed it things like this:
195 @newlist = upcase(@list1, @list2);
196 @newlist = upcase( split /:/, $var );
198 Do not, however, be tempted to do this:
200 (@a, @b) = upcase(@list1, @list2);
202 Like the flattened incoming parameter list, the return list is also
203 flattened on return. So all you have managed to do here is stored
204 everything in C<@a> and made C<@b> empty. See
205 L</Pass by Reference> for alternatives.
207 A subroutine may be called using an explicit C<&> prefix. The
208 C<&> is optional in modern Perl, as are parentheses if the
209 subroutine has been predeclared. The C<&> is I<not> optional
210 when just naming the subroutine, such as when it's used as
211 an argument to defined() or undef(). Nor is it optional when you
212 want to do an indirect subroutine call with a subroutine name or
213 reference using the C<&$subref()> or C<&{$subref}()> constructs,
214 although the C<< $subref->() >> notation solves that problem.
215 See L<perlref> for more about all that.
218 Subroutines may be called recursively. If a subroutine is called
219 using the C<&> form, the argument list is optional, and if omitted,
220 no C<@_> array is set up for the subroutine: the C<@_> array at the
221 time of the call is visible to subroutine instead. This is an
222 efficiency mechanism that new users may wish to avoid.
225 &foo(1,2,3); # pass three arguments
226 foo(1,2,3); # the same
228 foo(); # pass a null list
231 &foo; # foo() get current args, like foo(@_) !!
233 foo; # like foo() iff sub foo predeclared, else
234 # a compile-time error
236 foo; # like foo() iff sub foo predeclared, else
237 # a literal string "foo"
239 Not only does the C<&> form make the argument list optional, it also
240 disables any prototype checking on arguments you do provide. This
241 is partly for historical reasons, and partly for having a convenient way
242 to cheat if you know what you're doing. See L</Prototypes> below.
245 Since Perl 5.16.0, the C<__SUB__> token is available under C<use feature
246 'current_sub'> and C<use 5.16.0>. It will evaluate to a reference to the
247 currently-running sub, which allows for recursive calls without knowing
248 your subroutine's name.
251 my $factorial = sub {
254 return($x * __SUB__->( $x - 1 ) );
257 The behavior of C<__SUB__> within a regex code block (such as C</(?{...})/>)
258 is subject to change.
260 Subroutines whose names are in all upper case are reserved to the Perl
261 core, as are modules whose names are in all lower case. A subroutine in
262 all capitals is a loosely-held convention meaning it will be called
263 indirectly by the run-time system itself, usually due to a triggered event.
264 Subroutines whose name start with a left parenthesis are also reserved the
265 same way. The following is a list of some subroutines that currently do
266 special, pre-defined things.
270 =item documented later in this document
274 =item documented in L<perlmod>
276 C<CLONE>, C<CLONE_SKIP>
278 =item documented in L<perlobj>
282 =item documented in L<perltie>
284 C<BINMODE>, C<CLEAR>, C<CLOSE>, C<DELETE>, C<DESTROY>, C<EOF>, C<EXISTS>,
285 C<EXTEND>, C<FETCH>, C<FETCHSIZE>, C<FILENO>, C<FIRSTKEY>, C<GETC>,
286 C<NEXTKEY>, C<OPEN>, C<POP>, C<PRINT>, C<PRINTF>, C<PUSH>, C<READ>,
287 C<READLINE>, C<SCALAR>, C<SEEK>, C<SHIFT>, C<SPLICE>, C<STORE>,
288 C<STORESIZE>, C<TELL>, C<TIEARRAY>, C<TIEHANDLE>, C<TIEHASH>,
289 C<TIESCALAR>, C<UNSHIFT>, C<UNTIE>, C<WRITE>
291 =item documented in L<PerlIO::via>
293 C<BINMODE>, C<CLEARERR>, C<CLOSE>, C<EOF>, C<ERROR>, C<FDOPEN>, C<FILENO>,
294 C<FILL>, C<FLUSH>, C<OPEN>, C<POPPED>, C<PUSHED>, C<READ>, C<SEEK>,
295 C<SETLINEBUF>, C<SYSOPEN>, C<TELL>, C<UNREAD>, C<UTF8>, C<WRITE>
297 =item documented in L<perlfunc>
299 L<< C<import> | perlfunc/use >>, L<< C<unimport> | perlfunc/use >>,
300 L<< C<INC> | perlfunc/require >>
302 =item documented in L<UNIVERSAL>
306 =item documented in L<perldebguts>
308 C<DB::DB>, C<DB::sub>, C<DB::lsub>, C<DB::goto>, C<DB::postponed>
310 =item undocumented, used internally by the L<overload> feature
312 any starting with C<(>
316 The C<BEGIN>, C<UNITCHECK>, C<CHECK>, C<INIT> and C<END> subroutines
317 are not so much subroutines as named special code blocks, of which you
318 can have more than one in a package, and which you can B<not> call
319 explicitly. See L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END">
323 B<WARNING>: Subroutine signatures are experimental. The feature may be
324 modified or removed in future versions of Perl.
326 Perl has an experimental facility to allow a subroutine's formal
327 parameters to be introduced by special syntax, separate from the
328 procedural code of the subroutine body. The formal parameter list
329 is known as a I<signature>. The facility must be enabled first by a
330 pragmatic declaration, C<use feature 'signatures'>, and it will produce
331 a warning unless the "experimental::signatures" warnings category is
334 The signature is part of a subroutine's body. Normally the body of a
335 subroutine is simply a braced block of code, but when using a signature,
336 the signature is a parenthesised list that goes immediately before the
337 block, after any name or attributes.
341 sub foo :lvalue ($a, $b = 1, @c) { .... }
343 The signature declares lexical variables that are
344 in scope for the block. When the subroutine is called, the signature
345 takes control first. It populates the signature variables from the
346 list of arguments that were passed. If the argument list doesn't meet
347 the requirements of the signature, then it will throw an exception.
348 When the signature processing is complete, control passes to the block.
350 Positional parameters are handled by simply naming scalar variables in
351 the signature. For example,
353 sub foo ($left, $right) {
354 return $left + $right;
357 takes two positional parameters, which must be filled at runtime by
358 two arguments. By default the parameters are mandatory, and it is
359 not permitted to pass more arguments than expected. So the above is
363 die "Too many arguments for subroutine" unless @_ <= 2;
364 die "Too few arguments for subroutine" unless @_ >= 2;
367 return $left + $right;
370 An argument can be ignored by omitting the main part of the name from
371 a parameter declaration, leaving just a bare C<$> sigil. For example,
373 sub foo ($first, $, $third) {
374 return "first=$first, third=$third";
377 Although the ignored argument doesn't go into a variable, it is still
378 mandatory for the caller to pass it.
380 A positional parameter is made optional by giving a default value,
381 separated from the parameter name by C<=>:
383 sub foo ($left, $right = 0) {
384 return $left + $right;
387 The above subroutine may be called with either one or two arguments.
388 The default value expression is evaluated when the subroutine is called,
389 so it may provide different default values for different calls. It is
390 only evaluated if the argument was actually omitted from the call.
394 sub foo ($thing, $id = $auto_id++) {
395 print "$thing has ID $id";
398 automatically assigns distinct sequential IDs to things for which no
399 ID was supplied by the caller. A default value expression may also
400 refer to parameters earlier in the signature, making the default for
401 one parameter vary according to the earlier parameters. For example,
403 sub foo ($first_name, $surname, $nickname = $first_name) {
404 print "$first_name $surname is known as \"$nickname\"";
407 An optional parameter can be nameless just like a mandatory parameter.
410 sub foo ($thing, $ = 1) {
414 The parameter's default value will still be evaluated if the corresponding
415 argument isn't supplied, even though the value won't be stored anywhere.
416 This is in case evaluating it has important side effects. However, it
417 will be evaluated in void context, so if it doesn't have side effects
418 and is not trivial it will generate a warning if the "void" warning
419 category is enabled. If a nameless optional parameter's default value
420 is not important, it may be omitted just as the parameter's name was:
422 sub foo ($thing, $=) {
426 Optional positional parameters must come after all mandatory positional
427 parameters. (If there are no mandatory positional parameters then an
428 optional positional parameters can be the first thing in the signature.)
429 If there are multiple optional positional parameters and not enough
430 arguments are supplied to fill them all, they will be filled from left
433 After positional parameters, additional arguments may be captured in a
434 slurpy parameter. The simplest form of this is just an array variable:
436 sub foo ($filter, @inputs) {
437 print $filter->($_) foreach @inputs;
440 With a slurpy parameter in the signature, there is no upper limit on how
441 many arguments may be passed. A slurpy array parameter may be nameless
442 just like a positional parameter, in which case its only effect is to
443 turn off the argument limit that would otherwise apply:
445 sub foo ($thing, @) {
449 A slurpy parameter may instead be a hash, in which case the arguments
450 available to it are interpreted as alternating keys and values.
451 There must be as many keys as values: if there is an odd argument then
452 an exception will be thrown. Keys will be stringified, and if there are
453 duplicates then the later instance takes precedence over the earlier,
454 as with standard hash construction.
456 sub foo ($filter, %inputs) {
457 print $filter->($_, $inputs{$_}) foreach sort keys %inputs;
460 A slurpy hash parameter may be nameless just like other kinds of
461 parameter. It still insists that the number of arguments available to
462 it be even, even though they're not being put into a variable.
464 sub foo ($thing, %) {
468 A slurpy parameter, either array or hash, must be the last thing in the
469 signature. It may follow mandatory and optional positional parameters;
470 it may also be the only thing in the signature. Slurpy parameters cannot
471 have default values: if no arguments are supplied for them then you get
472 an empty array or empty hash.
474 A signature may be entirely empty, in which case all it does is check
475 that the caller passed no arguments:
481 In the current perl implementation, when using a signature the arguments
482 are still also available in the special array variable C<@_>. However,
483 accessing them via this array is now discouraged, and should not be
484 relied upon in newly-written code as this ability may change in a future
485 version. Code that attempts to access the C<@_> array will produce
486 warnings in the C<experimental::args_array_with_signatures> category when
490 # This line emits the warning seen below
491 print "Arguments are @_";
496 Use of @_ in join or string with signatured subroutine is
499 There is a difference between the two ways of accessing the arguments:
500 C<@_> I<aliases> the arguments, but the signature variables get
501 I<copies> of the arguments. So writing to a signature variable only
502 changes that variable, and has no effect on the caller's variables, but
503 writing to an element of C<@_> modifies whatever the caller used to
504 supply that argument.
506 There is a potential syntactic ambiguity between signatures and prototypes
507 (see L</Prototypes>), because both start with an opening parenthesis and
508 both can appear in some of the same places, such as just after the name
509 in a subroutine declaration. For historical reasons, when signatures
510 are not enabled, any opening parenthesis in such a context will trigger
511 very forgiving prototype parsing. Most signatures will be interpreted
512 as prototypes in those circumstances, but won't be valid prototypes.
513 (A valid prototype cannot contain any alphabetic character.) This will
514 lead to somewhat confusing error messages.
516 To avoid ambiguity, when signatures are enabled the special syntax
517 for prototypes is disabled. There is no attempt to guess whether a
518 parenthesised group was intended to be a prototype or a signature.
519 To give a subroutine a prototype under these circumstances, use a
520 L<prototype attribute|attributes/Built-in Attributes>. For example,
522 sub foo :prototype($) { $_[0] }
524 It is entirely possible for a subroutine to have both a prototype and
525 a signature. They do different jobs: the prototype affects compilation
526 of calls to the subroutine, and the signature puts argument values into
527 lexical variables at runtime. You can therefore write
529 sub foo :prototype($$) ($left, $right) {
530 return $left + $right;
533 The prototype attribute, and any other attributes, must come before
534 the signature. The signature always immediately precedes the block of
535 the subroutine's body.
537 =head2 Private Variables via my()
538 X<my> X<variable, lexical> X<lexical> X<lexical variable> X<scope, lexical>
539 X<lexical scope> X<attributes, my>
543 my $foo; # declare $foo lexically local
544 my (@wid, %get); # declare list of variables local
545 my $foo = "flurp"; # declare $foo lexical, and init it
546 my @oof = @bar; # declare @oof lexical, and init it
547 my $x : Foo = $y; # similar, with an attribute applied
549 B<WARNING>: The use of attribute lists on C<my> declarations is still
550 evolving. The current semantics and interface are subject to change.
551 See L<attributes> and L<Attribute::Handlers>.
553 The C<my> operator declares the listed variables to be lexically
554 confined to the enclosing block, conditional
555 (C<if>/C<unless>/C<elsif>/C<else>), loop
556 (C<for>/C<foreach>/C<while>/C<until>/C<continue>), subroutine, C<eval>,
557 or C<do>/C<require>/C<use>'d file. If more than one value is listed, the
558 list must be placed in parentheses. All listed elements must be
559 legal lvalues. Only alphanumeric identifiers may be lexically
560 scoped--magical built-ins like C<$/> must currently be C<local>ized
561 with C<local> instead.
563 Unlike dynamic variables created by the C<local> operator, lexical
564 variables declared with C<my> are totally hidden from the outside
565 world, including any called subroutines. This is true if it's the
566 same subroutine called from itself or elsewhere--every call gets
570 This doesn't mean that a C<my> variable declared in a statically
571 enclosing lexical scope would be invisible. Only dynamic scopes
572 are cut off. For example, the C<bumpx()> function below has access
573 to the lexical $x variable because both the C<my> and the C<sub>
574 occurred at the same scope, presumably file scope.
579 An C<eval()>, however, can see lexical variables of the scope it is
580 being evaluated in, so long as the names aren't hidden by declarations within
581 the C<eval()> itself. See L<perlref>.
584 The parameter list to my() may be assigned to if desired, which allows you
585 to initialize your variables. (If no initializer is given for a
586 particular variable, it is created with the undefined value.) Commonly
587 this is used to name input parameters to a subroutine. Examples:
589 $arg = "fred"; # "global" variable
591 print "$arg thinks the root is $n\n";
592 fred thinks the root is 3
595 my $arg = shift; # name doesn't matter
600 The C<my> is simply a modifier on something you might assign to. So when
601 you do assign to variables in its argument list, C<my> doesn't
602 change whether those variables are viewed as a scalar or an array. So
604 my ($foo) = <STDIN>; # WRONG?
607 both supply a list context to the right-hand side, while
611 supplies a scalar context. But the following declares only one variable:
613 my $foo, $bar = 1; # WRONG
615 That has the same effect as
620 The declared variable is not introduced (is not visible) until after
621 the current statement. Thus,
625 can be used to initialize a new $x with the value of the old $x, and
628 my $x = 123 and $x == 123
630 is false unless the old $x happened to have the value C<123>.
632 Lexical scopes of control structures are not bounded precisely by the
633 braces that delimit their controlled blocks; control expressions are
634 part of that scope, too. Thus in the loop
636 while (my $line = <>) {
642 the scope of $line extends from its declaration throughout the rest of
643 the loop construct (including the C<continue> clause), but not beyond
644 it. Similarly, in the conditional
646 if ((my $answer = <STDIN>) =~ /^yes$/i) {
648 } elsif ($answer =~ /^no$/i) {
652 die "'$answer' is neither 'yes' nor 'no'";
655 the scope of $answer extends from its declaration through the rest
656 of that conditional, including any C<elsif> and C<else> clauses,
657 but not beyond it. See L<perlsyn/"Simple Statements"> for information
658 on the scope of variables in statements with modifiers.
660 The C<foreach> loop defaults to scoping its index variable dynamically
661 in the manner of C<local>. However, if the index variable is
662 prefixed with the keyword C<my>, or if there is already a lexical
663 by that name in scope, then a new lexical is created instead. Thus
667 for my $i (1, 2, 3) {
671 the scope of $i extends to the end of the loop, but not beyond it,
672 rendering the value of $i inaccessible within C<some_function()>.
675 Some users may wish to encourage the use of lexically scoped variables.
676 As an aid to catching implicit uses to package variables,
677 which are always global, if you say
681 then any variable mentioned from there to the end of the enclosing
682 block must either refer to a lexical variable, be predeclared via
683 C<our> or C<use vars>, or else must be fully qualified with the package name.
684 A compilation error results otherwise. An inner block may countermand
685 this with C<no strict 'vars'>.
687 A C<my> has both a compile-time and a run-time effect. At compile
688 time, the compiler takes notice of it. The principal usefulness
689 of this is to quiet C<use strict 'vars'>, but it is also essential
690 for generation of closures as detailed in L<perlref>. Actual
691 initialization is delayed until run time, though, so it gets executed
692 at the appropriate time, such as each time through a loop, for
695 Variables declared with C<my> are not part of any package and are therefore
696 never fully qualified with the package name. In particular, you're not
697 allowed to try to make a package variable (or other global) lexical:
699 my $pack::var; # ERROR! Illegal syntax
701 In fact, a dynamic variable (also known as package or global variables)
702 are still accessible using the fully qualified C<::> notation even while a
703 lexical of the same name is also visible:
708 print "$x and $::x\n";
710 That will print out C<20> and C<10>.
712 You may declare C<my> variables at the outermost scope of a file
713 to hide any such identifiers from the world outside that file. This
714 is similar in spirit to C's static variables when they are used at
715 the file level. To do this with a subroutine requires the use of
716 a closure (an anonymous function that accesses enclosing lexicals).
717 If you want to create a private subroutine that cannot be called
718 from outside that block, it can declare a lexical variable containing
719 an anonymous sub reference:
721 my $secret_version = '1.001-beta';
722 my $secret_sub = sub { print $secret_version };
725 As long as the reference is never returned by any function within the
726 module, no outside module can see the subroutine, because its name is not in
727 any package's symbol table. Remember that it's not I<REALLY> called
728 C<$some_pack::secret_version> or anything; it's just $secret_version,
729 unqualified and unqualifiable.
731 This does not work with object methods, however; all object methods
732 have to be in the symbol table of some package to be found. See
733 L<perlref/"Function Templates"> for something of a work-around to
736 =head2 Persistent Private Variables
737 X<state> X<state variable> X<static> X<variable, persistent> X<variable, static> X<closure>
739 There are two ways to build persistent private variables in Perl 5.10.
740 First, you can simply use the C<state> feature. Or, you can use closures,
741 if you want to stay compatible with releases older than 5.10.
743 =head3 Persistent variables via state()
745 Beginning with Perl 5.10.0, you can declare variables with the C<state>
746 keyword in place of C<my>. For that to work, though, you must have
747 enabled that feature beforehand, either by using the C<feature> pragma, or
748 by using C<-E> on one-liners (see L<feature>). Beginning with Perl 5.16,
749 the C<CORE::state> form does not require the
752 The C<state> keyword creates a lexical variable (following the same scoping
753 rules as C<my>) that persists from one subroutine call to the next. If a
754 state variable resides inside an anonymous subroutine, then each copy of
755 the subroutine has its own copy of the state variable. However, the value
756 of the state variable will still persist between calls to the same copy of
757 the anonymous subroutine. (Don't forget that C<sub { ... }> creates a new
758 subroutine each time it is executed.)
760 For example, the following code maintains a private counter, incremented
761 each time the gimme_another() function is called:
764 sub gimme_another { state $x; return ++$x }
766 And this example uses anonymous subroutines to create separate counters:
770 return sub { state $x; return ++$x }
773 Also, since C<$x> is lexical, it can't be reached or modified by any Perl
776 When combined with variable declaration, simple assignment to C<state>
777 variables (as in C<state $x = 42>) is executed only the first time. When such
778 statements are evaluated subsequent times, the assignment is ignored. The
779 behavior of assignment to C<state> declarations where the left hand side
780 of the assignment involves any parentheses is currently undefined.
782 =head3 Persistent variables with closures
784 Just because a lexical variable is lexically (also called statically)
785 scoped to its enclosing block, C<eval>, or C<do> FILE, this doesn't mean that
786 within a function it works like a C static. It normally works more
787 like a C auto, but with implicit garbage collection.
789 Unlike local variables in C or C++, Perl's lexical variables don't
790 necessarily get recycled just because their scope has exited.
791 If something more permanent is still aware of the lexical, it will
792 stick around. So long as something else references a lexical, that
793 lexical won't be freed--which is as it should be. You wouldn't want
794 memory being free until you were done using it, or kept around once you
795 were done. Automatic garbage collection takes care of this for you.
797 This means that you can pass back or save away references to lexical
798 variables, whereas to return a pointer to a C auto is a grave error.
799 It also gives us a way to simulate C's function statics. Here's a
800 mechanism for giving a function private variables with both lexical
801 scoping and a static lifetime. If you do want to create something like
802 C's static variables, just enclose the whole function in an extra block,
803 and put the static variable outside the function but in the block.
808 return ++$secret_val;
811 # $secret_val now becomes unreachable by the outside
812 # world, but retains its value between calls to gimme_another
814 If this function is being sourced in from a separate file
815 via C<require> or C<use>, then this is probably just fine. If it's
816 all in the main program, you'll need to arrange for the C<my>
817 to be executed early, either by putting the whole block above
818 your main program, or more likely, placing merely a C<BEGIN>
819 code block around it to make sure it gets executed before your program
825 return ++$secret_val;
829 See L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END"> about the
830 special triggered code blocks, C<BEGIN>, C<UNITCHECK>, C<CHECK>,
833 If declared at the outermost scope (the file scope), then lexicals
834 work somewhat like C's file statics. They are available to all
835 functions in that same file declared below them, but are inaccessible
836 from outside that file. This strategy is sometimes used in modules
837 to create private variables that the whole module can see.
839 =head2 Temporary Values via local()
840 X<local> X<scope, dynamic> X<dynamic scope> X<variable, local>
841 X<variable, temporary>
843 B<WARNING>: In general, you should be using C<my> instead of C<local>, because
844 it's faster and safer. Exceptions to this include the global punctuation
845 variables, global filehandles and formats, and direct manipulation of the
846 Perl symbol table itself. C<local> is mostly used when the current value
847 of a variable must be visible to called subroutines.
851 # localization of values
853 local $foo; # make $foo dynamically local
854 local (@wid, %get); # make list of variables local
855 local $foo = "flurp"; # make $foo dynamic, and init it
856 local @oof = @bar; # make @oof dynamic, and init it
858 local $hash{key} = "val"; # sets a local value for this hash entry
859 delete local $hash{key}; # delete this entry for the current block
860 local ($cond ? $v1 : $v2); # several types of lvalues support
863 # localization of symbols
865 local *FH; # localize $FH, @FH, %FH, &FH ...
866 local *merlyn = *randal; # now $merlyn is really $randal, plus
867 # @merlyn is really @randal, etc
868 local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal
869 local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc
871 A C<local> modifies its listed variables to be "local" to the
872 enclosing block, C<eval>, or C<do FILE>--and to I<any subroutine
873 called from within that block>. A C<local> just gives temporary
874 values to global (meaning package) variables. It does I<not> create
875 a local variable. This is known as dynamic scoping. Lexical scoping
876 is done with C<my>, which works more like C's auto declarations.
878 Some types of lvalues can be localized as well: hash and array elements
879 and slices, conditionals (provided that their result is always
880 localizable), and symbolic references. As for simple variables, this
881 creates new, dynamically scoped values.
883 If more than one variable or expression is given to C<local>, they must be
884 placed in parentheses. This operator works
885 by saving the current values of those variables in its argument list on a
886 hidden stack and restoring them upon exiting the block, subroutine, or
887 eval. This means that called subroutines can also reference the local
888 variable, but not the global one. The argument list may be assigned to if
889 desired, which allows you to initialize your local variables. (If no
890 initializer is given for a particular variable, it is created with an
893 Because C<local> is a run-time operator, it gets executed each time
894 through a loop. Consequently, it's more efficient to localize your
895 variables outside the loop.
897 =head3 Grammatical note on local()
900 A C<local> is simply a modifier on an lvalue expression. When you assign to
901 a C<local>ized variable, the C<local> doesn't change whether its list is viewed
902 as a scalar or an array. So
904 local($foo) = <STDIN>;
905 local @FOO = <STDIN>;
907 both supply a list context to the right-hand side, while
909 local $foo = <STDIN>;
911 supplies a scalar context.
913 =head3 Localization of special variables
914 X<local, special variable>
916 If you localize a special variable, you'll be giving a new value to it,
917 but its magic won't go away. That means that all side-effects related
918 to this magic still work with the localized value.
920 This feature allows code like this to work :
922 # Read the whole contents of FILE in $slurp
923 { local $/ = undef; $slurp = <FILE>; }
925 Note, however, that this restricts localization of some values ; for
926 example, the following statement dies, as of perl 5.10.0, with an error
927 I<Modification of a read-only value attempted>, because the $1 variable is
928 magical and read-only :
932 One exception is the default scalar variable: starting with perl 5.14
933 C<local($_)> will always strip all magic from $_, to make it possible
934 to safely reuse $_ in a subroutine.
936 B<WARNING>: Localization of tied arrays and hashes does not currently
938 This will be fixed in a future release of Perl; in the meantime, avoid
939 code that relies on any particular behavior of localising tied arrays
940 or hashes (localising individual elements is still okay).
941 See L<perl58delta/"Localising Tied Arrays and Hashes Is Broken"> for more
945 =head3 Localization of globs
946 X<local, glob> X<glob>
952 creates a whole new symbol table entry for the glob C<name> in the
953 current package. That means that all variables in its glob slot ($name,
954 @name, %name, &name, and the C<name> filehandle) are dynamically reset.
956 This implies, among other things, that any magic eventually carried by
957 those variables is locally lost. In other words, saying C<local */>
958 will not have any effect on the internal value of the input record
961 =head3 Localization of elements of composite types
962 X<local, composite type element> X<local, array element> X<local, hash element>
964 It's also worth taking a moment to explain what happens when you
965 C<local>ize a member of a composite type (i.e. an array or hash element).
966 In this case, the element is C<local>ized I<by name>. This means that
967 when the scope of the C<local()> ends, the saved value will be
968 restored to the hash element whose key was named in the C<local()>, or
969 the array element whose index was named in the C<local()>. If that
970 element was deleted while the C<local()> was in effect (e.g. by a
971 C<delete()> from a hash or a C<shift()> of an array), it will spring
972 back into existence, possibly extending an array and filling in the
973 skipped elements with C<undef>. For instance, if you say
975 %hash = ( 'This' => 'is', 'a' => 'test' );
979 local($hash{'a'}) = 'drill';
980 while (my $e = pop(@ary)) {
985 $hash{'only a'} = 'test';
989 print join(' ', map { "$_ $hash{$_}" } sort keys %hash),".\n";
990 print "The array has ",scalar(@ary)," elements: ",
991 join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\n";
998 This is a test only a test.
999 The array has 6 elements: 0, 1, 2, undef, undef, 5
1001 The behavior of local() on non-existent members of composite
1002 types is subject to change in future. The behavior of local()
1003 on array elements specified using negative indexes is particularly
1004 surprising, and is very likely to change.
1006 =head3 Localized deletion of elements of composite types
1007 X<delete> X<local, composite type element> X<local, array element> X<local, hash element>
1009 You can use the C<delete local $array[$idx]> and C<delete local $hash{key}>
1010 constructs to delete a composite type entry for the current block and restore
1011 it when it ends. They return the array/hash value before the localization,
1012 which means that they are respectively equivalent to
1015 my $val = $array[$idx];
1017 delete $array[$idx];
1024 my $val = $hash{key};
1030 except that for those the C<local> is
1031 scoped to the C<do> block. Slices are
1040 my $a = delete local $hash{a};
1045 my @nums = delete local @$a[0, 2]
1047 # $a is [ undef, 8 ]
1049 $a[0] = 999; # will be erased when the scope ends
1051 # $a is back to [ 7, 8, 9 ]
1054 # %hash is back to its original state
1056 This construct is supported since Perl v5.12.
1058 =head2 Lvalue subroutines
1059 X<lvalue> X<subroutine, lvalue>
1061 It is possible to return a modifiable value from a subroutine.
1062 To do this, you have to declare the subroutine to return an lvalue.
1065 sub canmod : lvalue {
1066 $val; # or: return $val;
1072 canmod() = 5; # assigns to $val
1073 nomod() = 5; # ERROR
1075 The scalar/list context for the subroutine and for the right-hand
1076 side of assignment is determined as if the subroutine call is replaced
1077 by a scalar. For example, consider:
1079 data(2,3) = get_data(3,4);
1081 Both subroutines here are called in a scalar context, while in:
1083 (data(2,3)) = get_data(3,4);
1087 (data(2),data(3)) = get_data(3,4);
1089 all the subroutines are called in a list context.
1091 Lvalue subroutines are convenient, but you have to keep in mind that,
1092 when used with objects, they may violate encapsulation. A normal
1093 mutator can check the supplied argument before setting the attribute
1094 it is protecting, an lvalue subroutine cannot. If you require any
1095 special processing when storing and retrieving the values, consider
1096 using the CPAN module Sentinel or something similar.
1098 =head2 Lexical Subroutines
1099 X<my sub> X<state sub> X<our sub> X<subroutine, lexical>
1101 Beginning with Perl 5.18, you can declare a private subroutine with C<my>
1102 or C<state>. As with state variables, the C<state> keyword is only
1103 available under C<use feature 'state'> or C<use 5.010> or higher.
1105 Prior to Perl 5.26, lexical subroutines were deemed experimental and were
1106 available only under the C<use feature 'lexical_subs'> pragma. They also
1107 produced a warning unless the "experimental::lexical_subs" warnings
1108 category was disabled.
1110 These subroutines are only visible within the block in which they are
1111 declared, and only after that declaration:
1113 # Include these two lines if your code is intended to run under Perl
1114 # versions earlier than 5.26.
1115 no warnings "experimental::lexical_subs";
1116 use feature 'lexical_subs';
1118 foo(); # calls the package/global subroutine
1120 foo(); # also calls the package subroutine
1122 foo(); # calls "state" sub
1123 my $ref = \&foo; # take a reference to "state" sub
1126 bar(); # calls "my" sub
1128 You can't (directly) write a recursive lexical subroutine:
1135 This example fails because C<baz()> refers to the package/global subroutine
1136 C<baz>, not the lexical subroutine currently being defined.
1138 The solution is to use L<C<__SUB__>|perlfunc/__SUB__>:
1141 __SUB__->(); # calls itself
1144 It is possible to predeclare a lexical subroutine. The C<sub foo {...}>
1145 subroutine definition syntax respects any previous C<my sub;> or C<state sub;>
1146 declaration. Using this to define recursive subroutines is a bad idea,
1149 my sub baz; # predeclaration
1150 sub baz { # define the "my" sub
1151 baz(); # WRONG: calls itself, but leaks memory
1154 Just like C<< my $f; $f = sub { $f->() } >>, this example leaks memory. The
1155 name C<baz> is a reference to the subroutine, and the subroutine uses the name
1156 C<baz>; they keep each other alive (see L<perlref/Circular References>).
1158 =head3 C<state sub> vs C<my sub>
1160 What is the difference between "state" subs and "my" subs? Each time that
1161 execution enters a block when "my" subs are declared, a new copy of each
1162 sub is created. "State" subroutines persist from one execution of the
1163 containing block to the next.
1165 So, in general, "state" subroutines are faster. But "my" subs are
1166 necessary if you want to create closures:
1171 ... do something with $x ...
1176 In this example, a new C<$x> is created when C<whatever> is called, and
1177 also a new C<inner>, which can see the new C<$x>. A "state" sub will only
1178 see the C<$x> from the first call to C<whatever>.
1180 =head3 C<our> subroutines
1182 Like C<our $variable>, C<our sub> creates a lexical alias to the package
1183 subroutine of the same name.
1185 The two main uses for this are to switch back to using the package sub
1186 inside an inner scope:
1193 # need to use the outer foo here
1199 and to make a subroutine visible to other packages in the same scope:
1201 package MySneakyModule;
1203 our sub do_something { ... }
1205 sub do_something_with_caller {
1207 () = caller 1; # sets @DB::args
1208 do_something(@args); # uses MySneakyModule::do_something
1211 =head2 Passing Symbol Table Entries (typeglobs)
1214 B<WARNING>: The mechanism described in this section was originally
1215 the only way to simulate pass-by-reference in older versions of
1216 Perl. While it still works fine in modern versions, the new reference
1217 mechanism is generally easier to work with. See below.
1219 Sometimes you don't want to pass the value of an array to a subroutine
1220 but rather the name of it, so that the subroutine can modify the global
1221 copy of it rather than working with a local copy. In perl you can
1222 refer to all objects of a particular name by prefixing the name
1223 with a star: C<*foo>. This is often known as a "typeglob", because the
1224 star on the front can be thought of as a wildcard match for all the
1225 funny prefix characters on variables and subroutines and such.
1227 When evaluated, the typeglob produces a scalar value that represents
1228 all the objects of that name, including any filehandle, format, or
1229 subroutine. When assigned to, it causes the name mentioned to refer to
1230 whatever C<*> value was assigned to it. Example:
1233 local(*someary) = @_;
1234 foreach $elem (@someary) {
1241 Scalars are already passed by reference, so you can modify
1242 scalar arguments without using this mechanism by referring explicitly
1243 to C<$_[0]> etc. You can modify all the elements of an array by passing
1244 all the elements as scalars, but you have to use the C<*> mechanism (or
1245 the equivalent reference mechanism) to C<push>, C<pop>, or change the size of
1246 an array. It will certainly be faster to pass the typeglob (or reference).
1248 Even if you don't want to modify an array, this mechanism is useful for
1249 passing multiple arrays in a single LIST, because normally the LIST
1250 mechanism will merge all the array values so that you can't extract out
1251 the individual arrays. For more on typeglobs, see
1252 L<perldata/"Typeglobs and Filehandles">.
1254 =head2 When to Still Use local()
1255 X<local> X<variable, local>
1257 Despite the existence of C<my>, there are still three places where the
1258 C<local> operator still shines. In fact, in these three places, you
1259 I<must> use C<local> instead of C<my>.
1265 You need to give a global variable a temporary value, especially $_.
1267 The global variables, like C<@ARGV> or the punctuation variables, must be
1268 C<local>ized with C<local()>. This block reads in F</etc/motd>, and splits
1269 it up into chunks separated by lines of equal signs, which are placed
1273 local @ARGV = ("/etc/motd");
1276 @Fields = split /^\s*=+\s*$/;
1279 It particular, it's important to C<local>ize $_ in any routine that assigns
1280 to it. Look out for implicit assignments in C<while> conditionals.
1284 You need to create a local file or directory handle or a local function.
1286 A function that needs a filehandle of its own must use
1287 C<local()> on a complete typeglob. This can be used to create new symbol
1291 local (*READER, *WRITER); # not my!
1292 pipe (READER, WRITER) or die "pipe: $!";
1293 return (*READER, *WRITER);
1295 ($head, $tail) = ioqueue();
1297 See the Symbol module for a way to create anonymous symbol table
1300 Because assignment of a reference to a typeglob creates an alias, this
1301 can be used to create what is effectively a local function, or at least,
1305 local *grow = \&shrink; # only until this block exits
1306 grow(); # really calls shrink()
1307 move(); # if move() grow()s, it shrink()s too
1309 grow(); # get the real grow() again
1311 See L<perlref/"Function Templates"> for more about manipulating
1312 functions by name in this way.
1316 You want to temporarily change just one element of an array or hash.
1318 You can C<local>ize just one element of an aggregate. Usually this
1319 is done on dynamics:
1322 local $SIG{INT} = 'IGNORE';
1323 funct(); # uninterruptible
1325 # interruptibility automatically restored here
1327 But it also works on lexically declared aggregates.
1331 =head2 Pass by Reference
1332 X<pass by reference> X<pass-by-reference> X<reference>
1334 If you want to pass more than one array or hash into a function--or
1335 return them from it--and have them maintain their integrity, then
1336 you're going to have to use an explicit pass-by-reference. Before you
1337 do that, you need to understand references as detailed in L<perlref>.
1338 This section may not make much sense to you otherwise.
1340 Here are a few simple examples. First, let's pass in several arrays
1341 to a function and have it C<pop> all of then, returning a new list
1342 of all their former last elements:
1344 @tailings = popmany ( \@a, \@b, \@c, \@d );
1349 foreach $aref ( @_ ) {
1350 push @retlist, pop @$aref;
1355 Here's how you might write a function that returns a
1356 list of keys occurring in all the hashes passed to it:
1358 @common = inter( \%foo, \%bar, \%joe );
1360 my ($k, $href, %seen); # locals
1361 foreach $href (@_) {
1362 while ( $k = each %$href ) {
1366 return grep { $seen{$_} == @_ } keys %seen;
1369 So far, we're using just the normal list return mechanism.
1370 What happens if you want to pass or return a hash? Well,
1371 if you're using only one of them, or you don't mind them
1372 concatenating, then the normal calling convention is ok, although
1375 Where people get into trouble is here:
1377 (@a, @b) = func(@c, @d);
1379 (%a, %b) = func(%c, %d);
1381 That syntax simply won't work. It sets just C<@a> or C<%a> and
1382 clears the C<@b> or C<%b>. Plus the function didn't get passed
1383 into two separate arrays or hashes: it got one long list in C<@_>,
1386 If you can arrange for everyone to deal with this through references, it's
1387 cleaner code, although not so nice to look at. Here's a function that
1388 takes two array references as arguments, returning the two array elements
1389 in order of how many elements they have in them:
1391 ($aref, $bref) = func(\@c, \@d);
1392 print "@$aref has more than @$bref\n";
1394 my ($cref, $dref) = @_;
1395 if (@$cref > @$dref) {
1396 return ($cref, $dref);
1398 return ($dref, $cref);
1402 It turns out that you can actually do this also:
1404 (*a, *b) = func(\@c, \@d);
1405 print "@a has more than @b\n";
1407 local (*c, *d) = @_;
1415 Here we're using the typeglobs to do symbol table aliasing. It's
1416 a tad subtle, though, and also won't work if you're using C<my>
1417 variables, because only globals (even in disguise as C<local>s)
1418 are in the symbol table.
1420 If you're passing around filehandles, you could usually just use the bare
1421 typeglob, like C<*STDOUT>, but typeglobs references work, too.
1427 print $fh "her um well a hmmm\n";
1430 $rec = get_rec(\*STDIN);
1433 return scalar <$fh>;
1436 If you're planning on generating new filehandles, you could do this.
1437 Notice to pass back just the bare *FH, not its reference.
1442 return open (FH, $path) ? *FH : undef;
1446 X<prototype> X<subroutine, prototype>
1448 Perl supports a very limited kind of compile-time argument checking
1449 using function prototyping. This can be declared in either the PROTO
1450 section or with a L<prototype attribute|attributes/Built-in Attributes>.
1451 If you declare either of
1454 sub mypush :prototype(\@@)
1456 then C<mypush()> takes arguments exactly like C<push()> does.
1458 If subroutine signatures are enabled (see L</Signatures>), then
1459 the shorter PROTO syntax is unavailable, because it would clash with
1460 signatures. In that case, a prototype can only be declared in the form
1464 function declaration must be visible at compile time. The prototype
1465 affects only interpretation of new-style calls to the function,
1466 where new-style is defined as not using the C<&> character. In
1467 other words, if you call it like a built-in function, then it behaves
1468 like a built-in function. If you call it like an old-fashioned
1469 subroutine, then it behaves like an old-fashioned subroutine. It
1470 naturally falls out from this rule that prototypes have no influence
1471 on subroutine references like C<\&foo> or on indirect subroutine
1472 calls like C<&{$subref}> or C<< $subref->() >>.
1474 Method calls are not influenced by prototypes either, because the
1475 function to be called is indeterminate at compile time, since
1476 the exact code called depends on inheritance.
1478 Because the intent of this feature is primarily to let you define
1479 subroutines that work like built-in functions, here are prototypes
1480 for some other functions that parse almost exactly like the
1481 corresponding built-in.
1483 Declared as Called as
1485 sub mylink ($$) mylink $old, $new
1486 sub myvec ($$$) myvec $var, $offset, 1
1487 sub myindex ($$;$) myindex &getstring, "substr"
1488 sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off
1489 sub myreverse (@) myreverse $a, $b, $c
1490 sub myjoin ($@) myjoin ":", $a, $b, $c
1491 sub mypop (\@) mypop @array
1492 sub mysplice (\@$$@) mysplice @array, 0, 2, @pushme
1493 sub mykeys (\[%@]) mykeys $hashref->%*
1494 sub myopen (*;$) myopen HANDLE, $name
1495 sub mypipe (**) mypipe READHANDLE, WRITEHANDLE
1496 sub mygrep (&@) mygrep { /foo/ } $a, $b, $c
1497 sub myrand (;$) myrand 42
1498 sub mytime () mytime
1500 Any backslashed prototype character represents an actual argument
1501 that must start with that character (optionally preceded by C<my>,
1502 C<our> or C<local>), with the exception of C<$>, which will
1503 accept any scalar lvalue expression, such as C<$foo = 7> or
1504 C<< my_function()->[0] >>. The value passed as part of C<@_> will be a
1505 reference to the actual argument given in the subroutine call,
1506 obtained by applying C<\> to that argument.
1508 You can use the C<\[]> backslash group notation to specify more than one
1509 allowed argument type. For example:
1511 sub myref (\[$@%&*])
1513 will allow calling myref() as
1521 and the first argument of myref() will be a reference to
1522 a scalar, an array, a hash, a code, or a glob.
1524 Unbackslashed prototype characters have special meanings. Any
1525 unbackslashed C<@> or C<%> eats all remaining arguments, and forces
1526 list context. An argument represented by C<$> forces scalar context. An
1527 C<&> requires an anonymous subroutine, which, if passed as the first
1528 argument, does not require the C<sub> keyword or a subsequent comma.
1530 A C<*> allows the subroutine to accept a bareword, constant, scalar expression,
1531 typeglob, or a reference to a typeglob in that slot. The value will be
1532 available to the subroutine either as a simple scalar, or (in the latter
1533 two cases) as a reference to the typeglob. If you wish to always convert
1534 such arguments to a typeglob reference, use Symbol::qualify_to_ref() as
1537 use Symbol 'qualify_to_ref';
1540 my $fh = qualify_to_ref(shift, caller);
1544 The C<+> prototype is a special alternative to C<$> that will act like
1545 C<\[@%]> when given a literal array or hash variable, but will otherwise
1546 force scalar context on the argument. This is useful for functions which
1547 should accept either a literal array or an array reference as the argument:
1551 die "Not an array or arrayref" unless ref $aref eq 'ARRAY';
1555 When using the C<+> prototype, your function must check that the argument
1556 is of an acceptable type.
1558 A semicolon (C<;>) separates mandatory arguments from optional arguments.
1559 It is redundant before C<@> or C<%>, which gobble up everything else.
1561 As the last character of a prototype, or just before a semicolon, a C<@>
1562 or a C<%>, you can use C<_> in place of C<$>: if this argument is not
1563 provided, C<$_> will be used instead.
1565 Note how the last three examples in the table above are treated
1566 specially by the parser. C<mygrep()> is parsed as a true list
1567 operator, C<myrand()> is parsed as a true unary operator with unary
1568 precedence the same as C<rand()>, and C<mytime()> is truly without
1569 arguments, just like C<time()>. That is, if you say
1573 you'll get C<mytime() + 2>, not C<mytime(2)>, which is how it would be parsed
1574 without a prototype. If you want to force a unary function to have the
1575 same precedence as a list operator, add C<;> to the end of the prototype:
1577 sub mygetprotobynumber($;);
1578 mygetprotobynumber $a > $b; # parsed as mygetprotobynumber($a > $b)
1580 The interesting thing about C<&> is that you can generate new syntax with it,
1581 provided it's in the initial position:
1585 my($try,$catch) = @_;
1592 sub catch (&) { $_[0] }
1597 /phooey/ and print "unphooey\n";
1600 That prints C<"unphooey">. (Yes, there are still unresolved
1601 issues having to do with visibility of C<@_>. I'm ignoring that
1602 question for the moment. (But note that if we make C<@_> lexically
1603 scoped, those anonymous subroutines can act like closures... (Gee,
1604 is this sounding a little Lispish? (Never mind.))))
1606 And here's a reimplementation of the Perl C<grep> operator:
1613 push(@result, $_) if &$code;
1618 Some folks would prefer full alphanumeric prototypes. Alphanumerics have
1619 been intentionally left out of prototypes for the express purpose of
1620 someday in the future adding named, formal parameters. The current
1621 mechanism's main goal is to let module writers provide better diagnostics
1622 for module users. Larry feels the notation quite understandable to Perl
1623 programmers, and that it will not intrude greatly upon the meat of the
1624 module, nor make it harder to read. The line noise is visually
1625 encapsulated into a small pill that's easy to swallow.
1627 If you try to use an alphanumeric sequence in a prototype you will
1628 generate an optional warning - "Illegal character in prototype...".
1629 Unfortunately earlier versions of Perl allowed the prototype to be
1630 used as long as its prefix was a valid prototype. The warning may be
1631 upgraded to a fatal error in a future version of Perl once the
1632 majority of offending code is fixed.
1634 It's probably best to prototype new functions, not retrofit prototyping
1635 into older ones. That's because you must be especially careful about
1636 silent impositions of differing list versus scalar contexts. For example,
1637 if you decide that a function should take just one parameter, like this:
1641 print "you gave me $n\n";
1644 and someone has been calling it with an array or expression
1648 func( $text =~ /\w+/g );
1650 Then you've just supplied an automatic C<scalar> in front of their
1651 argument, which can be more than a bit surprising. The old C<@foo>
1652 which used to hold one thing doesn't get passed in. Instead,
1653 C<func()> now gets passed in a C<1>; that is, the number of elements
1654 in C<@foo>. And the C<m//g> gets called in scalar context so instead of a
1655 list of words it returns a boolean result and advances C<pos($text)>. Ouch!
1657 If a sub has both a PROTO and a BLOCK, the prototype is not applied
1658 until after the BLOCK is completely defined. This means that a recursive
1659 function with a prototype has to be predeclared for the prototype to take
1667 This is all very powerful, of course, and should be used only in moderation
1668 to make the world a better place.
1670 =head2 Constant Functions
1673 Functions with a prototype of C<()> are potential candidates for
1674 inlining. If the result after optimization and constant folding
1675 is either a constant or a lexically-scoped scalar which has no other
1676 references, then it will be used in place of function calls made
1677 without C<&>. Calls made using C<&> are never inlined. (See
1678 L<constant> for an easy way to declare most constants.)
1680 The following functions would all be inlined:
1682 sub pi () { 3.14159 } # Not exact, but close.
1683 sub PI () { 4 * atan2 1, 1 } # As good as it gets,
1684 # and it's inlined, too!
1688 sub FLAG_FOO () { 1 << 8 }
1689 sub FLAG_BAR () { 1 << 9 }
1690 sub FLAG_MASK () { FLAG_FOO | FLAG_BAR }
1692 sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) }
1694 sub N () { int(OPT_BAZ) / 3 }
1696 sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO }
1697 sub FOO_SET2 () { if (FLAG_MASK & FLAG_FOO) { 1 } }
1699 (Be aware that the last example was not always inlined in Perl 5.20 and
1700 earlier, which did not behave consistently with subroutines containing
1701 inner scopes.) You can countermand inlining by using an explicit
1712 sub bonk_val () { return 12345 }
1714 As alluded to earlier you can also declare inlined subs dynamically at
1715 BEGIN time if their body consists of a lexically-scoped scalar which
1716 has no other references. Only the first example here will be inlined:
1721 *INLINED = sub () { $var };
1728 *NOT_INLINED = sub () { $var };
1731 A not so obvious caveat with this (see [RT #79908]) is that the
1732 variable will be immediately inlined, and will stop behaving like a
1733 normal lexical variable, e.g. this will print C<79907>, not C<79908>:
1737 *RT_79908 = sub () { $x };
1740 print RT_79908(); # prints 79907
1742 As of Perl 5.22, this buggy behavior, while preserved for backward
1743 compatibility, is detected and emits a deprecation warning. If you want
1744 the subroutine to be inlined (with no warning), make sure the variable is
1745 not used in a context where it could be modified aside from where it is
1751 *INLINED = sub () { $x };
1753 # Warns. Future Perl versions will stop inlining it.
1757 *ALSO_INLINED = sub () { $x };
1760 Perl 5.22 also introduces the experimental "const" attribute as an
1761 alternative. (Disable the "experimental::const_attr" warnings if you want
1762 to use it.) When applied to an anonymous subroutine, it forces the sub to
1763 be called when the C<sub> expression is evaluated. The return value is
1764 captured and turned into a constant subroutine:
1767 *INLINED = sub : const { $x };
1770 The return value of C<INLINED> in this example will always be 54321,
1771 regardless of later modifications to $x. You can also put any arbitrary
1772 code inside the sub, at it will be executed immediately and its return
1773 value captured the same way.
1775 If you really want a subroutine with a C<()> prototype that returns a
1776 lexical variable you can easily force it to not be inlined by adding
1777 an explicit C<return>:
1781 *RT_79908 = sub () { return $x };
1784 print RT_79908(); # prints 79908
1786 The easiest way to tell if a subroutine was inlined is by using
1787 L<B::Deparse>. Consider this example of two subroutines returning
1788 C<1>, one with a C<()> prototype causing it to be inlined, and one
1789 without (with deparse output truncated for clarity):
1791 $ perl -MO=Deparse -le 'sub ONE { 1 } if (ONE) { print ONE if ONE }'
1796 print ONE() if ONE ;
1798 $ perl -MO=Deparse -le 'sub ONE () { 1 } if (ONE) { print ONE if ONE }'
1804 If you redefine a subroutine that was eligible for inlining, you'll
1805 get a warning by default. You can use this warning to tell whether or
1806 not a particular subroutine is considered inlinable, since it's
1807 different than the warning for overriding non-inlined subroutines:
1809 $ perl -e 'sub one () {1} sub one () {2}'
1810 Constant subroutine one redefined at -e line 1.
1811 $ perl -we 'sub one {1} sub one {2}'
1812 Subroutine one redefined at -e line 1.
1814 The warning is considered severe enough not to be affected by the
1815 B<-w> switch (or its absence) because previously compiled invocations
1816 of the function will still be using the old value of the function. If
1817 you need to be able to redefine the subroutine, you need to ensure
1818 that it isn't inlined, either by dropping the C<()> prototype (which
1819 changes calling semantics, so beware) or by thwarting the inlining
1820 mechanism in some other way, e.g. by adding an explicit C<return>, as
1823 sub not_inlined () { return 23 }
1825 =head2 Overriding Built-in Functions
1826 X<built-in> X<override> X<CORE> X<CORE::GLOBAL>
1828 Many built-in functions may be overridden, though this should be tried
1829 only occasionally and for good reason. Typically this might be
1830 done by a package attempting to emulate missing built-in functionality
1831 on a non-Unix system.
1833 Overriding may be done only by importing the name from a module at
1834 compile time--ordinary predeclaration isn't good enough. However, the
1835 C<use subs> pragma lets you, in effect, predeclare subs
1836 via the import syntax, and these names may then override built-in ones:
1838 use subs 'chdir', 'chroot', 'chmod', 'chown';
1842 To unambiguously refer to the built-in form, precede the
1843 built-in name with the special package qualifier C<CORE::>. For example,
1844 saying C<CORE::open()> always refers to the built-in C<open()>, even
1845 if the current package has imported some other subroutine called
1846 C<&open()> from elsewhere. Even though it looks like a regular
1847 function call, it isn't: the CORE:: prefix in that case is part of Perl's
1848 syntax, and works for any keyword, regardless of what is in the CORE
1849 package. Taking a reference to it, that is, C<\&CORE::open>, only works
1850 for some keywords. See L<CORE>.
1852 Library modules should not in general export built-in names like C<open>
1853 or C<chdir> as part of their default C<@EXPORT> list, because these may
1854 sneak into someone else's namespace and change the semantics unexpectedly.
1855 Instead, if the module adds that name to C<@EXPORT_OK>, then it's
1856 possible for a user to import the name explicitly, but not implicitly.
1857 That is, they could say
1861 and it would import the C<open> override. But if they said
1865 they would get the default imports without overrides.
1867 The foregoing mechanism for overriding built-in is restricted, quite
1868 deliberately, to the package that requests the import. There is a second
1869 method that is sometimes applicable when you wish to override a built-in
1870 everywhere, without regard to namespace boundaries. This is achieved by
1871 importing a sub into the special namespace C<CORE::GLOBAL::>. Here is an
1872 example that quite brazenly replaces the C<glob> operator with something
1873 that understands regular expressions.
1878 @EXPORT_OK = 'glob';
1884 my $where = ($sym =~ s/^GLOBAL_// ? 'CORE::GLOBAL' : caller(0));
1885 $pkg->export($where, $sym, @_);
1891 if (opendir my $d, '.') {
1892 @got = grep /$pat/, readdir $d;
1899 And here's how it could be (ab)used:
1901 #use REGlob 'GLOBAL_glob'; # override glob() in ALL namespaces
1903 use REGlob 'glob'; # override glob() in Foo:: only
1904 print for <^[a-z_]+\.pm\$>; # show all pragmatic modules
1906 The initial comment shows a contrived, even dangerous example.
1907 By overriding C<glob> globally, you would be forcing the new (and
1908 subversive) behavior for the C<glob> operator for I<every> namespace,
1909 without the complete cognizance or cooperation of the modules that own
1910 those namespaces. Naturally, this should be done with extreme caution--if
1911 it must be done at all.
1913 The C<REGlob> example above does not implement all the support needed to
1914 cleanly override perl's C<glob> operator. The built-in C<glob> has
1915 different behaviors depending on whether it appears in a scalar or list
1916 context, but our C<REGlob> doesn't. Indeed, many perl built-in have such
1917 context sensitive behaviors, and these must be adequately supported by
1918 a properly written override. For a fully functional example of overriding
1919 C<glob>, study the implementation of C<File::DosGlob> in the standard
1922 When you override a built-in, your replacement should be consistent (if
1923 possible) with the built-in native syntax. You can achieve this by using
1924 a suitable prototype. To get the prototype of an overridable built-in,
1925 use the C<prototype> function with an argument of C<"CORE::builtin_name">
1926 (see L<perlfunc/prototype>).
1928 Note however that some built-ins can't have their syntax expressed by a
1929 prototype (such as C<system> or C<chomp>). If you override them you won't
1930 be able to fully mimic their original syntax.
1932 The built-ins C<do>, C<require> and C<glob> can also be overridden, but due
1933 to special magic, their original syntax is preserved, and you don't have
1934 to define a prototype for their replacements. (You can't override the
1935 C<do BLOCK> syntax, though).
1937 C<require> has special additional dark magic: if you invoke your
1938 C<require> replacement as C<require Foo::Bar>, it will actually receive
1939 the argument C<"Foo/Bar.pm"> in @_. See L<perlfunc/require>.
1941 And, as you'll have noticed from the previous example, if you override
1942 C<glob>, the C<< <*> >> glob operator is overridden as well.
1944 In a similar fashion, overriding the C<readline> function also overrides
1945 the equivalent I/O operator C<< <FILEHANDLE> >>. Also, overriding
1946 C<readpipe> also overrides the operators C<``> and C<qx//>.
1948 Finally, some built-ins (e.g. C<exists> or C<grep>) can't be overridden.
1951 X<autoloading> X<AUTOLOAD>
1953 If you call a subroutine that is undefined, you would ordinarily
1954 get an immediate, fatal error complaining that the subroutine doesn't
1955 exist. (Likewise for subroutines being used as methods, when the
1956 method doesn't exist in any base class of the class's package.)
1957 However, if an C<AUTOLOAD> subroutine is defined in the package or
1958 packages used to locate the original subroutine, then that
1959 C<AUTOLOAD> subroutine is called with the arguments that would have
1960 been passed to the original subroutine. The fully qualified name
1961 of the original subroutine magically appears in the global $AUTOLOAD
1962 variable of the same package as the C<AUTOLOAD> routine. The name
1963 is not passed as an ordinary argument because, er, well, just
1964 because, that's why. (As an exception, a method call to a nonexistent
1965 C<import> or C<unimport> method is just skipped instead. Also, if
1966 the AUTOLOAD subroutine is an XSUB, there are other ways to retrieve the
1967 subroutine name. See L<perlguts/Autoloading with XSUBs> for details.)
1970 Many C<AUTOLOAD> routines load in a definition for the requested
1971 subroutine using eval(), then execute that subroutine using a special
1972 form of goto() that erases the stack frame of the C<AUTOLOAD> routine
1973 without a trace. (See the source to the standard module documented
1974 in L<AutoLoader>, for example.) But an C<AUTOLOAD> routine can
1975 also just emulate the routine and never define it. For example,
1976 let's pretend that a function that wasn't defined should just invoke
1977 C<system> with those arguments. All you'd do is:
1980 our $AUTOLOAD; # keep 'use strict' happy
1981 my $program = $AUTOLOAD;
1982 $program =~ s/.*:://;
1983 system($program, @_);
1989 In fact, if you predeclare functions you want to call that way, you don't
1990 even need parentheses:
1992 use subs qw(date who ls);
1997 A more complete example of this is the Shell module on CPAN, which
1998 can treat undefined subroutine calls as calls to external programs.
2000 Mechanisms are available to help modules writers split their modules
2001 into autoloadable files. See the standard AutoLoader module
2002 described in L<AutoLoader> and in L<AutoSplit>, the standard
2003 SelfLoader modules in L<SelfLoader>, and the document on adding C
2004 functions to Perl code in L<perlxs>.
2006 =head2 Subroutine Attributes
2007 X<attribute> X<subroutine, attribute> X<attrs>
2009 A subroutine declaration or definition may have a list of attributes
2010 associated with it. If such an attribute list is present, it is
2011 broken up at space or colon boundaries and treated as though a
2012 C<use attributes> had been seen. See L<attributes> for details
2013 about what attributes are currently supported.
2014 Unlike the limitation with the obsolescent C<use attrs>, the
2015 C<sub : ATTRLIST> syntax works to associate the attributes with
2016 a pre-declaration, and not just with a subroutine definition.
2018 The attributes must be valid as simple identifier names (without any
2019 punctuation other than the '_' character). They may have a parameter
2020 list appended, which is only checked for whether its parentheses ('(',')')
2023 Examples of valid syntax (even though the attributes are unknown):
2025 sub fnord (&\%) : switch(10,foo(7,3)) : expensive;
2026 sub plugh () : Ugly('\(") :Bad;
2027 sub xyzzy : _5x5 { ... }
2029 Examples of invalid syntax:
2031 sub fnord : switch(10,foo(); # ()-string not balanced
2032 sub snoid : Ugly('('); # ()-string not balanced
2033 sub xyzzy : 5x5; # "5x5" not a valid identifier
2034 sub plugh : Y2::north; # "Y2::north" not a simple identifier
2035 sub snurt : foo + bar; # "+" not a colon or space
2037 The attribute list is passed as a list of constant strings to the code
2038 which associates them with the subroutine. In particular, the second example
2039 of valid syntax above currently looks like this in terms of how it's
2042 use attributes __PACKAGE__, \&plugh, q[Ugly('\(")], 'Bad';
2044 For further details on attribute lists and their manipulation,
2045 see L<attributes> and L<Attribute::Handlers>.
2049 See L<perlref/"Function Templates"> for more about references and closures.
2050 See L<perlxs> if you'd like to learn about calling C subroutines from Perl.
2051 See L<perlembed> if you'd like to learn about calling Perl subroutines from C.
2052 See L<perlmod> to learn about bundling up your functions in separate files.
2053 See L<perlmodlib> to learn what library modules come standard on your system.
2054 See L<perlootut> to learn how to make object method calls.