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