What to Avoid

Perl isn't perfect. Some features are difficult to use correctly and others seemed great but don't work all that well. A few features combine with others in strange ways with weird edge cases. Knowing Perl's rough edges will help you avoid them, when possible, and avoid rough edges when you must use them.

Barewords

Perl is a malleable language. You can write programs in whichever creative, maintainable, obfuscated, or bizarre fashion you prefer. Good programmers write code that they want to maintain, but Perl won't decide for you what you consider maintainable.

Perl's parser understands Perl's builtins and operators. It uses sigils to identify variables and other punctuation to recognize function and method calls. Yet sometimes the parser has to guess what you mean, especially when you use a bareword—an identifier without a sigil or other syntactically significant punctuation.

Good Uses of Barewords

Though the strict pragma (Pragmas) rightly forbids ambiguous barewords, some barewords are acceptable.

Bareword hash keys

Hash keys in Perl are usually not ambiguous because the parser can identify them as string keys; pinball in $games{pinball} is obviously a string.

Occasionally this interpretation is not what you want, especially when you intend to evaluate a builtin or a function to produce the hash key. To make these cases clear, pass arguments to the function or use parentheses, or prepend a unary plus to force the evaluation of the builtin:

    # the literal 'shift' is the key
    my $value = $items{shift};

    # the value produced by shift is the key
    my $value = $items{shift @_}

    # the function returns the key
    my $value = $items{myshift( @_ )}

    # unary plus uses the builtin shift
    my $value = $items{+shift};

Bareword package names

Package names are also barewords. If your naming conventions rule that package names have initial capitals and functions do not, you'll rarely encounter naming collisions. Even still, Perl must determine how to parse Package->method. Does it mean "call a function named Package() and call method() on its return value?" or "Call a method named method() in the Package namespace?" The answer depends on the code you've already compiled.

Force the parser to treat Package as a package name by appending the package separator (::) Even among people who understand why this works, very few people do it. or make it a literal string:

    # probably a class method
    Package->method;

    # definitely a class method
    Package::->method;

    # a slightly less ugly class method
    'Package'->method;

Bareword named code blocks

The special named code blocks AUTOLOAD, BEGIN, CHECK, DESTROY, END, INIT, and UNITCHECK are barewords which declare functions without the sub builtin. You've seen this before (Code Generation):

    package Monkey::Butler;

    BEGIN { initialize_simians( __PACKAGE__ ) }

    sub AUTOLOAD { ... }

While you can declare AUTOLOAD() without using sub, few people do.

Bareword constants

Constants declared with the constant pragma are usable as barewords:

    # don't use this for real authentication
    use constant NAME     => 'Bucky';
    use constant PASSWORD => '|38fish!head74|';

    return unless $name eq NAME && $pass eq PASSWORD;

These constants do not interpolate in double-quoted strings.

Constants are a special case of prototyped functions (Prototypes). When you predeclare a function with a prototype, the parser will treat all subsequent uses of that bareword specially—and will warn about ambiguous parsing errors. All other drawbacks of prototypes still apply.

Ill-Advised Uses of Barewords

No matter how cautiously you code, barewords still produce ambiguous code. You can avoid the worst abuses, but you will encounter several types of barewords in legacy code.

Bareword hash values

Some old code may not take pains to quote the values of hash pairs:

    # poor style; do not use
    my %parents =
    (
        mother => Annette,
        father => Floyd,
    );

When neither the Floyd() nor Annette() functions exist, Perl will interpret these barewords as strings. strict 'subs' will produce an error in this situation.

Bareword function calls

Code written without strict 'subs' may use bareword function names. Adding parentheses will make the code pass strictures. Use perl -MO=Deparse,-p (see perldoc B::Deparse) to discover how Perl parses them, then parenthesize accordingly.

Bareword filehandles

Prior to lexical filehandles (Filehandle References), all file and directory handles used barewords. You can almost always safely rewrite this code to use lexical filehandles. Perl's parser recognizes the special exceptions of STDIN, STDOUT, and STDERR.

Bareword sort functions

Finally, the second operand of the sort builtin can be the name of a function to use for sorting. While this is rarely ambiguous to the parser, it can confuse human readers. The alternative of providing a function reference in a scalar is little better:

    # bareword style
    my @sorted = sort compare_lengths @unsorted;

    # function reference in scalar
    my $comparison = \&compare_lengths;
    my @sorted     = sort $comparison @unsorted;

