pod/perlsub.pod

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