| 1 |
NAME |
| 2 |
|
| 3 |
Attribute::Storage - declare and retrieve named attributes data |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
|
| 7 |
package My::Package; |
| 8 |
|
| 9 |
use Attribute::Storage; |
| 10 |
|
| 11 |
sub Title :ATTR(CODE) |
| 12 |
{ |
| 13 |
my $package = shift; |
| 14 |
my ( $title ) = @_; |
| 15 |
|
| 16 |
return $title; |
| 17 |
} |
| 18 |
|
| 19 |
package main; |
| 20 |
|
| 21 |
use Attribute::Storage qw( get_subattr ); |
| 22 |
use My::Package; |
| 23 |
|
| 24 |
sub myfunc :Title('The title of my function') |
| 25 |
{ |
| 26 |
... |
| 27 |
} |
| 28 |
|
| 29 |
print "Title of myfunc is: ".get_subattr(\&myfunc, 'Title')."\n"; |
| 30 |
|
| 31 |
DESCRIPTION |
| 32 |
|
| 33 |
This package provides a base, where a package using it can define |
| 34 |
handlers for particular named attributes. Other packages, using the |
| 35 |
package that defines the attributes, can then use them to annotate |
| 36 |
subroutines or variables. |
| 37 |
|
| 38 |
This is similar to Attribute::Handlers, with the following key |
| 39 |
differences: |
| 40 |
|
| 41 |
* Attribute::Storage will store the value returned by the attribute |
| 42 |
handling code, and provides convenient lookup functions to retrieve |
| 43 |
it later. Attribute::Handlers simply invokes the handling code. |
| 44 |
|
| 45 |
* Attribute::Storage immediately executes the attribute handling code |
| 46 |
at compile-time. Attribute::Handlers defers invocation so it can look |
| 47 |
up the symbolic name of the sub the attribute is attached to. |
| 48 |
Attribute::Storage uses B to provide the name of the sub at |
| 49 |
invocation time, using the name of the underlying GV. |
| 50 |
|
| 51 |
* Attribute::Storage works just as well on anonymous subs as named |
| 52 |
ones. |
| 53 |
|
| 54 |
* Attribute::Storage is safe to use on code that will be reloaded, |
| 55 |
because it executes handlers immediately. Attribute::Handlers will |
| 56 |
only execute handlers at defined phases such as BEGIN or INIT, and |
| 57 |
cannot reexecute the handlers in a file once it has been reloaded. |
| 58 |
|
| 59 |
Since version 0.11 this module also supports attributes on scalar, |
| 60 |
array and hash variables. |
| 61 |
|
| 62 |
ATTRIBUTES |
| 63 |
|
| 64 |
Each attribute that the defining package wants to define should be done |
| 65 |
using a marked subroutine, in a way similar to Attribute::Handlers. |
| 66 |
When a sub in the using package is marked with such an attribute, the |
| 67 |
code is executed, passing in the arguments. Whatever it returns is |
| 68 |
stored, to be returned later when queried by get_subattr or |
| 69 |
get_subattrs. The return value must be defined, or else the attribute |
| 70 |
will be marked as a compile error for perl to handle accordingly. |
| 71 |
|
| 72 |
sub AttributeName :ATTR(CODE) |
| 73 |
{ |
| 74 |
my $package = shift; |
| 75 |
my ( $attr, $args, $here ) = @_; |
| 76 |
... |
| 77 |
return $value; |
| 78 |
} |
| 79 |
|
| 80 |
At attachment time, the optional string that may appear within brackets |
| 81 |
following the attribute's name is parsed as a Perl expression in list |
| 82 |
context. If this succeeds, the values are passed as a list to the |
| 83 |
handling code. If this fails, an error is returned to the perl |
| 84 |
compiler. If no string is present, then an empty list is passed to the |
| 85 |
handling code. |
| 86 |
|
| 87 |
package Defining; |
| 88 |
|
| 89 |
sub NameMap :ATTR(CODE) |
| 90 |
{ |
| 91 |
my $package = shift; |
| 92 |
my @strings = @_; |
| 93 |
|
| 94 |
return { map { m/^(.*)=(.*)$/ and ( $1, $2 ) } @strings }; |
| 95 |
} |
| 96 |
|
| 97 |
package Using; |
| 98 |
|
| 99 |
use Defining; |
| 100 |
|
| 101 |
sub somefunc :NameMap("foo=FOO","bar=BAR","splot=WIBBLE") { ... } |
| 102 |
|
| 103 |
my $map = get_subattr("somefunc", "NameMap"); |
| 104 |
# Will yield: |
| 105 |
# { foo => "FOO", |
| 106 |
# bar => "BAR", |
| 107 |
# splot => "WIBBLE" } |
| 108 |
|
| 109 |
Note that it is impossible to distinguish |
| 110 |
|
| 111 |
sub somefunc :NameMap { ... } |
| 112 |
sub somefunc :NameMap() { ... } |
| 113 |
|
| 114 |
It is possible to create attributes that do not parse their argument as |
| 115 |
a perl list expression, instead they just pass the plain string as a |
| 116 |
single argument. For this, add the RAWDATA flag to the ATTR() list. |
| 117 |
|
| 118 |
sub Title :ATTR(CODE,RAWDATA) |
| 119 |
{ |
| 120 |
my $package = shift; |
| 121 |
my ( $text ) = @_; |
| 122 |
|
| 123 |
return $text; |
| 124 |
} |
| 125 |
|
| 126 |
sub thingy :Title(Here is the title for thingy) { ... } |
| 127 |
|
| 128 |
To obtain the name of the function to which the attribute is being |
| 129 |
applied, use the NAME flag to the ATTR() list. |
| 130 |
|
| 131 |
sub Callable :ATTR(CODE,NAME) |
| 132 |
{ |
| 133 |
my $package = shift; |
| 134 |
my ( $subname, @args ) = @_; |
| 135 |
|
| 136 |
print "The Callable attribute is being applied to $package :: $subname\n"; |
| 137 |
|
| 138 |
return; |
| 139 |
} |
| 140 |
|
| 141 |
Only CODE attributes support the NAME flag; it cannot be applied when |
| 142 |
SCALAR, ARRAY or HASH are also present. |
| 143 |
|
| 144 |
When applied to an anonymous function (sub { ... }), the name will |
| 145 |
appear as __ANON__. |
| 146 |
|
| 147 |
Normally it is an error to attempt to apply the same attribute more |
| 148 |
than once to the same target. Sometimes however, it would make sense |
| 149 |
for an attribute to be applied many times. If the ATTR() list is given |
| 150 |
the MULTI flag, then applying it more than once will be allowed. Each |
| 151 |
invocation of the handling code will be given the previous value that |
| 152 |
was returned, or undef for the first time. It is up to the code to |
| 153 |
perform whatever merging logic is required. |
| 154 |
|
| 155 |
sub Description :ATTR(CODE,MULTI,RAWDATA) |
| 156 |
{ |
| 157 |
my $package = shift; |
| 158 |
my ( $olddesc, $more ) = @_; |
| 159 |
|
| 160 |
return defined $olddesc ? "$olddesc$more\n" : "$more\n"; |
| 161 |
} |
| 162 |
|
| 163 |
sub Argument :ATTR(CODE,MULTI) |
| 164 |
{ |
| 165 |
my $package = shift; |
| 166 |
my ( $args, $argname ) = @_; |
| 167 |
|
| 168 |
push @$args, $argname; |
| 169 |
return $args; |
| 170 |
} |
| 171 |
|
| 172 |
sub Option :ATTR(CODE,MULTI) |
| 173 |
{ |
| 174 |
my $package = shift; |
| 175 |
my ( $opts, $optname ) = @_; |
| 176 |
|
| 177 |
$opts and exists $opts->{$optname} and |
| 178 |
croak "Already have the $optname option"; |
| 179 |
|
| 180 |
$opts->{$optname}++; |
| 181 |
return $opts; |
| 182 |
} |
| 183 |
|
| 184 |
... |
| 185 |
|
| 186 |
sub do_copy |
| 187 |
:Description(Copy from SOURCE to DESTINATION) |
| 188 |
:Description(Optionally preserves attributes) |
| 189 |
:Argument("SOURCE") |
| 190 |
:Argument("DESTINATION") |
| 191 |
:Option("attrs") |
| 192 |
:Option("verbose") |
| 193 |
{ |
| 194 |
... |
| 195 |
} |
| 196 |
|
| 197 |
FUNCTIONS |
| 198 |
|
| 199 |
get_subattrs |
| 200 |
|
| 201 |
$attrs = get_subattrs( $sub ); |
| 202 |
|
| 203 |
Returns a HASH reference containing all the attributes defined on the |
| 204 |
given sub. The sub should either be passed as a CODE reference, or as a |
| 205 |
name in the caller's package. |
| 206 |
|
| 207 |
get_varattrs |
| 208 |
|
| 209 |
$attrs = get_varattrs( $varref ); |
| 210 |
|
| 211 |
Since version 0.11. |
| 212 |
|
| 213 |
Returns a HASH reference containing all the attributes defined on the |
| 214 |
given variable, which should be passed in by reference. |
| 215 |
|
| 216 |
In both of the above functions, the returned HASH reference is a new |
| 217 |
shallow clone, and the caller may modify this hash arbitrarily without |
| 218 |
breaking the stored data or other users of it. If no attributes are |
| 219 |
defined then a reference to an empty HASH is returned. |
| 220 |
|
| 221 |
get_subattr |
| 222 |
|
| 223 |
$value = get_subattr( $sub, $attrname ); |
| 224 |
|
| 225 |
Returns the value of a single named attribute on the given sub. The sub |
| 226 |
should either be passed as a CODE reference, or as a name in the |
| 227 |
caller's package. |
| 228 |
|
| 229 |
get_varattr |
| 230 |
|
| 231 |
$value = get_varattr( $varref, $attrname ); |
| 232 |
|
| 233 |
Since version 0.11. |
| 234 |
|
| 235 |
Returns the value of a single named attribute on the given variable, |
| 236 |
which should be passed in by reference. |
| 237 |
|
| 238 |
In both of the above functions, if the attribute is not defined then |
| 239 |
undef is returned. |
| 240 |
|
| 241 |
apply_subattrs |
| 242 |
|
| 243 |
$sub = apply_subattrs( @attrs_kvlist, $sub ); |
| 244 |
|
| 245 |
A utility function to help apply attributes dynamically to the given |
| 246 |
CODE reference. The CODE reference is given last so that calls to the |
| 247 |
function appear similar in visual style to the same applied at |
| 248 |
compiletime. |
| 249 |
|
| 250 |
apply_subattrs |
| 251 |
Title => "Here is my title", |
| 252 |
sub { return $title }; |
| 253 |
|
| 254 |
Is equivalent to |
| 255 |
|
| 256 |
sub :Title(Here is my title) { return $title } |
| 257 |
|
| 258 |
except that because its arguments are evaluated at runtime, they can be |
| 259 |
calculated by other code in ways that the compiletime version cannot. |
| 260 |
|
| 261 |
As the attributes are given in a key-value pair list, it is allowed to |
| 262 |
apply the same attribute multiple times; and the attributes are applied |
| 263 |
in the order given. The value of each attribute should be a plain |
| 264 |
string exactly as it would appear between the parentheses. |
| 265 |
Specifically, if the attribute does not use the RAWDATA flag, it should |
| 266 |
be a valid perl expression. As this is still evaluated using an eval() |
| 267 |
call, take care when handling potentially-unsafe or user-supplied data. |
| 268 |
|
| 269 |
apply_subattrs_for_pkg |
| 270 |
|
| 271 |
$sub = apply_subattrs_for_pkg( $pkg, @attrs_kvlist, $sub ); |
| 272 |
|
| 273 |
As apply_subattrs but allows passing a specific package name, rather |
| 274 |
than using caller. |
| 275 |
|
| 276 |
find_subs_with_attr |
| 277 |
|
| 278 |
%subs = find_subs_with_attr( $pkg, $attrname, %opts ); |
| 279 |
|
| 280 |
A utility function to find CODE references in the given package that |
| 281 |
have the named attribute applied. The symbol table is checked for the |
| 282 |
given package, looking for CODE references that have the named |
| 283 |
attribute applied. These are returned in a key-value list, where the |
| 284 |
key gives the name of the function and the value is a CODE reference to |
| 285 |
it. |
| 286 |
|
| 287 |
$pkg can also be a reference to an array containing multiple package |
| 288 |
names, which will be searched in order with earlier ones taking |
| 289 |
precedence over later ones. This, for example, allows for subclass |
| 290 |
searching over an entire class heirarchy of packages, via the use of |
| 291 |
mro: |
| 292 |
|
| 293 |
%subs = find_subs_with_attr( mro::get_linear_isa( $class ), $attrname ); |
| 294 |
|
| 295 |
find_vars_with_attr |
| 296 |
|
| 297 |
%vars = find_vars_with_attr( $pkg, $attrname, %opts ); |
| 298 |
|
| 299 |
Since version 0.11. |
| 300 |
|
| 301 |
A utility function to find SCALAR, ARRAY or HASH references in the |
| 302 |
given package that have the named attribute applied. The symbol table |
| 303 |
is checked for the given package, looking for variable references that |
| 304 |
have the named attribute applied. These are returned in a key-value |
| 305 |
list, where the key gives the name of the variable and the value is a |
| 306 |
reference to it. |
| 307 |
|
| 308 |
Unlike for "find_subs_with_attr", the $pkg argument must be a single |
| 309 |
package name; no subclass search takes place. |
| 310 |
|
| 311 |
Both of the above functions take the following named options: |
| 312 |
|
| 313 |
matching => Regexp | CODE |
| 314 |
|
| 315 |
If present, gives a filter regexp or CODE reference to apply to |
| 316 |
names. Subs will be given as plain names; variable names will include |
| 317 |
the leading sigil. |
| 318 |
|
| 319 |
$name =~ $matching; |
| 320 |
$matching->( local $_ = $name ); |
| 321 |
|
| 322 |
filter => CODE |
| 323 |
|
| 324 |
If present, gives a filter CODE reference to apply to the target |
| 325 |
references before they are accepted as results. Note that this allows |
| 326 |
the possibility that the first match for a given method name to be |
| 327 |
rejected, while later ones are accepted. |
| 328 |
|
| 329 |
$filter->( $ref, $name, $package ); |
| 330 |
|
| 331 |
AUTHOR |
| 332 |
|
| 333 |
Paul Evans <[email protected]> |
| 334 |
|