What to Avoid

Perl 5 isn't perfect. Some features seemed like good ideas at the time, but they're difficult to use correctly. Others don't work as anyone might expect. A few more are simply bad ideas. These features will likely persist--removing a feature from Perl is a serious process reserved for only the most egregious offenses--but you can and should avoid them in almost every case.

Barewords

Perl's parser understands the builtin Perl builtins and operators; it knows that bless() means you're making objects (Blessed References). These are rarely ambiguous... but Perl programmers can add complexity to parsing by using barewords. A bareword is an identifier without a sigil or other attached disambiguation as to its intended syntactical function. Because there's no Perl 5 builtin curse, the literal word curse appearing in source code is ambiguous. Did you intend to use a variable $curse or to call a function curse()? The strict pragma warns about use of such ambiguous barewords for good reason.

Even so, barewords are permissible in several places in Perl 5 for good reason.

Good Uses of Barewords

Hash keys in Perl 5 are barewords. These are usually not ambiguous because their use as keys is sufficient for the parser to identify them as the equivalent of single-quoted strings. Yet be aware that attempting to evaluate a function call or a builtin operator (such as shift) to produce a hash key may not do what you expect, unless you disambiguate by providing arguments, using function argument parentheses, or prepending unary plus to force the evaluation of the builtin rather than its interpretation as a string:

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

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

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

Package names in Perl 5 are barewords in a sense. Good naming conventions for packages (initial caps) help prevent unwanted surprises, but the parser uses a complex heuristic based on the code it's already compiled within the current namespace to determine whether Package->method() means to call a function named Package() and then call the method() method on its results or whether to treat Package as the name of a package. You can disambiguate this with the postfix package separator (::), but that's rare and admittedly ugly:

    # probably a class method
    Package->method();

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

The special named code blocks provide their own types of barewords. AUTOLOAD, BEGIN, CHECK, DESTROY, END, INIT, and UNITCHECK declare functions, but they do not need the sub builtin to do so. You may be familiar with the idiom of writing BEGIN without sub:

    package Monkey::Butler;

    BEGIN { initialize_simians( __PACKAGE__ ) }

You can leave off the sub on AUTOLOAD() declarations, but that's uncommon.

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;

Be aware that these constants do not interpolate in interpolation contexts such as double-quoted strings.

Constants are a special case of prototyped functions (Prototypes). If you've predeclared a prototype for a function, you may use that function as a bareword; Perl 5 knows everything it needs to know to parse all occurrences of that function appropriately. The other drawbacks of prototypes still apply.

Ill-Advised Uses of Barewords

Barewords should be rare in modern Perl code; their ambiguity produces fragile code. You can avoid them in almost every case, but you may encounter several poor uses of barewords in legacy code.

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; the exceptions are STDIN, STDOUT, and STDERR.

Code written without strict 'subs' in effect may use bareword function names. You may safely parenthesize the argument lists to these functions without changing the intent of the code (footnote: Use perl -MO=Deparse,-p to discover how Perl parses them, then parenthesize accordingly.).

Along similar lines, old code may not take pains to quote the values of hash pairs appropriately:

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

Because neither the Floyd() nor Annette() functions exist, Perl parses these hash values as strings. The strict 'subs' pragma makes the parser give an error in this situation.

Finally, the sort builtin can take as its second argument the name of a function to use for sorting. Instead provide a reference to the function to use for sorting to avoid the use of barewords:

    # poor style; do not use
    my @sorted = sort compare_lengths @unsorted;

    # better style
    my $comparison = \&compare_lengths;
    my @sorted     = sort $comparison @unsorted;

The result is one line longer, but it avoids the use of a bareword. Unlike other bareword examples, Perl's parser needs no disambiguation for this syntax. There is only one way for it to interpret compare_lengths. However, the clarity of an explicit reference can help human readers.

Perl 5's parser does not understand the single-line version:

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

This is 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.

Indirect Objects

    my $q = new CGI; # DO NOT USE

    my $q = CGI->new();

One problem is that the name of the method is a bareword (Barewords). The parser must apply several heuristics to determine the proper interpretation. While these heuristics are well-tested and almost always correct, their failure modes are confusing. Worse, they're fragile in the face of the order of compilation and module loading.

Parsing is more difficult for humans and the computer when the constructor takes arguments. The indirect style may resemble:

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

... thus making the class name Class look like a function call. Perl 5 can disambiguate many of these cases, but its heuristics depend on which package names the parser has seen at the current point in the parse, which barewords it has already resolved (and how it resolved them), and the names of functions already declared in the current package.

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 infrequent, but so difficult to debug that avoiding this syntax is always worthwhile.

Indirect Notation Scalar Limitations

Another danger of the 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} "This is a diagnostic message!";

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. In the previous example, Perl will try to call the say method on the $config object. The solution is to disambiguate the expression which produces the intended invocant:

    say {$config->{output}} "This is a 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   = CGI->new();
    my $obj = Class->new( arg => $value );

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. Another option is to use the core IO::Handle module which adds IO methods to lexical filehandles.

