Chapter 6. Subroutines

Like many languages, Perl provides for user-defined subroutines.[1] These subroutines may be defined anywhere in the main program, loaded in from other files via the do, require, or use keywords, or generated at run time using eval. You can even load them at run time with the mechanism described in the section Section 6.2, "Autoloading" in Chapter 10, "Packages". You can call a subroutine indirectly, using a variable containing either its name or a reference to the routine, or through an object, letting the object determine which subroutine should really be called. You can generate anonymous subroutines, accessible only through references, and if you want, use these to clone new, nearly identical functions via closures, which are covered in the section by that name in Chapter 8, "References".

[1] We'll also call them functions, but functions are the same thing as subroutines in Perl. Sometimes we'll even call them methods, which are defined the same way, but called differently.

6.1. Syntax

To declare a named subroutine without defining it, use one of these forms:

sub NAME
sub NAME PROTO
sub NAME       ATTRS
sub NAME PROTO ATTRS

To declare and define a named subroutine, add a BLOCK:

sub NAME             BLOCK
sub NAME PROTO       BLOCK
sub NAME       ATTRS BLOCK
sub NAME PROTO ATTRS BLOCK

To create an anonymous subroutine or closure, leave out the NAME:

sub                  BLOCK
sub      PROTO       BLOCK
sub            ATTRS BLOCK
sub      PROTO ATTRS BLOCK

PROTO and ATTRS stand for the prototype and attributes, each of which is discussed in its own section later in the chapter. They're not so important--the NAME and the BLOCK are the essential parts, even when they're missing.

For the forms without a NAME, you still have to provide some way of calling the subroutine. So be sure to save the return value since this form of sub declaration is not only compiled at compile time as you would expect, but also produces a run-time return value:

$subref = sub BLOCK;

To import subroutines defined in another module, say:

use MODULE qw(NAME1 NAME2 NAME3...);

To call subroutines directly, say:

NAME(LIST)            # & is optional with parentheses.
NAME LIST             # Parens optional if sub predeclared/imported.
&NAME                 # Exposes current @_ to that subroutine,
                      # (and circumvents prototypes).

To call subroutines indirectly (by name or by reference), use any of these:

&$subref(LIST)        # The & is not optional on indirect call
$subref->(LIST)       # (unless using infix notation).
&$subref              # Exposes current @_ to that subroutine.

The official name of a subroutine includes the & prefix. A subroutine may be called using the prefix, but the & is usually optional, and so are the parentheses if the subroutine has been predeclared. However, the & is not optional when you're just naming the subroutine, such as when it's used as an argument to defined or undef or when you want to generate a reference to a named subroutine by saying $subref = \&name. Nor is the & optional when you want to make an indirect subroutine call using the &$subref() or &{$subref}() constructs. However, the more convenient $subref->() notation does not require it. See Chapter 8, "References" for more about references to subroutines.

Perl doesn't force a particular capitalization style on your subroutine names. However, one loosely held convention is that functions called indirectly by Perl's run-time system (BEGIN, CHECK, INIT, END, AUTOLOAD, DESTROY, and all the functions mentioned in Chapter 14, "Tied Variables") are in all capitals, so you might want to avoid using that style. (But subroutines used for constant values are customarily named with all caps too. That's okay. We hope...)

Chapter 6. Subroutines

Contents:

6.1. Syntax