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