Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "Attribute::Handlers 3" | |
132 | .TH Attribute::Handlers 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | Attribute::Handlers \- Simpler definition of attribute handlers | |
135 | .SH "VERSION" | |
136 | .IX Header "VERSION" | |
137 | This document describes version 0.78 of Attribute::Handlers, | |
138 | released October 5, 2002. | |
139 | .SH "SYNOPSIS" | |
140 | .IX Header "SYNOPSIS" | |
141 | .Vb 4 | |
142 | \& package MyClass; | |
143 | \& require v5.6.0; | |
144 | \& use Attribute::Handlers; | |
145 | \& no warnings 'redefine'; | |
146 | .Ve | |
147 | .PP | |
148 | .Vb 2 | |
149 | \& sub Good : ATTR(SCALAR) { | |
150 | \& my ($package, $symbol, $referent, $attr, $data) = @_; | |
151 | .Ve | |
152 | .PP | |
153 | .Vb 3 | |
154 | \& # Invoked for any scalar variable with a :Good attribute, | |
155 | \& # provided the variable was declared in MyClass (or | |
156 | \& # a derived class) or typed to MyClass. | |
157 | .Ve | |
158 | .PP | |
159 | .Vb 3 | |
160 | \& # Do whatever to $referent here (executed in CHECK phase). | |
161 | \& ... | |
162 | \& } | |
163 | .Ve | |
164 | .PP | |
165 | .Vb 6 | |
166 | \& sub Bad : ATTR(SCALAR) { | |
167 | \& # Invoked for any scalar variable with a :Bad attribute, | |
168 | \& # provided the variable was declared in MyClass (or | |
169 | \& # a derived class) or typed to MyClass. | |
170 | \& ... | |
171 | \& } | |
172 | .Ve | |
173 | .PP | |
174 | .Vb 6 | |
175 | \& sub Good : ATTR(ARRAY) { | |
176 | \& # Invoked for any array variable with a :Good attribute, | |
177 | \& # provided the variable was declared in MyClass (or | |
178 | \& # a derived class) or typed to MyClass. | |
179 | \& ... | |
180 | \& } | |
181 | .Ve | |
182 | .PP | |
183 | .Vb 6 | |
184 | \& sub Good : ATTR(HASH) { | |
185 | \& # Invoked for any hash variable with a :Good attribute, | |
186 | \& # provided the variable was declared in MyClass (or | |
187 | \& # a derived class) or typed to MyClass. | |
188 | \& ... | |
189 | \& } | |
190 | .Ve | |
191 | .PP | |
192 | .Vb 5 | |
193 | \& sub Ugly : ATTR(CODE) { | |
194 | \& # Invoked for any subroutine declared in MyClass (or a | |
195 | \& # derived class) with an :Ugly attribute. | |
196 | \& ... | |
197 | \& } | |
198 | .Ve | |
199 | .PP | |
200 | .Vb 8 | |
201 | \& sub Omni : ATTR { | |
202 | \& # Invoked for any scalar, array, hash, or subroutine | |
203 | \& # with an :Omni attribute, provided the variable or | |
204 | \& # subroutine was declared in MyClass (or a derived class) | |
205 | \& # or the variable was typed to MyClass. | |
206 | \& # Use ref($_[2]) to determine what kind of referent it was. | |
207 | \& ... | |
208 | \& } | |
209 | .Ve | |
210 | .PP | |
211 | .Vb 1 | |
212 | \& use Attribute::Handlers autotie => { Cycle => Tie::Cycle }; | |
213 | .Ve | |
214 | .PP | |
215 | .Vb 1 | |
216 | \& my $next : Cycle(['A'..'Z']); | |
217 | .Ve | |
218 | .SH "DESCRIPTION" | |
219 | .IX Header "DESCRIPTION" | |
220 | This module, when inherited by a package, allows that package's class to | |
221 | define attribute handler subroutines for specific attributes. Variables | |
222 | and subroutines subsequently defined in that package, or in packages | |
223 | derived from that package may be given attributes with the same names as | |
224 | the attribute handler subroutines, which will then be called in one of | |
225 | the compilation phases (i.e. in a \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`CHECK\*(C'\fR, \f(CW\*(C`INIT\*(C'\fR, or \f(CW\*(C`END\*(C'\fR | |
226 | block). | |
227 | .PP | |
228 | To create a handler, define it as a subroutine with the same name as | |
229 | the desired attribute, and declare the subroutine itself with the | |
230 | attribute \f(CW\*(C`:ATTR\*(C'\fR. For example: | |
231 | .PP | |
232 | .Vb 2 | |
233 | \& package LoudDecl; | |
234 | \& use Attribute::Handlers; | |
235 | .Ve | |
236 | .PP | |
237 | .Vb 10 | |
238 | \& sub Loud :ATTR { | |
239 | \& my ($package, $symbol, $referent, $attr, $data, $phase) = @_; | |
240 | \& print STDERR | |
241 | \& ref($referent), " ", | |
242 | \& *{$symbol}{NAME}, " ", | |
243 | \& "($referent) ", "was just declared ", | |
244 | \& "and ascribed the ${attr} attribute ", | |
245 | \& "with data ($data)\en", | |
246 | \& "in phase $phase\en"; | |
247 | \& } | |
248 | .Ve | |
249 | .PP | |
250 | This creates a handler for the attribute \f(CW\*(C`:Loud\*(C'\fR in the class LoudDecl. | |
251 | Thereafter, any subroutine declared with a \f(CW\*(C`:Loud\*(C'\fR attribute in the class | |
252 | LoudDecl: | |
253 | .PP | |
254 | .Vb 1 | |
255 | \& package LoudDecl; | |
256 | .Ve | |
257 | .PP | |
258 | .Vb 1 | |
259 | \& sub foo: Loud {...} | |
260 | .Ve | |
261 | .PP | |
262 | causes the above handler to be invoked, and passed: | |
263 | .IP "[0]" 4 | |
264 | .IX Item "[0]" | |
265 | the name of the package into which it was declared; | |
266 | .IP "[1]" 4 | |
267 | .IX Item "[1]" | |
268 | a reference to the symbol table entry (typeglob) containing the subroutine; | |
269 | .IP "[2]" 4 | |
270 | .IX Item "[2]" | |
271 | a reference to the subroutine; | |
272 | .IP "[3]" 4 | |
273 | .IX Item "[3]" | |
274 | the name of the attribute; | |
275 | .IP "[4]" 4 | |
276 | .IX Item "[4]" | |
277 | any data associated with that attribute; | |
278 | .IP "[5]" 4 | |
279 | .IX Item "[5]" | |
280 | the name of the phase in which the handler is being invoked. | |
281 | .PP | |
282 | Likewise, declaring any variables with the \f(CW\*(C`:Loud\*(C'\fR attribute within the | |
283 | package: | |
284 | .PP | |
285 | .Vb 1 | |
286 | \& package LoudDecl; | |
287 | .Ve | |
288 | .PP | |
289 | .Vb 3 | |
290 | \& my $foo :Loud; | |
291 | \& my @foo :Loud; | |
292 | \& my %foo :Loud; | |
293 | .Ve | |
294 | .PP | |
295 | will cause the handler to be called with a similar argument list (except, | |
296 | of course, that \f(CW$_[2]\fR will be a reference to the variable). | |
297 | .PP | |
298 | The package name argument will typically be the name of the class into | |
299 | which the subroutine was declared, but it may also be the name of a derived | |
300 | class (since handlers are inherited). | |
301 | .PP | |
302 | If a lexical variable is given an attribute, there is no symbol table to | |
303 | which it belongs, so the symbol table argument (\f(CW$_[1]\fR) is set to the | |
304 | string \f(CW'LEXICAL'\fR in that case. Likewise, ascribing an attribute to | |
305 | an anonymous subroutine results in a symbol table argument of \f(CW'ANON'\fR. | |
306 | .PP | |
307 | The data argument passes in the value (if any) associated with the | |
308 | attribute. For example, if \f(CW&foo\fR had been declared: | |
309 | .PP | |
310 | .Vb 1 | |
311 | \& sub foo :Loud("turn it up to 11, man!") {...} | |
312 | .Ve | |
313 | .PP | |
314 | then the string \f(CW"turn it up to 11, man!"\fR would be passed as the | |
315 | last argument. | |
316 | .PP | |
317 | Attribute::Handlers makes strenuous efforts to convert | |
318 | the data argument (\f(CW$_[4]\fR) to a useable form before passing it to | |
319 | the handler (but see \*(L"Non\-interpretive attribute handlers\*(R"). | |
320 | For example, all of these: | |
321 | .PP | |
322 | .Vb 5 | |
323 | \& sub foo :Loud(till=>ears=>are=>bleeding) {...} | |
324 | \& sub foo :Loud(['till','ears','are','bleeding']) {...} | |
325 | \& sub foo :Loud(qw/till ears are bleeding/) {...} | |
326 | \& sub foo :Loud(qw/my, ears, are, bleeding/) {...} | |
327 | \& sub foo :Loud(till,ears,are,bleeding) {...} | |
328 | .Ve | |
329 | .PP | |
330 | causes it to pass \f(CW\*(C`['till','ears','are','bleeding']\*(C'\fR as the handler's | |
331 | data argument. However, if the data can't be parsed as valid Perl, then | |
332 | it is passed as an uninterpreted string. For example: | |
333 | .PP | |
334 | .Vb 2 | |
335 | \& sub foo :Loud(my,ears,are,bleeding) {...} | |
336 | \& sub foo :Loud(qw/my ears are bleeding) {...} | |
337 | .Ve | |
338 | .PP | |
339 | cause the strings \f(CW'my,ears,are,bleeding'\fR and \f(CW'qw/my ears are bleeding'\fR | |
340 | respectively to be passed as the data argument. | |
341 | .PP | |
342 | If the attribute has only a single associated scalar data value, that value is | |
343 | passed as a scalar. If multiple values are associated, they are passed as an | |
344 | array reference. If no value is associated with the attribute, \f(CW\*(C`undef\*(C'\fR is | |
345 | passed. | |
346 | .Sh "Typed lexicals" | |
347 | .IX Subsection "Typed lexicals" | |
348 | Regardless of the package in which it is declared, if a lexical variable is | |
349 | ascribed an attribute, the handler that is invoked is the one belonging to | |
350 | the package to which it is typed. For example, the following declarations: | |
351 | .PP | |
352 | .Vb 1 | |
353 | \& package OtherClass; | |
354 | .Ve | |
355 | .PP | |
356 | .Vb 3 | |
357 | \& my LoudDecl $loudobj : Loud; | |
358 | \& my LoudDecl @loudobjs : Loud; | |
359 | \& my LoudDecl %loudobjex : Loud; | |
360 | .Ve | |
361 | .PP | |
362 | causes the LoudDecl::Loud handler to be invoked (even if OtherClass also | |
363 | defines a handler for \f(CW\*(C`:Loud\*(C'\fR attributes). | |
364 | .Sh "Type-specific attribute handlers" | |
365 | .IX Subsection "Type-specific attribute handlers" | |
366 | If an attribute handler is declared and the \f(CW\*(C`:ATTR\*(C'\fR specifier is | |
367 | given the name of a built-in type (\f(CW\*(C`SCALAR\*(C'\fR, \f(CW\*(C`ARRAY\*(C'\fR, \f(CW\*(C`HASH\*(C'\fR, or \f(CW\*(C`CODE\*(C'\fR), | |
368 | the handler is only applied to declarations of that type. For example, | |
369 | the following definition: | |
370 | .PP | |
371 | .Vb 1 | |
372 | \& package LoudDecl; | |
373 | .Ve | |
374 | .PP | |
375 | .Vb 1 | |
376 | \& sub RealLoud :ATTR(SCALAR) { print "Yeeeeow!" } | |
377 | .Ve | |
378 | .PP | |
379 | creates an attribute handler that applies only to scalars: | |
380 | .PP | |
381 | .Vb 2 | |
382 | \& package Painful; | |
383 | \& use base LoudDecl; | |
384 | .Ve | |
385 | .PP | |
386 | .Vb 4 | |
387 | \& my $metal : RealLoud; # invokes &LoudDecl::RealLoud | |
388 | \& my @metal : RealLoud; # error: unknown attribute | |
389 | \& my %metal : RealLoud; # error: unknown attribute | |
390 | \& sub metal : RealLoud {...} # error: unknown attribute | |
391 | .Ve | |
392 | .PP | |
393 | You can, of course, declare separate handlers for these types as well | |
394 | (but you'll need to specify \f(CW\*(C`no warnings 'redefine'\*(C'\fR to do it quietly): | |
395 | .PP | |
396 | .Vb 3 | |
397 | \& package LoudDecl; | |
398 | \& use Attribute::Handlers; | |
399 | \& no warnings 'redefine'; | |
400 | .Ve | |
401 | .PP | |
402 | .Vb 4 | |
403 | \& sub RealLoud :ATTR(SCALAR) { print "Yeeeeow!" } | |
404 | \& sub RealLoud :ATTR(ARRAY) { print "Urrrrrrrrrr!" } | |
405 | \& sub RealLoud :ATTR(HASH) { print "Arrrrrgggghhhhhh!" } | |
406 | \& sub RealLoud :ATTR(CODE) { croak "Real loud sub torpedoed" } | |
407 | .Ve | |
408 | .PP | |
409 | You can also explicitly indicate that a single handler is meant to be | |
410 | used for all types of referents like so: | |
411 | .PP | |
412 | .Vb 2 | |
413 | \& package LoudDecl; | |
414 | \& use Attribute::Handlers; | |
415 | .Ve | |
416 | .PP | |
417 | .Vb 1 | |
418 | \& sub SeriousLoud :ATTR(ANY) { warn "Hearing loss imminent" } | |
419 | .Ve | |
420 | .PP | |
421 | (I.e. \f(CW\*(C`ATTR(ANY)\*(C'\fR is a synonym for \f(CW\*(C`:ATTR\*(C'\fR). | |
422 | .Sh "Non-interpretive attribute handlers" | |
423 | .IX Subsection "Non-interpretive attribute handlers" | |
424 | Occasionally the strenuous efforts Attribute::Handlers makes to convert | |
425 | the data argument (\f(CW$_[4]\fR) to a useable form before passing it to | |
426 | the handler get in the way. | |
427 | .PP | |
428 | You can turn off that eagerness-to-help by declaring | |
429 | an attribute handler with the keyword \f(CW\*(C`RAWDATA\*(C'\fR. For example: | |
430 | .PP | |
431 | .Vb 3 | |
432 | \& sub Raw : ATTR(RAWDATA) {...} | |
433 | \& sub Nekkid : ATTR(SCALAR,RAWDATA) {...} | |
434 | \& sub Au::Naturale : ATTR(RAWDATA,ANY) {...} | |
435 | .Ve | |
436 | .PP | |
437 | Then the handler makes absolutely no attempt to interpret the data it | |
438 | receives and simply passes it as a string: | |
439 | .PP | |
440 | .Vb 1 | |
441 | \& my $power : Raw(1..100); # handlers receives "1..100" | |
442 | .Ve | |
443 | .Sh "Phase-specific attribute handlers" | |
444 | .IX Subsection "Phase-specific attribute handlers" | |
445 | By default, attribute handlers are called at the end of the compilation | |
446 | phase (in a \f(CW\*(C`CHECK\*(C'\fR block). This seems to be optimal in most cases because | |
447 | most things that can be defined are defined by that point but nothing has | |
448 | been executed. | |
449 | .PP | |
450 | However, it is possible to set up attribute handlers that are called at | |
451 | other points in the program's compilation or execution, by explicitly | |
452 | stating the phase (or phases) in which you wish the attribute handler to | |
453 | be called. For example: | |
454 | .PP | |
455 | .Vb 5 | |
456 | \& sub Early :ATTR(SCALAR,BEGIN) {...} | |
457 | \& sub Normal :ATTR(SCALAR,CHECK) {...} | |
458 | \& sub Late :ATTR(SCALAR,INIT) {...} | |
459 | \& sub Final :ATTR(SCALAR,END) {...} | |
460 | \& sub Bookends :ATTR(SCALAR,BEGIN,END) {...} | |
461 | .Ve | |
462 | .PP | |
463 | As the last example indicates, a handler may be set up to be (re)called in | |
464 | two or more phases. The phase name is passed as the handler's final argument. | |
465 | .PP | |
466 | Note that attribute handlers that are scheduled for the \f(CW\*(C`BEGIN\*(C'\fR phase | |
467 | are handled as soon as the attribute is detected (i.e. before any | |
468 | subsequently defined \f(CW\*(C`BEGIN\*(C'\fR blocks are executed). | |
469 | .ie n .Sh "Attributes as ""tie"" interfaces" | |
470 | .el .Sh "Attributes as \f(CWtie\fP interfaces" | |
471 | .IX Subsection "Attributes as tie interfaces" | |
472 | Attributes make an excellent and intuitive interface through which to tie | |
473 | variables. For example: | |
474 | .PP | |
475 | .Vb 2 | |
476 | \& use Attribute::Handlers; | |
477 | \& use Tie::Cycle; | |
478 | .Ve | |
479 | .PP | |
480 | .Vb 5 | |
481 | \& sub UNIVERSAL::Cycle : ATTR(SCALAR) { | |
482 | \& my ($package, $symbol, $referent, $attr, $data, $phase) = @_; | |
483 | \& $data = [ $data ] unless ref $data eq 'ARRAY'; | |
484 | \& tie $$referent, 'Tie::Cycle', $data; | |
485 | \& } | |
486 | .Ve | |
487 | .PP | |
488 | .Vb 1 | |
489 | \& # and thereafter... | |
490 | .Ve | |
491 | .PP | |
492 | .Vb 1 | |
493 | \& package main; | |
494 | .Ve | |
495 | .PP | |
496 | .Vb 1 | |
497 | \& my $next : Cycle('A'..'Z'); # $next is now a tied variable | |
498 | .Ve | |
499 | .PP | |
500 | .Vb 3 | |
501 | \& while (<>) { | |
502 | \& print $next; | |
503 | \& } | |
504 | .Ve | |
505 | .PP | |
506 | Note that, because the \f(CW\*(C`Cycle\*(C'\fR attribute receives its arguments in the | |
507 | \&\f(CW$data\fR variable, if the attribute is given a list of arguments, \f(CW$data\fR | |
508 | will consist of a single array reference; otherwise, it will consist of the | |
509 | single argument directly. Since Tie::Cycle requires its cycling values to | |
510 | be passed as an array reference, this means that we need to wrap | |
511 | non-array-reference arguments in an array constructor: | |
512 | .PP | |
513 | .Vb 1 | |
514 | \& $data = [ $data ] unless ref $data eq 'ARRAY'; | |
515 | .Ve | |
516 | .PP | |
517 | Typically, however, things are the other way around: the tieable class expects | |
518 | its arguments as a flattened list, so the attribute looks like: | |
519 | .PP | |
520 | .Vb 5 | |
521 | \& sub UNIVERSAL::Cycle : ATTR(SCALAR) { | |
522 | \& my ($package, $symbol, $referent, $attr, $data, $phase) = @_; | |
523 | \& my @data = ref $data eq 'ARRAY' ? @$data : $data; | |
524 | \& tie $$referent, 'Tie::Whatever', @data; | |
525 | \& } | |
526 | .Ve | |
527 | .PP | |
528 | This software pattern is so widely applicable that Attribute::Handlers | |
529 | provides a way to automate it: specifying \f(CW'autotie'\fR in the | |
530 | \&\f(CW\*(C`use Attribute::Handlers\*(C'\fR statement. So, the cycling example, | |
531 | could also be written: | |
532 | .PP | |
533 | .Vb 1 | |
534 | \& use Attribute::Handlers autotie => { Cycle => 'Tie::Cycle' }; | |
535 | .Ve | |
536 | .PP | |
537 | .Vb 1 | |
538 | \& # and thereafter... | |
539 | .Ve | |
540 | .PP | |
541 | .Vb 1 | |
542 | \& package main; | |
543 | .Ve | |
544 | .PP | |
545 | .Vb 1 | |
546 | \& my $next : Cycle(['A'..'Z']); # $next is now a tied variable | |
547 | .Ve | |
548 | .PP | |
549 | .Vb 2 | |
550 | \& while (<>) { | |
551 | \& print $next; | |
552 | .Ve | |
553 | .PP | |
554 | Note that we now have to pass the cycling values as an array reference, | |
555 | since the \f(CW\*(C`autotie\*(C'\fR mechanism passes \f(CW\*(C`tie\*(C'\fR a list of arguments as a list | |
556 | (as in the Tie::Whatever example), \fInot\fR as an array reference (as in | |
557 | the original Tie::Cycle example at the start of this section). | |
558 | .PP | |
559 | The argument after \f(CW'autotie'\fR is a reference to a hash in which each key is | |
560 | the name of an attribute to be created, and each value is the class to which | |
561 | variables ascribed that attribute should be tied. | |
562 | .PP | |
563 | Note that there is no longer any need to import the Tie::Cycle module \*(-- | |
564 | Attribute::Handlers takes care of that automagically. You can even pass | |
565 | arguments to the module's \f(CW\*(C`import\*(C'\fR subroutine, by appending them to the | |
566 | class name. For example: | |
567 | .PP | |
568 | .Vb 2 | |
569 | \& use Attribute::Handlers | |
570 | \& autotie => { Dir => 'Tie::Dir qw(DIR_UNLINK)' }; | |
571 | .Ve | |
572 | .PP | |
573 | If the attribute name is unqualified, the attribute is installed in the | |
574 | current package. Otherwise it is installed in the qualifier's package: | |
575 | .PP | |
576 | .Vb 1 | |
577 | \& package Here; | |
578 | .Ve | |
579 | .PP | |
580 | .Vb 5 | |
581 | \& use Attribute::Handlers autotie => { | |
582 | \& Other::Good => Tie::SecureHash, # tie attr installed in Other:: | |
583 | \& Bad => Tie::Taxes, # tie attr installed in Here:: | |
584 | \& UNIVERSAL::Ugly => Software::Patent # tie attr installed everywhere | |
585 | \& }; | |
586 | .Ve | |
587 | .PP | |
588 | Autoties are most commonly used in the module to which they actually tie, | |
589 | and need to export their attributes to any module that calls them. To | |
590 | facilitate this, Attribute::Handlers recognizes a special \*(L"pseudo\-class\*(R" \*(-- | |
591 | \&\f(CW\*(C`_\|_CALLER_\|_\*(C'\fR, which may be specified as the qualifier of an attribute: | |
592 | .PP | |
593 | .Vb 1 | |
594 | \& package Tie::Me::Kangaroo:Down::Sport; | |
595 | .Ve | |
596 | .PP | |
597 | .Vb 1 | |
598 | \& use Attribute::Handlers autotie => { '__CALLER__::Roo' => __PACKAGE__ }; | |
599 | .Ve | |
600 | .PP | |
601 | This causes Attribute::Handlers to define the \f(CW\*(C`Roo\*(C'\fR attribute in the package | |
602 | that imports the Tie::Me::Kangaroo:Down::Sport module. | |
603 | .PP | |
604 | Note that it is important to quote the _\|_CALLER_\|_::Roo identifier because | |
605 | a bug in perl 5.8 will refuse to parse it and cause an unknown error. | |
606 | .PP | |
607 | \fIPassing the tied object to \f(CI\*(C`tie\*(C'\fI\fR | |
608 | .IX Subsection "Passing the tied object to tie" | |
609 | .PP | |
610 | Occasionally it is important to pass a reference to the object being tied | |
611 | to the \s-1TIESCALAR\s0, \s-1TIEHASH\s0, etc. that ties it. | |
612 | .PP | |
613 | The \f(CW\*(C`autotie\*(C'\fR mechanism supports this too. The following code: | |
614 | .PP | |
615 | .Vb 2 | |
616 | \& use Attribute::Handlers autotieref => { Selfish => Tie::Selfish }; | |
617 | \& my $var : Selfish(@args); | |
618 | .Ve | |
619 | .PP | |
620 | has the same effect as: | |
621 | .PP | |
622 | .Vb 1 | |
623 | \& tie my $var, 'Tie::Selfish', @args; | |
624 | .Ve | |
625 | .PP | |
626 | But when \f(CW"autotieref"\fR is used instead of \f(CW"autotie"\fR: | |
627 | .PP | |
628 | .Vb 2 | |
629 | \& use Attribute::Handlers autotieref => { Selfish => Tie::Selfish }; | |
630 | \& my $var : Selfish(@args); | |
631 | .Ve | |
632 | .PP | |
633 | the effect is to pass the \f(CW\*(C`tie\*(C'\fR call an extra reference to the variable | |
634 | being tied: | |
635 | .PP | |
636 | .Vb 1 | |
637 | \& tie my $var, 'Tie::Selfish', \e$var, @args; | |
638 | .Ve | |
639 | .SH "EXAMPLES" | |
640 | .IX Header "EXAMPLES" | |
641 | If the class shown in \s-1SYNOPSIS\s0 were placed in the MyClass.pm | |
642 | module, then the following code: | |
643 | .PP | |
644 | .Vb 2 | |
645 | \& package main; | |
646 | \& use MyClass; | |
647 | .Ve | |
648 | .PP | |
649 | .Vb 1 | |
650 | \& my MyClass $slr :Good :Bad(1**1-1) :Omni(-vorous); | |
651 | .Ve | |
652 | .PP | |
653 | .Vb 2 | |
654 | \& package SomeOtherClass; | |
655 | \& use base MyClass; | |
656 | .Ve | |
657 | .PP | |
658 | .Vb 1 | |
659 | \& sub tent { 'acle' } | |
660 | .Ve | |
661 | .PP | |
662 | .Vb 3 | |
663 | \& sub fn :Ugly(sister) :Omni('po',tent()) {...} | |
664 | \& my @arr :Good :Omni(s/cie/nt/); | |
665 | \& my %hsh :Good(q/bye) :Omni(q/bus/); | |
666 | .Ve | |
667 | .PP | |
668 | would cause the following handlers to be invoked: | |
669 | .PP | |
670 | .Vb 1 | |
671 | \& # my MyClass $slr :Good :Bad(1**1-1) :Omni(-vorous); | |
672 | .Ve | |
673 | .PP | |
674 | .Vb 7 | |
675 | \& MyClass::Good:ATTR(SCALAR)( 'MyClass', # class | |
676 | \& 'LEXICAL', # no typeglob | |
677 | \& \e$slr, # referent | |
678 | \& 'Good', # attr name | |
679 | \& undef # no attr data | |
680 | \& 'CHECK', # compiler phase | |
681 | \& ); | |
682 | .Ve | |
683 | .PP | |
684 | .Vb 7 | |
685 | \& MyClass::Bad:ATTR(SCALAR)( 'MyClass', # class | |
686 | \& 'LEXICAL', # no typeglob | |
687 | \& \e$slr, # referent | |
688 | \& 'Bad', # attr name | |
689 | \& 0 # eval'd attr data | |
690 | \& 'CHECK', # compiler phase | |
691 | \& ); | |
692 | .Ve | |
693 | .PP | |
694 | .Vb 7 | |
695 | \& MyClass::Omni:ATTR(SCALAR)( 'MyClass', # class | |
696 | \& 'LEXICAL', # no typeglob | |
697 | \& \e$slr, # referent | |
698 | \& 'Omni', # attr name | |
699 | \& '-vorous' # eval'd attr data | |
700 | \& 'CHECK', # compiler phase | |
701 | \& ); | |
702 | .Ve | |
703 | .PP | |
704 | .Vb 1 | |
705 | \& # sub fn :Ugly(sister) :Omni('po',tent()) {...} | |
706 | .Ve | |
707 | .PP | |
708 | .Vb 7 | |
709 | \& MyClass::UGLY:ATTR(CODE)( 'SomeOtherClass', # class | |
710 | \& \e*SomeOtherClass::fn, # typeglob | |
711 | \& \e&SomeOtherClass::fn, # referent | |
712 | \& 'Ugly', # attr name | |
713 | \& 'sister' # eval'd attr data | |
714 | \& 'CHECK', # compiler phase | |
715 | \& ); | |
716 | .Ve | |
717 | .PP | |
718 | .Vb 7 | |
719 | \& MyClass::Omni:ATTR(CODE)( 'SomeOtherClass', # class | |
720 | \& \e*SomeOtherClass::fn, # typeglob | |
721 | \& \e&SomeOtherClass::fn, # referent | |
722 | \& 'Omni', # attr name | |
723 | \& ['po','acle'] # eval'd attr data | |
724 | \& 'CHECK', # compiler phase | |
725 | \& ); | |
726 | .Ve | |
727 | .PP | |
728 | .Vb 1 | |
729 | \& # my @arr :Good :Omni(s/cie/nt/); | |
730 | .Ve | |
731 | .PP | |
732 | .Vb 7 | |
733 | \& MyClass::Good:ATTR(ARRAY)( 'SomeOtherClass', # class | |
734 | \& 'LEXICAL', # no typeglob | |
735 | \& \e@arr, # referent | |
736 | \& 'Good', # attr name | |
737 | \& undef # no attr data | |
738 | \& 'CHECK', # compiler phase | |
739 | \& ); | |
740 | .Ve | |
741 | .PP | |
742 | .Vb 7 | |
743 | \& MyClass::Omni:ATTR(ARRAY)( 'SomeOtherClass', # class | |
744 | \& 'LEXICAL', # no typeglob | |
745 | \& \e@arr, # referent | |
746 | \& 'Omni', # attr name | |
747 | \& "" # eval'd attr data | |
748 | \& 'CHECK', # compiler phase | |
749 | \& ); | |
750 | .Ve | |
751 | .PP | |
752 | .Vb 1 | |
753 | \& # my %hsh :Good(q/bye) :Omni(q/bus/); | |
754 | .Ve | |
755 | .PP | |
756 | .Vb 7 | |
757 | \& MyClass::Good:ATTR(HASH)( 'SomeOtherClass', # class | |
758 | \& 'LEXICAL', # no typeglob | |
759 | \& \e%hsh, # referent | |
760 | \& 'Good', # attr name | |
761 | \& 'q/bye' # raw attr data | |
762 | \& 'CHECK', # compiler phase | |
763 | \& ); | |
764 | .Ve | |
765 | .PP | |
766 | .Vb 7 | |
767 | \& MyClass::Omni:ATTR(HASH)( 'SomeOtherClass', # class | |
768 | \& 'LEXICAL', # no typeglob | |
769 | \& \e%hsh, # referent | |
770 | \& 'Omni', # attr name | |
771 | \& 'bus' # eval'd attr data | |
772 | \& 'CHECK', # compiler phase | |
773 | \& ); | |
774 | .Ve | |
775 | .PP | |
776 | Installing handlers into \s-1UNIVERSAL\s0, makes them...err..universal. | |
777 | For example: | |
778 | .PP | |
779 | .Vb 2 | |
780 | \& package Descriptions; | |
781 | \& use Attribute::Handlers; | |
782 | .Ve | |
783 | .PP | |
784 | .Vb 2 | |
785 | \& my %name; | |
786 | \& sub name { return $name{$_[2]}||*{$_[1]}{NAME} } | |
787 | .Ve | |
788 | .PP | |
789 | .Vb 3 | |
790 | \& sub UNIVERSAL::Name :ATTR { | |
791 | \& $name{$_[2]} = $_[4]; | |
792 | \& } | |
793 | .Ve | |
794 | .PP | |
795 | .Vb 3 | |
796 | \& sub UNIVERSAL::Purpose :ATTR { | |
797 | \& print STDERR "Purpose of ", &name, " is $_[4]\en"; | |
798 | \& } | |
799 | .Ve | |
800 | .PP | |
801 | .Vb 3 | |
802 | \& sub UNIVERSAL::Unit :ATTR { | |
803 | \& print STDERR &name, " measured in $_[4]\en"; | |
804 | \& } | |
805 | .Ve | |
806 | .PP | |
807 | Let's you write: | |
808 | .PP | |
809 | .Vb 1 | |
810 | \& use Descriptions; | |
811 | .Ve | |
812 | .PP | |
813 | .Vb 3 | |
814 | \& my $capacity : Name(capacity) | |
815 | \& : Purpose(to store max storage capacity for files) | |
816 | \& : Unit(Gb); | |
817 | .Ve | |
818 | .PP | |
819 | .Vb 1 | |
820 | \& package Other; | |
821 | .Ve | |
822 | .PP | |
823 | .Vb 1 | |
824 | \& sub foo : Purpose(to foo all data before barring it) { } | |
825 | .Ve | |
826 | .PP | |
827 | .Vb 1 | |
828 | \& # etc. | |
829 | .Ve | |
830 | .SH "DIAGNOSTICS" | |
831 | .IX Header "DIAGNOSTICS" | |
832 | .ie n .IP """Bad attribute type: ATTR(%s)""" 4 | |
833 | .el .IP "\f(CWBad attribute type: ATTR(%s)\fR" 4 | |
834 | .IX Item "Bad attribute type: ATTR(%s)" | |
835 | An attribute handler was specified with an \f(CW\*(C`:ATTR(\f(CIref_type\f(CW)\*(C'\fR, but the | |
836 | type of referent it was defined to handle wasn't one of the five permitted: | |
837 | \&\f(CW\*(C`SCALAR\*(C'\fR, \f(CW\*(C`ARRAY\*(C'\fR, \f(CW\*(C`HASH\*(C'\fR, \f(CW\*(C`CODE\*(C'\fR, or \f(CW\*(C`ANY\*(C'\fR. | |
838 | .ie n .IP """Attribute handler %s doesn't handle %s attributes""" 4 | |
839 | .el .IP "\f(CWAttribute handler %s doesn't handle %s attributes\fR" 4 | |
840 | .IX Item "Attribute handler %s doesn't handle %s attributes" | |
841 | A handler for attributes of the specified name \fIwas\fR defined, but not | |
842 | for the specified type of declaration. Typically encountered whe trying | |
843 | to apply a \f(CW\*(C`VAR\*(C'\fR attribute handler to a subroutine, or a \f(CW\*(C`SCALAR\*(C'\fR | |
844 | attribute handler to some other type of variable. | |
845 | .ie n .IP """Declaration of %s attribute in package %s may clash with future reserved word""" 4 | |
846 | .el .IP "\f(CWDeclaration of %s attribute in package %s may clash with future reserved word\fR" 4 | |
847 | .IX Item "Declaration of %s attribute in package %s may clash with future reserved word" | |
848 | A handler for an attributes with an all-lowercase name was declared. An | |
849 | attribute with an all-lowercase name might have a meaning to Perl | |
850 | itself some day, even though most don't yet. Use a mixed-case attribute | |
851 | name, instead. | |
852 | .ie n .IP """Can't have two ATTR specifiers on one subroutine""" 4 | |
853 | .el .IP "\f(CWCan't have two ATTR specifiers on one subroutine\fR" 4 | |
854 | .IX Item "Can't have two ATTR specifiers on one subroutine" | |
855 | You just can't, okay? | |
856 | Instead, put all the specifications together with commas between them | |
857 | in a single \f(CW\*(C`ATTR(\f(CIspecification\f(CW)\*(C'\fR. | |
858 | .ie n .IP """Can't autotie a %s""" 4 | |
859 | .el .IP "\f(CWCan't autotie a %s\fR" 4 | |
860 | .IX Item "Can't autotie a %s" | |
861 | You can only declare autoties for types \f(CW"SCALAR"\fR, \f(CW"ARRAY"\fR, and | |
862 | \&\f(CW"HASH"\fR. They're the only things (apart from typeglobs \*(-- which are | |
863 | not declarable) that Perl can tie. | |
864 | .ie n .IP """Internal error: %s symbol went missing""" 4 | |
865 | .el .IP "\f(CWInternal error: %s symbol went missing\fR" 4 | |
866 | .IX Item "Internal error: %s symbol went missing" | |
867 | Something is rotten in the state of the program. An attributed | |
868 | subroutine ceased to exist between the point it was declared and the point | |
869 | at which its attribute handler(s) would have been called. | |
870 | .ie n .IP """Won't be able to apply END handler""" 4 | |
871 | .el .IP "\f(CWWon't be able to apply END handler\fR" 4 | |
872 | .IX Item "Won't be able to apply END handler" | |
873 | You have defined an \s-1END\s0 handler for an attribute that is being applied | |
874 | to a lexical variable. Since the variable may not be available during \s-1END\s0 | |
875 | this won't happen. | |
876 | .SH "AUTHOR" | |
877 | .IX Header "AUTHOR" | |
878 | Damian Conway (damian@conway.org) | |
879 | .SH "BUGS" | |
880 | .IX Header "BUGS" | |
881 | There are undoubtedly serious bugs lurking somewhere in code this funky :\-) | |
882 | Bug reports and other feedback are most welcome. | |
883 | .SH "COPYRIGHT" | |
884 | .IX Header "COPYRIGHT" | |
885 | .Vb 3 | |
886 | \& Copyright (c) 2001, Damian Conway. All Rights Reserved. | |
887 | \& This module is free software. It may be used, redistributed | |
888 | \& and/or modified under the same terms as Perl itself. | |
889 | .Ve |