Don't count on 'trap 0' inside () in shell script
[perl.git] / 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
12     sub NAME BLOCK        # A declaration and a definition.
13     sub NAME(PROTO) BLOCK #  ditto, but with prototypes
14
15 To define an anonymous subroutine at runtime:
16
17     $subref = sub BLOCK;
18
19 To import subroutines:
20
21     use PACKAGE qw(NAME1 NAME2 NAME3);
22
23 To call subroutines:
24
25     NAME(LIST);    # & is optional with parentheses.
26     NAME LIST;     # Parentheses optional if pre-declared/imported.
27     &NAME;         # Passes current @_ to subroutine.
28
29 =head1 DESCRIPTION
30
31 Like many languages, Perl provides for user-defined subroutines.  These
32 may be located anywhere in the main program, loaded in from other files
33 via the C<do>, C<require>, or C<use> keywords, or even generated on the
34 fly using C<eval> or anonymous subroutines (closures).  You can even call
35 a function indirectly using a variable containing its name or a CODE reference
36 to it, as in C<$var = \&function>.
37
38 The Perl model for function call and return values is simple: all
39 functions are passed as parameters one single flat list of scalars, and
40 all functions likewise return to their caller one single flat list of
41 scalars.  Any arrays or hashes in these call and return lists will
42 collapse, losing their identities--but you may always use
43 pass-by-reference instead to avoid this.  Both call and return lists may
44 contain as many or as few scalar elements as you'd like.  (Often a
45 function without an explicit return statement is called a subroutine, but
46 there's really no difference from the language's perspective.)
47
48 Any arguments passed to the routine come in as the array @_.  Thus if you
49 called a function with two arguments, those would be stored in C<$_[0]>
50 and C<$_[1]>.  The array @_ is a local array, but its values are implicit
51 references (predating L<perlref>) to the actual scalar parameters.  What
52 this means in practice is that when you explicitly modify C<$_[0]> et al.,
53 you will be changing the actual arguments.  As a result, all arguments
54 to functions are treated as lvalues.  Any hash or array elements that are
55 passed to functions will get created if they do not exist (irrespective
56 of whether the function does modify the contents of C<@_>).  This is
57 frequently a source of surprise.  See L<perltrap> for an example.
58
59 The return value of the subroutine is the value of the last expression
60 evaluated.  Alternatively, a return statement may be used to specify the
61 returned value and exit the subroutine.  If you return one or more arrays
62 and/or hashes, these will be flattened together into one large
63 indistinguishable list.
64
65 Perl does not have named formal parameters, but in practice all you do is
66 assign to a my() list of these.  Any variables you use in the function
67 that aren't declared private are global variables.  For the gory details
68 on creating private variables, see
69 L<"Private Variables via my()"> and L<"Temporary Values via local()">.
70 To create protected environments for a set of functions in a separate
71 package (and probably a separate file), see L<perlmod/"Packages">.
72
73 Example:
74
75     sub max {
76         my $max = shift(@_);
77         foreach $foo (@_) {
78             $max = $foo if $max < $foo;
79         }
80         return $max;
81     }
82     $bestday = max($mon,$tue,$wed,$thu,$fri);
83
84 Example:
85
86     # get a line, combining continuation lines
87     #  that start with whitespace
88
89     sub get_line {
90         $thisline = $lookahead;  # GLOBAL VARIABLES!!
91         LINE: while ($lookahead = <STDIN>) {
92             if ($lookahead =~ /^[ \t]/) {
93                 $thisline .= $lookahead;
94             }
95             else {
96                 last LINE;
97             }
98         }
99         $thisline;
100     }
101
102     $lookahead = <STDIN>;       # get first line
103     while ($_ = get_line()) {
104         ...
105     }
106
107 Use array assignment to a local list to name your formal arguments:
108
109     sub maybeset {
110         my($key, $value) = @_;
111         $Foo{$key} = $value unless $Foo{$key};
112     }
113
114 This also has the effect of turning call-by-reference into call-by-value,
115 because the assignment copies the values.  Otherwise a function is free to
116 do in-place modifications of @_ and change its caller's values.
117
118     upcase_in($v1, $v2);  # this changes $v1 and $v2
119     sub upcase_in {
120         for (@_) { tr/a-z/A-Z/ } 
121     } 
122
123 You aren't allowed to modify constants in this way, of course.  If an
124 argument were actually literal and you tried to change it, you'd take a
125 (presumably fatal) exception.   For example, this won't work:
126
127     upcase_in("frederick");
128
129 It would be much safer if the upcase_in() function 
130 were written to return a copy of its parameters instead
131 of changing them in place:
132
133     ($v3, $v4) = upcase($v1, $v2);  # this doesn't
134     sub upcase {
135         my @parms = @_;
136         for (@parms) { tr/a-z/A-Z/ } 
137         # wantarray checks if we were called in list context
138         return wantarray ? @parms : $parms[0];
139     } 
140
141 Notice how this (unprototyped) function doesn't care whether it was passed
142 real scalars or arrays.  Perl will see everything as one big long flat @_
143 parameter list.  This is one of the ways where Perl's simple
144 argument-passing style shines.  The upcase() function would work perfectly
145 well without changing the upcase() definition even if we fed it things
146 like this:
147
148     @newlist   = upcase(@list1, @list2);
149     @newlist   = upcase( split /:/, $var );
150
151 Do not, however, be tempted to do this:
152
153     (@a, @b)   = upcase(@list1, @list2);
154
155 Because like its flat incoming parameter list, the return list is also
156 flat.  So all you have managed to do here is stored everything in @a and
157 made @b an empty list.  See L</"Pass by Reference"> for alternatives.
158
159 A subroutine may be called using the "&" prefix.  The "&" is optional
160 in modern Perls, and so are the parentheses if the subroutine has been
161 pre-declared.  (Note, however, that the "&" is I<NOT> optional when
162 you're just naming the subroutine, such as when it's used as an
163 argument to defined() or undef().  Nor is it optional when you want to
164 do an indirect subroutine call with a subroutine name or reference
165 using the C<&$subref()> or C<&{$subref}()> constructs.  See L<perlref>
166 for more on that.)
167
168 Subroutines may be called recursively.  If a subroutine is called using
169 the "&" form, the argument list is optional, and if omitted, no @_ array is
170 set up for the subroutine: the @_ array at the time of the call is
171 visible to subroutine instead.  This is an efficiency mechanism that
172 new users may wish to avoid.
173
174     &foo(1,2,3);        # pass three arguments
175     foo(1,2,3);         # the same
176
177     foo();              # pass a null list
178     &foo();             # the same
179
180     &foo;               # foo() get current args, like foo(@_) !!
181     foo;                # like foo() IFF sub foo pre-declared, else "foo"
182
183 Not only does the "&" form make the argument list optional, but it also
184 disables any prototype checking on the arguments you do provide.  This
185 is partly for historical reasons, and partly for having a convenient way
186 to cheat if you know what you're doing.  See the section on Prototypes below.
187
188 =head2 Private Variables via my()
189
190 Synopsis:
191
192     my $foo;            # declare $foo lexically local
193     my (@wid, %get);    # declare list of variables local
194     my $foo = "flurp";  # declare $foo lexical, and init it
195     my @oof = @bar;     # declare @oof lexical, and init it
196
197 A "my" declares the listed variables to be confined (lexically) to the
198 enclosing block, conditional (C<if/unless/elsif/else>), loop
199 (C<for/foreach/while/until/continue>), subroutine, C<eval>, or
200 C<do/require/use>'d file.  If more than one value is listed, the list
201 must be placed in parentheses.  All listed elements must be legal lvalues.
202 Only alphanumeric identifiers may be lexically scoped--magical
203 builtins like $/ must currently be localized with "local" instead.
204
205 Unlike dynamic variables created by the "local" statement, lexical
206 variables declared with "my" are totally hidden from the outside world,
207 including any called subroutines (even if it's the same subroutine called
208 from itself or elsewhere--every call gets its own copy).
209
210 (An eval(), however, can see the lexical variables of the scope it is
211 being evaluated in so long as the names aren't hidden by declarations within
212 the eval() itself.  See L<perlref>.)
213
214 The parameter list to my() may be assigned to if desired, which allows you
215 to initialize your variables.  (If no initializer is given for a
216 particular variable, it is created with the undefined value.)  Commonly
217 this is used to name the parameters to a subroutine.  Examples:
218
219     $arg = "fred";        # "global" variable
220     $n = cube_root(27);
221     print "$arg thinks the root is $n\n";
222  fred thinks the root is 3
223
224     sub cube_root {
225         my $arg = shift;  # name doesn't matter
226         $arg **= 1/3;
227         return $arg;
228     }                   
229
230 The "my" is simply a modifier on something you might assign to.  So when
231 you do assign to the variables in its argument list, the "my" doesn't
232 change whether those variables is viewed as a scalar or an array.  So
233
234     my ($foo) = <STDIN>;
235     my @FOO = <STDIN>;
236
237 both supply a list context to the right-hand side, while
238
239     my $foo = <STDIN>;
240
241 supplies a scalar context.  But the following declares only one variable:
242
243     my $foo, $bar = 1;
244
245 That has the same effect as
246
247     my $foo;
248     $bar = 1;
249
250 The declared variable is not introduced (is not visible) until after
251 the current statement.  Thus,
252
253     my $x = $x;
254
255 can be used to initialize the new $x with the value of the old $x, and 
256 the expression
257
258     my $x = 123 and $x == 123
259
260 is false unless the old $x happened to have the value 123.
261
262 Lexical scopes of control structures are not bounded precisely by the
263 braces that delimit their controlled blocks; control expressions are
264 part of the scope, too.  Thus in the loop
265
266     while (my $line = <>) {
267         $line = lc $line;
268     } continue {
269         print $line;
270     }
271
272 the scope of $line extends from its declaration throughout the rest of
273 the loop construct (including the C<continue> clause), but not beyond
274 it.  Similarly, in the conditional
275
276     if ((my $answer = <STDIN>) =~ /^yes$/i) {
277         user_agrees();
278     } elsif ($answer =~ /^no$/i) {
279         user_disagrees();
280     } else {
281         chomp $answer;
282         die "'$answer' is neither 'yes' nor 'no'";
283     }
284
285 the scope of $answer extends from its declaration throughout the rest
286 of the conditional (including C<elsif> and C<else> clauses, if any),
287 but not beyond it.
288
289 (None of the foregoing applies to C<if/unless> or C<while/until>
290 modifiers appended to simple statements.  Such modifiers are not
291 control structures and have no effect on scoping.)
292
293 The C<foreach> loop defaults to scoping its index variable dynamically
294 (in the manner of C<local>; see below).  However, if the index
295 variable is prefixed with the keyword "my", then it is lexically
296 scoped instead.  Thus in the loop
297
298     for my $i (1, 2, 3) {
299         some_function();
300     }
301
302 the scope of $i extends to the end of the loop, but not beyond it, and
303 so the value of $i is unavailable in some_function().
304
305 Some users may wish to encourage the use of lexically scoped variables.
306 As an aid to catching implicit references to package variables,
307 if you say
308
309     use strict 'vars';
310
311 then any variable reference from there to the end of the enclosing
312 block must either refer to a lexical variable, or must be fully
313 qualified with the package name.  A compilation error results
314 otherwise.  An inner block may countermand this with S<"no strict 'vars'">.
315
316 A my() has both a compile-time and a run-time effect.  At compile time,
317 the compiler takes notice of it; the principle usefulness of this is to
318 quiet C<use strict 'vars'>.  The actual initialization doesn't happen
319 until run time, so gets executed every time through a loop.
320
321 Variables declared with "my" are not part of any package and are therefore
322 never fully qualified with the package name.  In particular, you're not
323 allowed to try to make a package variable (or other global) lexical:
324
325     my $pack::var;      # ERROR!  Illegal syntax
326     my $_;              # also illegal (currently)
327
328 In fact, a dynamic variable (also known as package or global variables)
329 are still accessible using the fully qualified :: notation even while a
330 lexical of the same name is also visible:
331
332     package main;
333     local $x = 10;
334     my    $x = 20;
335     print "$x and $::x\n";
336
337 That will print out 20 and 10.
338
339 You may declare "my" variables at the outermost scope of a file to
340 hide any such identifiers totally from the outside world.  This is similar
341 to C's static variables at the file level.  To do this with a subroutine
342 requires the use of a closure (anonymous function).  If a block (such as
343 an eval(), function, or C<package>) wants to create a private subroutine
344 that cannot be called from outside that block, it can declare a lexical
345 variable containing an anonymous sub reference:
346
347     my $secret_version = '1.001-beta';
348     my $secret_sub = sub { print $secret_version };
349     &$secret_sub();
350
351 As long as the reference is never returned by any function within the
352 module, no outside module can see the subroutine, because its name is not in
353 any package's symbol table.  Remember that it's not I<REALLY> called
354 $some_pack::secret_version or anything; it's just $secret_version,
355 unqualified and unqualifiable.
356
357 This does not work with object methods, however; all object methods have
358 to be in the symbol table of some package to be found.
359
360 Just because the lexical variable is lexically (also called statically)
361 scoped doesn't mean that within a function it works like a C static.  It
362 normally works more like a C auto.  But here's a mechanism for giving a
363 function private variables with both lexical scoping and a static
364 lifetime.  If you do want to create something like C's static variables,
365 just enclose the whole function in an extra block, and put the
366 static variable outside the function but in the block.
367
368     {
369         my $secret_val = 0; 
370         sub gimme_another {
371             return ++$secret_val;
372         } 
373     } 
374     # $secret_val now becomes unreachable by the outside
375     # world, but retains its value between calls to gimme_another
376
377 If this function is being sourced in from a separate file 
378 via C<require> or C<use>, then this is probably just fine.  If it's
379 all in the main program, you'll need to arrange for the my() 
380 to be executed early, either by putting the whole block above
381 your pain program, or more likely, placing merely a BEGIN 
382 sub around it to make sure it gets executed before your program
383 starts to run:
384
385     sub BEGIN {
386         my $secret_val = 0; 
387         sub gimme_another {
388             return ++$secret_val;
389         } 
390     } 
391
392 See L<perlrun> about the BEGIN function.
393
394 =head2 Temporary Values via local()
395
396 B<NOTE>: In general, you should be using "my" instead of "local", because
397 it's faster and safer.  Exceptions to this include the global punctuation
398 variables, filehandles and formats, and direct manipulation of the Perl
399 symbol table itself.  Format variables often use "local" though, as do
400 other variables whose current value must be visible to called
401 subroutines.
402
403 Synopsis:
404
405     local $foo;                 # declare $foo dynamically local
406     local (@wid, %get);         # declare list of variables local
407     local $foo = "flurp";       # declare $foo dynamic, and init it
408     local @oof = @bar;          # declare @oof dynamic, and init it
409
410     local *FH;                  # localize $FH, @FH, %FH, &FH  ...
411     local *merlyn = *randal;    # now $merlyn is really $randal, plus
412                                 #     @merlyn is really @randal, etc
413     local *merlyn = 'randal';   # SAME THING: promote 'randal' to *randal
414     local *merlyn = \$randal;   # just alias $merlyn, not @merlyn etc 
415
416 A local() modifies its listed variables to be local to the enclosing
417 block, (or subroutine, C<eval{}>, or C<do>) and I<any called from
418 within that block>.  A local() just gives temporary values to global
419 (meaning package) variables.  This is known as dynamic scoping.  Lexical
420 scoping is done with "my", which works more like C's auto declarations.
421
422 If more than one variable is given to local(), they must be placed in
423 parentheses.  All listed elements must be legal lvalues.  This operator works
424 by saving the current values of those variables in its argument list on a
425 hidden stack and restoring them upon exiting the block, subroutine, or
426 eval.  This means that called subroutines can also reference the local
427 variable, but not the global one.  The argument list may be assigned to if
428 desired, which allows you to initialize your local variables.  (If no
429 initializer is given for a particular variable, it is created with an
430 undefined value.)  Commonly this is used to name the parameters to a
431 subroutine.  Examples:
432
433     for $i ( 0 .. 9 ) {
434         $digits{$i} = $i;
435     } 
436     # assume this function uses global %digits hash
437     parse_num();  
438
439     # now temporarily add to %digits hash
440     if ($base12) {
441         # (NOTE: not claiming this is efficient!)
442         local %digits  = (%digits, 't' => 10, 'e' => 11);
443         parse_num();  # parse_num gets this new %digits!
444     }
445     # old %digits restored here
446
447 Because local() is a run-time command, it gets executed every time
448 through a loop.  In releases of Perl previous to 5.0, this used more stack
449 storage each time until the loop was exited.  Perl now reclaims the space
450 each time through, but it's still more efficient to declare your variables
451 outside the loop.
452
453 A local is simply a modifier on an lvalue expression.  When you assign to
454 a localized variable, the local doesn't change whether its list is viewed
455 as a scalar or an array.  So
456
457     local($foo) = <STDIN>;
458     local @FOO = <STDIN>;
459
460 both supply a list context to the right-hand side, while
461
462     local $foo = <STDIN>;
463
464 supplies a scalar context.
465
466 =head2 Passing Symbol Table Entries (typeglobs)
467
468 [Note:  The mechanism described in this section was originally the only
469 way to simulate pass-by-reference in older versions of Perl.  While it
470 still works fine in modern versions, the new reference mechanism is
471 generally easier to work with.  See below.]
472
473 Sometimes you don't want to pass the value of an array to a subroutine
474 but rather the name of it, so that the subroutine can modify the global
475 copy of it rather than working with a local copy.  In perl you can
476 refer to all objects of a particular name by prefixing the name
477 with a star: C<*foo>.  This is often known as a "typeglob", because the
478 star on the front can be thought of as a wildcard match for all the
479 funny prefix characters on variables and subroutines and such.
480
481 When evaluated, the typeglob produces a scalar value that represents
482 all the objects of that name, including any filehandle, format, or
483 subroutine.  When assigned to, it causes the name mentioned to refer to
484 whatever "*" value was assigned to it.  Example:
485
486     sub doubleary {
487         local(*someary) = @_;
488         foreach $elem (@someary) {
489             $elem *= 2;
490         }
491     }
492     doubleary(*foo);
493     doubleary(*bar);
494
495 Note that scalars are already passed by reference, so you can modify
496 scalar arguments without using this mechanism by referring explicitly
497 to C<$_[0]> etc.  You can modify all the elements of an array by passing
498 all the elements as scalars, but you have to use the * mechanism (or
499 the equivalent reference mechanism) to push, pop, or change the size of
500 an array.  It will certainly be faster to pass the typeglob (or reference).
501
502 Even if you don't want to modify an array, this mechanism is useful for
503 passing multiple arrays in a single LIST, because normally the LIST
504 mechanism will merge all the array values so that you can't extract out
505 the individual arrays.  For more on typeglobs, see
506 L<perldata/"Typeglobs and FileHandles">.
507
508 =head2 Pass by Reference
509
510 If you want to pass more than one array or hash into a function--or
511 return them from it--and have them maintain their integrity, then
512 you're going to have to use an explicit pass-by-reference.  Before you
513 do that, you need to understand references as detailed in L<perlref>.
514 This section may not make much sense to you otherwise.
515
516 Here are a few simple examples.  First, let's pass in several
517 arrays to a function and have it pop all of then, return a new
518 list of all their former last elements:
519
520     @tailings = popmany ( \@a, \@b, \@c, \@d );
521
522     sub popmany {
523         my $aref;
524         my @retlist = ();
525         foreach $aref ( @_ ) {
526             push @retlist, pop @$aref;
527         } 
528         return @retlist;
529     } 
530
531 Here's how you might write a function that returns a 
532 list of keys occurring in all the hashes passed to it:
533
534     @common = inter( \%foo, \%bar, \%joe ); 
535     sub inter {
536         my ($k, $href, %seen); # locals
537         foreach $href (@_) {
538             while ( $k = each %$href ) {
539                 $seen{$k}++;
540             } 
541         } 
542         return grep { $seen{$_} == @_ } keys %seen;
543     } 
544
545 So far, we're using just the normal list return mechanism.
546 What happens if you want to pass or return a hash?  Well, 
547 if you're using only one of them, or you don't mind them 
548 concatenating, then the normal calling convention is ok, although
549 a little expensive.  
550
551 Where people get into trouble is here:
552
553     (@a, @b) = func(@c, @d);
554 or
555     (%a, %b) = func(%c, %d);
556
557 That syntax simply won't work.  It sets just @a or %a and clears the @b or
558 %b.  Plus the function didn't get passed into two separate arrays or
559 hashes: it got one long list in @_, as always.
560
561 If you can arrange for everyone to deal with this through references, it's
562 cleaner code, although not so nice to look at.  Here's a function that
563 takes two array references as arguments, returning the two array elements
564 in order of how many elements they have in them:
565
566     ($aref, $bref) = func(\@c, \@d);
567     print "@$aref has more than @$bref\n";
568     sub func {
569         my ($cref, $dref) = @_;
570         if (@$cref > @$dref) {
571             return ($cref, $dref);
572         } else {
573             return ($dref, $cref);
574         } 
575     } 
576
577 It turns out that you can actually do this also:
578
579     (*a, *b) = func(\@c, \@d);
580     print "@a has more than @b\n";
581     sub func {
582         local (*c, *d) = @_;
583         if (@c > @d) {
584             return (\@c, \@d);
585         } else {
586             return (\@d, \@c);
587         } 
588     } 
589
590 Here we're using the typeglobs to do symbol table aliasing.  It's
591 a tad subtle, though, and also won't work if you're using my()
592 variables, because only globals (well, and local()s) are in the symbol table.
593
594 If you're passing around filehandles, you could usually just use the bare
595 typeglob, like *STDOUT, but typeglobs references would be better because
596 they'll still work properly under C<use strict 'refs'>.  For example:
597
598     splutter(\*STDOUT);
599     sub splutter {
600         my $fh = shift;
601         print $fh "her um well a hmmm\n";
602     }
603
604     $rec = get_rec(\*STDIN);
605     sub get_rec {
606         my $fh = shift;
607         return scalar <$fh>;
608     }
609
610 Another way to do this is using *HANDLE{IO}, see L<perlref> for usage
611 and caveats.
612
613 If you're planning on generating new filehandles, you could do this:
614
615     sub openit {
616         my $name = shift;
617         local *FH;
618         return open (FH, $path) ? *FH : undef;
619     } 
620
621 Although that will actually produce a small memory leak.  See the bottom
622 of L<perlfunc/open()> for a somewhat cleaner way using the IO::Handle
623 package.
624
625 =head2 Prototypes
626
627 As of the 5.002 release of perl, if you declare
628
629     sub mypush (\@@)
630
631 then mypush() takes arguments exactly like push() does.  The declaration
632 of the function to be called must be visible at compile time.  The prototype
633 affects only the interpretation of new-style calls to the function, where
634 new-style is defined as not using the C<&> character.  In other words,
635 if you call it like a builtin function, then it behaves like a builtin
636 function.  If you call it like an old-fashioned subroutine, then it
637 behaves like an old-fashioned subroutine.  It naturally falls out from
638 this rule that prototypes have no influence on subroutine references
639 like C<\&foo> or on indirect subroutine calls like C<&{$subref}>.
640
641 Method calls are not influenced by prototypes either, because the
642 function to be called is indeterminate at compile time, because it depends
643 on inheritance.
644
645 Because the intent is primarily to let you define subroutines that work
646 like builtin commands, here are the prototypes for some other functions
647 that parse almost exactly like the corresponding builtins.
648
649     Declared as                 Called as
650
651     sub mylink ($$)             mylink $old, $new
652     sub myvec ($$$)             myvec $var, $offset, 1
653     sub myindex ($$;$)          myindex &getstring, "substr"
654     sub mysyswrite ($$$;$)      mysyswrite $buf, 0, length($buf) - $off, $off
655     sub myreverse (@)           myreverse $a,$b,$c
656     sub myjoin ($@)             myjoin ":",$a,$b,$c
657     sub mypop (\@)              mypop @array
658     sub mysplice (\@$$@)        mysplice @array,@array,0,@pushme
659     sub mykeys (\%)             mykeys %{$hashref}
660     sub myopen (*;$)            myopen HANDLE, $name
661     sub mypipe (**)             mypipe READHANDLE, WRITEHANDLE
662     sub mygrep (&@)             mygrep { /foo/ } $a,$b,$c
663     sub myrand ($)              myrand 42
664     sub mytime ()               mytime
665
666 Any backslashed prototype character represents an actual argument
667 that absolutely must start with that character.  The value passed
668 to the subroutine (as part of C<@_>) will be a reference to the
669 actual argument given in the subroutine call, obtained by applying
670 C<\> to that argument.
671
672 Unbackslashed prototype characters have special meanings.  Any
673 unbackslashed @ or % eats all the rest of the arguments, and forces
674 list context.  An argument represented by $ forces scalar context.  An
675 & requires an anonymous subroutine, which, if passed as the first
676 argument, does not require the "sub" keyword or a subsequent comma.  A
677 * does whatever it has to do to turn the argument into a reference to a
678 symbol table entry.
679
680 A semicolon separates mandatory arguments from optional arguments.
681 (It is redundant before @ or %.)
682
683 Note how the last three examples above are treated specially by the parser.
684 mygrep() is parsed as a true list operator, myrand() is parsed as a
685 true unary operator with unary precedence the same as rand(), and
686 mytime() is truly without arguments, just like time().  That is, if you
687 say
688
689     mytime +2;
690
691 you'll get mytime() + 2, not mytime(2), which is how it would be parsed
692 without the prototype.
693
694 The interesting thing about & is that you can generate new syntax with it:
695
696     sub try (&@) {
697         my($try,$catch) = @_;
698         eval { &$try };
699         if ($@) {
700             local $_ = $@;
701             &$catch;
702         }
703     }
704     sub catch (&) { $_[0] }
705
706     try {
707         die "phooey";
708     } catch {
709         /phooey/ and print "unphooey\n";
710     };
711
712 That prints "unphooey".  (Yes, there are still unresolved
713 issues having to do with the visibility of @_.  I'm ignoring that
714 question for the moment.  (But note that if we make @_ lexically
715 scoped, those anonymous subroutines can act like closures... (Gee,
716 is this sounding a little Lispish?  (Never mind.))))
717
718 And here's a reimplementation of grep:
719
720     sub mygrep (&@) {
721         my $code = shift;
722         my @result;
723         foreach $_ (@_) {
724             push(@result, $_) if &$code;
725         }
726         @result;
727     }
728
729 Some folks would prefer full alphanumeric prototypes.  Alphanumerics have
730 been intentionally left out of prototypes for the express purpose of
731 someday in the future adding named, formal parameters.  The current
732 mechanism's main goal is to let module writers provide better diagnostics
733 for module users.  Larry feels the notation quite understandable to Perl
734 programmers, and that it will not intrude greatly upon the meat of the
735 module, nor make it harder to read.  The line noise is visually
736 encapsulated into a small pill that's easy to swallow.
737
738 It's probably best to prototype new functions, not retrofit prototyping
739 into older ones.  That's because you must be especially careful about
740 silent impositions of differing list versus scalar contexts.  For example,
741 if you decide that a function should take just one parameter, like this:
742
743     sub func ($) {
744         my $n = shift;
745         print "you gave me $n\n";
746     } 
747
748 and someone has been calling it with an array or expression
749 returning a list:
750
751     func(@foo);
752     func( split /:/ );
753
754 Then you've just supplied an automatic scalar() in front of their
755 argument, which can be more than a bit surprising.  The old @foo
756 which used to hold one thing doesn't get passed in.  Instead,
757 the func() now gets passed in 1, that is, the number of elements
758 in @foo.  And the split() gets called in a scalar context and
759 starts scribbling on your @_ parameter list.
760
761 This is all very powerful, of course, and should be used only in moderation
762 to make the world a better place.  
763
764 =head2 Constant Functions
765
766 Functions with a prototype of C<()> are potential candidates for
767 inlining.  If the result after optimization and constant folding is a
768 constant then it will be used in place of new-style calls to the
769 function.  Old-style calls (that is, calls made using C<&>) are not
770 affected.
771
772 All of the following functions would be inlined.
773
774     sub PI ()           { 3.14159 }
775     sub ST_DEV ()       { 0 }
776     sub ST_INO ()       { 1 }
777
778     sub FLAG_FOO ()     { 1 << 8 }
779     sub FLAG_BAR ()     { 1 << 9 }
780     sub FLAG_MASK ()    { FLAG_FOO | FLAG_BAR }
781     
782     sub OPT_BAZ ()      { 1 }
783     sub BAZ_VAL () {
784         if (OPT_BAZ) {
785             return 23;
786         }
787         else {
788             return 42;
789         }
790     }
791
792 If you redefine a subroutine which was eligible for inlining you'll get
793 a mandatory warning.  (You can use this warning to tell whether or not a
794 particular subroutine is considered constant.)  The warning is
795 considered severe enough not to be optional because previously compiled
796 invocations of the function will still be using the old value of the
797 function.  If you need to be able to redefine the subroutine you need to
798 ensure that it isn't inlined, either by dropping the C<()> prototype
799 (which changes the calling semantics, so beware) or by thwarting the
800 inlining mechanism in some other way, such as
801
802     my $dummy;
803     sub not_inlined () {
804         $dummy || 23
805     }
806
807 =head2 Overriding Builtin Functions
808
809 Many builtin functions may be overridden, though this should be tried
810 only occasionally and for good reason.  Typically this might be
811 done by a package attempting to emulate missing builtin functionality
812 on a non-Unix system.
813
814 Overriding may be done only by importing the name from a
815 module--ordinary predeclaration isn't good enough.  However, the
816 C<subs> pragma (compiler directive) lets you, in effect, pre-declare subs
817 via the import syntax, and these names may then override the builtin ones:
818
819     use subs 'chdir', 'chroot', 'chmod', 'chown';
820     chdir $somewhere;
821     sub chdir { ... }
822
823 Library modules should not in general export builtin names like "open"
824 or "chdir" as part of their default @EXPORT list, because these may
825 sneak into someone else's namespace and change the semantics unexpectedly.
826 Instead, if the module adds the name to the @EXPORT_OK list, then it's
827 possible for a user to import the name explicitly, but not implicitly.
828 That is, they could say
829
830     use Module 'open';
831
832 and it would import the open override, but if they said
833
834     use Module;
835
836 they would get the default imports without the overrides.
837
838 =head2 Autoloading
839
840 If you call a subroutine that is undefined, you would ordinarily get an
841 immediate fatal error complaining that the subroutine doesn't exist.
842 (Likewise for subroutines being used as methods, when the method
843 doesn't exist in any of the base classes of the class package.) If,
844 however, there is an C<AUTOLOAD> subroutine defined in the package or
845 packages that were searched for the original subroutine, then that
846 C<AUTOLOAD> subroutine is called with the arguments that would have been
847 passed to the original subroutine.  The fully qualified name of the
848 original subroutine magically appears in the $AUTOLOAD variable in the
849 same package as the C<AUTOLOAD> routine.  The name is not passed as an
850 ordinary argument because, er, well, just because, that's why...
851
852 Most C<AUTOLOAD> routines will load in a definition for the subroutine in
853 question using eval, and then execute that subroutine using a special
854 form of "goto" that erases the stack frame of the C<AUTOLOAD> routine
855 without a trace.  (See the standard C<AutoLoader> module, for example.)
856 But an C<AUTOLOAD> routine can also just emulate the routine and never
857 define it.   For example, let's pretend that a function that wasn't defined
858 should just call system() with those arguments.  All you'd do is this:
859
860     sub AUTOLOAD {
861         my $program = $AUTOLOAD;
862         $program =~ s/.*:://;
863         system($program, @_);
864     } 
865     date();
866     who('am', 'i');
867     ls('-l');
868
869 In fact, if you pre-declare the functions you want to call that way, you don't
870 even need the parentheses:
871
872     use subs qw(date who ls);
873     date;
874     who "am", "i";
875     ls -l;
876
877 A more complete example of this is the standard Shell module, which
878 can treat undefined subroutine calls as calls to Unix programs.
879
880 Mechanisms are available for modules writers to help split the modules
881 up into autoloadable files.  See the standard AutoLoader module
882 described in L<AutoLoader> and in L<AutoSplit>, the standard
883 SelfLoader modules in L<SelfLoader>, and the document on adding C
884 functions to perl code in L<perlxs>.
885
886 =head1 SEE ALSO
887
888 See L<perlref> for more on references.  See L<perlxs> if you'd
889 like to learn about calling C subroutines from perl.  See 
890 L<perlmod> to learn about bundling up your functions in 
891 separate files.