The second option avoids the use of a bareword, but the result is longer. Unfortunately, Perl's parser does not understand the single-line version due to the special parsing of sort; you cannot use an arbitrary expression (such as taking a reference to a named function) where a block or a scalar might otherwise go.

    # does not work
    my @sorted = sort \&compare_lengths @unsorted;

In both cases, the way sort invokes the function and provides arguments can be confusing (see perldoc -f sort for the details). Where possible, consider using the block form of sort instead. If you must use either function form, add a comment about what you're doing and why.

Indirect Objects

Perl has no operator new. A constructor is anything which returns an object. By convention, constructors are class methods named new(), but you can name these methods (or even use functions). Several old Perl OO tutorials promote the use of C++ and Java-style constructor calls:

    my $q = new CGI; # DO NOT USE

... instead of the obvious method call:

    my $q = CGI->new;

These syntaxes produce equivalent behavior, except when they don't.

Bareword Indirect Invocations

In the indirect object form (more precisely, the dative case) of the first example, the verb (the method) precedes the noun to which it refers (the object). This is fine in spoken languages, but it introduces parsing ambiguities in Perl.

Because the method's name is a bareword (Barewords), the parser uses several heuristics to figure out the proper interpretation of this code. While these heuristics are well-tested and almost always correct, their failure modes are confusing. Things get worse when you pass arguments to a constructor:

    # DO NOT USE
    my $obj = new Class( arg => $value );

In this example, the name of the class looks like a function call. Perl can disambiguate many of these cases, but its heuristics depend on which package names the parser has seen, which barewords it has already resolved (and how it resolved them), and the names of functions already declared in the current package. For an exhaustive list of these conditions, you have to read the source code of Perl's parser—not something the average Perl programmer wants to do.

Imagine running afoul of a prototyped function (Prototypes) with a name which just happens to conflict somehow with the name of a class or a method called indirectly. This is rare It's happened to your author when using the JSON module., but so unpleasant to debug that it's worth avoiding indirect invocations.

Indirect Notation Scalar Limitations

Another danger of the indirect syntax is that the parser expects a single scalar expression as the object. Printing to a filehandle stored in an aggregate variable seems obvious, but it is not:

    # DOES NOT WORK AS WRITTEN
    say $config->{output} 'Fun diagnostic message!';

Perl will attempt to call say on the $config object.

print, close, and say—all builtins which operate on filehandles—operate in an indirect fashion. This was fine when filehandles were package globals, but lexical filehandles (Filehandle References) make the indirect object syntax problems obvious. To solve this, disambiguate the subexpression which produces the intended invocant:

    say {$config->{output}} 'Fun diagnostic message!';

Alternatives to Indirect Notation

Direct invocation notation does not suffer this ambiguity problem. To construct an object, call the constructor method on the class name directly:

    my $q   = Plack::Request->new;
    my $obj = Class->new( arg => $value );

This syntax still has a bareword problem in that if you have a function named Request in the Plack namespace, Perl will interpret the bareword class name as a call to the function, as:

    sub Plack::Request;

    # you wrote Plack::Reuqest->new, but Perl saw
    my $q = Plack::Request()->new;

While this happens rarely, you can disambiguate classnames by appending the package separator (::) or by explicitly marking class names as string literals:

    # package separator
    my $q = Plack::Request::->new;

    # unambiguously a string literal
    my $q = 'Plack::Request'->new;

Almost no one ever does this.

For the limited case of filehandle operations, the dative use is so prevalent that you can use the indirect invocation approach if you surround your intended invocant with curly brackets. If you're using Perl 5.14 or newer (or if you load IO::File or IO::Handle), you can use methods on lexical filehandles Almost no one does this for print and say..

The CPAN module Perl::Critic::Policy::Dynamic::NoIndirect (a plugin for Perl::Critic) can analyze your code to find indirect invocations. The CPAN module indirect can identify and prohibit their use in running programs:

    # warn on indirect use
    no indirect;

    # throw exceptions on their use
    no indirect ':fatal';

Prototypes

