Debian Codegraph @

upstream/debian-unstable/man3/attributes.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "attributes 3perl"
58 .TH attributes 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 attributes \- get/set subroutine or variable attributes
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 3
68 \& sub foo : method ;
69 \& my ($x,@y,%z) : Bent = 1;
70 \& my $s = sub : method { ... };
71 \&
72 \& use attributes (); # optional, to get subroutine declarations
73 \& my @attrlist = attributes::get(\e&foo);
74 \&
75 \& use attributes \*(Aqget\*(Aq; # import the attributes::get subroutine
76 \& my @attrlist = get \e&foo;
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 Subroutine declarations and definitions may optionally have attribute lists
81 associated with them. (Variable \f(CW\*(C`my\*(C'\fR declarations also may, but see the
82 warning below.) Perl handles these declarations by passing some information
83 about the call site and the thing being declared along with the attribute
84 list to this module. In particular, the first example above is equivalent to
85 the following:
86 .PP
87 .Vb 1
88 \& use attributes _\|_PACKAGE_\|_, \e&foo, \*(Aqmethod\*(Aq;
89 .Ve
90 .PP
91 The second example in the synopsis does something equivalent to this:
92 .PP
93 .Vb 6
94 \& use attributes ();
95 \& my ($x,@y,%z);
96 \& attributes::\->import(_\|_PACKAGE_\|_, \e$x, \*(AqBent\*(Aq);
97 \& attributes::\->import(_\|_PACKAGE_\|_, \e@y, \*(AqBent\*(Aq);
98 \& attributes::\->import(_\|_PACKAGE_\|_, \e%z, \*(AqBent\*(Aq);
99 \& ($x,@y,%z) = 1;
100 .Ve
101 .PP
102 Yes, that's a lot of expansion.
103 .PP
104 \&\fBWARNING\fR: attribute declarations for variables are still evolving.
105 The semantics and interfaces of such declarations could change in
106 future versions. They are present for purposes of experimentation
107 with what the semantics ought to be. Do not rely on the current
108 implementation of this feature.
109 .PP
110 There are only a few attributes currently handled by Perl itself (or
111 directly by this module, depending on how you look at it.) However,
112 package-specific attributes are allowed by an extension mechanism.
113 (See "Package-specific Attribute Handling" below.)
114 .PP
115 The setting of subroutine attributes happens at compile time.
116 Variable attributes in \f(CW\*(C`our\*(C'\fR declarations are also applied at compile time.
117 However, \f(CW\*(C`my\*(C'\fR variables get their attributes applied at run-time.
118 This means that you have to \fIreach\fR the run-time component of the \f(CW\*(C`my\*(C'\fR
119 before those attributes will get applied. For example:
120 .PP
121 .Vb 1
122 \& my $x : Bent = 42 if 0;
123 .Ve
124 .PP
125 will neither assign 42 to \f(CW$x\fR \fInor\fR will it apply the \f(CW\*(C`Bent\*(C'\fR attribute
126 to the variable.
127 .PP
128 An attempt to set an unrecognized attribute is a fatal error. (The
129 error is trappable, but it still stops the compilation within that
130 \&\f(CW\*(C`eval\*(C'\fR.) Setting an attribute with a name that's all lowercase
131 letters that's not a built-in attribute (such as "foo") will result in
132 a warning with \fB\-w\fR or \f(CW\*(C`use warnings \*(Aqreserved\*(Aq\*(C'\fR.
133 .ie n .SS "What ""import"" does"
134 .el .SS "What \f(CWimport\fP does"
135 .IX Subsection "What import does"
136 In the description it is mentioned that
137 .PP
138 .Vb 1
139 \& sub foo : method;
140 .Ve
141 .PP
142 is equivalent to
143 .PP
144 .Vb 1
145 \& use attributes _\|_PACKAGE_\|_, \e&foo, \*(Aqmethod\*(Aq;
146 .Ve
147 .PP
148 As you might know this calls the \f(CW\*(C`import\*(C'\fR function of \f(CW\*(C`attributes\*(C'\fR at compile
149 time with these parameters: 'attributes', the caller's package name, the reference
150 to the code and 'method'.
151 .PP
152 .Vb 1
153 \& attributes\->import( _\|_PACKAGE_\|_, \e&foo, \*(Aqmethod\*(Aq );
154 .Ve
155 .PP
156 So you want to know what \f(CW\*(C`import\*(C'\fR actually does?
157 .PP
158 First of all \f(CW\*(C`import\*(C'\fR gets the type of the third parameter ('CODE' in this case).
159 \&\f(CW\*(C`attributes.pm\*(C'\fR checks if there is a subroutine called \f(CW\*(C`MODIFY_<reftype>_ATTRIBUTES\*(C'\fR
160 in the caller's namespace (here: 'main'). In this case a
161 subroutine \f(CW\*(C`MODIFY_CODE_ATTRIBUTES\*(C'\fR is required. Then this
162 method is called to check if you have used a "bad attribute".
163 The subroutine call in this example would look like
164 .PP
165 .Vb 1
166 \& MODIFY_CODE_ATTRIBUTES( \*(Aqmain\*(Aq, \e&foo, \*(Aqmethod\*(Aq );
167 .Ve
168 .PP
169 \&\f(CW\*(C`MODIFY_<reftype>_ATTRIBUTES\*(C'\fR has to return a list of all "bad attributes".
170 If there are any bad attributes \f(CW\*(C`import\*(C'\fR croaks.
171 .PP
172 (See "Package-specific Attribute Handling" below.)
173 .SS "Built-in Attributes"
174 .IX Subsection "Built-in Attributes"
175 The following are the built-in attributes for subroutines:
176 .IP lvalue 4
177 .IX Item "lvalue"
178 Indicates that the referenced subroutine is a valid lvalue and can
179 be assigned to. The subroutine must return a modifiable value such
180 as a scalar variable, as described in perlsub.
181 .Sp
182 This module allows one to set this attribute on a subroutine that is
183 already defined. For Perl subroutines (XSUBs are fine), it may or may not
184 do what you want, depending on the code inside the subroutine, with details
185 subject to change in future Perl versions. You may run into problems with
186 lvalue context not being propagated properly into the subroutine, or maybe
187 even assertion failures. For this reason, a warning is emitted if warnings
188 are enabled. In other words, you should only do this if you really know
189 what you are doing. You have been warned.
190 .IP method 4
191 .IX Item "method"
192 Indicates that the referenced subroutine
193 is a method. A subroutine so marked
194 will not trigger the "Ambiguous call resolved as CORE::%s" warning.
195 .IP prototype(..) 4
196 .IX Item "prototype(..)"
197 The "prototype" attribute is an alternate means of specifying a prototype
198 on a sub. The desired prototype is within the parens.
199 .Sp
200 The prototype from the attribute is assigned to the sub immediately after
201 the prototype from the sub, which means that if both are declared at the
202 same time, the traditionally defined prototype is ignored. In other words,
203 \&\f(CW\*(C`sub foo($$) : prototype(@) {}\*(C'\fR is indistinguishable from \f(CW\*(C`sub foo(@){}\*(C'\fR.
204 .Sp
205 If illegalproto warnings are enabled, the prototype declared inside this
206 attribute will be sanity checked at compile time.
207 .IP const 4
208 .IX Item "const"
209 This experimental attribute, introduced in Perl 5.22, only applies to
210 anonymous subroutines. It causes the subroutine to be called as soon as
211 the \f(CW\*(C`sub\*(C'\fR expression is evaluated. The return value is captured and
212 turned into a constant subroutine.
213 .PP
214 The following are the built-in attributes for variables:
215 .IP shared 4
216 .IX Item "shared"
217 Indicates that the referenced variable can be shared across different threads
218 when used in conjunction with the threads and threads::shared modules.
219 .SS "Available Subroutines"
220 .IX Subsection "Available Subroutines"
221 The following subroutines are available for general use once this module
222 has been loaded:
223 .IP get 4
224 .IX Item "get"
225 This routine expects a single parameter\-\-a reference to a
226 subroutine or variable. It returns a list of attributes, which may be
227 empty. If passed invalid arguments, it uses \fBdie()\fR (via Carp::croak)
228 to raise a fatal exception. If it can find an appropriate package name
229 for a class method lookup, it will include the results from a
230 \&\f(CW\*(C`FETCH_\fR\f(CItype\fR\f(CW_ATTRIBUTES\*(C'\fR call in its return list, as described in
231 "Package-specific Attribute Handling" below.
232 Otherwise, only built-in attributes will be returned.
233 .IP reftype 4
234 .IX Item "reftype"
235 This routine expects a single parameter\-\-a reference to a subroutine or
236 variable. It returns the built-in type of the referenced variable,
237 ignoring any package into which it might have been blessed.
238 This can be useful for determining the \fItype\fR value which forms part of
239 the method names described in "Package-specific Attribute Handling" below.
240 .PP
241 Note that these routines are \fInot\fR exported by default.
242 .SS "Package-specific Attribute Handling"
243 .IX Subsection "Package-specific Attribute Handling"
244 \&\fBWARNING\fR: the mechanisms described here are still experimental. Do not
245 rely on the current implementation. In particular, there is no provision
246 for applying package attributes to 'cloned' copies of subroutines used as
247 closures. (See "Making References" in perlref for information on closures.)
248 Package-specific attribute handling may change incompatibly in a future
249 release.
250 .PP
251 When an attribute list is present in a declaration, a check is made to see
252 whether an attribute 'modify' handler is present in the appropriate package
253 (or its \f(CW@ISA\fR inheritance tree). Similarly, when \f(CW\*(C`attributes::get\*(C'\fR is
254 called on a valid reference, a check is made for an appropriate attribute
255 \&'fetch' handler. See "EXAMPLES" to see how the "appropriate package"
256 determination works.
257 .PP
258 The handler names are based on the underlying type of the variable being
259 declared or of the reference passed. Because these attributes are
260 associated with subroutine or variable declarations, this deliberately
261 ignores any possibility of being blessed into some package. Thus, a
262 subroutine declaration uses "CODE" as its \fItype\fR, and even a blessed
263 hash reference uses "HASH" as its \fItype\fR.
264 .PP
265 The class methods invoked for modifying and fetching are these:
266 .IP FETCH_\fItype\fR_ATTRIBUTES 4
267 .IX Item "FETCH_type_ATTRIBUTES"
268 This method is called with two arguments: the relevant package name,
269 and a reference to a variable or subroutine for which package-defined
270 attributes are desired. The expected return value is a list of
271 associated attributes. This list may be empty.
272 .IP MODIFY_\fItype\fR_ATTRIBUTES 4
273 .IX Item "MODIFY_type_ATTRIBUTES"
274 This method is called with two fixed arguments, followed by the list of
275 attributes from the relevant declaration. The two fixed arguments are
276 the relevant package name and a reference to the declared subroutine or
277 variable. The expected return value is a list of attributes which were
278 not recognized by this handler. Note that this allows for a derived class
279 to delegate a call to its base class, and then only examine the attributes
280 which the base class didn't already handle for it.
281 .Sp
282 The call to this method is currently made \fIduring\fR the processing of the
283 declaration. In particular, this means that a subroutine reference will
284 probably be for an undefined subroutine, even if this declaration is
285 actually part of the definition.
286 .PP
287 Calling \f(CWattributes::get()\fR from within the scope of a null package
288 declaration \f(CW\*(C`package ;\*(C'\fR for an unblessed variable reference will
289 not provide any starting package name for the 'fetch' method lookup.
290 Thus, this circumstance will not result in a method call for package-defined
291 attributes. A named subroutine knows to which symbol table entry it belongs
292 (or originally belonged), and it will use the corresponding package.
293 An anonymous subroutine knows the package name into which it was compiled
294 (unless it was also compiled with a null package declaration), and so it
295 will use that package name.
296 .SS "Syntax of Attribute Lists"
297 .IX Subsection "Syntax of Attribute Lists"
298 An attribute list is a sequence of attribute specifications, separated by
299 whitespace or a colon (with optional whitespace).
300 Each attribute specification is a simple
301 name, optionally followed by a parenthesised parameter list.
302 If such a parameter list is present, it is scanned past as for the rules
303 for the \f(CWq()\fR operator. (See "Quote and Quote-like Operators" in perlop.)
304 The parameter list is passed as it was found, however, and not as per \f(CWq()\fR.
305 .PP
306 Some examples of syntactically valid attribute lists:
307 .PP
308 .Vb 4
309 \& switch(10,foo(7,3)) : expensive
310 \& Ugly(\*(Aq\e(") :Bad
311 \& _5x5
312 \& lvalue method
313 .Ve
314 .PP
315 Some examples of syntactically invalid attribute lists (with annotation):
316 .PP
317 .Vb 5
318 \& switch(10,foo() # ()\-string not balanced
319 \& Ugly(\*(Aq(\*(Aq) # ()\-string not balanced
320 \& 5x5 # "5x5" not a valid identifier
321 \& Y2::north # "Y2::north" not a simple identifier
322 \& foo + bar # "+" neither a colon nor whitespace
323 .Ve
324 .SH EXPORTS
325 .IX Header "EXPORTS"
326 .SS "Default exports"
327 .IX Subsection "Default exports"
328 None.
329 .SS "Available exports"
330 .IX Subsection "Available exports"
331 The routines \f(CW\*(C`get\*(C'\fR and \f(CW\*(C`reftype\*(C'\fR are exportable.
332 .SS "Export tags defined"
333 .IX Subsection "Export tags defined"
334 The \f(CW\*(C`:ALL\*(C'\fR tag will get all of the above exports.
335 .SH EXAMPLES
336 .IX Header "EXAMPLES"
337 Here are some samples of syntactically valid declarations, with annotation
338 as to how they resolve internally into \f(CW\*(C`use attributes\*(C'\fR invocations by
339 perl. These examples are primarily useful to see how the "appropriate
340 package" is found for the possible method lookups for package-defined
341 attributes.
342 .IP 1. 4
343 Code:
344 .Sp
345 .Vb 3
346 \& package Canine;
347 \& package Dog;
348 \& my Canine $spot : Watchful ;
349 .Ve
350 .Sp
351 Effect:
352 .Sp
353 .Vb 2
354 \& use attributes ();
355 \& attributes::\->import(Canine => \e$spot, "Watchful");
356 .Ve
357 .IP 2. 4
358 Code:
359 .Sp
360 .Vb 2
361 \& package Felis;
362 \& my $cat : Nervous;
363 .Ve
364 .Sp
365 Effect:
366 .Sp
367 .Vb 2
368 \& use attributes ();
369 \& attributes::\->import(Felis => \e$cat, "Nervous");
370 .Ve
371 .IP 3. 4
372 Code:
373 .Sp
374 .Vb 2
375 \& package X;
376 \& sub foo : lvalue ;
377 .Ve
378 .Sp
379 Effect:
380 .Sp
381 .Vb 1
382 \& use attributes X => \e&foo, "lvalue";
383 .Ve
384 .IP 4. 4
385 Code:
386 .Sp
387 .Vb 2
388 \& package X;
389 \& sub Y::x : lvalue { 1 }
390 .Ve
391 .Sp
392 Effect:
393 .Sp
394 .Vb 1
395 \& use attributes Y => \e&Y::x, "lvalue";
396 .Ve
397 .IP 5. 4
398 Code:
399 .Sp
400 .Vb 2
401 \& package X;
402 \& sub foo { 1 }
403 \&
404 \& package Y;
405 \& BEGIN { *bar = \e&X::foo; }
406 \&
407 \& package Z;
408 \& sub Y::bar : lvalue ;
409 .Ve
410 .Sp
411 Effect:
412 .Sp
413 .Vb 1
414 \& use attributes X => \e&X::foo, "lvalue";
415 .Ve
416 .PP
417 This last example is purely for purposes of completeness. You should not
418 be trying to mess with the attributes of something in a package that's
419 not your own.
420 .SH "MORE EXAMPLES"
421 .IX Header "MORE EXAMPLES"
422 .IP 1. 4
423 .Vb 2
424 \& sub MODIFY_CODE_ATTRIBUTES {
425 \& my ($class,$code,@attrs) = @_;
426 \&
427 \& my $allowed = \*(AqMyAttribute\*(Aq;
428 \& my @bad = grep { $_ ne $allowed } @attrs;
429 \&
430 \& return @bad;
431 \& }
432 \&
433 \& sub foo : MyAttribute {
434 \& print "foo\en";
435 \& }
436 .Ve
437 .Sp
438 This example runs. At compile time
439 \&\f(CW\*(C`MODIFY_CODE_ATTRIBUTES\*(C'\fR is called. In that
440 subroutine, we check if any attribute is disallowed and we return a list of
441 these "bad attributes".
442 .Sp
443 As we return an empty list, everything is fine.
444 .IP 2. 4
445 .Vb 2
446 \& sub MODIFY_CODE_ATTRIBUTES {
447 \& my ($class,$code,@attrs) = @_;
448 \&
449 \& my $allowed = \*(AqMyAttribute\*(Aq;
450 \& my @bad = grep{ $_ ne $allowed }@attrs;
451 \&
452 \& return @bad;
453 \& }
454 \&
455 \& sub foo : MyAttribute Test {
456 \& print "foo\en";
457 \& }
458 .Ve
459 .Sp
460 This example is aborted at compile time as we use the attribute "Test" which
461 isn't allowed. \f(CW\*(C`MODIFY_CODE_ATTRIBUTES\*(C'\fR
462 returns a list that contains a single
463 element ('Test').
464 .SH "SEE ALSO"
465 .IX Header "SEE ALSO"
466 "Private Variables via \fBmy()\fR" in perlsub and
467 "Subroutine Attributes" in perlsub for details on the basic declarations;
468 "use" in perlfunc for details on the normal invocation mechanism.