1attributes(3pm) Perl Programmers Reference Guide attributes(3pm)
2
3
4
6 attributes - get/set subroutine or variable attributes
7
9 sub foo : method ;
10 my ($x,@y,%z) : Bent = 1;
11 my $s = sub : method { ... };
12
13 use attributes (); # optional, to get subroutine declarations
14 my @attrlist = attributes::get(\&foo);
15
16 use attributes 'get'; # import the attributes::get subroutine
17 my @attrlist = get \&foo;
18
20 Subroutine declarations and definitions may optionally have attribute
21 lists associated with them. (Variable "my" declarations also may, but
22 see the warning below.) Perl handles these declarations by passing
23 some information about the call site and the thing being declared along
24 with the attribute list to this module. In particular, the first
25 example above is equivalent to the following:
26
27 use attributes __PACKAGE__, \&foo, 'method';
28
29 The second example in the synopsis does something equivalent to this:
30
31 use attributes ();
32 my ($x,@y,%z);
33 attributes::->import(__PACKAGE__, \$x, 'Bent');
34 attributes::->import(__PACKAGE__, \@y, 'Bent');
35 attributes::->import(__PACKAGE__, \%z, 'Bent');
36 ($x,@y,%z) = 1;
37
38 Yes, that's a lot of expansion.
39
40 WARNING: attribute declarations for variables are still evolving. The
41 semantics and interfaces of such declarations could change in future
42 versions. They are present for purposes of experimentation with what
43 the semantics ought to be. Do not rely on the current implementation
44 of this feature.
45
46 There are only a few attributes currently handled by Perl itself (or
47 directly by this module, depending on how you look at it.) However,
48 package-specific attributes are allowed by an extension mechanism.
49 (See "Package-specific Attribute Handling" below.)
50
51 The setting of subroutine attributes happens at compile time. Variable
52 attributes in "our" declarations are also applied at compile time.
53 However, "my" variables get their attributes applied at run-time. This
54 means that you have to reach the run-time component of the "my" before
55 those attributes will get applied. For example:
56
57 my $x : Bent = 42 if 0;
58
59 will neither assign 42 to $x nor will it apply the "Bent" attribute to
60 the variable.
61
62 An attempt to set an unrecognized attribute is a fatal error. (The
63 error is trappable, but it still stops the compilation within that
64 "eval".) Setting an attribute with a name that's all lowercase letters
65 that's not a built-in attribute (such as "foo") will result in a
66 warning with -w or "use warnings 'reserved'".
67
68 What "import" does
69 In the description it is mentioned that
70
71 sub foo : method;
72
73 is equivalent to
74
75 use attributes __PACKAGE__, \&foo, 'method';
76
77 As you might know this calls the "import" function of "attributes" at
78 compile time with these parameters: 'attributes', the caller's package
79 name, the reference to the code and 'method'.
80
81 attributes->import( __PACKAGE__, \&foo, 'method' );
82
83 So you want to know what "import" actually does?
84
85 First of all "import" gets the type of the third parameter ('CODE' in
86 this case). "attributes.pm" checks if there is a subroutine called
87 "MODIFY_<reftype>_ATTRIBUTES" in the caller's namespace (here: 'main').
88 In this case a subroutine "MODIFY_CODE_ATTRIBUTES" is required. Then
89 this method is called to check if you have used a "bad attribute". The
90 subroutine call in this example would look like
91
92 MODIFY_CODE_ATTRIBUTES( 'main', \&foo, 'method' );
93
94 "MODIFY_<reftype>_ATTRIBUTES" has to return a list of all "bad
95 attributes". If there are any bad attributes "import" croaks.
96
97 (See "Package-specific Attribute Handling" below.)
98
99 Built-in Attributes
100 The following are the built-in attributes for subroutines:
101
102 locked
103 5.005 threads only! The use of the "locked" attribute currently
104 only makes sense if you are using the deprecated "Perl 5.005
105 threads" implementation of threads.
106
107 Setting this attribute is only meaningful when the subroutine or
108 method is to be called by multiple threads. When set on a method
109 subroutine (i.e., one marked with the method attribute below), Perl
110 ensures that any invocation of it implicitly locks its first
111 argument before execution. When set on a non-method subroutine,
112 Perl ensures that a lock is taken on the subroutine itself before
113 execution. The semantics of the lock are exactly those of one
114 explicitly taken with the "lock" operator immediately after the
115 subroutine is entered.
116
117 method
118 Indicates that the referenced subroutine is a method. This has a
119 meaning when taken together with the locked attribute, as described
120 there. It also means that a subroutine so marked will not trigger
121 the "Ambiguous call resolved as CORE::%s" warning.
122
123 lvalue
124 Indicates that the referenced subroutine is a valid lvalue and can
125 be assigned to. The subroutine must return a modifiable value such
126 as a scalar variable, as described in perlsub.
127
128 For global variables there is "unique" attribute: see "our" in
129 perlfunc.
130
131 Available Subroutines
132 The following subroutines are available for general use once this
133 module has been loaded:
134
135 get This routine expects a single parameter--a reference to a
136 subroutine or variable. It returns a list of attributes, which may
137 be empty. If passed invalid arguments, it uses die() (via
138 Carp::croak) to raise a fatal exception. If it can find an
139 appropriate package name for a class method lookup, it will include
140 the results from a "FETCH_type_ATTRIBUTES" call in its return list,
141 as described in "Package-specific Attribute Handling" below.
142 Otherwise, only built-in attributes will be returned.
143
144 reftype
145 This routine expects a single parameter--a reference to a
146 subroutine or variable. It returns the built-in type of the
147 referenced variable, ignoring any package into which it might have
148 been blessed. This can be useful for determining the type value
149 which forms part of the method names described in "Package-specific
150 Attribute Handling" below.
151
152 Note that these routines are not exported by default.
153
154 Package-specific Attribute Handling
155 WARNING: the mechanisms described here are still experimental. Do not
156 rely on the current implementation. In particular, there is no
157 provision for applying package attributes to 'cloned' copies of
158 subroutines used as closures. (See "Making References" in perlref for
159 information on closures.) Package-specific attribute handling may
160 change incompatibly in a future release.
161
162 When an attribute list is present in a declaration, a check is made to
163 see whether an attribute 'modify' handler is present in the appropriate
164 package (or its @ISA inheritance tree). Similarly, when
165 "attributes::get" is called on a valid reference, a check is made for
166 an appropriate attribute 'fetch' handler. See "EXAMPLES" to see how
167 the "appropriate package" determination works.
168
169 The handler names are based on the underlying type of the variable
170 being declared or of the reference passed. Because these attributes
171 are associated with subroutine or variable declarations, this
172 deliberately ignores any possibility of being blessed into some
173 package. Thus, a subroutine declaration uses "CODE" as its type, and
174 even a blessed hash reference uses "HASH" as its type.
175
176 The class methods invoked for modifying and fetching are these:
177
178 FETCH_type_ATTRIBUTES
179 This method is called with two arguments: the relevant package
180 name, and a reference to a variable or subroutine for which
181 package-defined attributes are desired. The expected return value
182 is a list of associated attributes. This list may be empty.
183
184 MODIFY_type_ATTRIBUTES
185 This method is called with two fixed arguments, followed by the
186 list of attributes from the relevant declaration. The two fixed
187 arguments are the relevant package name and a reference to the
188 declared subroutine or variable. The expected return value is a
189 list of attributes which were not recognized by this handler. Note
190 that this allows for a derived class to delegate a call to its base
191 class, and then only examine the attributes which the base class
192 didn't already handle for it.
193
194 The call to this method is currently made during the processing of
195 the declaration. In particular, this means that a subroutine
196 reference will probably be for an undefined subroutine, even if
197 this declaration is actually part of the definition.
198
199 Calling "attributes::get()" from within the scope of a null package
200 declaration "package ;" for an unblessed variable reference will not
201 provide any starting package name for the 'fetch' method lookup. Thus,
202 this circumstance will not result in a method call for package-defined
203 attributes. A named subroutine knows to which symbol table entry it
204 belongs (or originally belonged), and it will use the corresponding
205 package. An anonymous subroutine knows the package name into which it
206 was compiled (unless it was also compiled with a null package
207 declaration), and so it will use that package name.
208
209 Syntax of Attribute Lists
210 An attribute list is a sequence of attribute specifications, separated
211 by whitespace or a colon (with optional whitespace). Each attribute
212 specification is a simple name, optionally followed by a parenthesised
213 parameter list. If such a parameter list is present, it is scanned
214 past as for the rules for the "q()" operator. (See "Quote and Quote-
215 like Operators" in perlop.) The parameter list is passed as it was
216 found, however, and not as per "q()".
217
218 Some examples of syntactically valid attribute lists:
219
220 switch(10,foo(7,3)) : expensive
221 Ugly('\(") :Bad
222 _5x5
223 locked method
224
225 Some examples of syntactically invalid attribute lists (with
226 annotation):
227
228 switch(10,foo() # ()-string not balanced
229 Ugly('(') # ()-string not balanced
230 5x5 # "5x5" not a valid identifier
231 Y2::north # "Y2::north" not a simple identifier
232 foo + bar # "+" neither a colon nor whitespace
233
235 Default exports
236 None.
237
238 Available exports
239 The routines "get" and "reftype" are exportable.
240
241 Export tags defined
242 The ":ALL" tag will get all of the above exports.
243
245 Here are some samples of syntactically valid declarations, with
246 annotation as to how they resolve internally into "use attributes"
247 invocations by perl. These examples are primarily useful to see how
248 the "appropriate package" is found for the possible method lookups for
249 package-defined attributes.
250
251 1. Code:
252
253 package Canine;
254 package Dog;
255 my Canine $spot : Watchful ;
256
257 Effect:
258
259 use attributes ();
260 attributes::->import(Canine => \$spot, "Watchful");
261
262 2. Code:
263
264 package Felis;
265 my $cat : Nervous;
266
267 Effect:
268
269 use attributes ();
270 attributes::->import(Felis => \$cat, "Nervous");
271
272 3. Code:
273
274 package X;
275 sub foo : locked ;
276
277 Effect:
278
279 use attributes X => \&foo, "locked";
280
281 4. Code:
282
283 package X;
284 sub Y::x : locked { 1 }
285
286 Effect:
287
288 use attributes Y => \&Y::x, "locked";
289
290 5. Code:
291
292 package X;
293 sub foo { 1 }
294
295 package Y;
296 BEGIN { *bar = \&X::foo; }
297
298 package Z;
299 sub Y::bar : locked ;
300
301 Effect:
302
303 use attributes X => \&X::foo, "locked";
304
305 This last example is purely for purposes of completeness. You should
306 not be trying to mess with the attributes of something in a package
307 that's not your own.
308
310 1.
311 sub MODIFY_CODE_ATTRIBUTES {
312 my ($class,$code,@attrs) = @_;
313
314 my $allowed = 'MyAttribute';
315 my @bad = grep { $_ ne $allowed } @attrs;
316
317 return @bad;
318 }
319
320 sub foo : MyAttribute {
321 print "foo\n";
322 }
323
324 This example runs. At compile time "MODIFY_CODE_ATTRIBUTES" is
325 called. In that subroutine, we check if any attribute is disallowed
326 and we return a list of these "bad attributes".
327
328 As we return an empty list, everything is fine.
329
330 2.
331 sub MODIFY_CODE_ATTRIBUTES {
332 my ($class,$code,@attrs) = @_;
333
334 my $allowed = 'MyAttribute';
335 my @bad = grep{ $_ ne $allowed }@attrs;
336
337 return @bad;
338 }
339
340 sub foo : MyAttribute Test {
341 print "foo\n";
342 }
343
344 This example is aborted at compile time as we use the attribute
345 "Test" which isn't allowed. "MODIFY_CODE_ATTRIBUTES" returns a list
346 that contains a single element ('Test').
347
349 "Private Variables via my()" in perlsub and "Subroutine Attributes" in
350 perlsub for details on the basic declarations; attrs for the
351 obsolescent form of subroutine attribute specification which this
352 module replaces; "use" in perlfunc for details on the normal invocation
353 mechanism.
354
355
356
357perl v5.10.1 2009-04-22 attributes(3pm)