| 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 "Attribute::Handlers 3perl" |
| 58 |
.TH Attribute::Handlers 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 |
Attribute::Handlers \- Simpler definition of attribute handlers |
| 65 |
.SH VERSION |
| 66 |
.IX Header "VERSION" |
| 67 |
This document describes version 1.03 of Attribute::Handlers. |
| 68 |
.SH SYNOPSIS |
| 69 |
.IX Header "SYNOPSIS" |
| 70 |
.Vb 4 |
| 71 |
\& package MyClass; |
| 72 |
\& require 5.006; |
| 73 |
\& use Attribute::Handlers; |
| 74 |
\& no warnings \*(Aqredefine\*(Aq; |
| 75 |
\& |
| 76 |
\& |
| 77 |
\& sub Good : ATTR(SCALAR) { |
| 78 |
\& my ($package, $symbol, $referent, $attr, $data) = @_; |
| 79 |
\& |
| 80 |
\& # Invoked for any scalar variable with a :Good attribute, |
| 81 |
\& # provided the variable was declared in MyClass (or |
| 82 |
\& # a derived class) or typed to MyClass. |
| 83 |
\& |
| 84 |
\& # Do whatever to $referent here (executed in CHECK phase). |
| 85 |
\& ... |
| 86 |
\& } |
| 87 |
\& |
| 88 |
\& sub Bad : ATTR(SCALAR) { |
| 89 |
\& # Invoked for any scalar variable with a :Bad attribute, |
| 90 |
\& # provided the variable was declared in MyClass (or |
| 91 |
\& # a derived class) or typed to MyClass. |
| 92 |
\& ... |
| 93 |
\& } |
| 94 |
\& |
| 95 |
\& sub Good : ATTR(ARRAY) { |
| 96 |
\& # Invoked for any array variable with a :Good attribute, |
| 97 |
\& # provided the variable was declared in MyClass (or |
| 98 |
\& # a derived class) or typed to MyClass. |
| 99 |
\& ... |
| 100 |
\& } |
| 101 |
\& |
| 102 |
\& sub Good : ATTR(HASH) { |
| 103 |
\& # Invoked for any hash variable with a :Good attribute, |
| 104 |
\& # provided the variable was declared in MyClass (or |
| 105 |
\& # a derived class) or typed to MyClass. |
| 106 |
\& ... |
| 107 |
\& } |
| 108 |
\& |
| 109 |
\& sub Ugly : ATTR(CODE) { |
| 110 |
\& # Invoked for any subroutine declared in MyClass (or a |
| 111 |
\& # derived class) with an :Ugly attribute. |
| 112 |
\& ... |
| 113 |
\& } |
| 114 |
\& |
| 115 |
\& sub Omni : ATTR { |
| 116 |
\& # Invoked for any scalar, array, hash, or subroutine |
| 117 |
\& # with an :Omni attribute, provided the variable or |
| 118 |
\& # subroutine was declared in MyClass (or a derived class) |
| 119 |
\& # or the variable was typed to MyClass. |
| 120 |
\& # Use ref($_[2]) to determine what kind of referent it was. |
| 121 |
\& ... |
| 122 |
\& } |
| 123 |
\& |
| 124 |
\& |
| 125 |
\& use Attribute::Handlers autotie => { Cycle => Tie::Cycle }; |
| 126 |
\& |
| 127 |
\& my $next : Cycle([\*(AqA\*(Aq..\*(AqZ\*(Aq]); |
| 128 |
.Ve |
| 129 |
.SH DESCRIPTION |
| 130 |
.IX Header "DESCRIPTION" |
| 131 |
This module, when inherited by a package, allows that package's class to |
| 132 |
define attribute handler subroutines for specific attributes. Variables |
| 133 |
and subroutines subsequently defined in that package, or in packages |
| 134 |
derived from that package may be given attributes with the same names as |
| 135 |
the attribute handler subroutines, which will then be called in one of |
| 136 |
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 |
| 137 |
block). (\f(CW\*(C`UNITCHECK\*(C'\fR blocks don't correspond to a global compilation |
| 138 |
phase, so they can't be specified here.) |
| 139 |
.PP |
| 140 |
To create a handler, define it as a subroutine with the same name as |
| 141 |
the desired attribute, and declare the subroutine itself with the |
| 142 |
attribute \f(CW\*(C`:ATTR\*(C'\fR. For example: |
| 143 |
.PP |
| 144 |
.Vb 2 |
| 145 |
\& package LoudDecl; |
| 146 |
\& use Attribute::Handlers; |
| 147 |
\& |
| 148 |
\& sub Loud :ATTR { |
| 149 |
\& my ($package, $symbol, $referent, $attr, $data, $phase, |
| 150 |
\& $filename, $linenum) = @_; |
| 151 |
\& print STDERR |
| 152 |
\& ref($referent), " ", |
| 153 |
\& *{$symbol}{NAME}, " ", |
| 154 |
\& "($referent) ", "was just declared ", |
| 155 |
\& "and ascribed the ${attr} attribute ", |
| 156 |
\& "with data ($data)\en", |
| 157 |
\& "in phase $phase\en", |
| 158 |
\& "in file $filename at line $linenum\en"; |
| 159 |
\& } |
| 160 |
.Ve |
| 161 |
.PP |
| 162 |
This creates a handler for the attribute \f(CW\*(C`:Loud\*(C'\fR in the class LoudDecl. |
| 163 |
Thereafter, any subroutine declared with a \f(CW\*(C`:Loud\*(C'\fR attribute in the class |
| 164 |
LoudDecl: |
| 165 |
.PP |
| 166 |
.Vb 1 |
| 167 |
\& package LoudDecl; |
| 168 |
\& |
| 169 |
\& sub foo: Loud {...} |
| 170 |
.Ve |
| 171 |
.PP |
| 172 |
causes the above handler to be invoked, and passed: |
| 173 |
.IP [0] 4 |
| 174 |
.IX Item "[0]" |
| 175 |
the name of the package into which it was declared; |
| 176 |
.IP [1] 4 |
| 177 |
.IX Item "[1]" |
| 178 |
a reference to the symbol table entry (typeglob) containing the subroutine; |
| 179 |
.IP [2] 4 |
| 180 |
.IX Item "[2]" |
| 181 |
a reference to the subroutine; |
| 182 |
.IP [3] 4 |
| 183 |
.IX Item "[3]" |
| 184 |
the name of the attribute; |
| 185 |
.IP [4] 4 |
| 186 |
.IX Item "[4]" |
| 187 |
any data associated with that attribute; |
| 188 |
.IP [5] 4 |
| 189 |
.IX Item "[5]" |
| 190 |
the name of the phase in which the handler is being invoked; |
| 191 |
.IP [6] 4 |
| 192 |
.IX Item "[6]" |
| 193 |
the filename in which the handler is being invoked; |
| 194 |
.IP [7] 4 |
| 195 |
.IX Item "[7]" |
| 196 |
the line number in this file. |
| 197 |
.PP |
| 198 |
Likewise, declaring any variables with the \f(CW\*(C`:Loud\*(C'\fR attribute within the |
| 199 |
package: |
| 200 |
.PP |
| 201 |
.Vb 1 |
| 202 |
\& package LoudDecl; |
| 203 |
\& |
| 204 |
\& my $foo :Loud; |
| 205 |
\& my @foo :Loud; |
| 206 |
\& my %foo :Loud; |
| 207 |
.Ve |
| 208 |
.PP |
| 209 |
will cause the handler to be called with a similar argument list (except, |
| 210 |
of course, that \f(CW$_[2]\fR will be a reference to the variable). |
| 211 |
.PP |
| 212 |
The package name argument will typically be the name of the class into |
| 213 |
which the subroutine was declared, but it may also be the name of a derived |
| 214 |
class (since handlers are inherited). |
| 215 |
.PP |
| 216 |
If a lexical variable is given an attribute, there is no symbol table to |
| 217 |
which it belongs, so the symbol table argument (\f(CW$_[1]\fR) is set to the |
| 218 |
string \f(CW\*(AqLEXICAL\*(Aq\fR in that case. Likewise, ascribing an attribute to |
| 219 |
an anonymous subroutine results in a symbol table argument of \f(CW\*(AqANON\*(Aq\fR. |
| 220 |
.PP |
| 221 |
The data argument passes in the value (if any) associated with the |
| 222 |
attribute. For example, if \f(CW&foo\fR had been declared: |
| 223 |
.PP |
| 224 |
.Vb 1 |
| 225 |
\& sub foo :Loud("turn it up to 11, man!") {...} |
| 226 |
.Ve |
| 227 |
.PP |
| 228 |
then a reference to an array containing the string |
| 229 |
\&\f(CW"turn it up to 11, man!"\fR would be passed as the last argument. |
| 230 |
.PP |
| 231 |
Attribute::Handlers makes strenuous efforts to convert |
| 232 |
the data argument (\f(CW$_[4]\fR) to a usable form before passing it to |
| 233 |
the handler (but see "Non-interpretive attribute handlers"). |
| 234 |
If those efforts succeed, the interpreted data is passed in an array |
| 235 |
reference; if they fail, the raw data is passed as a string. |
| 236 |
For example, all of these: |
| 237 |
.PP |
| 238 |
.Vb 4 |
| 239 |
\& sub foo :Loud(till=>ears=>are=>bleeding) {...} |
| 240 |
\& sub foo :Loud(qw/till ears are bleeding/) {...} |
| 241 |
\& sub foo :Loud(qw/till, ears, are, bleeding/) {...} |
| 242 |
\& sub foo :Loud(till,ears,are,bleeding) {...} |
| 243 |
.Ve |
| 244 |
.PP |
| 245 |
causes it to pass \f(CW\*(C`[\*(Aqtill\*(Aq,\*(Aqears\*(Aq,\*(Aqare\*(Aq,\*(Aqbleeding\*(Aq]\*(C'\fR as the handler's |
| 246 |
data argument. While: |
| 247 |
.PP |
| 248 |
.Vb 1 |
| 249 |
\& sub foo :Loud([\*(Aqtill\*(Aq,\*(Aqears\*(Aq,\*(Aqare\*(Aq,\*(Aqbleeding\*(Aq]) {...} |
| 250 |
.Ve |
| 251 |
.PP |
| 252 |
causes it to pass \f(CW\*(C`[ [\*(Aqtill\*(Aq,\*(Aqears\*(Aq,\*(Aqare\*(Aq,\*(Aqbleeding\*(Aq] ]\*(C'\fR; the array |
| 253 |
reference specified in the data being passed inside the standard |
| 254 |
array reference indicating successful interpretation. |
| 255 |
.PP |
| 256 |
However, if the data can't be parsed as valid Perl, then |
| 257 |
it is passed as an uninterpreted string. For example: |
| 258 |
.PP |
| 259 |
.Vb 2 |
| 260 |
\& sub foo :Loud(my,ears,are,bleeding) {...} |
| 261 |
\& sub foo :Loud(qw/my ears are bleeding) {...} |
| 262 |
.Ve |
| 263 |
.PP |
| 264 |
cause the strings \f(CW\*(Aqmy,ears,are,bleeding\*(Aq\fR and |
| 265 |
\&\f(CW\*(Aqqw/my ears are bleeding\*(Aq\fR respectively to be passed as the |
| 266 |
data argument. |
| 267 |
.PP |
| 268 |
If no value is associated with the attribute, \f(CW\*(C`undef\*(C'\fR is passed. |
| 269 |
.SS "Typed lexicals" |
| 270 |
.IX Subsection "Typed lexicals" |
| 271 |
Regardless of the package in which it is declared, if a lexical variable is |
| 272 |
ascribed an attribute, the handler that is invoked is the one belonging to |
| 273 |
the package to which it is typed. For example, the following declarations: |
| 274 |
.PP |
| 275 |
.Vb 1 |
| 276 |
\& package OtherClass; |
| 277 |
\& |
| 278 |
\& my LoudDecl $loudobj : Loud; |
| 279 |
\& my LoudDecl @loudobjs : Loud; |
| 280 |
\& my LoudDecl %loudobjex : Loud; |
| 281 |
.Ve |
| 282 |
.PP |
| 283 |
causes the LoudDecl::Loud handler to be invoked (even if OtherClass also |
| 284 |
defines a handler for \f(CW\*(C`:Loud\*(C'\fR attributes). |
| 285 |
.SS "Type-specific attribute handlers" |
| 286 |
.IX Subsection "Type-specific attribute handlers" |
| 287 |
If an attribute handler is declared and the \f(CW\*(C`:ATTR\*(C'\fR specifier is |
| 288 |
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), |
| 289 |
the handler is only applied to declarations of that type. For example, |
| 290 |
the following definition: |
| 291 |
.PP |
| 292 |
.Vb 1 |
| 293 |
\& package LoudDecl; |
| 294 |
\& |
| 295 |
\& sub RealLoud :ATTR(SCALAR) { print "Yeeeeow!" } |
| 296 |
.Ve |
| 297 |
.PP |
| 298 |
creates an attribute handler that applies only to scalars: |
| 299 |
.PP |
| 300 |
.Vb 2 |
| 301 |
\& package Painful; |
| 302 |
\& use base LoudDecl; |
| 303 |
\& |
| 304 |
\& my $metal : RealLoud; # invokes &LoudDecl::RealLoud |
| 305 |
\& my @metal : RealLoud; # error: unknown attribute |
| 306 |
\& my %metal : RealLoud; # error: unknown attribute |
| 307 |
\& sub metal : RealLoud {...} # error: unknown attribute |
| 308 |
.Ve |
| 309 |
.PP |
| 310 |
You can, of course, declare separate handlers for these types as well |
| 311 |
(but you'll need to specify \f(CW\*(C`no warnings \*(Aqredefine\*(Aq\*(C'\fR to do it quietly): |
| 312 |
.PP |
| 313 |
.Vb 3 |
| 314 |
\& package LoudDecl; |
| 315 |
\& use Attribute::Handlers; |
| 316 |
\& no warnings \*(Aqredefine\*(Aq; |
| 317 |
\& |
| 318 |
\& sub RealLoud :ATTR(SCALAR) { print "Yeeeeow!" } |
| 319 |
\& sub RealLoud :ATTR(ARRAY) { print "Urrrrrrrrrr!" } |
| 320 |
\& sub RealLoud :ATTR(HASH) { print "Arrrrrgggghhhhhh!" } |
| 321 |
\& sub RealLoud :ATTR(CODE) { croak "Real loud sub torpedoed" } |
| 322 |
.Ve |
| 323 |
.PP |
| 324 |
You can also explicitly indicate that a single handler is meant to be |
| 325 |
used for all types of referents like so: |
| 326 |
.PP |
| 327 |
.Vb 2 |
| 328 |
\& package LoudDecl; |
| 329 |
\& use Attribute::Handlers; |
| 330 |
\& |
| 331 |
\& sub SeriousLoud :ATTR(ANY) { warn "Hearing loss imminent" } |
| 332 |
.Ve |
| 333 |
.PP |
| 334 |
(I.e. \f(CWATTR(ANY)\fR is a synonym for \f(CW\*(C`:ATTR\*(C'\fR). |
| 335 |
.SS "Non-interpretive attribute handlers" |
| 336 |
.IX Subsection "Non-interpretive attribute handlers" |
| 337 |
Occasionally the strenuous efforts Attribute::Handlers makes to convert |
| 338 |
the data argument (\f(CW$_[4]\fR) to a usable form before passing it to |
| 339 |
the handler get in the way. |
| 340 |
.PP |
| 341 |
You can turn off that eagerness-to-help by declaring |
| 342 |
an attribute handler with the keyword \f(CW\*(C`RAWDATA\*(C'\fR. For example: |
| 343 |
.PP |
| 344 |
.Vb 3 |
| 345 |
\& sub Raw : ATTR(RAWDATA) {...} |
| 346 |
\& sub Nekkid : ATTR(SCALAR,RAWDATA) {...} |
| 347 |
\& sub Au::Naturale : ATTR(RAWDATA,ANY) {...} |
| 348 |
.Ve |
| 349 |
.PP |
| 350 |
Then the handler makes absolutely no attempt to interpret the data it |
| 351 |
receives and simply passes it as a string: |
| 352 |
.PP |
| 353 |
.Vb 1 |
| 354 |
\& my $power : Raw(1..100); # handlers receives "1..100" |
| 355 |
.Ve |
| 356 |
.SS "Phase-specific attribute handlers" |
| 357 |
.IX Subsection "Phase-specific attribute handlers" |
| 358 |
By default, attribute handlers are called at the end of the compilation |
| 359 |
phase (in a \f(CW\*(C`CHECK\*(C'\fR block). This seems to be optimal in most cases because |
| 360 |
most things that can be defined are defined by that point but nothing has |
| 361 |
been executed. |
| 362 |
.PP |
| 363 |
However, it is possible to set up attribute handlers that are called at |
| 364 |
other points in the program's compilation or execution, by explicitly |
| 365 |
stating the phase (or phases) in which you wish the attribute handler to |
| 366 |
be called. For example: |
| 367 |
.PP |
| 368 |
.Vb 5 |
| 369 |
\& sub Early :ATTR(SCALAR,BEGIN) {...} |
| 370 |
\& sub Normal :ATTR(SCALAR,CHECK) {...} |
| 371 |
\& sub Late :ATTR(SCALAR,INIT) {...} |
| 372 |
\& sub Final :ATTR(SCALAR,END) {...} |
| 373 |
\& sub Bookends :ATTR(SCALAR,BEGIN,END) {...} |
| 374 |
.Ve |
| 375 |
.PP |
| 376 |
As the last example indicates, a handler may be set up to be (re)called in |
| 377 |
two or more phases. The phase name is passed as the handler's final argument. |
| 378 |
.PP |
| 379 |
Note that attribute handlers that are scheduled for the \f(CW\*(C`BEGIN\*(C'\fR phase |
| 380 |
are handled as soon as the attribute is detected (i.e. before any |
| 381 |
subsequently defined \f(CW\*(C`BEGIN\*(C'\fR blocks are executed). |
| 382 |
.ie n .SS "Attributes as ""tie"" interfaces" |
| 383 |
.el .SS "Attributes as \f(CWtie\fP interfaces" |
| 384 |
.IX Subsection "Attributes as tie interfaces" |
| 385 |
Attributes make an excellent and intuitive interface through which to tie |
| 386 |
variables. For example: |
| 387 |
.PP |
| 388 |
.Vb 2 |
| 389 |
\& use Attribute::Handlers; |
| 390 |
\& use Tie::Cycle; |
| 391 |
\& |
| 392 |
\& sub UNIVERSAL::Cycle : ATTR(SCALAR) { |
| 393 |
\& my ($package, $symbol, $referent, $attr, $data, $phase) = @_; |
| 394 |
\& $data = [ $data ] unless ref $data eq \*(AqARRAY\*(Aq; |
| 395 |
\& tie $$referent, \*(AqTie::Cycle\*(Aq, $data; |
| 396 |
\& } |
| 397 |
\& |
| 398 |
\& # and thereafter... |
| 399 |
\& |
| 400 |
\& package main; |
| 401 |
\& |
| 402 |
\& my $next : Cycle(\*(AqA\*(Aq..\*(AqZ\*(Aq); # $next is now a tied variable |
| 403 |
\& |
| 404 |
\& while (<>) { |
| 405 |
\& print $next; |
| 406 |
\& } |
| 407 |
.Ve |
| 408 |
.PP |
| 409 |
Note that, because the \f(CW\*(C`Cycle\*(C'\fR attribute receives its arguments in the |
| 410 |
\&\f(CW$data\fR variable, if the attribute is given a list of arguments, \f(CW$data\fR |
| 411 |
will consist of a single array reference; otherwise, it will consist of the |
| 412 |
single argument directly. Since Tie::Cycle requires its cycling values to |
| 413 |
be passed as an array reference, this means that we need to wrap |
| 414 |
non-array-reference arguments in an array constructor: |
| 415 |
.PP |
| 416 |
.Vb 1 |
| 417 |
\& $data = [ $data ] unless ref $data eq \*(AqARRAY\*(Aq; |
| 418 |
.Ve |
| 419 |
.PP |
| 420 |
Typically, however, things are the other way around: the tieable class expects |
| 421 |
its arguments as a flattened list, so the attribute looks like: |
| 422 |
.PP |
| 423 |
.Vb 5 |
| 424 |
\& sub UNIVERSAL::Cycle : ATTR(SCALAR) { |
| 425 |
\& my ($package, $symbol, $referent, $attr, $data, $phase) = @_; |
| 426 |
\& my @data = ref $data eq \*(AqARRAY\*(Aq ? @$data : $data; |
| 427 |
\& tie $$referent, \*(AqTie::Whatever\*(Aq, @data; |
| 428 |
\& } |
| 429 |
.Ve |
| 430 |
.PP |
| 431 |
This software pattern is so widely applicable that Attribute::Handlers |
| 432 |
provides a way to automate it: specifying \f(CW\*(Aqautotie\*(Aq\fR in the |
| 433 |
\&\f(CW\*(C`use Attribute::Handlers\*(C'\fR statement. So, the cycling example, |
| 434 |
could also be written: |
| 435 |
.PP |
| 436 |
.Vb 1 |
| 437 |
\& use Attribute::Handlers autotie => { Cycle => \*(AqTie::Cycle\*(Aq }; |
| 438 |
\& |
| 439 |
\& # and thereafter... |
| 440 |
\& |
| 441 |
\& package main; |
| 442 |
\& |
| 443 |
\& my $next : Cycle([\*(AqA\*(Aq..\*(AqZ\*(Aq]); # $next is now a tied variable |
| 444 |
\& |
| 445 |
\& while (<>) { |
| 446 |
\& print $next; |
| 447 |
\& } |
| 448 |
.Ve |
| 449 |
.PP |
| 450 |
Note that we now have to pass the cycling values as an array reference, |
| 451 |
since the \f(CW\*(C`autotie\*(C'\fR mechanism passes \f(CW\*(C`tie\*(C'\fR a list of arguments as a list |
| 452 |
(as in the Tie::Whatever example), \fInot\fR as an array reference (as in |
| 453 |
the original Tie::Cycle example at the start of this section). |
| 454 |
.PP |
| 455 |
The argument after \f(CW\*(Aqautotie\*(Aq\fR is a reference to a hash in which each key is |
| 456 |
the name of an attribute to be created, and each value is the class to which |
| 457 |
variables ascribed that attribute should be tied. |
| 458 |
.PP |
| 459 |
Note that there is no longer any need to import the Tie::Cycle module \-\- |
| 460 |
Attribute::Handlers takes care of that automagically. You can even pass |
| 461 |
arguments to the module's \f(CW\*(C`import\*(C'\fR subroutine, by appending them to the |
| 462 |
class name. For example: |
| 463 |
.PP |
| 464 |
.Vb 2 |
| 465 |
\& use Attribute::Handlers |
| 466 |
\& autotie => { Dir => \*(AqTie::Dir qw(DIR_UNLINK)\*(Aq }; |
| 467 |
.Ve |
| 468 |
.PP |
| 469 |
If the attribute name is unqualified, the attribute is installed in the |
| 470 |
current package. Otherwise it is installed in the qualifier's package: |
| 471 |
.PP |
| 472 |
.Vb 1 |
| 473 |
\& package Here; |
| 474 |
\& |
| 475 |
\& use Attribute::Handlers autotie => { |
| 476 |
\& Other::Good => Tie::SecureHash, # tie attr installed in Other:: |
| 477 |
\& Bad => Tie::Taxes, # tie attr installed in Here:: |
| 478 |
\& UNIVERSAL::Ugly => Software::Patent # tie attr installed everywhere |
| 479 |
\& }; |
| 480 |
.Ve |
| 481 |
.PP |
| 482 |
Autoties are most commonly used in the module to which they actually tie, |
| 483 |
and need to export their attributes to any module that calls them. To |
| 484 |
facilitate this, Attribute::Handlers recognizes a special "pseudo-class" \-\- |
| 485 |
\&\f(CW\*(C`_\|_CALLER_\|_\*(C'\fR, which may be specified as the qualifier of an attribute: |
| 486 |
.PP |
| 487 |
.Vb 1 |
| 488 |
\& package Tie::Me::Kangaroo::Down::Sport; |
| 489 |
\& |
| 490 |
\& use Attribute::Handlers autotie => |
| 491 |
\& { \*(Aq_\|_CALLER_\|_::Roo\*(Aq => _\|_PACKAGE_\|_ }; |
| 492 |
.Ve |
| 493 |
.PP |
| 494 |
This causes Attribute::Handlers to define the \f(CW\*(C`Roo\*(C'\fR attribute in the package |
| 495 |
that imports the Tie::Me::Kangaroo::Down::Sport module. |
| 496 |
.PP |
| 497 |
Note that it is important to quote the _\|_CALLER_\|_::Roo identifier because |
| 498 |
a bug in perl 5.8 will refuse to parse it and cause an unknown error. |
| 499 |
.PP |
| 500 |
\fIPassing the tied object to \fR\f(CI\*(C`tie\*(C'\fR |
| 501 |
.IX Subsection "Passing the tied object to tie" |
| 502 |
.PP |
| 503 |
Occasionally it is important to pass a reference to the object being tied |
| 504 |
to the TIESCALAR, TIEHASH, etc. that ties it. |
| 505 |
.PP |
| 506 |
The \f(CW\*(C`autotie\*(C'\fR mechanism supports this too. The following code: |
| 507 |
.PP |
| 508 |
.Vb 2 |
| 509 |
\& use Attribute::Handlers autotieref => { Selfish => Tie::Selfish }; |
| 510 |
\& my $var : Selfish(@args); |
| 511 |
.Ve |
| 512 |
.PP |
| 513 |
has the same effect as: |
| 514 |
.PP |
| 515 |
.Vb 1 |
| 516 |
\& tie my $var, \*(AqTie::Selfish\*(Aq, @args; |
| 517 |
.Ve |
| 518 |
.PP |
| 519 |
But when \f(CW"autotieref"\fR is used instead of \f(CW"autotie"\fR: |
| 520 |
.PP |
| 521 |
.Vb 2 |
| 522 |
\& use Attribute::Handlers autotieref => { Selfish => Tie::Selfish }; |
| 523 |
\& my $var : Selfish(@args); |
| 524 |
.Ve |
| 525 |
.PP |
| 526 |
the effect is to pass the \f(CW\*(C`tie\*(C'\fR call an extra reference to the variable |
| 527 |
being tied: |
| 528 |
.PP |
| 529 |
.Vb 1 |
| 530 |
\& tie my $var, \*(AqTie::Selfish\*(Aq, \e$var, @args; |
| 531 |
.Ve |
| 532 |
.SH EXAMPLES |
| 533 |
.IX Header "EXAMPLES" |
| 534 |
If the class shown in "SYNOPSIS" were placed in the MyClass.pm |
| 535 |
module, then the following code: |
| 536 |
.PP |
| 537 |
.Vb 2 |
| 538 |
\& package main; |
| 539 |
\& use MyClass; |
| 540 |
\& |
| 541 |
\& my MyClass $slr :Good :Bad(1**1\-1) :Omni(\-vorous); |
| 542 |
\& |
| 543 |
\& package SomeOtherClass; |
| 544 |
\& use base MyClass; |
| 545 |
\& |
| 546 |
\& sub tent { \*(Aqacle\*(Aq } |
| 547 |
\& |
| 548 |
\& sub fn :Ugly(sister) :Omni(\*(Aqpo\*(Aq,tent()) {...} |
| 549 |
\& my @arr :Good :Omni(s/cie/nt/); |
| 550 |
\& my %hsh :Good(q/bye/) :Omni(q/bus/); |
| 551 |
.Ve |
| 552 |
.PP |
| 553 |
would cause the following handlers to be invoked: |
| 554 |
.PP |
| 555 |
.Vb 1 |
| 556 |
\& # my MyClass $slr :Good :Bad(1**1\-1) :Omni(\-vorous); |
| 557 |
\& |
| 558 |
\& MyClass::Good:ATTR(SCALAR)( \*(AqMyClass\*(Aq, # class |
| 559 |
\& \*(AqLEXICAL\*(Aq, # no typeglob |
| 560 |
\& \e$slr, # referent |
| 561 |
\& \*(AqGood\*(Aq, # attr name |
| 562 |
\& undef # no attr data |
| 563 |
\& \*(AqCHECK\*(Aq, # compiler phase |
| 564 |
\& ); |
| 565 |
\& |
| 566 |
\& MyClass::Bad:ATTR(SCALAR)( \*(AqMyClass\*(Aq, # class |
| 567 |
\& \*(AqLEXICAL\*(Aq, # no typeglob |
| 568 |
\& \e$slr, # referent |
| 569 |
\& \*(AqBad\*(Aq, # attr name |
| 570 |
\& 0 # eval\*(Aqd attr data |
| 571 |
\& \*(AqCHECK\*(Aq, # compiler phase |
| 572 |
\& ); |
| 573 |
\& |
| 574 |
\& MyClass::Omni:ATTR(SCALAR)( \*(AqMyClass\*(Aq, # class |
| 575 |
\& \*(AqLEXICAL\*(Aq, # no typeglob |
| 576 |
\& \e$slr, # referent |
| 577 |
\& \*(AqOmni\*(Aq, # attr name |
| 578 |
\& \*(Aq\-vorous\*(Aq # eval\*(Aqd attr data |
| 579 |
\& \*(AqCHECK\*(Aq, # compiler phase |
| 580 |
\& ); |
| 581 |
\& |
| 582 |
\& |
| 583 |
\& # sub fn :Ugly(sister) :Omni(\*(Aqpo\*(Aq,tent()) {...} |
| 584 |
\& |
| 585 |
\& MyClass::UGLY:ATTR(CODE)( \*(AqSomeOtherClass\*(Aq, # class |
| 586 |
\& \e*SomeOtherClass::fn, # typeglob |
| 587 |
\& \e&SomeOtherClass::fn, # referent |
| 588 |
\& \*(AqUgly\*(Aq, # attr name |
| 589 |
\& \*(Aqsister\*(Aq # eval\*(Aqd attr data |
| 590 |
\& \*(AqCHECK\*(Aq, # compiler phase |
| 591 |
\& ); |
| 592 |
\& |
| 593 |
\& MyClass::Omni:ATTR(CODE)( \*(AqSomeOtherClass\*(Aq, # class |
| 594 |
\& \e*SomeOtherClass::fn, # typeglob |
| 595 |
\& \e&SomeOtherClass::fn, # referent |
| 596 |
\& \*(AqOmni\*(Aq, # attr name |
| 597 |
\& [\*(Aqpo\*(Aq,\*(Aqacle\*(Aq] # eval\*(Aqd attr data |
| 598 |
\& \*(AqCHECK\*(Aq, # compiler phase |
| 599 |
\& ); |
| 600 |
\& |
| 601 |
\& |
| 602 |
\& # my @arr :Good :Omni(s/cie/nt/); |
| 603 |
\& |
| 604 |
\& MyClass::Good:ATTR(ARRAY)( \*(AqSomeOtherClass\*(Aq, # class |
| 605 |
\& \*(AqLEXICAL\*(Aq, # no typeglob |
| 606 |
\& \e@arr, # referent |
| 607 |
\& \*(AqGood\*(Aq, # attr name |
| 608 |
\& undef # no attr data |
| 609 |
\& \*(AqCHECK\*(Aq, # compiler phase |
| 610 |
\& ); |
| 611 |
\& |
| 612 |
\& MyClass::Omni:ATTR(ARRAY)( \*(AqSomeOtherClass\*(Aq, # class |
| 613 |
\& \*(AqLEXICAL\*(Aq, # no typeglob |
| 614 |
\& \e@arr, # referent |
| 615 |
\& \*(AqOmni\*(Aq, # attr name |
| 616 |
\& "" # eval\*(Aqd attr data |
| 617 |
\& \*(AqCHECK\*(Aq, # compiler phase |
| 618 |
\& ); |
| 619 |
\& |
| 620 |
\& |
| 621 |
\& # my %hsh :Good(q/bye) :Omni(q/bus/); |
| 622 |
\& |
| 623 |
\& MyClass::Good:ATTR(HASH)( \*(AqSomeOtherClass\*(Aq, # class |
| 624 |
\& \*(AqLEXICAL\*(Aq, # no typeglob |
| 625 |
\& \e%hsh, # referent |
| 626 |
\& \*(AqGood\*(Aq, # attr name |
| 627 |
\& \*(Aqq/bye\*(Aq # raw attr data |
| 628 |
\& \*(AqCHECK\*(Aq, # compiler phase |
| 629 |
\& ); |
| 630 |
\& |
| 631 |
\& MyClass::Omni:ATTR(HASH)( \*(AqSomeOtherClass\*(Aq, # class |
| 632 |
\& \*(AqLEXICAL\*(Aq, # no typeglob |
| 633 |
\& \e%hsh, # referent |
| 634 |
\& \*(AqOmni\*(Aq, # attr name |
| 635 |
\& \*(Aqbus\*(Aq # eval\*(Aqd attr data |
| 636 |
\& \*(AqCHECK\*(Aq, # compiler phase |
| 637 |
\& ); |
| 638 |
.Ve |
| 639 |
.PP |
| 640 |
Installing handlers into UNIVERSAL, makes them...err..universal. |
| 641 |
For example: |
| 642 |
.PP |
| 643 |
.Vb 2 |
| 644 |
\& package Descriptions; |
| 645 |
\& use Attribute::Handlers; |
| 646 |
\& |
| 647 |
\& my %name; |
| 648 |
\& sub name { return $name{$_[2]}||*{$_[1]}{NAME} } |
| 649 |
\& |
| 650 |
\& sub UNIVERSAL::Name :ATTR { |
| 651 |
\& $name{$_[2]} = $_[4]; |
| 652 |
\& } |
| 653 |
\& |
| 654 |
\& sub UNIVERSAL::Purpose :ATTR { |
| 655 |
\& print STDERR "Purpose of ", &name, " is $_[4]\en"; |
| 656 |
\& } |
| 657 |
\& |
| 658 |
\& sub UNIVERSAL::Unit :ATTR { |
| 659 |
\& print STDERR &name, " measured in $_[4]\en"; |
| 660 |
\& } |
| 661 |
.Ve |
| 662 |
.PP |
| 663 |
Let's you write: |
| 664 |
.PP |
| 665 |
.Vb 1 |
| 666 |
\& use Descriptions; |
| 667 |
\& |
| 668 |
\& my $capacity : Name(capacity) |
| 669 |
\& : Purpose(to store max storage capacity for files) |
| 670 |
\& : Unit(Gb); |
| 671 |
\& |
| 672 |
\& |
| 673 |
\& package Other; |
| 674 |
\& |
| 675 |
\& sub foo : Purpose(to foo all data before barring it) { } |
| 676 |
\& |
| 677 |
\& # etc. |
| 678 |
.Ve |
| 679 |
.SH "UTILITY FUNCTIONS" |
| 680 |
.IX Header "UTILITY FUNCTIONS" |
| 681 |
This module offers a single utility function, \f(CWfindsym()\fR. |
| 682 |
.IP findsym 4 |
| 683 |
.IX Item "findsym" |
| 684 |
.Vb 1 |
| 685 |
\& my $symbol = Attribute::Handlers::findsym($package, $referent); |
| 686 |
.Ve |
| 687 |
.Sp |
| 688 |
The function looks in the symbol table of \f(CW$package\fR for the typeglob for |
| 689 |
\&\f(CW$referent\fR, which is a reference to a variable or subroutine (SCALAR, ARRAY, |
| 690 |
HASH, or CODE). If it finds the typeglob, it returns it. Otherwise, it returns |
| 691 |
undef. Note that \f(CW\*(C`findsym\*(C'\fR memoizes the typeglobs it has previously |
| 692 |
successfully found, so subsequent calls with the same arguments should be |
| 693 |
much faster. |
| 694 |
.SH DIAGNOSTICS |
| 695 |
.IX Header "DIAGNOSTICS" |
| 696 |
.ie n .IP """Bad attribute type: ATTR(%s)""" 4 |
| 697 |
.el .IP "\f(CWBad attribute type: ATTR(%s)\fR" 4 |
| 698 |
.IX Item "Bad attribute type: ATTR(%s)" |
| 699 |
An attribute handler was specified with an \f(CW:ATTR(\fR\f(CIref_type\fR\f(CW)\fR, but the |
| 700 |
type of referent it was defined to handle wasn't one of the five permitted: |
| 701 |
\&\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. |
| 702 |
.ie n .IP """Attribute handler %s doesn\*(Aqt handle %s attributes""" 4 |
| 703 |
.el .IP "\f(CWAttribute handler %s doesn\*(Aqt handle %s attributes\fR" 4 |
| 704 |
.IX Item "Attribute handler %s doesnt handle %s attributes" |
| 705 |
A handler for attributes of the specified name \fIwas\fR defined, but not |
| 706 |
for the specified type of declaration. Typically encountered when trying |
| 707 |
to apply a \f(CW\*(C`VAR\*(C'\fR attribute handler to a subroutine, or a \f(CW\*(C`SCALAR\*(C'\fR |
| 708 |
attribute handler to some other type of variable. |
| 709 |
.ie n .IP """Declaration of %s attribute in package %s may clash with future reserved word""" 4 |
| 710 |
.el .IP "\f(CWDeclaration of %s attribute in package %s may clash with future reserved word\fR" 4 |
| 711 |
.IX Item "Declaration of %s attribute in package %s may clash with future reserved word" |
| 712 |
A handler for an attributes with an all-lowercase name was declared. An |
| 713 |
attribute with an all-lowercase name might have a meaning to Perl |
| 714 |
itself some day, even though most don't yet. Use a mixed-case attribute |
| 715 |
name, instead. |
| 716 |
.ie n .IP """Can\*(Aqt have two ATTR specifiers on one subroutine""" 4 |
| 717 |
.el .IP "\f(CWCan\*(Aqt have two ATTR specifiers on one subroutine\fR" 4 |
| 718 |
.IX Item "Cant have two ATTR specifiers on one subroutine" |
| 719 |
You just can't, okay? |
| 720 |
Instead, put all the specifications together with commas between them |
| 721 |
in a single \f(CWATTR(\fR\f(CIspecification\fR\f(CW)\fR. |
| 722 |
.ie n .IP """Can\*(Aqt autotie a %s""" 4 |
| 723 |
.el .IP "\f(CWCan\*(Aqt autotie a %s\fR" 4 |
| 724 |
.IX Item "Cant autotie a %s" |
| 725 |
You can only declare autoties for types \f(CW"SCALAR"\fR, \f(CW"ARRAY"\fR, and |
| 726 |
\&\f(CW"HASH"\fR. They're the only things (apart from typeglobs \-\- which are |
| 727 |
not declarable) that Perl can tie. |
| 728 |
.ie n .IP """Internal error: %s symbol went missing""" 4 |
| 729 |
.el .IP "\f(CWInternal error: %s symbol went missing\fR" 4 |
| 730 |
.IX Item "Internal error: %s symbol went missing" |
| 731 |
Something is rotten in the state of the program. An attributed |
| 732 |
subroutine ceased to exist between the point it was declared and the point |
| 733 |
at which its attribute handler(s) would have been called. |
| 734 |
.ie n .IP """Won\*(Aqt be able to apply END handler""" 4 |
| 735 |
.el .IP "\f(CWWon\*(Aqt be able to apply END handler\fR" 4 |
| 736 |
.IX Item "Wont be able to apply END handler" |
| 737 |
You have defined an END handler for an attribute that is being applied |
| 738 |
to a lexical variable. Since the variable may not be available during END |
| 739 |
this won't happen. |
| 740 |
.SH AUTHOR |
| 741 |
.IX Header "AUTHOR" |
| 742 |
Damian Conway ([email protected]). The maintainer of this module is now Rafael |
| 743 |
Garcia-Suarez ([email protected]). |
| 744 |
.PP |
| 745 |
Maintainer of the CPAN release is Steffen Mueller ([email protected]). |
| 746 |
Contact him with technical difficulties with respect to the packaging of the |
| 747 |
CPAN module. |
| 748 |
.SH BUGS |
| 749 |
.IX Header "BUGS" |
| 750 |
There are undoubtedly serious bugs lurking somewhere in code this funky :\-) |
| 751 |
Bug reports and other feedback are most welcome. |
| 752 |
.SH "COPYRIGHT AND LICENSE" |
| 753 |
.IX Header "COPYRIGHT AND LICENSE" |
| 754 |
.Vb 3 |
| 755 |
\& Copyright (c) 2001\-2014, Damian Conway. All Rights Reserved. |
| 756 |
\& This module is free software. It may be used, redistributed |
| 757 |
\& and/or modified under the same terms as Perl itself. |
| 758 |
.Ve |