A prototype is a piece of metadata attached to a function or variable. A function prototype changes how Perl's parser understands it.

Prototypes allow users to define their own functions which behave like builtins. Consider the builtin push, which takes an array and a list. While Perl would normally flatten the array and list into a single list passed to push, the parser knows to treat the array as a container, not to flatten its values. In effect, this is like passing a reference to an array and a list of values to push. The parser's behavior allows push to modify the values of the container.

Function prototypes attach to function declarations:

    sub foo        (&@);
    sub bar        ($$) { ... }
    my  $baz = sub (&&) { ... };

Any prototype attached to a forward declaration must match the prototype attached to the function declaration. Perl will give a warning if this is not true. Strangely you may omit the prototype from a forward declaration and include it for the full declaration—but there's no reason to do so.

The builtin prototype takes the name of a function and returns a string representing its prototype.

To see the prototype of a builtin, use the CORE:: form of the builtin's name as the operand to prototype:

    $ perl -E "say prototype 'CORE::push';"
    \@@
    $ perl -E "say prototype 'CORE::keys';"
    \%
    $ perl -E "say prototype 'CORE::open';"
    *;$@

prototype will return undef for those builtins whose functions you cannot emulate:

    say prototype 'CORE::system' // 'undef'
    # undef; cannot emulate builtin system

    say prototype 'CORE::prototype' // 'undef'
    # undef; builtin prototype has no prototype

Remember push?

    $ perl -E "say prototype 'CORE::push';"
    \@@

The @ character represents a list. The backslash forces the use of a reference to the corresponding argument. This prototype means that push takes a reference to an array and a list of values. You might write mypush as:

    sub mypush (\@@)
    {
        my ($array, @rest) = @_;
        push @$array, @rest;
    }

Other prototype characters include $ to force a scalar argument, % to mark a hash (most often used as a reference), and & to identify a code block. See perldoc perlsub for more information.

The Problem with Prototypes

Prototypes change how Perl parses your code and how Perl coerces arguments to your functions. While these prototypes may superficially resemble function signatures in other languages, they are very different. They do not document the number or types of arguments functions expect, nor do they map arguments to named parameters.

Prototype coercions work in subtle ways, such as enforcing scalar context on incoming arguments:

    sub numeric_equality($$)
    {
        my ($left, $right) = @_;
        return $left == $right;
    }

    my @nums = 1 .. 10;

    say 'They're equal, whatever that means!'
        if numeric_equality @nums, 10;

... but only work on simple expressions:

    sub mypush(\@@);

    # compilation error: prototype mismatch
    # (expects array, gets scalar assignment)
    mypush( my $elems = [], 1 .. 20 );

To debug this, users of mypush must know both that a prototype exists, and the limitations of the array prototype.

Good Uses of Prototypes

Prototypes do have a few good uses that outweigh their problems. For example, you can use a prototyped function to override one of Perl's builtins. First check that you can override the builtin by examining its prototype in a small test program. Then use the subs pragma to tell Perl that you plan to override a builtin, and finally declare your override with the correct prototype:

    use subs 'push';

    sub push (\@@) { ... }

Beware that the subs pragma is in effect for the remainder of the file, regardless of any lexical scoping.

The second reason to use prototypes is to define compile-time constants. When Perl encounters a function declared with an empty prototype (as opposed to no prototype) and this function evaluates to a single constant expression, the optimizer will turn all calls to that function into constants instead of function calls:

    sub PI () { 4 * atan2(1, 1) }

All subsequent code will use the calculated value of pi in place of the bareword PI or a call to PI(), with respect to scoping and visibility.

The core pragma constant handles these details for you. The Const::Fast module from the CPAN creates constant scalars which you can interpolate into strings.

A reasonable use of prototypes is to extend Perl's syntax to operate on anonymous functions as blocks. The CPAN module Test::Exception uses this to good effect to provide a nice API with delayed computation See also Test::Fatal. Its throws_ok() function takes three arguments: a block of code to run, a regular expression to match against the string of the exception, and an optional description of the test:

    use Test::More;
    use Test::Exception;

    throws_ok
        { my $unobject; $unobject->yoink }
        qr/Can't call method "yoink" on an undefined/,
        'Method on undefined invocant should fail';

    done_testing();

