Perl Subroutines

A Perl subroutine (also called function) may be defined anywhere in the main program, loaded in from other files via the do (see functions and statements), require, or use (see functions and pragmas), or generated on the fly with eval.

It is possible to generate anonymous subroutine, accessible only through references; or to call a subroutine indirectly using a variable containing either its name or reference.

To declare a subroutine use one of the following forms:
   sub NAME; # a forward declaration    sub NAME (PROTO); # a forward declaration plus prototype To declare and define a subroutineuse one of the following forms:
   sub NAME BLOCK # a declaration and a definition    sub NAME (PROTO) BLOCK # same with prototype To define an anonymous subroutine with reference use:
   $subref = sub NAME BLOCK # or    $subref = sub NAME (PROTO) BLOCK To import subroutines defined in another package use:
   $subref = sub PACKAGE qw(NAME1 NAME2 ...) To call subroutines directly:
   NAME (LIST); # & is optional with parentheses    NAME LIST; # parentheses optional if predeclared/imported    &NAME; # pass current @_ to subroutine To call subroutines indirectly by name or reference):
   &$subref(LIST); # & is not optional on indirect    &$subref; # pass current @_ to subroutine

All subroutine parameters are passed as a single flat list of scalars; and multiple return values are returned as on single flat list of scalars. As with any list, arrays or hashes passed in these lists passed into these listswill interpolate their values into the flattend list, losing their identities. Normally the list is variable length, but a prototype limits this to the prototype. The array @_ is a local array whose values are references to each scalar parameter, so changing an input parameter changes it to the calling world.

Perl does not have named formal parameters. What is usually done is to assign @_ to a my list:

sub foo {
    my ($stuff, $info) = @_;
    ...
}

which has the effect of changing call by reference to call by value (if @_ is ignored after that); but it is not necessary by using only the list @_:

sub max {
    my $max=shift(@_);
    foreach $foo (@_) {
        $max=$foo if $max<$foo;
    }
    return $max;
}

The return value of the subroutine (or any other block) is the value of the last expression evaluated; or an explicit return can be used to specify the return value and exit the subroutine. The return value is evaluated according to the context (e.g. scalar or list) of its calling expression.

Prototypes

Declared as	Called as
sub xlink ($$)	xlink $old $new
sub xvec ($$$)	xvec $var, $offset, 1
sub xindex ($$;$)	xindex &getstring, "substr"
sub xsyswrite ($$$;$)	xsyswrite $buf, 0, length($buf)-$off, $off
sub xreverse (@)	xreverse $a, $b $c
sub xjoin ($@)	xjoin ":", $a, $b $c
sub xpop (\@)	xpop @array
sub xsplice (\@$$@)	xsplice @array, @array, 0, @pushme
sub xkeys (\%)	xkeys %{$hashref}
sub xopen (*;$)	xopen HANDLE, $name
sub xpipe (**)	xpipe HANDLE, WRITEHANDLE
sub xgrep (&@)	xgrep { /foo/ } $a, $b, $c
sub xrand (@)	xrand 42
sub xtime ()	xtime

Any backslashed prototype character (shown between parenthesis in the left column) represents an actual argument that absolutely must start with that character. Jast as the first argument to keys must start with %, so too must the first argument of xkeys.

Unslashed prototype characters have special meaning. Any unbackslashed @ or % eats all the rest of the actual arguments, and forces list context. An argument represented by $ forces scalar context on it. An & requires an anonymous subroutine (which, if passed as the first argument, does not require the "sub" keyowrd or a subsequent comma). And a * does whatever it has to do to turn the argument into a reference to a symbol table entry. It's typically used for filehandles. A semicolon separates mandatory arguments from optional arguments. (It would be redundant before @ or %, since list can be null).

Note how the last three examples above aretreated specialy by the parser. xgrep is parsed as a true list operator, xrand is parsed as a true unary operator with undary precedence and xtime is truly argumentless.