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 docstringscomments 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.

Running the Hack

The easiest way to create and use attributes is with the Attribute::Handlers module. This allows you to write subroutines named after the attributes you want to declare. The implementation of Attribute::Docstring is:

package Attribute::Docstring; use strict; use warnings; use Scalar::Util 'blessed'; use Attribute::Handlers; my %doc; sub UNIVERSAL::Doc :ATTR {     my ($package, $symbol, $referent, $attr, $data, $phase) = @_;     return if $symbol eq 'LEXICAL';     my $name                  = *{$symbol}{NAME};     $doc{ $package }{ $name } = $data; } sub UNIVERSAL::doc {     my ($self, $name) = @_;     my $package       = blessed( $self ) || $self;     return unless exists $doc{ $package }{ $name };     return               $doc{ $package }{ $name }; } 1;

To make the Doc attribute available everywhere, the module defines a subroutine called UNIVERSAL::Doc. This subroutine itself has an attribute, :ATTR, which identifies it as an attribute handler.

For any subroutine or variable that declares a Doc attribute, the subroutine receives several pieces of information. Here, the important ones are the package containing the subroutine, the symbolfrom which the typeglob access can retrieve the name, and the data provided to the attribute. In the Counter class, the attribute handler receives a package name of Counter and the typeglob with the name new for the symbol when Perl finishes compiling the new( ) method. It then stores the attribute data (the docstring itself) in a hash keyed first on the name of the package and then on the name of the symbol.

Because of the difference between how Perl treats lexical and global variables, the handler can't do much if it receives a lexical symbol (that is, when $symbol is LEXICAL). Then again, these are private to the package so they're not worth documenting in this way anyway.

The similarly named doc( ) method works on any class or object, so that calling Counter->doc( 'new' ) or $counter->doc( 'get_count' ) both return the docstring for the appropriate method. It simply looks up the docstring in the appropriate package for the given name and returns it.

Hacking the Hack

One potential enhancement is to add the appropriate sigil to the name, so that the docstrings for a variable named $count and a method named count( ) will not overwrite each other. That would require a change to UNIVERSAL::doc( ) so that $name contains the sigil (or, with no sigil, defaults to the method).

Another possibility is to take UNIVERSAL::Doc( ) out of UNIVERSAL, instead importing it into any package that uses this module. That unclutters UNIVERSAL somewhat at the expense of cluttering calling classes. That may or may not be a useful tradeoff.

Attributes may span lines, but you cannot use heredocs, unfortunately.



Perl Hacks
Perl Hacks: Tips & Tools for Programming, Debugging, and Surviving
ISBN: 0596526741
EAN: 2147483647
Year: 2004
Pages: 141

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net