Debian Codegraph @

upstream/mageia-cauldron/man3pm/attributes.3pm

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