Paul Evans > Attribute-Storage-0.06 > Attribute::Storage

Download:
Attribute-Storage-0.06.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.06   Source   Latest Release: Attribute-Storage-0.08

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

 1;

 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:

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) { ... }

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>

syntax highlighting: