1attributes(3pm) Perl Programmers Reference Guide attributes(3pm)
2
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 use attributes (); # optional, to get subroutine declarations
14 my @attrlist = attributes::get(\&foo);
15 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 use attributes __PACKAGE__, \&foo, 'method';
28 The second example in the synopsis does something equivalent to this:
30 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 Yes, that's a lot of expansion.
39 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 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 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 my $x : Bent = 42 if 0;
58 will neither assign 42 to $x nor will it apply the "Bent" attribute to
60 the variable.
61 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 What "import" does
69 In the description it is mentioned that
70 sub foo : method;
72 is equivalent to
74 use attributes __PACKAGE__, \&foo, 'method';
76 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 attributes->import( __PACKAGE__, \&foo, 'method' );
82 So you want to know what "import" actually does?
84 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 MODIFY_CODE_ATTRIBUTES( 'main', \&foo, 'method' );
93 "MODIFY_<reftype>_ATTRIBUTES" has to return a list of all "bad
95 attributes". If there are any bad attributes "import" croaks.
96 (See "Package-specific Attribute Handling" below.)
98 Built-in Attributes
100 The following are the built-in attributes for subroutines:
101 lvalue
103 Indicates that the referenced subroutine is a valid lvalue and can
104 be assigned to. The subroutine must return a modifiable value such
105 as a scalar variable, as described in perlsub.
106 method
108 Indicates that the referenced subroutine is a method. A subroutine
109 so marked will not trigger the "Ambiguous call resolved as
110 CORE::%s" warning.
111 locked
113 The "locked" attribute has no effect in 5.10.0 and later. It was
114 used as part of the now-removed "Perl 5.005 threads".
115 Available Subroutines
117 The following subroutines are available for general use once this
118 module has been loaded:
119 get This routine expects a single parameter--a reference to a
121 subroutine or variable. It returns a list of attributes, which may
122 be empty. If passed invalid arguments, it uses die() (via
123 Carp::croak) to raise a fatal exception. If it can find an
124 appropriate package name for a class method lookup, it will include
125 the results from a "FETCH_type_ATTRIBUTES" call in its return list,
126 as described in "Package-specific Attribute Handling" below.
127 Otherwise, only built-in attributes will be returned.
128 reftype
130 This routine expects a single parameter--a reference to a
131 subroutine or variable. It returns the built-in type of the
132 referenced variable, ignoring any package into which it might have
133 been blessed. This can be useful for determining the type value
134 which forms part of the method names described in "Package-specific
135 Attribute Handling" below.
136 Note that these routines are not exported by default.
138 Package-specific Attribute Handling
140 WARNING: the mechanisms described here are still experimental. Do not
141 rely on the current implementation. In particular, there is no
142 provision for applying package attributes to 'cloned' copies of
143 subroutines used as closures. (See "Making References" in perlref for
144 information on closures.) Package-specific attribute handling may
145 change incompatibly in a future release.
146 When an attribute list is present in a declaration, a check is made to
148 see whether an attribute 'modify' handler is present in the appropriate
149 package (or its @ISA inheritance tree). Similarly, when
150 "attributes::get" is called on a valid reference, a check is made for
151 an appropriate attribute 'fetch' handler. See "EXAMPLES" to see how
152 the "appropriate package" determination works.
153 The handler names are based on the underlying type of the variable
155 being declared or of the reference passed. Because these attributes
156 are associated with subroutine or variable declarations, this
157 deliberately ignores any possibility of being blessed into some
158 package. Thus, a subroutine declaration uses "CODE" as its type, and
159 even a blessed hash reference uses "HASH" as its type.
160 The class methods invoked for modifying and fetching are these:
162 FETCH_type_ATTRIBUTES
164 This method is called with two arguments: the relevant package
165 name, and a reference to a variable or subroutine for which
166 package-defined attributes are desired. The expected return value
167 is a list of associated attributes. This list may be empty.
168 MODIFY_type_ATTRIBUTES
170 This method is called with two fixed arguments, followed by the
171 list of attributes from the relevant declaration. The two fixed
172 arguments are the relevant package name and a reference to the
173 declared subroutine or variable. The expected return value is a
174 list of attributes which were not recognized by this handler. Note
175 that this allows for a derived class to delegate a call to its base
176 class, and then only examine the attributes which the base class
177 didn't already handle for it.
178 The call to this method is currently made during the processing of
180 the declaration. In particular, this means that a subroutine
181 reference will probably be for an undefined subroutine, even if
182 this declaration is actually part of the definition.
183 Calling "attributes::get()" from within the scope of a null package
185 declaration "package ;" for an unblessed variable reference will not
186 provide any starting package name for the 'fetch' method lookup. Thus,
187 this circumstance will not result in a method call for package-defined
188 attributes. A named subroutine knows to which symbol table entry it
189 belongs (or originally belonged), and it will use the corresponding
190 package. An anonymous subroutine knows the package name into which it
191 was compiled (unless it was also compiled with a null package
192 declaration), and so it will use that package name.
193 Syntax of Attribute Lists
195 An attribute list is a sequence of attribute specifications, separated
196 by whitespace or a colon (with optional whitespace). Each attribute
197 specification is a simple name, optionally followed by a parenthesised
198 parameter list. If such a parameter list is present, it is scanned
199 past as for the rules for the "q()" operator. (See "Quote and Quote-
200 like Operators" in perlop.) The parameter list is passed as it was
201 found, however, and not as per "q()".
202 Some examples of syntactically valid attribute lists:
204 switch(10,foo(7,3)) : expensive
206 Ugly('\(") :Bad
207 _5x5
208 lvalue method
209 Some examples of syntactically invalid attribute lists (with
211 annotation):
212 switch(10,foo() # ()-string not balanced
214 Ugly('(') # ()-string not balanced
215 5x5 # "5x5" not a valid identifier
216 Y2::north # "Y2::north" not a simple identifier
217 foo + bar # "+" neither a colon nor whitespace
218
220 Default exports
221 None.
222 Available exports
224 The routines "get" and "reftype" are exportable.
225 Export tags defined
227 The ":ALL" tag will get all of the above exports.
228
230 Here are some samples of syntactically valid declarations, with
231 annotation as to how they resolve internally into "use attributes"
232 invocations by perl. These examples are primarily useful to see how
233 the "appropriate package" is found for the possible method lookups for
234 package-defined attributes.
235 1. Code:
237 package Canine;
239 package Dog;
240 my Canine $spot : Watchful ;
241 Effect:
243 use attributes ();
245 attributes::->import(Canine => \$spot, "Watchful");
246 2. Code:
248 package Felis;
250 my $cat : Nervous;
251 Effect:
253 use attributes ();
255 attributes::->import(Felis => \$cat, "Nervous");
256 3. Code:
258 package X;
260 sub foo : lvalue ;
261 Effect:
263 use attributes X => \&foo, "lvalue";
265 4. Code:
267 package X;
269 sub Y::x : lvalue { 1 }
270 Effect:
272 use attributes Y => \&Y::x, "lvalue";
274 5. Code:
276 package X;
278 sub foo { 1 }
279 package Y;
281 BEGIN { *bar = \&X::foo; }
282 package Z;
284 sub Y::bar : lvalue ;
285 Effect:
287 use attributes X => \&X::foo, "lvalue";
289 This last example is purely for purposes of completeness. You should
291 not be trying to mess with the attributes of something in a package
292 that's not your own.
293
295 1.
296 sub MODIFY_CODE_ATTRIBUTES {
297 my ($class,$code,@attrs) = @_;
298 my $allowed = 'MyAttribute';
300 my @bad = grep { $_ ne $allowed } @attrs;
301 return @bad;
303 }
304 sub foo : MyAttribute {
306 print "foo\n";
307 }
308 This example runs. At compile time "MODIFY_CODE_ATTRIBUTES" is
310 called. In that subroutine, we check if any attribute is disallowed
311 and we return a list of these "bad attributes".
312 As we return an empty list, everything is fine.
314 2.
316 sub MODIFY_CODE_ATTRIBUTES {
317 my ($class,$code,@attrs) = @_;
318 my $allowed = 'MyAttribute';
320 my @bad = grep{ $_ ne $allowed }@attrs;
321 return @bad;
323 }
324 sub foo : MyAttribute Test {
326 print "foo\n";
327 }
328 This example is aborted at compile time as we use the attribute
330 "Test" which isn't allowed. "MODIFY_CODE_ATTRIBUTES" returns a list
331 that contains a single element ('Test').
332
334 "Private Variables via my()" in perlsub and "Subroutine Attributes" in
335 perlsub for details on the basic declarations; "use" in perlfunc for
336 details on the normal invocation mechanism.
337perl v5.12.4 2011-06-07 attributes(3pm)