This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Re: Exceptions in IPC::Open2
[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
3e3baf6d 61evaluated. Alternatively, a return statement may be used to exit the
54310121
PP
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
7b8d334a 162made @b an empty list. See L<Pass by Reference> for alternatives.
cb1a09d0 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
3e3baf6d
TB
472A note about C<local()> and composite types is in order. Something
473like C<local(%foo)> works by temporarily placing a brand new hash in
474the symbol table. The old hash is left alone, but is hidden "behind"
475the new one.
476
477This means the old variable is completely invisible via the symbol
478table (i.e. the hash entry in the C<*foo> typeglob) for the duration
479of the dynamic scope within which the C<local()> was seen. This
480has the effect of allowing one to temporarily occlude any magic on
481composite types. For instance, this will briefly alter a tied
482hash to some other implementation:
483
484 tie %ahash, 'APackage';
485 [...]
486 {
487 local %ahash;
488 tie %ahash, 'BPackage';
489 [..called code will see %ahash tied to 'BPackage'..]
490 {
491 local %ahash;
492 [..%ahash is a normal (untied) hash here..]
493 }
494 }
495 [..%ahash back to its initial tied self again..]
496
497As another example, a custom implementation of C<%ENV> might look
498like this:
499
500 {
501 local %ENV;
502 tie %ENV, 'MyOwnEnv';
503 [..do your own fancy %ENV manipulation here..]
504 }
505 [..normal %ENV behavior here..]
506
6ee623d5
GS
507It's also worth taking a moment to explain what happens when you
508localize a member of a composite type (i.e. an array or hash element).
509In this case, the element is localized I<by name>. This means that
510when the scope of the C<local()> ends, the saved value will be
511restored to the hash element whose key was named in the C<local()>, or
512the array element whose index was named in the C<local()>. If that
513element was deleted while the C<local()> was in effect (e.g. by a
514C<delete()> from a hash or a C<shift()> of an array), it will spring
515back into existence, possibly extending an array and filling in the
516skipped elements with C<undef>. For instance, if you say
517
518 %hash = ( 'This' => 'is', 'a' => 'test' );
519 @ary = ( 0..5 );
520 {
521 local($ary[5]) = 6;
522 local($hash{'a'}) = 'drill';
523 while (my $e = pop(@ary)) {
524 print "$e . . .\n";
525 last unless $e > 3;
526 }
527 if (@ary) {
528 $hash{'only a'} = 'test';
529 delete $hash{'a'};
530 }
531 }
532 print join(' ', map { "$_ $hash{$_}" } sort keys %hash),".\n";
533 print "The array has ",scalar(@ary)," elements: ",
534 join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\n";
535
536Perl will print
537
538 6 . . .
539 4 . . .
540 3 . . .
541 This is a test only a test.
542 The array has 6 elements: 0, 1, 2, undef, undef, 5
543
544In short, be careful when manipulating the containers for composite types
545whose elements have been localized.
3e3baf6d 546
cb1a09d0
AD
547=head2 Passing Symbol Table Entries (typeglobs)
548
549[Note: The mechanism described in this section was originally the only
550way to simulate pass-by-reference in older versions of Perl. While it
551still works fine in modern versions, the new reference mechanism is
552generally easier to work with. See below.]
a0d0e21e
LW
553
554Sometimes you don't want to pass the value of an array to a subroutine
555but rather the name of it, so that the subroutine can modify the global
556copy of it rather than working with a local copy. In perl you can
cb1a09d0 557refer to all objects of a particular name by prefixing the name
5f05dabc 558with a star: C<*foo>. This is often known as a "typeglob", because the
a0d0e21e
LW
559star on the front can be thought of as a wildcard match for all the
560funny prefix characters on variables and subroutines and such.
561
55497cff 562When evaluated, the typeglob produces a scalar value that represents
5f05dabc 563all the objects of that name, including any filehandle, format, or
a0d0e21e
LW
564subroutine. When assigned to, it causes the name mentioned to refer to
565whatever "*" value was assigned to it. Example:
566
567 sub doubleary {
568 local(*someary) = @_;
569 foreach $elem (@someary) {
570 $elem *= 2;
571 }
572 }
573 doubleary(*foo);
574 doubleary(*bar);
575
576Note that scalars are already passed by reference, so you can modify
577scalar arguments without using this mechanism by referring explicitly
1fef88e7 578to C<$_[0]> etc. You can modify all the elements of an array by passing
a0d0e21e 579all the elements as scalars, but you have to use the * mechanism (or
5f05dabc 580the equivalent reference mechanism) to push, pop, or change the size of
a0d0e21e
LW
581an array. It will certainly be faster to pass the typeglob (or reference).
582
583Even if you don't want to modify an array, this mechanism is useful for
5f05dabc 584passing multiple arrays in a single LIST, because normally the LIST
a0d0e21e 585mechanism will merge all the array values so that you can't extract out
55497cff 586the individual arrays. For more on typeglobs, see
2ae324a7 587L<perldata/"Typeglobs and Filehandles">.
cb1a09d0
AD
588
589=head2 Pass by Reference
590
55497cff
PP
591If you want to pass more than one array or hash into a function--or
592return them from it--and have them maintain their integrity, then
593you're going to have to use an explicit pass-by-reference. Before you
594do that, you need to understand references as detailed in L<perlref>.
c07a80fd 595This section may not make much sense to you otherwise.
cb1a09d0
AD
596
597Here are a few simple examples. First, let's pass in several
598arrays to a function and have it pop all of then, return a new
599list of all their former last elements:
600
601 @tailings = popmany ( \@a, \@b, \@c, \@d );
602
603 sub popmany {
604 my $aref;
605 my @retlist = ();
606 foreach $aref ( @_ ) {
607 push @retlist, pop @$aref;
54310121 608 }
cb1a09d0 609 return @retlist;
54310121 610 }
cb1a09d0 611
54310121 612Here's how you might write a function that returns a
cb1a09d0
AD
613list of keys occurring in all the hashes passed to it:
614
54310121 615 @common = inter( \%foo, \%bar, \%joe );
cb1a09d0
AD
616 sub inter {
617 my ($k, $href, %seen); # locals
618 foreach $href (@_) {
619 while ( $k = each %$href ) {
620 $seen{$k}++;
54310121
PP
621 }
622 }
cb1a09d0 623 return grep { $seen{$_} == @_ } keys %seen;
54310121 624 }
cb1a09d0 625
5f05dabc 626So far, we're using just the normal list return mechanism.
54310121
PP
627What happens if you want to pass or return a hash? Well,
628if you're using only one of them, or you don't mind them
cb1a09d0 629concatenating, then the normal calling convention is ok, although
54310121 630a little expensive.
cb1a09d0
AD
631
632Where people get into trouble is here:
633
634 (@a, @b) = func(@c, @d);
635or
636 (%a, %b) = func(%c, %d);
637
5f05dabc 638That syntax simply won't work. It sets just @a or %a and clears the @b or
cb1a09d0
AD
639%b. Plus the function didn't get passed into two separate arrays or
640hashes: it got one long list in @_, as always.
641
642If you can arrange for everyone to deal with this through references, it's
643cleaner code, although not so nice to look at. Here's a function that
644takes two array references as arguments, returning the two array elements
645in order of how many elements they have in them:
646
647 ($aref, $bref) = func(\@c, \@d);
648 print "@$aref has more than @$bref\n";
649 sub func {
650 my ($cref, $dref) = @_;
651 if (@$cref > @$dref) {
652 return ($cref, $dref);
653 } else {
c07a80fd 654 return ($dref, $cref);
54310121
PP
655 }
656 }
cb1a09d0
AD
657
658It turns out that you can actually do this also:
659
660 (*a, *b) = func(\@c, \@d);
661 print "@a has more than @b\n";
662 sub func {
663 local (*c, *d) = @_;
664 if (@c > @d) {
665 return (\@c, \@d);
666 } else {
667 return (\@d, \@c);
54310121
PP
668 }
669 }
cb1a09d0
AD
670
671Here we're using the typeglobs to do symbol table aliasing. It's
672a tad subtle, though, and also won't work if you're using my()
5f05dabc
PP
673variables, because only globals (well, and local()s) are in the symbol table.
674
675If you're passing around filehandles, you could usually just use the bare
676typeglob, like *STDOUT, but typeglobs references would be better because
677they'll still work properly under C<use strict 'refs'>. For example:
678
679 splutter(\*STDOUT);
680 sub splutter {
681 my $fh = shift;
682 print $fh "her um well a hmmm\n";
683 }
684
685 $rec = get_rec(\*STDIN);
686 sub get_rec {
687 my $fh = shift;
688 return scalar <$fh>;
689 }
690
691Another way to do this is using *HANDLE{IO}, see L<perlref> for usage
692and caveats.
693
694If you're planning on generating new filehandles, you could do this:
695
696 sub openit {
697 my $name = shift;
698 local *FH;
e05a3a1e 699 return open (FH, $path) ? *FH : undef;
54310121 700 }
5f05dabc
PP
701
702Although that will actually produce a small memory leak. See the bottom
703of L<perlfunc/open()> for a somewhat cleaner way using the IO::Handle
704package.
cb1a09d0 705
cb1a09d0
AD
706=head2 Prototypes
707
708As of the 5.002 release of perl, if you declare
709
710 sub mypush (\@@)
711
c07a80fd
PP
712then mypush() takes arguments exactly like push() does. The declaration
713of the function to be called must be visible at compile time. The prototype
5f05dabc 714affects only the interpretation of new-style calls to the function, where
c07a80fd
PP
715new-style is defined as not using the C<&> character. In other words,
716if you call it like a builtin function, then it behaves like a builtin
717function. If you call it like an old-fashioned subroutine, then it
718behaves like an old-fashioned subroutine. It naturally falls out from
719this rule that prototypes have no influence on subroutine references
720like C<\&foo> or on indirect subroutine calls like C<&{$subref}>.
721
722Method calls are not influenced by prototypes either, because the
5f05dabc 723function to be called is indeterminate at compile time, because it depends
c07a80fd 724on inheritance.
cb1a09d0 725
5f05dabc 726Because the intent is primarily to let you define subroutines that work
c07a80fd
PP
727like builtin commands, here are the prototypes for some other functions
728that parse almost exactly like the corresponding builtins.
cb1a09d0
AD
729
730 Declared as Called as
731
732 sub mylink ($$) mylink $old, $new
733 sub myvec ($$$) myvec $var, $offset, 1
734 sub myindex ($$;$) myindex &getstring, "substr"
735 sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off
736 sub myreverse (@) myreverse $a,$b,$c
737 sub myjoin ($@) myjoin ":",$a,$b,$c
738 sub mypop (\@) mypop @array
739 sub mysplice (\@$$@) mysplice @array,@array,0,@pushme
740 sub mykeys (\%) mykeys %{$hashref}
741 sub myopen (*;$) myopen HANDLE, $name
742 sub mypipe (**) mypipe READHANDLE, WRITEHANDLE
743 sub mygrep (&@) mygrep { /foo/ } $a,$b,$c
744 sub myrand ($) myrand 42
745 sub mytime () mytime
746
c07a80fd 747Any backslashed prototype character represents an actual argument
6e47f808
PP
748that absolutely must start with that character. The value passed
749to the subroutine (as part of C<@_>) will be a reference to the
750actual argument given in the subroutine call, obtained by applying
751C<\> to that argument.
c07a80fd
PP
752
753Unbackslashed prototype characters have special meanings. Any
754unbackslashed @ or % eats all the rest of the arguments, and forces
755list context. An argument represented by $ forces scalar context. An
756& requires an anonymous subroutine, which, if passed as the first
757argument, does not require the "sub" keyword or a subsequent comma. A
758* does whatever it has to do to turn the argument into a reference to a
759symbol table entry.
760
761A semicolon separates mandatory arguments from optional arguments.
762(It is redundant before @ or %.)
cb1a09d0 763
c07a80fd 764Note how the last three examples above are treated specially by the parser.
cb1a09d0
AD
765mygrep() is parsed as a true list operator, myrand() is parsed as a
766true unary operator with unary precedence the same as rand(), and
5f05dabc 767mytime() is truly without arguments, just like time(). That is, if you
cb1a09d0
AD
768say
769
770 mytime +2;
771
772you'll get mytime() + 2, not mytime(2), which is how it would be parsed
773without the prototype.
774
775The interesting thing about & is that you can generate new syntax with it:
776
6d28dffb 777 sub try (&@) {
cb1a09d0
AD
778 my($try,$catch) = @_;
779 eval { &$try };
780 if ($@) {
781 local $_ = $@;
782 &$catch;
783 }
784 }
55497cff 785 sub catch (&) { $_[0] }
cb1a09d0
AD
786
787 try {
788 die "phooey";
789 } catch {
790 /phooey/ and print "unphooey\n";
791 };
792
793That prints "unphooey". (Yes, there are still unresolved
794issues having to do with the visibility of @_. I'm ignoring that
795question for the moment. (But note that if we make @_ lexically
796scoped, those anonymous subroutines can act like closures... (Gee,
5f05dabc 797is this sounding a little Lispish? (Never mind.))))
cb1a09d0
AD
798
799And here's a reimplementation of grep:
800
801 sub mygrep (&@) {
802 my $code = shift;
803 my @result;
804 foreach $_ (@_) {
6e47f808 805 push(@result, $_) if &$code;
cb1a09d0
AD
806 }
807 @result;
808 }
a0d0e21e 809
cb1a09d0
AD
810Some folks would prefer full alphanumeric prototypes. Alphanumerics have
811been intentionally left out of prototypes for the express purpose of
812someday in the future adding named, formal parameters. The current
813mechanism's main goal is to let module writers provide better diagnostics
814for module users. Larry feels the notation quite understandable to Perl
815programmers, and that it will not intrude greatly upon the meat of the
816module, nor make it harder to read. The line noise is visually
817encapsulated into a small pill that's easy to swallow.
818
819It's probably best to prototype new functions, not retrofit prototyping
820into older ones. That's because you must be especially careful about
821silent impositions of differing list versus scalar contexts. For example,
822if you decide that a function should take just one parameter, like this:
823
824 sub func ($) {
825 my $n = shift;
826 print "you gave me $n\n";
54310121 827 }
cb1a09d0
AD
828
829and someone has been calling it with an array or expression
830returning a list:
831
832 func(@foo);
833 func( split /:/ );
834
835Then you've just supplied an automatic scalar() in front of their
836argument, which can be more than a bit surprising. The old @foo
837which used to hold one thing doesn't get passed in. Instead,
5f05dabc 838the func() now gets passed in 1, that is, the number of elements
cb1a09d0
AD
839in @foo. And the split() gets called in a scalar context and
840starts scribbling on your @_ parameter list.
841
5f05dabc 842This is all very powerful, of course, and should be used only in moderation
54310121 843to make the world a better place.
44a8e56a
PP
844
845=head2 Constant Functions
846
847Functions with a prototype of C<()> are potential candidates for
54310121
PP
848inlining. If the result after optimization and constant folding is
849either a constant or a lexically-scoped scalar which has no other
850references, then it will be used in place of function calls made
851without C<&> or C<do>. Calls made using C<&> or C<do> are never
852inlined. (See constant.pm for an easy way to declare most
853constants.)
44a8e56a
PP
854
855All of the following functions would be inlined.
856
699e6cd4
TP
857 sub pi () { 3.14159 } # Not exact, but close.
858 sub PI () { 4 * atan2 1, 1 } # As good as it gets,
859 # and it's inlined, too!
44a8e56a
PP
860 sub ST_DEV () { 0 }
861 sub ST_INO () { 1 }
862
863 sub FLAG_FOO () { 1 << 8 }
864 sub FLAG_BAR () { 1 << 9 }
865 sub FLAG_MASK () { FLAG_FOO | FLAG_BAR }
54310121
PP
866
867 sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) }
44a8e56a
PP
868 sub BAZ_VAL () {
869 if (OPT_BAZ) {
870 return 23;
871 }
872 else {
873 return 42;
874 }
875 }
cb1a09d0 876
54310121
PP
877 sub N () { int(BAZ_VAL) / 3 }
878 BEGIN {
879 my $prod = 1;
880 for (1..N) { $prod *= $_ }
881 sub N_FACTORIAL () { $prod }
882 }
883
4cee8e80
CS
884If you redefine a subroutine which was eligible for inlining you'll get
885a mandatory warning. (You can use this warning to tell whether or not a
886particular subroutine is considered constant.) The warning is
887considered severe enough not to be optional because previously compiled
888invocations of the function will still be using the old value of the
889function. If you need to be able to redefine the subroutine you need to
890ensure that it isn't inlined, either by dropping the C<()> prototype
891(which changes the calling semantics, so beware) or by thwarting the
892inlining mechanism in some other way, such as
893
4cee8e80 894 sub not_inlined () {
54310121 895 23 if $];
4cee8e80
CS
896 }
897
cb1a09d0 898=head2 Overriding Builtin Functions
a0d0e21e 899
5f05dabc
PP
900Many builtin functions may be overridden, though this should be tried
901only occasionally and for good reason. Typically this might be
a0d0e21e
LW
902done by a package attempting to emulate missing builtin functionality
903on a non-Unix system.
904
5f05dabc 905Overriding may be done only by importing the name from a
a0d0e21e 906module--ordinary predeclaration isn't good enough. However, the
54310121 907C<subs> pragma (compiler directive) lets you, in effect, predeclare subs
a0d0e21e
LW
908via the import syntax, and these names may then override the builtin ones:
909
910 use subs 'chdir', 'chroot', 'chmod', 'chown';
911 chdir $somewhere;
912 sub chdir { ... }
913
fb73857a
PP
914To unambiguously refer to the builtin form, one may precede the
915builtin name with the special package qualifier C<CORE::>. For example,
916saying C<CORE::open()> will always refer to the builtin C<open()>, even
917if the current package has imported some other subroutine called
918C<&open()> from elsewhere.
919
a0d0e21e 920Library modules should not in general export builtin names like "open"
5f05dabc 921or "chdir" as part of their default @EXPORT list, because these may
a0d0e21e
LW
922sneak into someone else's namespace and change the semantics unexpectedly.
923Instead, if the module adds the name to the @EXPORT_OK list, then it's
924possible for a user to import the name explicitly, but not implicitly.
925That is, they could say
926
927 use Module 'open';
928
929and it would import the open override, but if they said
930
931 use Module;
932
933they would get the default imports without the overrides.
934
95d94a4f
GS
935The foregoing mechanism for overriding builtins is restricted, quite
936deliberately, to the package that requests the import. There is a second
937method that is sometimes applicable when you wish to override a builtin
938everywhere, without regard to namespace boundaries. This is achieved by
939importing a sub into the special namespace C<CORE::GLOBAL::>. Here is an
940example that quite brazenly replaces the C<glob> operator with something
941that understands regular expressions.
942
943 package REGlob;
944 require Exporter;
945 @ISA = 'Exporter';
946 @EXPORT_OK = 'glob';
947
948 sub import {
949 my $pkg = shift;
950 return unless @_;
951 my $sym = shift;
952 my $where = ($sym =~ s/^GLOBAL_// ? 'CORE::GLOBAL' : caller(0));
953 $pkg->export($where, $sym, @_);
954 }
955
956 sub glob {
957 my $pat = shift;
958 my @got;
959 local(*D);
960 if (opendir D, '.') { @got = grep /$pat/o, readdir D; closedir D; }
961 @got;
962 }
963 1;
964
965And here's how it could be (ab)used:
966
967 #use REGlob 'GLOBAL_glob'; # override glob() in ALL namespaces
968 package Foo;
969 use REGlob 'glob'; # override glob() in Foo:: only
970 print for <^[a-z_]+\.pm\$>; # show all pragmatic modules
971
972Note that the initial comment shows a contrived, even dangerous example.
973By overriding C<glob> globally, you would be forcing the new (and
974subversive) behavior for the C<glob> operator for B<every> namespace,
975without the complete cognizance or cooperation of the modules that own
976those namespaces. Naturally, this should be done with extreme caution--if
977it must be done at all.
978
979The C<REGlob> example above does not implement all the support needed to
980cleanly override perl's C<glob> operator. The builtin C<glob> has
981different behaviors depending on whether it appears in a scalar or list
982context, but our C<REGlob> doesn't. Indeed, many perl builtins have such
983context sensitive behaviors, and these must be adequately supported by
984a properly written override. For a fully functional example of overriding
985C<glob>, study the implementation of C<File::DosGlob> in the standard
986library.
987
fb73857a 988
a0d0e21e
LW
989=head2 Autoloading
990
991If you call a subroutine that is undefined, you would ordinarily get an
992immediate fatal error complaining that the subroutine doesn't exist.
993(Likewise for subroutines being used as methods, when the method
994doesn't exist in any of the base classes of the class package.) If,
995however, there is an C<AUTOLOAD> subroutine defined in the package or
996packages that were searched for the original subroutine, then that
997C<AUTOLOAD> subroutine is called with the arguments that would have been
998passed to the original subroutine. The fully qualified name of the
999original subroutine magically appears in the $AUTOLOAD variable in the
1000same package as the C<AUTOLOAD> routine. The name is not passed as an
1001ordinary argument because, er, well, just because, that's why...
1002
1003Most C<AUTOLOAD> routines will load in a definition for the subroutine in
1004question using eval, and then execute that subroutine using a special
1005form of "goto" that erases the stack frame of the C<AUTOLOAD> routine
1006without a trace. (See the standard C<AutoLoader> module, for example.)
1007But an C<AUTOLOAD> routine can also just emulate the routine and never
cb1a09d0
AD
1008define it. For example, let's pretend that a function that wasn't defined
1009should just call system() with those arguments. All you'd do is this:
1010
1011 sub AUTOLOAD {
1012 my $program = $AUTOLOAD;
1013 $program =~ s/.*:://;
1014 system($program, @_);
54310121 1015 }
cb1a09d0 1016 date();
6d28dffb 1017 who('am', 'i');
cb1a09d0
AD
1018 ls('-l');
1019
54310121 1020In fact, if you predeclare the functions you want to call that way, you don't
cb1a09d0
AD
1021even need the parentheses:
1022
1023 use subs qw(date who ls);
1024 date;
1025 who "am", "i";
1026 ls -l;
1027
1028A more complete example of this is the standard Shell module, which
a0d0e21e
LW
1029can treat undefined subroutine calls as calls to Unix programs.
1030
cb1a09d0 1031Mechanisms are available for modules writers to help split the modules
6d28dffb
PP
1032up into autoloadable files. See the standard AutoLoader module
1033described in L<AutoLoader> and in L<AutoSplit>, the standard
1034SelfLoader modules in L<SelfLoader>, and the document on adding C
1035functions to perl code in L<perlxs>.
cb1a09d0
AD
1036
1037=head1 SEE ALSO
a0d0e21e 1038
cb1a09d0 1039See L<perlref> for more on references. See L<perlxs> if you'd
54310121
PP
1040like to learn about calling C subroutines from perl. See
1041L<perlmod> to learn about bundling up your functions in
cb1a09d0 1042separate files.