Debian Codegraph @

README

raw
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