5 @EXPORT_OK = qw(get reftype);
7 %EXPORT_TAGS = (ALL => [@EXPORT, @EXPORT_OK]);
22 $deprecated{CODE} = qr/\A-?(locked)\z/;
23 $deprecated{ARRAY} = $deprecated{HASH} = $deprecated{SCALAR}
27 lvalue => 'lvalue attribute applied to already-defined subroutine',
28 -lvalue => 'lvalue attribute removed from already-defined subroutine',
29 const => 'Useless use of attribute "const"',
32 sub _modify_attrs_and_deprecate {
34 # Now that we've removed handling of locked from the XS code, we need to
35 # remove it here, else it ends up in @badattrs. (If we do the deprecation in
36 # XS, we can't control the warning based on *our* caller's lexical settings,
37 # and the warned line is in this package)
39 $deprecated{$svtype} && /$deprecated{$svtype}/ ? do {
41 warnings::warnif('deprecated', "Attribute \"$1\" is deprecated");
43 } : $svtype eq 'CODE' && exists $msg{$_} ? do {
55 @_ > 2 && ref $_[2] or do {
57 goto &Exporter::import;
59 my (undef,$home_stash,$svref,@attrs) = @_;
61 my $svtype = uc reftype($svref);
63 $pkgmeth = UNIVERSAL::can($home_stash, "MODIFY_${svtype}_ATTRIBUTES")
64 if defined $home_stash && $home_stash ne '';
67 my @pkgattrs = _modify_attrs_and_deprecate($svtype, $svref, @attrs);
68 @badattrs = $pkgmeth->($home_stash, $svref, @pkgattrs);
69 if (!@badattrs && @pkgattrs) {
71 return unless warnings::enabled('reserved');
72 @pkgattrs = grep { m/\A[[:lower:]]+(?:\z|\()/ } @pkgattrs;
74 for my $attr (@pkgattrs) {
77 my $s = ((@pkgattrs == 1) ? '' : 's');
78 carp "$svtype package attribute$s " .
79 "may clash with future reserved word$s: " .
80 join(' : ' , @pkgattrs);
85 @badattrs = _modify_attrs_and_deprecate($svtype, $svref, @attrs);
88 croak "Invalid $svtype attribute" .
89 (( @badattrs == 1 ) ? '' : 's') .
91 join(' : ', @badattrs);
96 @_ == 1 && ref $_[0] or
97 croak 'Usage: '.__PACKAGE__.'::get $ref';
99 my $svtype = uc reftype($svref);
100 my $stash = _guess_stash($svref);
101 $stash = caller unless defined $stash;
103 $pkgmeth = UNIVERSAL::can($stash, "FETCH_${svtype}_ATTRIBUTES")
104 if defined $stash && $stash ne '';
106 (_fetch_attrs($svref), $pkgmeth->($stash, $svref)) :
107 (_fetch_attrs($svref))
111 sub require_version { goto &UNIVERSAL::VERSION }
122 attributes - get/set subroutine or variable attributes
127 my ($x,@y,%z) : Bent = 1;
128 my $s = sub : method { ... };
130 use attributes (); # optional, to get subroutine declarations
131 my @attrlist = attributes::get(\&foo);
133 use attributes 'get'; # import the attributes::get subroutine
134 my @attrlist = get \&foo;
138 Subroutine declarations and definitions may optionally have attribute lists
139 associated with them. (Variable C<my> declarations also may, but see the
140 warning below.) Perl handles these declarations by passing some information
141 about the call site and the thing being declared along with the attribute
142 list to this module. In particular, the first example above is equivalent to
145 use attributes __PACKAGE__, \&foo, 'method';
147 The second example in the synopsis does something equivalent to this:
151 attributes::->import(__PACKAGE__, \$x, 'Bent');
152 attributes::->import(__PACKAGE__, \@y, 'Bent');
153 attributes::->import(__PACKAGE__, \%z, 'Bent');
156 Yes, that's a lot of expansion.
158 B<WARNING>: attribute declarations for variables are still evolving.
159 The semantics and interfaces of such declarations could change in
160 future versions. They are present for purposes of experimentation
161 with what the semantics ought to be. Do not rely on the current
162 implementation of this feature.
164 There are only a few attributes currently handled by Perl itself (or
165 directly by this module, depending on how you look at it.) However,
166 package-specific attributes are allowed by an extension mechanism.
167 (See L<"Package-specific Attribute Handling"> below.)
169 The setting of subroutine attributes happens at compile time.
170 Variable attributes in C<our> declarations are also applied at compile time.
171 However, C<my> variables get their attributes applied at run-time.
172 This means that you have to I<reach> the run-time component of the C<my>
173 before those attributes will get applied. For example:
175 my $x : Bent = 42 if 0;
177 will neither assign 42 to $x I<nor> will it apply the C<Bent> attribute
180 An attempt to set an unrecognized attribute is a fatal error. (The
181 error is trappable, but it still stops the compilation within that
182 C<eval>.) Setting an attribute with a name that's all lowercase
183 letters that's not a built-in attribute (such as "foo") will result in
184 a warning with B<-w> or C<use warnings 'reserved'>.
186 =head2 What C<import> does
188 In the description it is mentioned that
194 use attributes __PACKAGE__, \&foo, 'method';
196 As you might know this calls the C<import> function of C<attributes> at compile
197 time with these parameters: 'attributes', the caller's package name, the reference
198 to the code and 'method'.
200 attributes->import( __PACKAGE__, \&foo, 'method' );
202 So you want to know what C<import> actually does?
204 First of all C<import> gets the type of the third parameter ('CODE' in this case).
205 C<attributes.pm> checks if there is a subroutine called C<< MODIFY_<reftype>_ATTRIBUTES >>
206 in the caller's namespace (here: 'main'). In this case a
207 subroutine C<MODIFY_CODE_ATTRIBUTES> is required. Then this
208 method is called to check if you have used a "bad attribute".
209 The subroutine call in this example would look like
211 MODIFY_CODE_ATTRIBUTES( 'main', \&foo, 'method' );
213 C<< MODIFY_<reftype>_ATTRIBUTES >> has to return a list of all "bad attributes".
214 If there are any bad attributes C<import> croaks.
216 (See L<"Package-specific Attribute Handling"> below.)
218 =head2 Built-in Attributes
220 The following are the built-in attributes for subroutines:
226 Indicates that the referenced subroutine is a valid lvalue and can
227 be assigned to. The subroutine must return a modifiable value such
228 as a scalar variable, as described in L<perlsub>.
230 This module allows one to set this attribute on a subroutine that is
231 already defined. For Perl subroutines (XSUBs are fine), it may or may not
232 do what you want, depending on the code inside the subroutine, with details
233 subject to change in future Perl versions. You may run into problems with
234 lvalue context not being propagated properly into the subroutine, or maybe
235 even assertion failures. For this reason, a warning is emitted if warnings
236 are enabled. In other words, you should only do this if you really know
237 what you are doing. You have been warned.
241 Indicates that the referenced subroutine
242 is a method. A subroutine so marked
243 will not trigger the "Ambiguous call resolved as CORE::%s" warning.
247 The "prototype" attribute is an alternate means of specifying a prototype
248 on a sub. The desired prototype is within the parens.
250 The prototype from the attribute is assigned to the sub immediately after
251 the prototype from the sub, which means that if both are declared at the
252 same time, the traditionally defined prototype is ignored. In other words,
253 C<sub foo($$) : prototype(@) {}> is indistinguishable from C<sub foo(@){}>.
255 If illegalproto warnings are enabled, the prototype declared inside this
256 attribute will be sanity checked at compile time.
260 The "locked" attribute is deprecated, and has no effect in 5.10.0 and later.
261 It was used as part of the now-removed "Perl 5.005 threads".
265 This experimental attribute, introduced in Perl 5.22, only applies to
266 anonymous subroutines. It causes the subroutine to be called as soon as
267 the C<sub> expression is evaluated. The return value is captured and
268 turned into a constant subroutine.
272 The following are the built-in attributes for variables:
278 Indicates that the referenced variable can be shared across different threads
279 when used in conjunction with the L<threads> and L<threads::shared> modules.
283 The "unique" attribute is deprecated, and has no effect in 5.10.0 and later.
284 It used to indicate that a single copy of an C<our> variable was to be used by
285 all interpreters should the program happen to be running in a
286 multi-interpreter environment.
290 =head2 Available Subroutines
292 The following subroutines are available for general use once this module
299 This routine expects a single parameter--a reference to a
300 subroutine or variable. It returns a list of attributes, which may be
301 empty. If passed invalid arguments, it uses die() (via L<Carp::croak|Carp>)
302 to raise a fatal exception. If it can find an appropriate package name
303 for a class method lookup, it will include the results from a
304 C<FETCH_I<type>_ATTRIBUTES> call in its return list, as described in
305 L<"Package-specific Attribute Handling"> below.
306 Otherwise, only L<built-in attributes|"Built-in Attributes"> will be returned.
310 This routine expects a single parameter--a reference to a subroutine or
311 variable. It returns the built-in type of the referenced variable,
312 ignoring any package into which it might have been blessed.
313 This can be useful for determining the I<type> value which forms part of
314 the method names described in L<"Package-specific Attribute Handling"> below.
318 Note that these routines are I<not> exported by default.
320 =head2 Package-specific Attribute Handling
322 B<WARNING>: the mechanisms described here are still experimental. Do not
323 rely on the current implementation. In particular, there is no provision
324 for applying package attributes to 'cloned' copies of subroutines used as
325 closures. (See L<perlref/"Making References"> for information on closures.)
326 Package-specific attribute handling may change incompatibly in a future
329 When an attribute list is present in a declaration, a check is made to see
330 whether an attribute 'modify' handler is present in the appropriate package
331 (or its @ISA inheritance tree). Similarly, when C<attributes::get> is
332 called on a valid reference, a check is made for an appropriate attribute
333 'fetch' handler. See L<"EXAMPLES"> to see how the "appropriate package"
336 The handler names are based on the underlying type of the variable being
337 declared or of the reference passed. Because these attributes are
338 associated with subroutine or variable declarations, this deliberately
339 ignores any possibility of being blessed into some package. Thus, a
340 subroutine declaration uses "CODE" as its I<type>, and even a blessed
341 hash reference uses "HASH" as its I<type>.
343 The class methods invoked for modifying and fetching are these:
347 =item FETCH_I<type>_ATTRIBUTES
349 This method is called with two arguments: the relevant package name,
350 and a reference to a variable or subroutine for which package-defined
351 attributes are desired. The expected return value is a list of
352 associated attributes. This list may be empty.
354 =item MODIFY_I<type>_ATTRIBUTES
356 This method is called with two fixed arguments, followed by the list of
357 attributes from the relevant declaration. The two fixed arguments are
358 the relevant package name and a reference to the declared subroutine or
359 variable. The expected return value is a list of attributes which were
360 not recognized by this handler. Note that this allows for a derived class
361 to delegate a call to its base class, and then only examine the attributes
362 which the base class didn't already handle for it.
364 The call to this method is currently made I<during> the processing of the
365 declaration. In particular, this means that a subroutine reference will
366 probably be for an undefined subroutine, even if this declaration is
367 actually part of the definition.
371 Calling C<attributes::get()> from within the scope of a null package
372 declaration C<package ;> for an unblessed variable reference will
373 not provide any starting package name for the 'fetch' method lookup.
374 Thus, this circumstance will not result in a method call for package-defined
375 attributes. A named subroutine knows to which symbol table entry it belongs
376 (or originally belonged), and it will use the corresponding package.
377 An anonymous subroutine knows the package name into which it was compiled
378 (unless it was also compiled with a null package declaration), and so it
379 will use that package name.
381 =head2 Syntax of Attribute Lists
383 An attribute list is a sequence of attribute specifications, separated by
384 whitespace or a colon (with optional whitespace).
385 Each attribute specification is a simple
386 name, optionally followed by a parenthesised parameter list.
387 If such a parameter list is present, it is scanned past as for the rules
388 for the C<q()> operator. (See L<perlop/"Quote and Quote-like Operators">.)
389 The parameter list is passed as it was found, however, and not as per C<q()>.
391 Some examples of syntactically valid attribute lists:
393 switch(10,foo(7,3)) : expensive
398 Some examples of syntactically invalid attribute lists (with annotation):
400 switch(10,foo() # ()-string not balanced
401 Ugly('(') # ()-string not balanced
402 5x5 # "5x5" not a valid identifier
403 Y2::north # "Y2::north" not a simple identifier
404 foo + bar # "+" neither a colon nor whitespace
408 =head2 Default exports
412 =head2 Available exports
414 The routines C<get> and C<reftype> are exportable.
416 =head2 Export tags defined
418 The C<:ALL> tag will get all of the above exports.
422 Here are some samples of syntactically valid declarations, with annotation
423 as to how they resolve internally into C<use attributes> invocations by
424 perl. These examples are primarily useful to see how the "appropriate
425 package" is found for the possible method lookups for package-defined
436 my Canine $spot : Watchful ;
441 attributes::->import(Canine => \$spot, "Watchful");
453 attributes::->import(Felis => \$cat, "Nervous");
464 use attributes X => \&foo, "lvalue";
471 sub Y::x : lvalue { 1 }
475 use attributes Y => \&Y::x, "lvalue";
485 BEGIN { *bar = \&X::foo; }
488 sub Y::bar : lvalue ;
492 use attributes X => \&X::foo, "lvalue";
496 This last example is purely for purposes of completeness. You should not
497 be trying to mess with the attributes of something in a package that's
506 sub MODIFY_CODE_ATTRIBUTES {
507 my ($class,$code,@attrs) = @_;
509 my $allowed = 'MyAttribute';
510 my @bad = grep { $_ ne $allowed } @attrs;
515 sub foo : MyAttribute {
519 This example runs. At compile time
520 C<MODIFY_CODE_ATTRIBUTES> is called. In that
521 subroutine, we check if any attribute is disallowed and we return a list of
522 these "bad attributes".
524 As we return an empty list, everything is fine.
528 sub MODIFY_CODE_ATTRIBUTES {
529 my ($class,$code,@attrs) = @_;
531 my $allowed = 'MyAttribute';
532 my @bad = grep{ $_ ne $allowed }@attrs;
537 sub foo : MyAttribute Test {
541 This example is aborted at compile time as we use the attribute "Test" which
542 isn't allowed. C<MODIFY_CODE_ATTRIBUTES>
543 returns a list that contains a single
550 L<perlsub/"Private Variables via my()"> and
551 L<perlsub/"Subroutine Attributes"> for details on the basic declarations;
552 L<perlfunc/use> for details on the normal invocation mechanism.