pod/perlsub.pod

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