NAME
`Attribute::Storage' - declare and retrieve named attributes about CODE
references
SYNOPSIS
package My::Package;
use Attribute::Storage;
sub Title :ATTR(CODE)
{
my $package = shift;
my ( $title ) = @_;
return $title;
}
package main;
use Attribute::Storage qw( get_subattr );
use My::Package;
sub myfunc :Title('The title of my function')
{
...
}
print "Title of myfunc is: ".get_subattr(\&myfunc, 'Title')."\n";
DESCRIPTION
This package provides a base, where a package using it can define
handlers for particular code attributes. Other packages, using the
package that defines the code attributes, can then use them to annotate
subs.
This is similar to `Attribute::Handlers', with the following key
differences:
* `Attribute::Storage' will store the value returned by the attribute
handling code, and provides convenient lookup functions to retrieve
it later. `Attribute::Handlers' simply invokes the handling code.
* `Attribute::Storage' immediately executes the attribute handling
code at compile-time. `Attribute::Handlers' defers invocation so it
can look up the symbolic name of the sub the attribute is attached
to. `Attribute::Storage' uses B to provide the name of the sub at
invocation time, using the name of the underlying `GV'.
* `Attribute::Storage' works just as well on anonymous subs as named
ones.
* `Attribute::Storage' is safe to use on code that will be reloaded,
because it executes handlers immediately. `Attribute::Handlers' will
only execute handlers at defined phases such as `BEGIN' or `INIT',
and cannot reexecute the handlers in a file once it has been
reloaded.
ATTRIBUTES
Each attribute that the defining package wants to define should be done
using a marked subroutine, in a way similar to Attribute::Handlers. When
a sub in the using package is marked with such an attribute, the code is
executed, passing in the arguments. Whatever it returns is stored, to be
returned later when queried by `get_subattr' or `get_subattrs'. The
return value must be defined, or else the attribute will be marked as a
compile error for perl to handle accordingly.
Only `CODE' attributes are supported at present.
sub AttributeName :ATTR(CODE)
{
my $package = shift;
my ( $attr, $args, $here ) = @_;
...
return $value;
}
At attachment time, the optional string that may appear within brackets
following the attribute's name is parsed as a Perl expression in list
context. If this succeeds, the values are passed as a list to the
handling code. If this fails, an error is returned to the perl compiler.
If no string is present, then an empty list is passed to the handling
code.
package Defining;
sub NameMap :ATTR(CODE)
{
my $package = shift;
my @strings = @_;
return { map { m/^(.*)=(.*)$/ and ( $1, $2 ) } @strings };
}
package Using;
use Defining;
sub somefunc :NameMap("foo=FOO","bar=BAR","splot=WIBBLE") { ... }
my $map = get_subattr("somefunc", "NameMap");
# Will yield:
# { foo => "FOO",
# bar => "BAR",
# splot => "WIBBLE" }
Note that it is impossible to distinguish
sub somefunc :NameMap { ... }
sub somefunc :NameMap() { ... }
It is possible to create attributes that do not parse their argument as
a perl list expression, instead they just pass the plain string as a
single argument. For this, add the `RAWDATA' flag to the `ATTR()' list.
sub Title :ATTR(CODE,RAWDATA)
{
my $package = shift;
my ( $text ) = @_;
return $text;
}
sub thingy :Title(Here is the title for thingy) { ... }
To obtain the name of the function to which the attribute is being
applied, use the `NAME' flag to the `ATTR()' list.
sub Callable :ATTR(CODE,NAME)
{
my $package = shift;
my ( $subname, @args ) = @_;
print "The Callable attribute is being applied to $package :: $subname\n";
return;
}
When applied to an anonymous function (`sub { ... }'), the name will
appear as `__ANON__'.
Normally it is an error to attempt to apply the same attribute more than
once to the same function. Sometimes however, it would make sense for an
attribute to be applied many times. If the `ATTR()' list is given the
`MULTI' flag, then applying it more than once will be allowed. Each
invocation of the handling code will be given the previous value that
was returned, or `undef' for the first time. It is up to the code to
perform whatever merging logic is required.
sub Description :ATTR(CODE,MULTI,RAWDATA)
{
my $package = shift;
my ( $olddesc, $more ) = @_;
return defined $olddesc ? "$olddesc$more\n" : "$more\n";
}
sub Argument :ATTR(CODE,MULTI)
{
my $package = shift;
my ( $args, $argname ) = @_;
push @$args, $argname;
return $args;
}
sub Option :ATTR(CODE,MULTI)
{
my $package = shift;
my ( $opts, $optname ) = @_;
$opts and exists $opts->{$optname} and
croak "Already have the $optname option";
$opts->{$optname}++;
return $opts;
}
...
sub do_copy
:Description(Copy from SOURCE to DESTINATION)
:Description(Optionally preserves attributes)
:Argument("SOURCE")
:Argument("DESTINATION")
:Option("attrs")
:Option("verbose")
{
...
}
FUNCTIONS
$attrs = get_subattrs( $sub )
Returns a HASH reference containing all the attributes defined on the
given sub. The sub should either be passed as a CODE reference, or as a
name in the caller's package. If no attributes are defined, a reference
to an empty HASH is returned.
The returned HASH reference is a new shallow clone, the caller may
modify this hash arbitrarily without breaking the stored data, or other
users of it.
$value = get_subattr( $sub, $attrname )
Returns the value of a single named attribute on the given sub. The sub
should either be passed as a CODE reference, or as a name in the
caller's package. If the attribute is not defined, `undef' is returned.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>