3 perlsub - Perl subroutines
7 To declare subroutines:
9 sub NAME; # A "forward" declaration.
10 sub NAME(PROTO); # ditto, but with prototypes
12 sub NAME BLOCK # A declaration and a definition.
13 sub NAME(PROTO) BLOCK # ditto, but with prototypes
15 To define an anonymous subroutine at runtime:
19 To import subroutines:
21 use PACKAGE qw(NAME1 NAME2 NAME3);
25 NAME(LIST); # & is optional with parentheses.
26 NAME LIST; # Parentheses optional if predeclared/imported.
27 &NAME; # Passes current @_ to subroutine.
31 Like many languages, Perl provides for user-defined subroutines. These
32 may be located anywhere in the main program, loaded in from other files
33 via the C<do>, C<require>, or C<use> keywords, or even generated on the
34 fly using C<eval> or anonymous subroutines (closures). You can even call
35 a function indirectly using a variable containing its name or a CODE reference
36 to it, as in C<$var = \&function>.
38 The Perl model for function call and return values is simple: all
39 functions are passed as parameters one single flat list of scalars, and
40 all functions likewise return to their caller one single flat list of
41 scalars. Any arrays or hashes in these call and return lists will
42 collapse, losing their identities--but you may always use
43 pass-by-reference instead to avoid this. Both call and return lists may
44 contain as many or as few scalar elements as you'd like. (Often a
45 function without an explicit return statement is called a subroutine, but
46 there's really no difference from the language's perspective.)
48 Any arguments passed to the routine come in as the array @_. Thus if you
49 called a function with two arguments, those would be stored in C<$_[0]>
50 and C<$_[1]>. The array @_ is a local array, but its elements are
51 aliases for the actual scalar parameters. In particular, if an element
52 C<$_[0]> is updated, the corresponding argument is updated (or an error
53 occurs if it is not updatable). If an argument is an array or hash
54 element which did not exist when the function was called, that element is
55 created only when (and if) it is modified or if a reference to it is
56 taken. (Some earlier versions of Perl created the element whether or not
57 it was assigned to.) Note that assigning to the whole array @_ removes
58 the aliasing, and does not update any arguments.
60 The return value of the subroutine is the value of the last expression
61 evaluated. Alternatively, a return statement may be used exit the
62 subroutine, optionally specifying the returned value, which will be
63 evaluated in the appropriate context (list, scalar, or void) depending
64 on the context of the subroutine call. If you specify no return value,
65 the subroutine will return an empty list in a list context, an undefined
66 value in a scalar context, or nothing in a void context. If you return
67 one or more arrays and/or hashes, these will be flattened together into
68 one large indistinguishable list.
70 Perl does not have named formal parameters, but in practice all you do is
71 assign to a my() list of these. Any variables you use in the function
72 that aren't declared private are global variables. For the gory details
73 on creating private variables, see
74 L<"Private Variables via my()"> and L<"Temporary Values via local()">.
75 To create protected environments for a set of functions in a separate
76 package (and probably a separate file), see L<perlmod/"Packages">.
83 $max = $foo if $max < $foo;
87 $bestday = max($mon,$tue,$wed,$thu,$fri);
91 # get a line, combining continuation lines
92 # that start with whitespace
95 $thisline = $lookahead; # GLOBAL VARIABLES!!
96 LINE: while (defined($lookahead = <STDIN>)) {
97 if ($lookahead =~ /^[ \t]/) {
98 $thisline .= $lookahead;
107 $lookahead = <STDIN>; # get first line
108 while ($_ = get_line()) {
112 Use array assignment to a local list to name your formal arguments:
115 my($key, $value) = @_;
116 $Foo{$key} = $value unless $Foo{$key};
119 This also has the effect of turning call-by-reference into call-by-value,
120 because the assignment copies the values. Otherwise a function is free to
121 do in-place modifications of @_ and change its caller's values.
123 upcase_in($v1, $v2); # this changes $v1 and $v2
125 for (@_) { tr/a-z/A-Z/ }
128 You aren't allowed to modify constants in this way, of course. If an
129 argument were actually literal and you tried to change it, you'd take a
130 (presumably fatal) exception. For example, this won't work:
132 upcase_in("frederick");
134 It would be much safer if the upcase_in() function
135 were written to return a copy of its parameters instead
136 of changing them in place:
138 ($v3, $v4) = upcase($v1, $v2); # this doesn't
140 return unless defined wantarray; # void context, do nothing
142 for (@parms) { tr/a-z/A-Z/ }
143 return wantarray ? @parms : $parms[0];
146 Notice how this (unprototyped) function doesn't care whether it was passed
147 real scalars or arrays. Perl will see everything as one big long flat @_
148 parameter list. This is one of the ways where Perl's simple
149 argument-passing style shines. The upcase() function would work perfectly
150 well without changing the upcase() definition even if we fed it things
153 @newlist = upcase(@list1, @list2);
154 @newlist = upcase( split /:/, $var );
156 Do not, however, be tempted to do this:
158 (@a, @b) = upcase(@list1, @list2);
160 Because like its flat incoming parameter list, the return list is also
161 flat. So all you have managed to do here is stored everything in @a and
162 made @b an empty list. See L</"Pass by Reference"> for alternatives.
164 A subroutine may be called using the "&" prefix. The "&" is optional
165 in modern Perls, and so are the parentheses if the subroutine has been
166 predeclared. (Note, however, that the "&" is I<NOT> optional when
167 you're just naming the subroutine, such as when it's used as an
168 argument to defined() or undef(). Nor is it optional when you want to
169 do an indirect subroutine call with a subroutine name or reference
170 using the C<&$subref()> or C<&{$subref}()> constructs. See L<perlref>
173 Subroutines may be called recursively. If a subroutine is called using
174 the "&" form, the argument list is optional, and if omitted, no @_ array is
175 set up for the subroutine: the @_ array at the time of the call is
176 visible to subroutine instead. This is an efficiency mechanism that
177 new users may wish to avoid.
179 &foo(1,2,3); # pass three arguments
180 foo(1,2,3); # the same
182 foo(); # pass a null list
185 &foo; # foo() get current args, like foo(@_) !!
186 foo; # like foo() IFF sub foo predeclared, else "foo"
188 Not only does the "&" form make the argument list optional, but it also
189 disables any prototype checking on the arguments you do provide. This
190 is partly for historical reasons, and partly for having a convenient way
191 to cheat if you know what you're doing. See the section on Prototypes below.
193 =head2 Private Variables via my()
197 my $foo; # declare $foo lexically local
198 my (@wid, %get); # declare list of variables local
199 my $foo = "flurp"; # declare $foo lexical, and init it
200 my @oof = @bar; # declare @oof lexical, and init it
202 A "my" declares the listed variables to be confined (lexically) to the
203 enclosing block, conditional (C<if/unless/elsif/else>), loop
204 (C<for/foreach/while/until/continue>), subroutine, C<eval>, or
205 C<do/require/use>'d file. If more than one value is listed, the list
206 must be placed in parentheses. All listed elements must be legal lvalues.
207 Only alphanumeric identifiers may be lexically scoped--magical
208 builtins like $/ must currently be localized with "local" instead.
210 Unlike dynamic variables created by the "local" statement, lexical
211 variables declared with "my" are totally hidden from the outside world,
212 including any called subroutines (even if it's the same subroutine called
213 from itself or elsewhere--every call gets its own copy).
215 (An eval(), however, can see the lexical variables of the scope it is
216 being evaluated in so long as the names aren't hidden by declarations within
217 the eval() itself. See L<perlref>.)
219 The parameter list to my() may be assigned to if desired, which allows you
220 to initialize your variables. (If no initializer is given for a
221 particular variable, it is created with the undefined value.) Commonly
222 this is used to name the parameters to a subroutine. Examples:
224 $arg = "fred"; # "global" variable
226 print "$arg thinks the root is $n\n";
227 fred thinks the root is 3
230 my $arg = shift; # name doesn't matter
235 The "my" is simply a modifier on something you might assign to. So when
236 you do assign to the variables in its argument list, the "my" doesn't
237 change whether those variables is viewed as a scalar or an array. So
242 both supply a list context to the right-hand side, while
246 supplies a scalar context. But the following declares only one variable:
250 That has the same effect as
255 The declared variable is not introduced (is not visible) until after
256 the current statement. Thus,
260 can be used to initialize the new $x with the value of the old $x, and
263 my $x = 123 and $x == 123
265 is false unless the old $x happened to have the value 123.
267 Lexical scopes of control structures are not bounded precisely by the
268 braces that delimit their controlled blocks; control expressions are
269 part of the scope, too. Thus in the loop
271 while (defined(my $line = <>)) {
277 the scope of $line extends from its declaration throughout the rest of
278 the loop construct (including the C<continue> clause), but not beyond
279 it. Similarly, in the conditional
281 if ((my $answer = <STDIN>) =~ /^yes$/i) {
283 } elsif ($answer =~ /^no$/i) {
287 die "'$answer' is neither 'yes' nor 'no'";
290 the scope of $answer extends from its declaration throughout the rest
291 of the conditional (including C<elsif> and C<else> clauses, if any),
294 (None of the foregoing applies to C<if/unless> or C<while/until>
295 modifiers appended to simple statements. Such modifiers are not
296 control structures and have no effect on scoping.)
298 The C<foreach> loop defaults to scoping its index variable dynamically
299 (in the manner of C<local>; see below). However, if the index
300 variable is prefixed with the keyword "my", then it is lexically
301 scoped instead. Thus in the loop
303 for my $i (1, 2, 3) {
307 the scope of $i extends to the end of the loop, but not beyond it, and
308 so the value of $i is unavailable in some_function().
310 Some users may wish to encourage the use of lexically scoped variables.
311 As an aid to catching implicit references to package variables,
316 then any variable reference from there to the end of the enclosing
317 block must either refer to a lexical variable, or must be fully
318 qualified with the package name. A compilation error results
319 otherwise. An inner block may countermand this with S<"no strict 'vars'">.
321 A my() has both a compile-time and a run-time effect. At compile time,
322 the compiler takes notice of it; the principle usefulness of this is to
323 quiet C<use strict 'vars'>. The actual initialization doesn't happen
324 until run time, so gets executed every time through a loop.
326 Variables declared with "my" are not part of any package and are therefore
327 never fully qualified with the package name. In particular, you're not
328 allowed to try to make a package variable (or other global) lexical:
330 my $pack::var; # ERROR! Illegal syntax
331 my $_; # also illegal (currently)
333 In fact, a dynamic variable (also known as package or global variables)
334 are still accessible using the fully qualified :: notation even while a
335 lexical of the same name is also visible:
340 print "$x and $::x\n";
342 That will print out 20 and 10.
344 You may declare "my" variables at the outermost scope of a file to
345 hide any such identifiers totally from the outside world. This is similar
346 to C's static variables at the file level. To do this with a subroutine
347 requires the use of a closure (anonymous function). If a block (such as
348 an eval(), function, or C<package>) wants to create a private subroutine
349 that cannot be called from outside that block, it can declare a lexical
350 variable containing an anonymous sub reference:
352 my $secret_version = '1.001-beta';
353 my $secret_sub = sub { print $secret_version };
356 As long as the reference is never returned by any function within the
357 module, no outside module can see the subroutine, because its name is not in
358 any package's symbol table. Remember that it's not I<REALLY> called
359 $some_pack::secret_version or anything; it's just $secret_version,
360 unqualified and unqualifiable.
362 This does not work with object methods, however; all object methods have
363 to be in the symbol table of some package to be found.
365 Just because the lexical variable is lexically (also called statically)
366 scoped doesn't mean that within a function it works like a C static. It
367 normally works more like a C auto. But here's a mechanism for giving a
368 function private variables with both lexical scoping and a static
369 lifetime. If you do want to create something like C's static variables,
370 just enclose the whole function in an extra block, and put the
371 static variable outside the function but in the block.
376 return ++$secret_val;
379 # $secret_val now becomes unreachable by the outside
380 # world, but retains its value between calls to gimme_another
382 If this function is being sourced in from a separate file
383 via C<require> or C<use>, then this is probably just fine. If it's
384 all in the main program, you'll need to arrange for the my()
385 to be executed early, either by putting the whole block above
386 your pain program, or more likely, placing merely a BEGIN
387 sub around it to make sure it gets executed before your program
393 return ++$secret_val;
397 See L<perlrun> about the BEGIN function.
399 =head2 Temporary Values via local()
401 B<NOTE>: In general, you should be using "my" instead of "local", because
402 it's faster and safer. Exceptions to this include the global punctuation
403 variables, filehandles and formats, and direct manipulation of the Perl
404 symbol table itself. Format variables often use "local" though, as do
405 other variables whose current value must be visible to called
410 local $foo; # declare $foo dynamically local
411 local (@wid, %get); # declare list of variables local
412 local $foo = "flurp"; # declare $foo dynamic, and init it
413 local @oof = @bar; # declare @oof dynamic, and init it
415 local *FH; # localize $FH, @FH, %FH, &FH ...
416 local *merlyn = *randal; # now $merlyn is really $randal, plus
417 # @merlyn is really @randal, etc
418 local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal
419 local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc
421 A local() modifies its listed variables to be local to the enclosing
422 block, (or subroutine, C<eval{}>, or C<do>) and I<any called from
423 within that block>. A local() just gives temporary values to global
424 (meaning package) variables. This is known as dynamic scoping. Lexical
425 scoping is done with "my", which works more like C's auto declarations.
427 If more than one variable is given to local(), they must be placed in
428 parentheses. All listed elements must be legal lvalues. This operator works
429 by saving the current values of those variables in its argument list on a
430 hidden stack and restoring them upon exiting the block, subroutine, or
431 eval. This means that called subroutines can also reference the local
432 variable, but not the global one. The argument list may be assigned to if
433 desired, which allows you to initialize your local variables. (If no
434 initializer is given for a particular variable, it is created with an
435 undefined value.) Commonly this is used to name the parameters to a
436 subroutine. Examples:
441 # assume this function uses global %digits hash
444 # now temporarily add to %digits hash
446 # (NOTE: not claiming this is efficient!)
447 local %digits = (%digits, 't' => 10, 'e' => 11);
448 parse_num(); # parse_num gets this new %digits!
450 # old %digits restored here
452 Because local() is a run-time command, it gets executed every time
453 through a loop. In releases of Perl previous to 5.0, this used more stack
454 storage each time until the loop was exited. Perl now reclaims the space
455 each time through, but it's still more efficient to declare your variables
458 A local is simply a modifier on an lvalue expression. When you assign to
459 a localized variable, the local doesn't change whether its list is viewed
460 as a scalar or an array. So
462 local($foo) = <STDIN>;
463 local @FOO = <STDIN>;
465 both supply a list context to the right-hand side, while
467 local $foo = <STDIN>;
469 supplies a scalar context.
471 =head2 Passing Symbol Table Entries (typeglobs)
473 [Note: The mechanism described in this section was originally the only
474 way to simulate pass-by-reference in older versions of Perl. While it
475 still works fine in modern versions, the new reference mechanism is
476 generally easier to work with. See below.]
478 Sometimes you don't want to pass the value of an array to a subroutine
479 but rather the name of it, so that the subroutine can modify the global
480 copy of it rather than working with a local copy. In perl you can
481 refer to all objects of a particular name by prefixing the name
482 with a star: C<*foo>. This is often known as a "typeglob", because the
483 star on the front can be thought of as a wildcard match for all the
484 funny prefix characters on variables and subroutines and such.
486 When evaluated, the typeglob produces a scalar value that represents
487 all the objects of that name, including any filehandle, format, or
488 subroutine. When assigned to, it causes the name mentioned to refer to
489 whatever "*" value was assigned to it. Example:
492 local(*someary) = @_;
493 foreach $elem (@someary) {
500 Note that scalars are already passed by reference, so you can modify
501 scalar arguments without using this mechanism by referring explicitly
502 to C<$_[0]> etc. You can modify all the elements of an array by passing
503 all the elements as scalars, but you have to use the * mechanism (or
504 the equivalent reference mechanism) to push, pop, or change the size of
505 an array. It will certainly be faster to pass the typeglob (or reference).
507 Even if you don't want to modify an array, this mechanism is useful for
508 passing multiple arrays in a single LIST, because normally the LIST
509 mechanism will merge all the array values so that you can't extract out
510 the individual arrays. For more on typeglobs, see
511 L<perldata/"Typeglobs and Filehandles">.
513 =head2 Pass by Reference
515 If you want to pass more than one array or hash into a function--or
516 return them from it--and have them maintain their integrity, then
517 you're going to have to use an explicit pass-by-reference. Before you
518 do that, you need to understand references as detailed in L<perlref>.
519 This section may not make much sense to you otherwise.
521 Here are a few simple examples. First, let's pass in several
522 arrays to a function and have it pop all of then, return a new
523 list of all their former last elements:
525 @tailings = popmany ( \@a, \@b, \@c, \@d );
530 foreach $aref ( @_ ) {
531 push @retlist, pop @$aref;
536 Here's how you might write a function that returns a
537 list of keys occurring in all the hashes passed to it:
539 @common = inter( \%foo, \%bar, \%joe );
541 my ($k, $href, %seen); # locals
543 while ( $k = each %$href ) {
547 return grep { $seen{$_} == @_ } keys %seen;
550 So far, we're using just the normal list return mechanism.
551 What happens if you want to pass or return a hash? Well,
552 if you're using only one of them, or you don't mind them
553 concatenating, then the normal calling convention is ok, although
556 Where people get into trouble is here:
558 (@a, @b) = func(@c, @d);
560 (%a, %b) = func(%c, %d);
562 That syntax simply won't work. It sets just @a or %a and clears the @b or
563 %b. Plus the function didn't get passed into two separate arrays or
564 hashes: it got one long list in @_, as always.
566 If you can arrange for everyone to deal with this through references, it's
567 cleaner code, although not so nice to look at. Here's a function that
568 takes two array references as arguments, returning the two array elements
569 in order of how many elements they have in them:
571 ($aref, $bref) = func(\@c, \@d);
572 print "@$aref has more than @$bref\n";
574 my ($cref, $dref) = @_;
575 if (@$cref > @$dref) {
576 return ($cref, $dref);
578 return ($dref, $cref);
582 It turns out that you can actually do this also:
584 (*a, *b) = func(\@c, \@d);
585 print "@a has more than @b\n";
595 Here we're using the typeglobs to do symbol table aliasing. It's
596 a tad subtle, though, and also won't work if you're using my()
597 variables, because only globals (well, and local()s) are in the symbol table.
599 If you're passing around filehandles, you could usually just use the bare
600 typeglob, like *STDOUT, but typeglobs references would be better because
601 they'll still work properly under C<use strict 'refs'>. For example:
606 print $fh "her um well a hmmm\n";
609 $rec = get_rec(\*STDIN);
615 Another way to do this is using *HANDLE{IO}, see L<perlref> for usage
618 If you're planning on generating new filehandles, you could do this:
623 return open (FH, $path) ? *FH : undef;
626 Although that will actually produce a small memory leak. See the bottom
627 of L<perlfunc/open()> for a somewhat cleaner way using the IO::Handle
632 As of the 5.002 release of perl, if you declare
636 then mypush() takes arguments exactly like push() does. The declaration
637 of the function to be called must be visible at compile time. The prototype
638 affects only the interpretation of new-style calls to the function, where
639 new-style is defined as not using the C<&> character. In other words,
640 if you call it like a builtin function, then it behaves like a builtin
641 function. If you call it like an old-fashioned subroutine, then it
642 behaves like an old-fashioned subroutine. It naturally falls out from
643 this rule that prototypes have no influence on subroutine references
644 like C<\&foo> or on indirect subroutine calls like C<&{$subref}>.
646 Method calls are not influenced by prototypes either, because the
647 function to be called is indeterminate at compile time, because it depends
650 Because the intent is primarily to let you define subroutines that work
651 like builtin commands, here are the prototypes for some other functions
652 that parse almost exactly like the corresponding builtins.
654 Declared as Called as
656 sub mylink ($$) mylink $old, $new
657 sub myvec ($$$) myvec $var, $offset, 1
658 sub myindex ($$;$) myindex &getstring, "substr"
659 sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off
660 sub myreverse (@) myreverse $a,$b,$c
661 sub myjoin ($@) myjoin ":",$a,$b,$c
662 sub mypop (\@) mypop @array
663 sub mysplice (\@$$@) mysplice @array,@array,0,@pushme
664 sub mykeys (\%) mykeys %{$hashref}
665 sub myopen (*;$) myopen HANDLE, $name
666 sub mypipe (**) mypipe READHANDLE, WRITEHANDLE
667 sub mygrep (&@) mygrep { /foo/ } $a,$b,$c
668 sub myrand ($) myrand 42
671 Any backslashed prototype character represents an actual argument
672 that absolutely must start with that character. The value passed
673 to the subroutine (as part of C<@_>) will be a reference to the
674 actual argument given in the subroutine call, obtained by applying
675 C<\> to that argument.
677 Unbackslashed prototype characters have special meanings. Any
678 unbackslashed @ or % eats all the rest of the arguments, and forces
679 list context. An argument represented by $ forces scalar context. An
680 & requires an anonymous subroutine, which, if passed as the first
681 argument, does not require the "sub" keyword or a subsequent comma. A
682 * does whatever it has to do to turn the argument into a reference to a
685 A semicolon separates mandatory arguments from optional arguments.
686 (It is redundant before @ or %.)
688 Note how the last three examples above are treated specially by the parser.
689 mygrep() is parsed as a true list operator, myrand() is parsed as a
690 true unary operator with unary precedence the same as rand(), and
691 mytime() is truly without arguments, just like time(). That is, if you
696 you'll get mytime() + 2, not mytime(2), which is how it would be parsed
697 without the prototype.
699 The interesting thing about & is that you can generate new syntax with it:
702 my($try,$catch) = @_;
709 sub catch (&) { $_[0] }
714 /phooey/ and print "unphooey\n";
717 That prints "unphooey". (Yes, there are still unresolved
718 issues having to do with the visibility of @_. I'm ignoring that
719 question for the moment. (But note that if we make @_ lexically
720 scoped, those anonymous subroutines can act like closures... (Gee,
721 is this sounding a little Lispish? (Never mind.))))
723 And here's a reimplementation of grep:
729 push(@result, $_) if &$code;
734 Some folks would prefer full alphanumeric prototypes. Alphanumerics have
735 been intentionally left out of prototypes for the express purpose of
736 someday in the future adding named, formal parameters. The current
737 mechanism's main goal is to let module writers provide better diagnostics
738 for module users. Larry feels the notation quite understandable to Perl
739 programmers, and that it will not intrude greatly upon the meat of the
740 module, nor make it harder to read. The line noise is visually
741 encapsulated into a small pill that's easy to swallow.
743 It's probably best to prototype new functions, not retrofit prototyping
744 into older ones. That's because you must be especially careful about
745 silent impositions of differing list versus scalar contexts. For example,
746 if you decide that a function should take just one parameter, like this:
750 print "you gave me $n\n";
753 and someone has been calling it with an array or expression
759 Then you've just supplied an automatic scalar() in front of their
760 argument, which can be more than a bit surprising. The old @foo
761 which used to hold one thing doesn't get passed in. Instead,
762 the func() now gets passed in 1, that is, the number of elements
763 in @foo. And the split() gets called in a scalar context and
764 starts scribbling on your @_ parameter list.
766 This is all very powerful, of course, and should be used only in moderation
767 to make the world a better place.
769 =head2 Constant Functions
771 Functions with a prototype of C<()> are potential candidates for
772 inlining. If the result after optimization and constant folding is
773 either a constant or a lexically-scoped scalar which has no other
774 references, then it will be used in place of function calls made
775 without C<&> or C<do>. Calls made using C<&> or C<do> are never
776 inlined. (See constant.pm for an easy way to declare most
779 All of the following functions would be inlined.
781 sub pi () { 3.14159 } # Not exact, but close.
782 sub PI () { 4 * atan2 1, 1 } # As good as it gets,
783 # and it's inlined, too!
787 sub FLAG_FOO () { 1 << 8 }
788 sub FLAG_BAR () { 1 << 9 }
789 sub FLAG_MASK () { FLAG_FOO | FLAG_BAR }
791 sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) }
801 sub N () { int(BAZ_VAL) / 3 }
804 for (1..N) { $prod *= $_ }
805 sub N_FACTORIAL () { $prod }
808 If you redefine a subroutine which was eligible for inlining you'll get
809 a mandatory warning. (You can use this warning to tell whether or not a
810 particular subroutine is considered constant.) The warning is
811 considered severe enough not to be optional because previously compiled
812 invocations of the function will still be using the old value of the
813 function. If you need to be able to redefine the subroutine you need to
814 ensure that it isn't inlined, either by dropping the C<()> prototype
815 (which changes the calling semantics, so beware) or by thwarting the
816 inlining mechanism in some other way, such as
822 =head2 Overriding Builtin Functions
824 Many builtin functions may be overridden, though this should be tried
825 only occasionally and for good reason. Typically this might be
826 done by a package attempting to emulate missing builtin functionality
827 on a non-Unix system.
829 Overriding may be done only by importing the name from a
830 module--ordinary predeclaration isn't good enough. However, the
831 C<subs> pragma (compiler directive) lets you, in effect, predeclare subs
832 via the import syntax, and these names may then override the builtin ones:
834 use subs 'chdir', 'chroot', 'chmod', 'chown';
838 Library modules should not in general export builtin names like "open"
839 or "chdir" as part of their default @EXPORT list, because these may
840 sneak into someone else's namespace and change the semantics unexpectedly.
841 Instead, if the module adds the name to the @EXPORT_OK list, then it's
842 possible for a user to import the name explicitly, but not implicitly.
843 That is, they could say
847 and it would import the open override, but if they said
851 they would get the default imports without the overrides.
855 If you call a subroutine that is undefined, you would ordinarily get an
856 immediate fatal error complaining that the subroutine doesn't exist.
857 (Likewise for subroutines being used as methods, when the method
858 doesn't exist in any of the base classes of the class package.) If,
859 however, there is an C<AUTOLOAD> subroutine defined in the package or
860 packages that were searched for the original subroutine, then that
861 C<AUTOLOAD> subroutine is called with the arguments that would have been
862 passed to the original subroutine. The fully qualified name of the
863 original subroutine magically appears in the $AUTOLOAD variable in the
864 same package as the C<AUTOLOAD> routine. The name is not passed as an
865 ordinary argument because, er, well, just because, that's why...
867 Most C<AUTOLOAD> routines will load in a definition for the subroutine in
868 question using eval, and then execute that subroutine using a special
869 form of "goto" that erases the stack frame of the C<AUTOLOAD> routine
870 without a trace. (See the standard C<AutoLoader> module, for example.)
871 But an C<AUTOLOAD> routine can also just emulate the routine and never
872 define it. For example, let's pretend that a function that wasn't defined
873 should just call system() with those arguments. All you'd do is this:
876 my $program = $AUTOLOAD;
877 $program =~ s/.*:://;
878 system($program, @_);
884 In fact, if you predeclare the functions you want to call that way, you don't
885 even need the parentheses:
887 use subs qw(date who ls);
892 A more complete example of this is the standard Shell module, which
893 can treat undefined subroutine calls as calls to Unix programs.
895 Mechanisms are available for modules writers to help split the modules
896 up into autoloadable files. See the standard AutoLoader module
897 described in L<AutoLoader> and in L<AutoSplit>, the standard
898 SelfLoader modules in L<SelfLoader>, and the document on adding C
899 functions to perl code in L<perlxs>.
903 See L<perlref> for more on references. See L<perlxs> if you'd
904 like to learn about calling C subroutines from perl. See
905 L<perlmod> to learn about bundling up your functions in