The exported throws_ok() function has a prototype of &$;$. Its first argument is a block, which becomes an anonymous function. The second argument is a scalar. The third argument is optional.

Careful readers may have spotted the absence of a comma after the block. This is a quirk of Perl's parser, which expects whitespace after a prototyped block, not the comma operator. This is a drawback of the prototype syntax. If that bothers you, use throws_ok() without taking advantage of the prototype:

    use Test::More;
    use Test::Exception;

    throws_ok(
        sub { my $unobject; $unobject->yoink() },
        qr/Can't call method "yoink" on an undefined/,
        'Method on undefined invocant should fail' );

    done_testing();

A final good use of prototypes is when defining a custom named function to use with sort Ben Tilly suggested this example.:

    sub length_sort ($$)
    {
        my ($left, $right) = @_;
        return length($left) <=> length($right);
    }

    my @sorted = sort length_sort @unsorted;

The prototype of $$ forces Perl to pass the sort pairs in @_. sort's documentation suggests that this is slightly slower than using the package globals $a and $b, but using lexical variables often makes up for any speed penalty.

Method-Function Equivalence

Perl's object system is deliberately minimal (Blessed References). Because a class is a package, Perl does not distinguish between a function and a method stored in a package. The same builtin, sub, declares both. Perl will happily dispatch to a function called as a method. Likewise, you can invoke a method as if it were a function—fully-qualified, exported, or as a reference—if you pass in your own invocant manually.

Invoking the wrong thing in the wrong way causes problems.

Caller-side

Consider a class with several methods:

    package Order;

    use List::Util 'sum';

    ...

    sub calculate_price
    {
        my $self = shift;
        return sum( 0, $self->get_items );
    }

Given an Order object $o, the following invocations of this method may seem equivalent:

    my $price = $o->calculate_price;

    # broken; do not use
    my $price = Order::calculate_price( $o );

Though in this simple case, they produce the same output, the latter violates object encapsulation by avoiding method lookup.

If $o were instead a subclass or allomorph (Roles) of Order which overrode calculate_price(), bypassing method dispatch would call the wrong method. Any change to the implementation of calculate_price(), such as a modification of inheritance or delegation through AUTOLOAD()—might break calling code.

Perl has one circumstance where this behavior may seem necessary. If you force method resolution without dispatch, how do you invoke the resulting method reference?

    my $meth_ref = $o->can( 'apply_discount' );

There are two possibilities. The first is to discard the return value of the can() method:

    $o->apply_discount if $o->can( 'apply_discount' );

The second is to use the reference itself with method invocation syntax:

    if (my $meth_ref = $o->can( 'apply_discount' ))
    {
        $o->$meth_ref();
    }

When $meth_ref contains a function reference, Perl will invoke that reference with $o as the invocant. This works even under strictures, as it does when invoking a method with a scalar containing its name:

    my $name = 'apply_discount';
    $o->$name();

There is one small drawback in invoking a method by reference; if the structure of the program changes between storing the reference and invoking the reference, the reference may no longer refer to the most appropriate method. If the Order class has changed such that Order::apply_discount is no longer the right method to call, the reference in $meth_ref will not have updated.

When you use this invocation form, limit the scope of the references.

Callee-side

Because Perl makes no distinction between functions and methods at the point of declaration and because it's possible (however inadvisable) to invoke a given function as a function or a method, it's possible to write a function callable as either.

The CGI module has these two-faced functions. Every one of them must apply several heuristics to determine whether the first argument is an invocant. This causes problems. It's difficult to predict exactly which invocants are potentially valid for a given method, especially when you may have to deal with subclasses. Creating an API that users cannot easily misuse is more difficult too, as is your documentation burden. What happens when one part of the project uses the procedural interface and another uses the object interface?

If you must provide a separate procedural and OO interface to a library, create two separate APIs.

Automatic Dereferencing

Perl can automatically dereference certain references on your behalf. Given an array reference in $arrayref, you can write:

    push $arrayref, qw( list of values );

Given an expression which returns an array reference, you can do the same:

    push $houses{$location}[$closets], \@new_shoes;

