Perl Hacks

Hack #45. Add Information with Attributes

Give your variables and subroutines a little extra information.

Subroutines and variables are straighforward. Sure, you can pass around references to them or make them anonymous and do weird things with them, but you have few options to change what Perl does with them.

Your best option is to give them attributes. Attributes are little pieces of data that attach to variables or subroutines. In return, Perl runs any code you like. This has many, many possibilities.

The Hack

Suppose that you have a class and want to document the purpose of each method. Some languages support docstrings—comments that you can introspect by calling class methods. Perl's comments are pretty boring, but you can achieve almost the same effect by annotating methods with subroutine attributes.

Consider a Counter class, intended to provide a default constructor that counts the number of objects created. If there's a Doc attribute provided by the Attribute::Docstring module, the class may resemble:

package Counter;

use strict;
use warnings;

use Attribute::Docstring;

our $counter :Doc( 'a count of all new Foo objects' );

sub new :Doc( 'the constructor for Foo' )
{
    $counter++;
    bless { }, shift;
}

sub get_count :Doc( 'returns the count for all foo objects' )
{
    return $counter;
}

1;

The prototype comes after the name of the subroutine and has a preceding colon. Otherwise, it looks like a function call. The documentation string is the (single) argument to the attribute.