NAME

    Attribute::Storage - declare and retrieve named attributes data

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 named attributes. Other packages, using the
    package that defines the attributes, can then use them to annotate
    subroutines or variables.

    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.

    Since version 0.11 this module also supports attributes on scalar,
    array and hash variables.

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.

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

    Only CODE attributes support the NAME flag; it cannot be applied when
    SCALAR, ARRAY or HASH are also present.

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

 get_subattrs

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

 get_varattrs

       $attrs = get_varattrs( $varref );

    Since version 0.11.

    Returns a HASH reference containing all the attributes defined on the
    given variable, which should be passed in by reference.

    In both of the above functions, the returned HASH reference is a new
    shallow clone, and the caller may modify this hash arbitrarily without
    breaking the stored data or other users of it. If no attributes are
    defined then a reference to an empty HASH is returned.

 get_subattr

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

 get_varattr

       $value = get_varattr( $varref, $attrname );

    Since version 0.11.

    Returns the value of a single named attribute on the given variable,
    which should be passed in by reference.

    In both of the above functions, if the attribute is not defined then
    undef is returned.

 apply_subattrs

       $sub = apply_subattrs( @attrs_kvlist, $sub );

    A utility function to help apply attributes dynamically to the given
    CODE reference. The CODE reference is given last so that calls to the
    function appear similar in visual style to the same applied at
    compiletime.

       apply_subattrs
          Title => "Here is my title",
          sub { return $title };

    Is equivalent to

       sub :Title(Here is my title) { return $title }

    except that because its arguments are evaluated at runtime, they can be
    calculated by other code in ways that the compiletime version cannot.

    As the attributes are given in a key-value pair list, it is allowed to
    apply the same attribute multiple times; and the attributes are applied
    in the order given. The value of each attribute should be a plain
    string exactly as it would appear between the parentheses.
    Specifically, if the attribute does not use the RAWDATA flag, it should
    be a valid perl expression. As this is still evaluated using an eval()
    call, take care when handling potentially-unsafe or user-supplied data.

 apply_subattrs_for_pkg

       $sub = apply_subattrs_for_pkg( $pkg, @attrs_kvlist, $sub );

    As apply_subattrs but allows passing a specific package name, rather
    than using caller.

 find_subs_with_attr

       %subs = find_subs_with_attr( $pkg, $attrname, %opts );

    A utility function to find CODE references in the given package that
    have the named attribute applied. The symbol table is checked for the
    given package, looking for CODE references that have the named
    attribute applied. These are returned in a key-value list, where the
    key gives the name of the function and the value is a CODE reference to
    it.

    $pkg can also be a reference to an array containing multiple package
    names, which will be searched in order with earlier ones taking
    precedence over later ones. This, for example, allows for subclass
    searching over an entire class heirarchy of packages, via the use of
    mro:

       %subs = find_subs_with_attr( mro::get_linear_isa( $class ), $attrname );

 find_vars_with_attr

       %vars = find_vars_with_attr( $pkg, $attrname, %opts );

    Since version 0.11.

    A utility function to find SCALAR, ARRAY or HASH references in the
    given package that have the named attribute applied. The symbol table
    is checked for the given package, looking for variable references that
    have the named attribute applied. These are returned in a key-value
    list, where the key gives the name of the variable and the value is a
    reference to it.

    Unlike for "find_subs_with_attr", the $pkg argument must be a single
    package name; no subclass search takes place.

    Both of the above functions take the following named options:

    matching => Regexp | CODE

      If present, gives a filter regexp or CODE reference to apply to
      names. Subs will be given as plain names; variable names will include
      the leading sigil.

         $name =~ $matching;
         $matching->( local $_ = $name );

    filter => CODE

      If present, gives a filter CODE reference to apply to the target
      references before they are accepted as results. Note that this allows
      the possibility that the first match for a given method name to be
      rejected, while later ones are accepted.

         $filter->( $ref, $name, $package );

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>