The same goes for the array operators pop, shift, unshift, splice, keys, values, and each and the hash operators keys, values, and each. If the reference provided is not of the proper type—if it does not dereference properly—Perl will throw an exception. While this may seem more dangerous than explicitly dereferencing references directly, it is in fact the same behavior:

    my $ref = sub { ... };

    # will throw an exception
    push  $ref, qw( list of values );

    # will also throw an exception
    push @$ref, qw( list of values );

Unfortunately, this automatic dereferencing has two problems. First, it only works on plain variables. If you have a blessed array or hash, a tied hash, or an object with array or hash overloading, Perl will throw a runtime exception instead of dereferencing the reference.

Second, remember that each, keys, and values can operate on both arrays and hashes. You can't look at:

    my @items = each $ref;

... and tell whether @items contains a list of key/value pairs or index/value pairs, because you don't know whether you should expect $ref to refer to a hash or an array. Yes, choosing good variable names will help, but this code is intrinsically confusing.

Neither of these drawbacks make this syntax unusable in general, but its rough edges and potential for confusing readers make it less useful than it could be.

Tie

Where overloading (Overloading) allows you to customize the behavior of classes and objects for specific types of coercion, a mechanism called tying allows you to customize the behavior of primitive variables (scalars, arrays, hashes, and filehandles). Any operation you might perform on a tied variable translates to a specific method call on an object.

The tie builtin originally allowed you to use disk space instead of RAM for hashes and arrays, so that Perl could use data larger than available memory. The core module Tie::File allows you to do this, in effect treating files as if they were arrays.

The class to which you tie a variable must conform to a defined interface for a specific data type. Read perldoc perltie for an overview, then see the core modules Tie::StdScalar, Tie::StdArray, and Tie::StdHash for specific details. Start by inheriting from one of those classes, then override any specific methods you need to modify.

Tying Variables

To tie a variable:

    use Tie::File;
    tie my @file, 'Tie::File', @args;

The first argument is the variable to tie. The second is the name of the class into which to tie it. @args is an optional list of arguments required for the tying function. In the case of Tie::File, @args should contain a valid filename.

Tying functions resemble constructors: TIESCALAR, TIEARRAY(), TIEHASH(), or TIEHANDLE() for scalars, arrays, hashes, and filehandles respectively. Each function returns a new object which represents the tied variable. Both tie and tied return this object, though most people use tied in a boolean context.

Implementing Tied Variables

To implement the class of a tied variable, inherit from a core module such as Tie::StdScalar Tie::StdScalar lacks its own .pm file, so write use Tie::Scalar;., then override the specific methods for the operations you want to change. In the case of a tied scalar, these are likely FETCH and STORE, possibly TIESCALAR(), and probably not DESTROY().

Here's a class which logs all reads from and writes to a scalar:

    package Tie::Scalar::Logged
    {
        use Modern::Perl;

        use Tie::Scalar;
        use parent -norequire => 'Tie::StdScalar';

        sub STORE
        {
            my ($self, $value) = @_;
            Logger->log("Storing <$value> (was [$$self])", 1);
            $$self = $value;
        }

        sub FETCH
        {
            my $self = shift;
            Logger->log("Retrieving <$$self>", 1);
            return $$self;
        }
    }

Assume that the Logger class method log() takes a string and the number of frames up the call stack of which to report the location.

Within the STORE() and FETCH() methods, $self works as a blessed scalar. Assigning to that scalar reference changes the value of the scalar and reading from it returns its value.

Similarly, the methods of Tie::StdArray and Tie::StdHash act on blessed array and hash references, respectively. Again, perldoc perltie explains the methods tied variables support, such as reading or writing multiple values at once.

When to use Tied Variables

Tied variables seem like fun opportunities for cleverness, but they can produce confusing interfaces. Unless you have a very good reason for making objects behave as if they were builtin data types, avoid creating your own ties. tied variables are often much slower than builtin data types.

With that said, tied variables can help you debug tricky code (use the logged scalar to help you understand where a value changes) or to make certain impossible things possible (access large files without running out of memory). Tied variables are less useful as the primary interfaces to objects; it's often too difficult and constraining to try to fit your whole interface to that supported by tie().

A final word of warning is a sad indictment of lazy programming: a lot of code goes out of its way to prevent use of tied variables, often by accident. This is unfortunate, but library code is sometimes fast and lazy with what it expects, and you can't always fix it.