The CPAN module Perl::Critic::Policy::Dynamic::NoIndirect (a plugin for Perl::Critic) can identify indirect invocations during code reviews. 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

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

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

    $ perl -E "say prototype 'CORE::system' // 'undef' "
    undef
    # You can't emulate builtin function system's calling convention.

    $ perl -E "say prototype 'CORE::prototype' // 'undef' "
    undef
    # Builtin function prototype has no prototype.

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

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

    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;

    sub mypush(\@@);

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

    use subs 'push';

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

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

    use Test::More tests => 1;
    use Test::Exception;

    throws_ok
        { my $not_an_object; $not_an_object->some_method() }
        qr/Can't call method "some_method" on an undefined value/,
        'Calling a method on an undefined invocant should throw exception';

    use Test::More tests => 1;
    use Test::Exception;

    throws_ok(
        sub { my $not_an_object; $not_an_object->some_method() },
        qr/Can't call method "some_method" on an undefined value/,
        'Calling a method on an undefined invocant should throw exception');

Perl 5's object system is deliberately minimal (Blessed References). Because a class is a package, Perl itself makes no strong distinction between a function stored in a package and a method stored in a package. The same builtin, sub, expresses both. Documentation and the convention of treating the first parameter as $self can imply intent to readers of the code, but Perl itself will treat any function of the appropriate name it can find in an appropriate package as a method if you try to call it 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.

Both approaches have their problems; avoid them.

Caller-side

Suppose you have a class which contains several methods:

    package Order;

    use List::Util 'sum';

    ...

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

If you have 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 the encapsulation of objects in subtle ways. It avoids method lookup altogether.

If $o were instead a subclass or allomorph (Roles) of Order which overrode calculate_price(), calling the method as a function would produce the wrong behavior. 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 has changed between storing the reference and invoking the reference, the reference may no longer refer to the current, 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.

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

Callee-side

Because Perl 5 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 core CGI module is a prime offender. Its functions manually inspect @_ to determine whether the first argument is a likely invocant. If so, they ensure that any object state the function needs to access is available. If the first argument is not a likely invocant, the function must consult global data elsewhere.

As with all heuristics, there are corner cases. It's difficult to predict exactly which invocants are potentially valid for a given method, especially when considering that users can create their own subclasses. The documentation burden is also greater, given the need to explain the dichotomy of the code and the desire to avoid misuse. What happens when one part of the project uses the procedural interface and another uses the object interface?

Providing separate procedural and object interfaces to a library may be justifiable. Some designs make some techniques more useful than others. Conflating the two into a single API will create a maintenance burden. Avoid it.

Tie

Overloading (Overloading) lets you give classes custom behavior for specific types of coercions and accesses. A similar mechanism exists for making classes act like built-in types (scalars, arrays, and hashes), but with more specific behaviors. This mechanism uses the tie builtin; it is tying.

The original use of tie was to produce a hash stored on disk, rather than in memory. This allowed the use of DBM files from Perl, as well as the ability to access files larger than could fit in memory. The core module Tie::File provides a similar system by which to handle data files too large to fit in memory.

The class to which you tie a variable must conform to a defined interface for the specific data type. perldoc perltie is the primary source of information about these interfaces, though the core modules Tie::StdScalar, Tie::StdArray, and Tie::StdHash are more useful in practice. Inherit from them to start, and override only those specific methods you need to modify.

Tying Variables

Given a variable to tie, tie it with the syntax:

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

... where the first argument is the variable to tie, the second is the name of the class into which to tie it, and @args is an optional list of arguments required for the tying function. In the case of Tie::File, this is the name of the file to which to tie the array.

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 the tie and tied builtins return this object, but most people ignore it in favor of checking its boolification to determine whether a given variable is tied.

Implementing Tied Variables

To implement the class of a tied variable, inherit from a core module such as Tie::StdScalar, then override the specific methods for the operations you want to change. In the case of a tied scalar, you probably need to override FETCH and STORE, may need to override TIESCALAR(), and can often ignore DESTROY().

You can create a class which logs all reads from and writes to a scalar with very little code:

    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;
    }

    1;

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. Be aware that Tie::StdScalar does not have its own .pm file, so you must use Tie::Scalar to make it available.

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. The perldoc perltie documentation explains the copious methods they support, as you can read or write multiple values from them, among other operations.

When to use Tied Variables

Tied variables seem like fun opportunities for cleverness, but they make for confusing interfaces in almost all cases, due mostly to their rarity. Unless you have a very good reason for making objects behave as if they were built-in data types, avoid creating your own ties.

Good reasons include to ease debugging (use the logged scalar to help you understand where a value changes) and to make certain impossible operations possible (accessing large files in a memory-efficient way). 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().

The final word of warning is both sad and convincing; far too much code does not expect to work with tied variables. Code which violates encapsulation may prohibit good and valid uses of cleverness. This is unfortunate, but violating the expectations of library code tends to reveal bugs that are often out of your power to fix.