1N/Aperlsub - Perl subroutines
1N/ATo declare subroutines:
1N/A sub NAME; # A "forward" declaration.
1N/A sub NAME(PROTO); # ditto, but with prototypes
1N/A sub NAME : ATTRS; # with attributes
1N/A sub NAME(PROTO) : ATTRS; # with attributes and prototypes
1N/A sub NAME BLOCK # A declaration and a definition.
1N/A sub NAME(PROTO) BLOCK # ditto, but with prototypes
1N/A sub NAME : ATTRS BLOCK # with attributes
1N/A sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes
1N/ATo define an anonymous subroutine at runtime:
1N/A $subref = sub BLOCK; # no proto
1N/A $subref = sub (PROTO) BLOCK; # with proto
1N/A $subref = sub : ATTRS BLOCK; # with attributes
1N/A $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes
1N/ATo import subroutines:
1N/A use MODULE qw(NAME1 NAME2 NAME3);
1N/A NAME(LIST); # & is optional with parentheses.
1N/A &NAME(LIST); # Circumvent prototypes.
1N/A &NAME; # Makes current @_ visible to called subroutine.
1N/ALike many languages, Perl provides for user-defined subroutines.
1N/AThese may be located anywhere in the main program, loaded in from
1N/Aother files via the C<do>, C<require>, or C<use> keywords, or
1N/Agenerated on the fly using C<eval> or anonymous subroutines.
1N/AYou can even call a function indirectly using a variable containing
1N/Aits name or a CODE reference.
1N/AThe Perl model for function call and return values is simple: all
1N/Afunctions are passed as parameters one single flat list of scalars, and
1N/Aall functions likewise return to their caller one single flat list of
1N/Ascalars. Any arrays or hashes in these call and return lists will
1N/Acollapse, losing their identities--but you may always use
1N/Apass-by-reference instead to avoid this. Both call and return lists may
1N/Acontain as many or as few scalar elements as you'd like. (Often a
1N/Afunction without an explicit return statement is called a subroutine, but
1N/Athere's really no difference from Perl's perspective.)
1N/AAny arguments passed in show up in the array C<@_>. Therefore, if
1N/Ayou called a function with two arguments, those would be stored in
1N/AC<$_[0]> and C<$_[1]>. The array C<@_> is a local array, but its
1N/Aelements are aliases for the actual scalar parameters. In particular,
1N/Aif an element C<$_[0]> is updated, the corresponding argument is
1N/Aupdated (or an error occurs if it is not updatable). If an argument
1N/Ais an array or hash element which did not exist when the function
1N/Awas called, that element is created only when (and if) it is modified
1N/Aor a reference to it is taken. (Some earlier versions of Perl
1N/Acreated the element whether or not the element was assigned to.)
1N/AAssigning to the whole array C<@_> removes that aliasing, and does
1N/Anot update any arguments.
1N/AThe return value of a subroutine is the value of the last expression
1N/Aevaluated by that sub, or the empty list in the case of an empty sub.
1N/AMore explicitly, a C<return> statement may be used to exit the
1N/Asubroutine, optionally specifying the returned value, which will be
1N/Aevaluated in the appropriate context (list, scalar, or void) depending
1N/Aon the context of the subroutine call. If you specify no return value,
1N/Athe subroutine returns an empty list in list context, the undefined
1N/Avalue in scalar context, or nothing in void context. If you return
1N/Aone or more aggregates (arrays and hashes), these will be flattened
1N/Atogether into one large indistinguishable list.
1N/APerl does not have named formal parameters. In practice all you
1N/Ado is assign to a C<my()> list of these. Variables that aren't
1N/Adeclared to be private are global variables. For gory details
1N/Aon creating private variables, see L<"Private Variables via my()">
1N/Aand L<"Temporary Values via local()">. To create protected
1N/Aenvironments for a set of functions in a separate package (and
1N/Aprobably a separate file), see L<perlmod/"Packages">.
1N/A my $max = shift(@_);
1N/A $max = $foo if $max < $foo;
1N/A $bestday = max($mon,$tue,$wed,$thu,$fri);
1N/A # get a line, combining continuation lines
1N/A # that start with whitespace
1N/A $thisline = $lookahead; # global variables!
1N/A LINE: while (defined($lookahead = <STDIN>)) {
1N/A if ($lookahead =~ /^[ \t]/) {
1N/A $thisline .= $lookahead;
1N/A $lookahead = <STDIN>; # get first line
1N/A while (defined($line = get_line())) {
1N/AAssigning to a list of private variables to name your arguments:
1N/A my($key, $value) = @_;
1N/A $Foo{$key} = $value unless $Foo{$key};
1N/ABecause the assignment copies the values, this also has the effect
1N/Aof turning call-by-reference into call-by-value. Otherwise a
1N/Afunction is free to do in-place modifications of C<@_> and change
1N/A upcase_in($v1, $v2); # this changes $v1 and $v2
1N/AYou aren't allowed to modify constants in this way, of course. If an
1N/Aargument were actually literal and you tried to change it, you'd take a
1N/A(presumably fatal) exception. For example, this won't work:
1N/A upcase_in("frederick");
1N/AIt would be much safer if the C<upcase_in()> function
1N/Awere written to return a copy of its parameters instead
1N/Aof changing them in place:
1N/A ($v3, $v4) = upcase($v1, $v2); # this doesn't change $v1 and $v2
1N/A return unless defined wantarray; # void context, do nothing
1N/A return wantarray ? @parms : $parms[0];
1N/ANotice how this (unprototyped) function doesn't care whether it was
1N/Apassed real scalars or arrays. Perl sees all arguments as one big,
1N/Along, flat parameter list in C<@_>. This is one area where
1N/APerl's simple argument-passing style shines. The C<upcase()>
1N/Afunction would work perfectly well without changing the C<upcase()>
1N/Adefinition even if we fed it things like this:
1N/A @newlist = upcase(@list1, @list2);
1N/A @newlist = upcase( split /:/, $var );
1N/ADo not, however, be tempted to do this:
1N/A (@a, @b) = upcase(@list1, @list2);
1N/ALike the flattened incoming parameter list, the return list is also
1N/Aflattened on return. So all you have managed to do here is stored
1N/Aeverything in C<@a> and made C<@b> empty. See
1N/AL<Pass by Reference> for alternatives.
1N/AA subroutine may be called using an explicit C<&> prefix. The
1N/AC<&> is optional in modern Perl, as are parentheses if the
1N/Asubroutine has been predeclared. The C<&> is I<not> optional
1N/Awhen just naming the subroutine, such as when it's used as
1N/Aan argument to defined() or undef(). Nor is it optional when you
1N/Awant to do an indirect subroutine call with a subroutine name or
1N/Areference using the C<&$subref()> or C<&{$subref}()> constructs,
1N/Aalthough the C<< $subref->() >> notation solves that problem.
1N/ASee L<perlref> for more about all that.
1N/ASubroutines may be called recursively. If a subroutine is called
1N/Ausing the C<&> form, the argument list is optional, and if omitted,
1N/Ano C<@_> array is set up for the subroutine: the C<@_> array at the
1N/Atime of the call is visible to subroutine instead. This is an
1N/Aefficiency mechanism that new users may wish to avoid.
1N/A &foo(1,2,3); # pass three arguments
1N/A foo(1,2,3); # the same
1N/A foo(); # pass a null list
1N/A &foo; # foo() get current args, like foo(@_) !!
1N/A foo; # like foo() IFF sub foo predeclared, else "foo"
1N/ANot only does the C<&> form make the argument list optional, it also
1N/Adisables any prototype checking on arguments you do provide. This
1N/Ais partly for historical reasons, and partly for having a convenient way
1N/Ato cheat if you know what you're doing. See L<Prototypes> below.
1N/ASubroutines whose names are in all upper case are reserved to the Perl
1N/Acore, as are modules whose names are in all lower case. A subroutine in
1N/Aall capitals is a loosely-held convention meaning it will be called
1N/Aindirectly by the run-time system itself, usually due to a triggered event.
1N/ASubroutines that do special, pre-defined things include C<AUTOLOAD>, C<CLONE>,
1N/AC<DESTROY> plus all functions mentioned in L<perltie> and L<PerlIO::via>.
1N/AThe C<BEGIN>, C<CHECK>, C<INIT> and C<END> subroutines are not so much
1N/Asubroutines as named special code blocks, of which you can have more
1N/Athan one in a package, and which you can B<not> call explicitely. See
1N/AL<perlmod/"BEGIN, CHECK, INIT and END">
1N/A=head2 Private Variables via my()
1N/A my $foo; # declare $foo lexically local
1N/A my (@wid, %get); # declare list of variables local
1N/A my $foo = "flurp"; # declare $foo lexical, and init it
1N/A my @oof = @bar; # declare @oof lexical, and init it
1N/A my $x : Foo = $y; # similar, with an attribute applied
1N/AB<WARNING>: The use of attribute lists on C<my> declarations is still
1N/Aevolving. The current semantics and interface are subject to change.
1N/ASee L<attributes> and L<Attribute::Handlers>.
1N/AThe C<my> operator declares the listed variables to be lexically
1N/Alist must be placed in parentheses. All listed elements must be
1N/Alegal lvalues. Only alphanumeric identifiers may be lexically
1N/Ascoped--magical built-ins like C<$/> must currently be C<local>ized
1N/Awith C<local> instead.
1N/AUnlike dynamic variables created by the C<local> operator, lexical
1N/Avariables declared with C<my> are totally hidden from the outside
1N/Aworld, including any called subroutines. This is true if it's the
1N/Asame subroutine called from itself or elsewhere--every call gets
1N/AThis doesn't mean that a C<my> variable declared in a statically
1N/Aenclosing lexical scope would be invisible. Only dynamic scopes
1N/Aare cut off. For example, the C<bumpx()> function below has access
1N/Ato the lexical $x variable because both the C<my> and the C<sub>
1N/Aoccurred at the same scope, presumably file scope.
1N/AAn C<eval()>, however, can see lexical variables of the scope it is
1N/Abeing evaluated in, so long as the names aren't hidden by declarations within
1N/Athe C<eval()> itself. See L<perlref>.
1N/AThe parameter list to my() may be assigned to if desired, which allows you
1N/Ato initialize your variables. (If no initializer is given for a
1N/Aparticular variable, it is created with the undefined value.) Commonly
1N/Athis is used to name input parameters to a subroutine. Examples:
1N/A $arg = "fred"; # "global" variable
1N/A print "$arg thinks the root is $n\n";
1N/A fred thinks the root is 3
1N/A my $arg = shift; # name doesn't matter
1N/AThe C<my> is simply a modifier on something you might assign to. So when
1N/Ayou do assign to variables in its argument list, C<my> doesn't
1N/Achange whether those variables are viewed as a scalar or an array. So
1N/A my ($foo) = <STDIN>; # WRONG?
1N/Aboth supply a list context to the right-hand side, while
1N/Asupplies a scalar context. But the following declares only one variable:
1N/A my $foo, $bar = 1; # WRONG
1N/AThat has the same effect as
1N/AThe declared variable is not introduced (is not visible) until after
1N/Athe current statement. Thus,
1N/Acan be used to initialize a new $x with the value of the old $x, and
1N/A my $x = 123 and $x == 123
1N/Ais false unless the old $x happened to have the value C<123>.
1N/ALexical scopes of control structures are not bounded precisely by the
1N/Abraces that delimit their controlled blocks; control expressions are
1N/Apart of that scope, too. Thus in the loop
1N/A while (my $line = <>) {
1N/Athe scope of $line extends from its declaration throughout the rest of
1N/Athe loop construct (including the C<continue> clause), but not beyond
1N/Ait. Similarly, in the conditional
1N/A if ((my $answer = <STDIN>) =~ /^yes$/i) {
1N/A } elsif ($answer =~ /^no$/i) {
1N/A die "'$answer' is neither 'yes' nor 'no'";
1N/Athe scope of $answer extends from its declaration through the rest
1N/Aof that conditional, including any C<elsif> and C<else> clauses,
1N/Abut not beyond it. See L<perlsyn/"Simple statements"> for information
1N/Aon the scope of variables in statements with modifiers.
1N/AThe C<foreach> loop defaults to scoping its index variable dynamically
1N/Ain the manner of C<local>. However, if the index variable is
1N/Aprefixed with the keyword C<my>, or if there is already a lexical
1N/Aby that name in scope, then a new lexical is created instead. Thus
1N/A for my $i (1, 2, 3) {
1N/Athe scope of $i extends to the end of the loop, but not beyond it,
1N/Arendering the value of $i inaccessible within C<some_function()>.
1N/ASome users may wish to encourage the use of lexically scoped variables.
1N/AAs an aid to catching implicit uses to package variables,
1N/Awhich are always global, if you say
1N/Athen any variable mentioned from there to the end of the enclosing
1N/Ablock must either refer to a lexical variable, be predeclared via
1N/AC<our> or C<use vars>, or else must be fully qualified with the package name.
1N/AA compilation error results otherwise. An inner block may countermand
1N/Athis with C<no strict 'vars'>.
1N/AA C<my> has both a compile-time and a run-time effect. At compile
1N/Atime, the compiler takes notice of it. The principal usefulness
1N/Aof this is to quiet C<use strict 'vars'>, but it is also essential
1N/Afor generation of closures as detailed in L<perlref>. Actual
1N/Ainitialization is delayed until run time, though, so it gets executed
1N/Aat the appropriate time, such as each time through a loop, for
1N/AVariables declared with C<my> are not part of any package and are therefore
1N/Anever fully qualified with the package name. In particular, you're not
1N/Aallowed to try to make a package variable (or other global) lexical:
1N/A my $pack::var; # ERROR! Illegal syntax
1N/A my $_; # also illegal (currently)
1N/AIn fact, a dynamic variable (also known as package or global variables)
1N/Aare still accessible using the fully qualified C<::> notation even while a
1N/Alexical of the same name is also visible:
1N/A print "$x and $::x\n";
1N/AThat will print out C<20> and C<10>.
1N/AYou may declare C<my> variables at the outermost scope of a file
1N/Ato hide any such identifiers from the world outside that file. This
1N/Ais similar in spirit to C's static variables when they are used at
1N/Athe file level. To do this with a subroutine requires the use of
1N/Aa closure (an anonymous function that accesses enclosing lexicals).
1N/AIf you want to create a private subroutine that cannot be called
1N/Afrom outside that block, it can declare a lexical variable containing
1N/Aan anonymous sub reference:
1N/A my $secret_version = '1.001-beta';
1N/A my $secret_sub = sub { print $secret_version };
1N/AAs long as the reference is never returned by any function within the
1N/Amodule, no outside module can see the subroutine, because its name is not in
1N/Aany package's symbol table. Remember that it's not I<REALLY> called
1N/AC<$some_pack::secret_version> or anything; it's just $secret_version,
1N/Aunqualified and unqualifiable.
1N/AThis does not work with object methods, however; all object methods
1N/Ahave to be in the symbol table of some package to be found. See
1N/AL<perlref/"Function Templates"> for something of a work-around to
1N/A=head2 Persistent Private Variables
1N/AJust because a lexical variable is lexically (also called statically)
1N/Ascoped to its enclosing block, C<eval>, or C<do> FILE, this doesn't mean that
1N/Awithin a function it works like a C static. It normally works more
1N/Alike a C auto, but with implicit garbage collection.
1N/AUnlike local variables in C or C++, Perl's lexical variables don't
1N/Anecessarily get recycled just because their scope has exited.
1N/AIf something more permanent is still aware of the lexical, it will
1N/Astick around. So long as something else references a lexical, that
1N/Alexical won't be freed--which is as it should be. You wouldn't want
1N/Amemory being free until you were done using it, or kept around once you
1N/Awere done. Automatic garbage collection takes care of this for you.
1N/AThis means that you can pass back or save away references to lexical
1N/Avariables, whereas to return a pointer to a C auto is a grave error.
1N/AIt also gives us a way to simulate C's function statics. Here's a
1N/Amechanism for giving a function private variables with both lexical
1N/Ascoping and a static lifetime. If you do want to create something like
1N/AC's static variables, just enclose the whole function in an extra block,
1N/Aand put the static variable outside the function but in the block.
1N/A return ++$secret_val;
1N/A # $secret_val now becomes unreachable by the outside
1N/A # world, but retains its value between calls to gimme_another
1N/AIf this function is being sourced in from a separate file
1N/Avia C<require> or C<use>, then this is probably just fine. If it's
1N/Aall in the main program, you'll need to arrange for the C<my>
1N/Ato be executed early, either by putting the whole block above
1N/Ayour main program, or more likely, placing merely a C<BEGIN>
1N/Acode block around it to make sure it gets executed before your program
1N/A return ++$secret_val;
1N/ASee L<perlmod/"BEGIN, CHECK, INIT and END"> about the
1N/Aspecial triggered code blocks, C<BEGIN>, C<CHECK>, C<INIT> and C<END>.
1N/AIf declared at the outermost scope (the file scope), then lexicals
1N/Awork somewhat like C's file statics. They are available to all
1N/Afunctions in that same file declared below them, but are inaccessible
1N/Afrom outside that file. This strategy is sometimes used in modules
1N/Ato create private variables that the whole module can see.
1N/A=head2 Temporary Values via local()
1N/AB<WARNING>: In general, you should be using C<my> instead of C<local>, because
1N/Ait's faster and safer. Exceptions to this include the global punctuation
1N/Avariables, global filehandles and formats, and direct manipulation of the
1N/APerl symbol table itself. C<local> is mostly used when the current value
1N/Aof a variable must be visible to called subroutines.
1N/A # localization of values
1N/A local $foo; # make $foo dynamically local
1N/A local (@wid, %get); # make list of variables local
1N/A local $foo = "flurp"; # make $foo dynamic, and init it
1N/A local @oof = @bar; # make @oof dynamic, and init it
1N/A local $hash{key} = "val"; # sets a local value for this hash entry
1N/A local ($cond ? $v1 : $v2); # several types of lvalues support
1N/A # localization of symbols
1N/A local *FH; # localize $FH, @FH, %FH, &FH ...
1N/A local *merlyn = *randal; # now $merlyn is really $randal, plus
1N/A # @merlyn is really @randal, etc
1N/A local *merlyn = 'randal'; # SAME THING: promote 'randal' to *randal
1N/A local *merlyn = \$randal; # just alias $merlyn, not @merlyn etc
1N/AA C<local> modifies its listed variables to be "local" to the
1N/Aenclosing block, C<eval>, or C<do FILE>--and to I<any subroutine
1N/Acalled from within that block>. A C<local> just gives temporary
1N/Avalues to global (meaning package) variables. It does I<not> create
1N/Aa local variable. This is known as dynamic scoping. Lexical scoping
1N/Ais done with C<my>, which works more like C's auto declarations.
1N/ASome types of lvalues can be localized as well : hash and array elements
1N/Aand slices, conditionals (provided that their result is always
1N/Alocalizable), and symbolic references. As for simple variables, this
1N/Acreates new, dynamically scoped values.
1N/AIf more than one variable or expression is given to C<local>, they must be
1N/Aplaced in parentheses. This operator works
1N/Aby saving the current values of those variables in its argument list on a
1N/Ahidden stack and restoring them upon exiting the block, subroutine, or
1N/Aeval. This means that called subroutines can also reference the local
1N/Avariable, but not the global one. The argument list may be assigned to if
1N/Adesired, which allows you to initialize your local variables. (If no
1N/Ainitializer is given for a particular variable, it is created with an
1N/ABecause C<local> is a run-time operator, it gets executed each time
1N/Athrough a loop. Consequently, it's more efficient to localize your
1N/Avariables outside the loop.
1N/A=head3 Grammatical note on local()
1N/AA C<local> is simply a modifier on an lvalue expression. When you assign to
1N/Aa C<local>ized variable, the C<local> doesn't change whether its list is viewed
1N/Aas a scalar or an array. So
1N/A local($foo) = <STDIN>;
1N/A local @FOO = <STDIN>;
1N/Aboth supply a list context to the right-hand side, while
1N/A local $foo = <STDIN>;
1N/Asupplies a scalar context.
1N/A=head3 Localization of special variables
1N/AIf you localize a special variable, you'll be giving a new value to it,
1N/Abut its magic won't go away. That means that all side-effects related
1N/Ato this magic still work with the localized value.
1N/AThis feature allows code like this to work :
1N/A # Read the whole contents of FILE in $slurp
1N/A { local $/ = undef; $slurp = <FILE>; }
1N/ANote, however, that this restricts localization of some values ; for
1N/Aexample, the following statement dies, as of perl 5.9.0, with an error
1N/AI<Modification of a read-only value attempted>, because the $1 variable is
1N/Amagical and read-only :
1N/ASimilarly, but in a way more difficult to spot, the following snippet will
1N/A sub f { local $_ = "foo"; print }
1N/A # now $_ is aliased to $1, thus is magic and readonly
1N/ASee next section for an alternative to this situation.
1N/AB<WARNING>: Localization of tied arrays and hashes does not currently
1N/AThis will be fixed in a future release of Perl; in the meantime, avoid
1N/Acode that relies on any particular behaviour of localising tied arrays
1N/Aor hashes (localising individual elements is still okay).
1N/ASee L<perl58delta/"Localising Tied Arrays and Hashes Is Broken"> for more
1N/A=head3 Localization of globs
1N/Acreates a whole new symbol table entry for the glob C<name> in the
1N/Acurrent package. That means that all variables in its glob slot ($name,
1N/A@name, %name, &name, and the C<name> filehandle) are dynamically reset.
1N/AThis implies, among other things, that any magic eventually carried by
1N/Athose variables is locally lost. In other words, saying C<local */>
1N/Awill not have any effect on the internal value of the input record
1N/ANotably, if you want to work with a brand new value of the default scalar
1N/A$_, and avoid the potential problem listed above about $_ previously
1N/Acarrying a magic value, you should use C<local *_> instead of C<local $_>.
1N/A=head3 Localization of elements of composite types
1N/AIt's also worth taking a moment to explain what happens when you
1N/AC<local>ize a member of a composite type (
i.e. an array or hash element).
1N/AIn this case, the element is C<local>ized I<by name>. This means that
1N/Awhen the scope of the C<local()> ends, the saved value will be
1N/Arestored to the hash element whose key was named in the C<local()>, or
1N/Athe array element whose index was named in the C<local()>. If that
1N/Aelement was deleted while the C<local()> was in effect (
e.g. by a
1N/AC<delete()> from a hash or a C<shift()> of an array), it will spring
1N/Aback into existence, possibly extending an array and filling in the
1N/Askipped elements with C<undef>. For instance, if you say
1N/A %hash = ( 'This' => 'is', 'a' => 'test' );
1N/A local($hash{'a'}) = 'drill';
1N/A while (my $e = pop(@ary)) {
1N/A $hash{'only a'} = 'test';
1N/A print join(' ', map { "$_ $hash{$_}" } sort keys %hash),".\n";
1N/A print "The array has ",scalar(@ary)," elements: ",
1N/A join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\n";
1N/A This is a test only a test.
1N/A The array has 6 elements: 0, 1, 2, undef, undef, 5
1N/AThe behavior of local() on non-existent members of composite
1N/Atypes is subject to change in future.
1N/A=head2 Lvalue subroutines
1N/AB<WARNING>: Lvalue subroutines are still experimental and the
1N/Aimplementation may change in future versions of Perl.
1N/AIt is possible to return a modifiable value from a subroutine.
1N/ATo do this, you have to declare the subroutine to return an lvalue.
1N/A sub canmod : lvalue {
1N/A # return $val; this doesn't work, don't say "return"
1N/A canmod() = 5; # assigns to $val
1N/A nomod() = 5; # ERROR
1N/Aside of assignment is determined as if the subroutine call is replaced
1N/Aby a scalar. For example, consider:
1N/A data(2,3) = get_data(3,4);
1N/ABoth subroutines here are called in a scalar context, while in:
1N/A (data(2,3)) = get_data(3,4);
1N/A (data(2),data(3)) = get_data(3,4);
1N/Aall the subroutines are called in a list context.
1N/A=item Lvalue subroutines are EXPERIMENTAL
1N/AThey appear to be convenient, but there are several reasons to be
1N/AYou can't use the return keyword, you must pass out the value before
1N/Afalling out of subroutine scope. (see comment in example above). This
1N/Ais usually not a problem, but it disallows an explicit return out of a
1N/Adeeply nested loop, which is sometimes a nice way out.
1N/AThey violate encapsulation. A normal mutator can check the supplied
1N/Aargument before setting the attribute it is protecting, an lvalue
1N/Asubroutine never gets that chance. Consider;
1N/A my $some_array_ref = []; # protected by mutators ??
1N/A sub set_arr { # normal mutator
1N/A die("expected array, you supplied ", ref $val)
1N/A unless ref $val eq 'ARRAY';
1N/A $some_array_ref = $val;
1N/A sub set_arr_lv : lvalue { # lvalue mutator
1N/A # set_arr_lv cannot stop this !
1N/A set_arr_lv() = { a => 1 };
1N/A=head2 Passing Symbol Table Entries (typeglobs)
1N/AB<WARNING>: The mechanism described in this section was originally
1N/Athe only way to simulate pass-by-reference in older versions of
1N/APerl. While it still works fine in modern versions, the new reference
1N/Amechanism is generally easier to work with. See below.
1N/ASometimes you don't want to pass the value of an array to a subroutine
1N/Abut rather the name of it, so that the subroutine can modify the global
1N/Acopy of it rather than working with a local copy. In perl you can
1N/Arefer to all objects of a particular name by prefixing the name
1N/Awith a star: C<*foo>. This is often known as a "typeglob", because the
1N/Astar on the front can be thought of as a wildcard match for all the
1N/Afunny prefix characters on variables and subroutines and such.
1N/AWhen evaluated, the typeglob produces a scalar value that represents
1N/Aall the objects of that name, including any filehandle, format, or
1N/Asubroutine. When assigned to, it causes the name mentioned to refer to
1N/Awhatever C<*> value was assigned to it. Example:
1N/A local(*someary) = @_;
1N/A foreach $elem (@someary) {
1N/AScalars are already passed by reference, so you can modify
1N/Ascalar arguments without using this mechanism by referring explicitly
1N/Ato C<$_[0]> etc. You can modify all the elements of an array by passing
1N/Aall the elements as scalars, but you have to use the C<*> mechanism (or
1N/Athe equivalent reference mechanism) to C<push>, C<pop>, or change the size of
1N/Aan array. It will certainly be faster to pass the typeglob (or reference).
1N/AEven if you don't want to modify an array, this mechanism is useful for
1N/Apassing multiple arrays in a single LIST, because normally the LIST
1N/Amechanism will merge all the array values so that you can't extract out
1N/Athe individual arrays. For more on typeglobs, see
1N/AL<perldata/"Typeglobs and Filehandles">.
1N/A=head2 When to Still Use local()
1N/ADespite the existence of C<my>, there are still three places where the
1N/AC<local> operator still shines. In fact, in these three places, you
1N/AI<must> use C<local> instead of C<my>.
1N/AYou need to give a global variable a temporary value, especially $_.
1N/AThe global variables, like C<@ARGV> or the punctuation variables, must be
1N/AC<local>ized with C<local()>. This block reads in F<
/etc/motd>, and splits
1N/Ait up into chunks separated by lines of equal signs, which are placed
1N/A @Fields = split /^\s*=+\s*$/;
1N/AIt particular, it's important to C<local>ize $_ in any routine that assigns
1N/Ato it. Look out for implicit assignments in C<while> conditionals.
1N/AYou need to create a local file or directory handle or a local function.
1N/AA function that needs a filehandle of its own must use
1N/AC<local()> on a complete typeglob. This can be used to create new symbol
1N/A local (*READER, *WRITER); # not my!
1N/A pipe (READER, WRITER) or die "pipe: $!";
1N/A return (*READER, *WRITER);
1N/A ($head, $tail) = ioqueue();
1N/ASee the Symbol module for a way to create anonymous symbol table
1N/ABecause assignment of a reference to a typeglob creates an alias, this
1N/Acan be used to create what is effectively a local function, or at least,
1N/A local *grow = \&shrink; # only until this block exists
1N/A grow(); # really calls shrink()
1N/A move(); # if move() grow()s, it shrink()s too
1N/A grow(); # get the real grow() again
1N/ASee L<perlref/"Function Templates"> for more about manipulating
1N/Afunctions by name in this way.
1N/AYou want to temporarily change just one element of an array or hash.
1N/AYou can C<local>ize just one element of an aggregate. Usually this
1N/A local $SIG{INT} = 'IGNORE';
1N/A funct(); # uninterruptible
1N/A # interruptibility automatically restored here
1N/ABut it also works on lexically declared aggregates. Prior to 5.005,
1N/Athis operation could on occasion misbehave.
1N/A=head2 Pass by Reference
1N/AIf you want to pass more than one array or hash into a function--or
1N/Areturn them from it--and have them maintain their integrity, then
1N/Ayou're going to have to use an explicit pass-by-reference. Before you
1N/Ado that, you need to understand references as detailed in L<perlref>.
1N/AThis section may not make much sense to you otherwise.
1N/AHere are a few simple examples. First, let's pass in several arrays
1N/Ato a function and have it C<pop> all of then, returning a new list
1N/Aof all their former last elements:
1N/A @tailings = popmany ( \@a, \@b, \@c, \@d );
1N/A foreach $aref ( @_ ) {
1N/A push @retlist, pop @$aref;
1N/AHere's how you might write a function that returns a
1N/Alist of keys occurring in all the hashes passed to it:
1N/A @common = inter( \%foo, \%bar, \%joe );
1N/A my ($k, $href, %seen); # locals
1N/A foreach $href (@_) {
1N/A while ( $k = each %$href ) {
1N/A return grep { $seen{$_} == @_ } keys %seen;
1N/ASo far, we're using just the normal list return mechanism.
1N/AWhat happens if you want to pass or return a hash? Well,
1N/Aif you're using only one of them, or you don't mind them
1N/Aconcatenating, then the normal calling convention is ok, although
1N/AWhere people get into trouble is here:
1N/A (@a, @b) = func(@c, @d);
1N/A (%a, %b) = func(%c, %d);
1N/AThat syntax simply won't work. It sets just C<@a> or C<%a> and
1N/Aclears the C<@b> or C<%b>. Plus the function didn't get passed
1N/Ainto two separate arrays or hashes: it got one long list in C<@_>,
1N/AIf you can arrange for everyone to deal with this through references, it's
1N/Acleaner code, although not so nice to look at. Here's a function that
1N/Atakes two array references as arguments, returning the two array elements
1N/Ain order of how many elements they have in them:
1N/A ($aref, $bref) = func(\@c, \@d);
1N/A print "@$aref has more than @$bref\n";
1N/A my ($cref, $dref) = @_;
1N/A if (@$cref > @$dref) {
1N/A return ($cref, $dref);
1N/A return ($dref, $cref);
1N/AIt turns out that you can actually do this also:
1N/A (*a, *b) = func(\@c, \@d);
1N/A print "@a has more than @b\n";
1N/A local (*c, *d) = @_;
1N/AHere we're using the typeglobs to do symbol table aliasing. It's
1N/Aa tad subtle, though, and also won't work if you're using C<my>
1N/Avariables, because only globals (even in disguise as C<local>s)
1N/Aare in the symbol table.
1N/AIf you're passing around filehandles, you could usually just use the bare
1N/Atypeglob, like C<*STDOUT>, but typeglobs references work, too.
1N/A print $fh "her um well a hmmm\n";
1N/A $rec = get_rec(\*STDIN);
1N/A return scalar <$fh>;
1N/AIf you're planning on generating new filehandles, you could do this.
1N/ANotice to pass back just the bare *FH, not its reference.
1N/A return open (FH, $path) ? *FH : undef;
1N/APerl supports a very limited kind of compile-time argument checking
1N/Ausing function prototyping. If you declare
1N/Athen C<mypush()> takes arguments exactly like C<push()> does. The
1N/Afunction declaration must be visible at compile time. The prototype
1N/Aaffects only interpretation of new-style calls to the function,
1N/Awhere new-style is defined as not using the C<&> character. In
1N/Aother words, if you call it like a built-in function, then it behaves
1N/Alike a built-in function. If you call it like an old-fashioned
1N/Asubroutine, then it behaves like an old-fashioned subroutine. It
1N/Anaturally falls out from this rule that prototypes have no influence
1N/Aon subroutine references like C<\&foo> or on indirect subroutine
1N/Acalls like C<&{$subref}> or C<< $subref->() >>.
1N/AMethod calls are not influenced by prototypes either, because the
1N/Afunction to be called is indeterminate at compile time, since
1N/Athe exact code called depends on inheritance.
1N/ABecause the intent of this feature is primarily to let you define
1N/Asubroutines that work like built-in functions, here are prototypes
1N/Afor some other functions that parse almost exactly like the
1N/Acorresponding built-in.
1N/A Declared as Called as
1N/A sub mylink ($$) mylink $old, $new
1N/A sub myvec ($$$) myvec $var, $offset, 1
1N/A sub myindex ($$;$) myindex &getstring, "substr"
1N/A sub mysyswrite ($$$;$) mysyswrite $buf, 0, length($buf) - $off, $off
1N/A sub myreverse (@) myreverse $a, $b, $c
1N/A sub myjoin ($@) myjoin ":", $a, $b, $c
1N/A sub mypop (\@) mypop @array
1N/A sub mysplice (\@$$@) mysplice @array, @array, 0, @pushme
1N/A sub mykeys (\%) mykeys %{$hashref}
1N/A sub myopen (*;$) myopen HANDLE, $name
1N/A sub mypipe (**) mypipe READHANDLE, WRITEHANDLE
1N/A sub mygrep (&@) mygrep { /foo/ } $a, $b, $c
1N/A sub myrand ($) myrand 42
1N/A sub mytime () mytime
1N/AAny backslashed prototype character represents an actual argument
1N/Athat absolutely must start with that character. The value passed
1N/Aas part of C<@_> will be a reference to the actual argument given
1N/Ain the subroutine call, obtained by applying C<\> to that argument.
1N/AYou can also backslash several argument types simultaneously by using
1N/A sub myref (\[$@%&*])
1N/Awill allow calling myref() as
1N/Aand the first argument of myref() will be a reference to
1N/Aa scalar, an array, a hash, a code, or a glob.
1N/AUnbackslashed prototype characters have special meanings. Any
1N/Aunbackslashed C<@> or C<%> eats all remaining arguments, and forces
1N/Alist context. An argument represented by C<$> forces scalar context. An
1N/AC<&> requires an anonymous subroutine, which, if passed as the first
1N/Aargument, does not require the C<sub> keyword or a subsequent comma.
1N/AA C<*> allows the subroutine to accept a bareword, constant, scalar expression,
1N/Atypeglob, or a reference to a typeglob in that slot. The value will be
1N/Aavailable to the subroutine either as a simple scalar, or (in the latter
1N/Atwo cases) as a reference to the typeglob. If you wish to always convert
1N/Asuch arguments to a typeglob reference, use Symbol::qualify_to_ref() as
1N/A use Symbol 'qualify_to_ref';
1N/A my $fh = qualify_to_ref(shift, caller);
1N/AA semicolon separates mandatory arguments from optional arguments.
1N/AIt is redundant before C<@> or C<%>, which gobble up everything else.
1N/ANote how the last three examples in the table above are treated
1N/Aspecially by the parser. C<mygrep()> is parsed as a true list
1N/Aoperator, C<myrand()> is parsed as a true unary operator with unary
1N/Aprecedence the same as C<rand()>, and C<mytime()> is truly without
1N/Aarguments, just like C<time()>. That is, if you say
1N/Ayou'll get C<mytime() + 2>, not C<mytime(2)>, which is how it would be parsed
1N/AThe interesting thing about C<&> is that you can generate new syntax with it,
1N/Aprovided it's in the initial position:
1N/A my($try,$catch) = @_;
1N/A sub catch (&) { $_[0] }
1N/A /phooey/ and print "unphooey\n";
1N/AThat prints C<"unphooey">. (Yes, there are still unresolved
1N/Aissues having to do with visibility of C<@_>. I'm ignoring that
1N/Aquestion for the moment. (But note that if we make C<@_> lexically
1N/Ascoped, those anonymous subroutines can act like closures... (Gee,
1N/Ais this sounding a little Lispish? (Never mind.))))
1N/AAnd here's a reimplementation of the Perl C<grep> operator:
1N/A push(@result, $_) if &$code;
1N/ASome folks would prefer full alphanumeric prototypes. Alphanumerics have
1N/Abeen intentionally left out of prototypes for the express purpose of
1N/Asomeday in the future adding named, formal parameters. The current
1N/Amechanism's main goal is to let module writers provide better diagnostics
1N/Afor module users. Larry feels the notation quite understandable to Perl
1N/Aprogrammers, and that it will not intrude greatly upon the meat of the
1N/Amodule, nor make it harder to read. The line noise is visually
1N/Aencapsulated into a small pill that's easy to swallow.
1N/AIf you try to use an alphanumeric sequence in a prototype you will
1N/Agenerate an optional warning - "Illegal character in prototype...".
1N/AUnfortunately earlier versions of Perl allowed the prototype to be
1N/Aused as long as its prefix was a valid prototype. The warning may be
1N/Aupgraded to a fatal error in a future version of Perl once the
1N/Amajority of offending code is fixed.
1N/AIt's probably best to prototype new functions, not retrofit prototyping
1N/Ainto older ones. That's because you must be especially careful about
1N/Asilent impositions of differing list versus scalar contexts. For example,
1N/Aif you decide that a function should take just one parameter, like this:
1N/A print "you gave me $n\n";
1N/Aand someone has been calling it with an array or expression
1N/AThen you've just supplied an automatic C<scalar> in front of their
1N/Aargument, which can be more than a bit surprising. The old C<@foo>
1N/Awhich used to hold one thing doesn't get passed in. Instead,
1N/AC<func()> now gets passed in a C<1>; that is, the number of elements
1N/Ain C<@foo>. And the C<split> gets called in scalar context so it
1N/Astarts scribbling on your C<@_> parameter list. Ouch!
1N/AThis is all very powerful, of course, and should be used only in moderation
1N/Ato make the world a better place.
1N/A=head2 Constant Functions
1N/AFunctions with a prototype of C<()> are potential candidates for
1N/Ainlining. If the result after optimization and constant folding
1N/Ais either a constant or a lexically-scoped scalar which has no other
1N/Areferences, then it will be used in place of function calls made
1N/Awithout C<&>. Calls made using C<&> are never inlined. (See
1N/AThe following functions would all be inlined:
1N/A sub pi () { 3.14159 } # Not exact, but close.
1N/A sub PI () { 4 * atan2 1, 1 } # As good as it gets,
1N/A # and it's inlined, too!
1N/A sub FLAG_FOO () { 1 << 8 }
1N/A sub FLAG_BAR () { 1 << 9 }
1N/A sub FLAG_MASK () { FLAG_FOO | FLAG_BAR }
1N/A sub OPT_BAZ () { not (0x1B58 & FLAG_MASK) }
1N/A sub N () { int(OPT_BAZ) / 3 }
1N/A sub FOO_SET () { 1 if FLAG_MASK & FLAG_FOO }
1N/ABe aware that these will not be inlined; as they contain inner scopes,
1N/Athe constant folding doesn't reduce them to a single constant:
1N/A sub foo_set () { if (FLAG_MASK & FLAG_FOO) { 1 } }
1N/AIf you redefine a subroutine that was eligible for inlining, you'll get
1N/Aa mandatory warning. (You can use this warning to tell whether or not a
1N/Aparticular subroutine is considered constant.) The warning is
1N/Aconsidered severe enough not to be optional because previously compiled
1N/Ainvocations of the function will still be using the old value of the
1N/Afunction. If you need to be able to redefine the subroutine, you need to
1N/Aensure that it isn't inlined, either by dropping the C<()> prototype
1N/A(which changes calling semantics, so beware) or by thwarting the
1N/Ainlining mechanism in some other way, such as
1N/A sub not_inlined () {
1N/A=head2 Overriding Built-in Functions
1N/AMany built-in functions may be overridden, though this should be tried
1N/Aonly occasionally and for good reason. Typically this might be
1N/Adone by a package attempting to emulate missing built-in functionality
1N/Aon a non-Unix system.
1N/AOverriding may be done only by importing the name from a module at
1N/Acompile time--ordinary predeclaration isn't good enough. However, the
1N/AC<use subs> pragma lets you, in effect, predeclare subs
1N/Avia the import syntax, and these names may then override built-in ones:
1N/A use subs 'chdir', 'chroot', 'chmod', 'chown';
1N/ATo unambiguously refer to the built-in form, precede the
1N/Abuilt-in name with the special package qualifier C<CORE::>. For example,
1N/Asaying C<CORE::open()> always refers to the built-in C<open()>, even
1N/Aif the current package has imported some other subroutine called
1N/AC<&open()> from elsewhere. Even though it looks like a regular
1N/Afunction call, it isn't: you can't take a reference to it, such as
1N/Athe incorrect C<\&CORE::open> might appear to produce.
1N/ALibrary modules should not in general export built-in names like C<open>
1N/Aor C<chdir> as part of their default C<@EXPORT> list, because these may
1N/Asneak into someone else's namespace and change the semantics unexpectedly.
1N/AInstead, if the module adds that name to C<@EXPORT_OK>, then it's
1N/Apossible for a user to import the name explicitly, but not implicitly.
1N/AThat is, they could say
1N/Aand it would import the C<open> override. But if they said
1N/Athey would get the default imports without overrides.
1N/AThe foregoing mechanism for overriding built-in is restricted, quite
1N/Adeliberately, to the package that requests the import. There is a second
1N/Amethod that is sometimes applicable when you wish to override a built-in
1N/Aeverywhere, without regard to namespace boundaries. This is achieved by
1N/Aimporting a sub into the special namespace C<CORE::GLOBAL::>. Here is an
1N/Aexample that quite brazenly replaces the C<glob> operator with something
1N/Athat understands regular expressions.
1N/A @EXPORT_OK = 'glob';
1N/A my $where = ($sym =~ s/^GLOBAL_// ? 'CORE::GLOBAL' : caller(0));
1N/A $pkg->export($where, $sym, @_);
1N/A if (opendir D, '.') {
1N/A @got = grep /$pat/, readdir D;
1N/AAnd here's how it could be (ab)used:
1N/A #use REGlob 'GLOBAL_glob'; # override glob() in ALL namespaces
1N/A use REGlob 'glob'; # override glob() in Foo:: only
1N/A print for <^[a-z_]+\.pm\$>; # show all pragmatic modules
1N/AThe initial comment shows a contrived, even dangerous example.
1N/ABy overriding C<glob> globally, you would be forcing the new (and
1N/Asubversive) behavior for the C<glob> operator for I<every> namespace,
1N/Awithout the complete cognizance or cooperation of the modules that own
1N/Athose namespaces. Naturally, this should be done with extreme caution--if
1N/Ait must be done at all.
1N/AThe C<REGlob> example above does not implement all the support needed to
1N/Acleanly override perl's C<glob> operator. The built-in C<glob> has
1N/Adifferent behaviors depending on whether it appears in a scalar or list
1N/Acontext, but our C<REGlob> doesn't. Indeed, many perl built-in have such
1N/Acontext sensitive behaviors, and these must be adequately supported by
1N/Aa properly written override. For a fully functional example of overriding
1N/AC<glob>, study the implementation of C<File::DosGlob> in the standard
1N/AWhen you override a built-in, your replacement should be consistent (if
1N/Apossible) with the built-in native syntax. You can achieve this by using
1N/Aa suitable prototype. To get the prototype of an overridable built-in,
1N/Ause the C<prototype> function with an argument of C<"CORE::builtin_name">
1N/ANote however that some built-ins can't have their syntax expressed by a
1N/Aprototype (such as C<system> or C<chomp>). If you override them you won't
1N/Abe able to fully mimic their original syntax.
1N/AThe built-ins C<do>, C<require> and C<glob> can also be overridden, but due
1N/Ato special magic, their original syntax is preserved, and you don't have
1N/Ato define a prototype for their replacements. (You can't override the
1N/AC<do BLOCK> syntax, though).
1N/AC<require> has special additional dark magic: if you invoke your
1N/AC<require> replacement as C<require Foo::Bar>, it will actually receive
1N/AAnd, as you'll have noticed from the previous example, if you override
1N/AC<glob>, the C<E<lt>*E<gt>> glob operator is overridden as well.
1N/AIn a similar fashion, overriding the C<readline> function also overrides
1N/Athe equivalent I/O operator C<< <FILEHANDLE> >>.
1N/AFinally, some built-ins (
e.g. C<exists> or C<grep>) can't be overridden.
1N/AIf you call a subroutine that is undefined, you would ordinarily
1N/Aget an immediate, fatal error complaining that the subroutine doesn't
1N/Aexist. (Likewise for subroutines being used as methods, when the
1N/Amethod doesn't exist in any base class of the class's package.)
1N/AHowever, if an C<AUTOLOAD> subroutine is defined in the package or
1N/Apackages used to locate the original subroutine, then that
1N/AC<AUTOLOAD> subroutine is called with the arguments that would have
1N/Abeen passed to the original subroutine. The fully qualified name
1N/Aof the original subroutine magically appears in the global $AUTOLOAD
1N/Avariable of the same package as the C<AUTOLOAD> routine. The name
1N/Ais not passed as an ordinary argument because, er, well, just
1N/Abecause, that's why...
1N/AMany C<AUTOLOAD> routines load in a definition for the requested
1N/Asubroutine using eval(), then execute that subroutine using a special
1N/Aform of goto() that erases the stack frame of the C<AUTOLOAD> routine
1N/Awithout a trace. (See the source to the standard module documented
1N/Ain L<AutoLoader>, for example.) But an C<AUTOLOAD> routine can
1N/Aalso just emulate the routine and never define it. For example,
1N/Alet's pretend that a function that wasn't defined should just invoke
1N/AC<system> with those arguments. All you'd do is:
1N/A my $program = $AUTOLOAD;
1N/A $program =~ s/.*:://;
1N/A system($program, @_);
1N/AIn fact, if you predeclare functions you want to call that way, you don't
1N/Aeven need parentheses:
1N/A use subs qw(date who ls);
1N/AA more complete example of this is the standard Shell module, which
1N/Acan treat undefined subroutine calls as calls to external programs.
1N/AMechanisms are available to help modules writers split their modules
1N/Ainto autoloadable files. See the standard AutoLoader module
1N/Adescribed in L<AutoLoader> and in L<AutoSplit>, the standard
1N/ASelfLoader modules in L<SelfLoader>, and the document on adding C
1N/Afunctions to Perl code in L<perlxs>.
1N/A=head2 Subroutine Attributes
1N/AA subroutine declaration or definition may have a list of attributes
1N/Aassociated with it. If such an attribute list is present, it is
1N/Abroken up at space or colon boundaries and treated as though a
1N/AC<use attributes> had been seen. See L<attributes> for details
1N/Aabout what attributes are currently supported.
1N/AUnlike the limitation with the obsolescent C<use attrs>, the
1N/AC<sub : ATTRLIST> syntax works to associate the attributes with
1N/Aa pre-declaration, and not just with a subroutine definition.
1N/AThe attributes must be valid as simple identifier names (without any
1N/Apunctuation other than the '_' character). They may have a parameter
1N/Alist appended, which is only checked for whether its parentheses ('(',')')
1N/AExamples of valid syntax (even though the attributes are unknown):
1N/A sub fnord (&\%) : switch(10,foo(7,3)) : expensive ;
1N/A sub plugh () : Ugly('\(") :Bad ;
1N/A sub xyzzy : _5x5 { ... }
1N/AExamples of invalid syntax:
1N/A sub fnord : switch(10,foo() ; # ()-string not balanced
1N/A sub snoid : Ugly('(') ; # ()-string not balanced
1N/A sub xyzzy : 5x5 ; # "5x5" not a valid identifier
1N/A sub plugh : Y2::north ; # "Y2::north" not a simple identifier
1N/A sub snurt : foo + bar ; # "+" not a colon or space
1N/AThe attribute list is passed as a list of constant strings to the code
1N/Awhich associates them with the subroutine. In particular, the second example
1N/Aof valid syntax above currently looks like this in terms of how it's
1N/A use attributes __PACKAGE__, \&plugh, q[Ugly('\(")], 'Bad';
1N/AFor further details on attribute lists and their manipulation,
1N/Asee L<attributes> and L<Attribute::Handlers>.
1N/ASee L<perlref/"Function Templates"> for more about references and closures.
1N/ASee L<perlxs> if you'd like to learn about calling C subroutines from Perl.
1N/ASee L<perlembed> if you'd like to learn about calling Perl subroutines from C.
1N/ASee L<perlmod> to learn about bundling up your functions in separate files.
1N/ASee L<perlmodlib> to learn what library modules come standard on your system.
1N/ASee L<perltoot> to learn how to make object method calls.