mingw/html/lib/Attribute/Handlers.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Attribute::Handlers - Simpler definition of attribute handlers</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Attribute::Handlers - Simpler definition of attribute handlers</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#version">VERSION</a></li>
  24         <li><a href="#synopsis">SYNOPSIS</a></li>
  25         <li><a href="#description">DESCRIPTION</a></li>
  26         <ul>
  27
  28                 <li><a href="#typed_lexicals">Typed lexicals</a></li>
  29                 <li><a href="#typespecific_attribute_handlers">Type-specific attribute handlers</a></li>
  30                 <li><a href="#noninterpretive_attribute_handlers">Non-interpretive attribute handlers</a></li>
  31                 <li><a href="#phasespecific_attribute_handlers">Phase-specific attribute handlers</a></li>
  32                 <li><a href="#attributes_as_tie_interfaces">Attributes as <code>tie</code> interfaces</a></li>
  33                 <ul>
  34
  35                         <li><a href="#passing_the_tied_object_to_tie">Passing the tied object to <code>tie</code></a></li>
  36                 </ul>
  37
  38         </ul>
  39
  40         <li><a href="#examples">EXAMPLES</a></li>
  41         <li><a href="#diagnostics">DIAGNOSTICS</a></li>
  42         <li><a href="#author">AUTHOR</a></li>
  43         <li><a href="#bugs">BUGS</a></li>
  44         <li><a href="#copyright">COPYRIGHT</a></li>
  45 </ul>
  46 <!-- INDEX END -->
  47
  48 <hr />
  49 <p>
  50 </p>
  51 <h1><a name="name">NAME</a></h1>
  52 <p>Attribute::Handlers - Simpler definition of attribute handlers</p>
  53 <p>
  54 </p>
  55 <hr />
  56 <h1><a name="version">VERSION</a></h1>
  57 <p>This document describes version 0.78 of Attribute::Handlers,
  58 released October 5, 2002.</p>
  59 <p>
  60 </p>
  61 <hr />
  62 <h1><a name="synopsis">SYNOPSIS</a></h1>
  63 <pre>
  64         package MyClass;
  65         require v5.6.0;
  66         use Attribute::Handlers;
  67         no warnings 'redefine';</pre>
  68 <pre>
  69         sub Good : ATTR(SCALAR) {
  70                 my ($package, $symbol, $referent, $attr, $data) = @_;</pre>
  71 <pre>
  72                 # Invoked for any scalar variable with a :Good attribute,
  73                 # provided the variable was declared in MyClass (or
  74                 # a derived class) or typed to MyClass.</pre>
  75 <pre>
  76                 # Do whatever to $referent here (executed in CHECK phase).
  77                 ...
  78         }</pre>
  79 <pre>
  80         sub Bad : ATTR(SCALAR) {
  81                 # Invoked for any scalar variable with a :Bad attribute,
  82                 # provided the variable was declared in MyClass (or
  83                 # a derived class) or typed to MyClass.
  84                 ...
  85         }</pre>
  86 <pre>
  87         sub Good : ATTR(ARRAY) {
  88                 # Invoked for any array variable with a :Good attribute,
  89                 # provided the variable was declared in MyClass (or
  90                 # a derived class) or typed to MyClass.
  91                 ...
  92         }</pre>
  93 <pre>
  94         sub Good : ATTR(HASH) {
  95                 # Invoked for any hash variable with a :Good attribute,
  96                 # provided the variable was declared in MyClass (or
  97                 # a derived class) or typed to MyClass.
  98                 ...
  99         }</pre>
 100 <pre>
 101         sub Ugly : ATTR(CODE) {
 102                 # Invoked for any subroutine declared in MyClass (or a
 103                 # derived class) with an :Ugly attribute.
 104                 ...
 105         }</pre>
 106 <pre>
 107         sub Omni : ATTR {
 108                 # Invoked for any scalar, array, hash, or subroutine
 109                 # with an :Omni attribute, provided the variable or
 110                 # subroutine was declared in MyClass (or a derived class)
 111                 # or the variable was typed to MyClass.
 112                 # Use ref($_[2]) to determine what kind of referent it was.
 113                 ...
 114         }</pre>
 115 <pre>
 116         use Attribute::Handlers autotie =&gt; { Cycle =&gt; Tie::Cycle };</pre>
 117 <pre>
 118         my $next : Cycle(['A'..'Z']);</pre>
 119 <p>
 120 </p>
 121 <hr />
 122 <h1><a name="description">DESCRIPTION</a></h1>
 123 <p>This module, when inherited by a package, allows that package's class to
 124 define attribute handler subroutines for specific attributes. Variables
 125 and subroutines subsequently defined in that package, or in packages
 126 derived from that package may be given attributes with the same names as
 127 the attribute handler subroutines, which will then be called in one of
 128 the compilation phases (i.e. in a <code>BEGIN</code>, <code>CHECK</code>, <code>INIT</code>, or <code>END</code>
 129 block).</p>
 130 <p>To create a handler, define it as a subroutine with the same name as
 131 the desired attribute, and declare the subroutine itself with the
 132 attribute <code>:ATTR</code>. For example:</p>
 133 <pre>
 134         package LoudDecl;
 135         use Attribute::Handlers;</pre>
 136 <pre>
 137         sub Loud :ATTR {
 138                 my ($package, $symbol, $referent, $attr, $data, $phase) = @_;
 139                 print STDERR
 140                         ref($referent), &quot; &quot;,
 141                         *{$symbol}{NAME}, &quot; &quot;,
 142                         &quot;($referent) &quot;, &quot;was just declared &quot;,
 143                         &quot;and ascribed the ${attr} attribute &quot;,
 144                         &quot;with data ($data)\n&quot;,
 145                         &quot;in phase $phase\n&quot;;
 146         }</pre>
 147 <p>This creates a handler for the attribute <code>:Loud</code> in the class LoudDecl.
 148 Thereafter, any subroutine declared with a <code>:Loud</code> attribute in the class
 149 LoudDecl:</p>
 150 <pre>
 151         package LoudDecl;</pre>
 152 <pre>
 153         sub foo: Loud {...}</pre>
 154 <p>causes the above handler to be invoked, and passed:</p>
 155 <dl>
 156 <dt><strong><a name="item__5b0_5d">[0]</a></strong>
 157
 158 <dd>
 159 <p>the name of the package into which it was declared;</p>
 160 </dd>
 161 </li>
 162 <dt><strong><a name="item__5b1_5d">[1]</a></strong>
 163
 164 <dd>
 165 <p>a reference to the symbol table entry (typeglob) containing the subroutine;</p>
 166 </dd>
 167 </li>
 168 <dt><strong><a name="item__5b2_5d">[2]</a></strong>
 169
 170 <dd>
 171 <p>a reference to the subroutine;</p>
 172 </dd>
 173 </li>
 174 <dt><strong><a name="item__5b3_5d">[3]</a></strong>
 175
 176 <dd>
 177 <p>the name of the attribute;</p>
 178 </dd>
 179 </li>
 180 <dt><strong><a name="item__5b4_5d">[4]</a></strong>
 181
 182 <dd>
 183 <p>any data associated with that attribute;</p>
 184 </dd>
 185 </li>
 186 <dt><strong><a name="item__5b5_5d">[5]</a></strong>
 187
 188 <dd>
 189 <p>the name of the phase in which the handler is being invoked.</p>
 190 </dd>
 191 </li>
 192 </dl>
 193 <p>Likewise, declaring any variables with the <code>:Loud</code> attribute within the
 194 package:</p>
 195 <pre>
 196         package LoudDecl;</pre>
 197 <pre>
 198         my $foo :Loud;
 199         my @foo :Loud;
 200         my %foo :Loud;</pre>
 201 <p>will cause the handler to be called with a similar argument list (except,
 202 of course, that <code>$_[2]</code> will be a reference to the variable).</p>
 203 <p>The package name argument will typically be the name of the class into
 204 which the subroutine was declared, but it may also be the name of a derived
 205 class (since handlers are inherited).</p>
 206 <p>If a lexical variable is given an attribute, there is no symbol table to
 207 which it belongs, so the symbol table argument (<code>$_[1]</code>) is set to the
 208 string <code>'LEXICAL'</code> in that case. Likewise, ascribing an attribute to
 209 an anonymous subroutine results in a symbol table argument of <code>'ANON'</code>.</p>
 210 <p>The data argument passes in the value (if any) associated with the
 211 attribute. For example, if <code>&amp;foo</code> had been declared:</p>
 212 <pre>
 213         sub foo :Loud(&quot;turn it up to 11, man!&quot;) {...}</pre>
 214 <p>then the string <code>&quot;turn it up to 11, man!&quot;</code> would be passed as the
 215 last argument.</p>
 216 <p>Attribute::Handlers makes strenuous efforts to convert
 217 the data argument (<code>$_[4]</code>) to a useable form before passing it to
 218 the handler (but see <a href="#noninterpretive_attribute_handlers">Non-interpretive attribute handlers</a>).
 219 For example, all of these:</p>
 220 <pre>
 221         sub foo :Loud(till=&gt;ears=&gt;are=&gt;bleeding) {...}
 222         sub foo :Loud(['till','ears','are','bleeding']) {...}
 223         sub foo :Loud(qw/till ears are bleeding/) {...}
 224         sub foo :Loud(qw/my, ears, are, bleeding/) {...}
 225         sub foo :Loud(till,ears,are,bleeding) {...}</pre>
 226 <p>causes it to pass <code>['till','ears','are','bleeding']</code> as the handler's
 227 data argument. However, if the data can't be parsed as valid Perl, then
 228 it is passed as an uninterpreted string. For example:</p>
 229 <pre>
 230         sub foo :Loud(my,ears,are,bleeding) {...}
 231         sub foo :Loud(qw/my ears are bleeding) {...}</pre>
 232 <p>cause the strings <code>'my,ears,are,bleeding'</code> and <code>'qw/my ears are bleeding'</code>
 233 respectively to be passed as the data argument.</p>
 234 <p>If the attribute has only a single associated scalar data value, that value is
 235 passed as a scalar. If multiple values are associated, they are passed as an
 236 array reference. If no value is associated with the attribute, <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> is
 237 passed.</p>
 238 <p>
 239 </p>
 240 <h2><a name="typed_lexicals">Typed lexicals</a></h2>
 241 <p>Regardless of the package in which it is declared, if a lexical variable is
 242 ascribed an attribute, the handler that is invoked is the one belonging to
 243 the package to which it is typed. For example, the following declarations:</p>
 244 <pre>
 245         package OtherClass;</pre>
 246 <pre>
 247         my LoudDecl $loudobj : Loud;
 248         my LoudDecl @loudobjs : Loud;
 249         my LoudDecl %loudobjex : Loud;</pre>
 250 <p>causes the LoudDecl::Loud handler to be invoked (even if OtherClass also
 251 defines a handler for <code>:Loud</code> attributes).</p>
 252 <p>
 253 </p>
 254 <h2><a name="typespecific_attribute_handlers">Type-specific attribute handlers</a></h2>
 255 <p>If an attribute handler is declared and the <code>:ATTR</code> specifier is
 256 given the name of a built-in type (<code>SCALAR</code>, <code>ARRAY</code>, <code>HASH</code>, or <code>CODE</code>),
 257 the handler is only applied to declarations of that type. For example,
 258 the following definition:</p>
 259 <pre>
 260         package LoudDecl;</pre>
 261 <pre>
 262         sub RealLoud :ATTR(SCALAR) { print &quot;Yeeeeow!&quot; }</pre>
 263 <p>creates an attribute handler that applies only to scalars:</p>
 264 <pre>
 265         package Painful;
 266         use base LoudDecl;</pre>
 267 <pre>
 268         my $metal : RealLoud;           # invokes &amp;LoudDecl::RealLoud
 269         my @metal : RealLoud;           # error: unknown attribute
 270         my %metal : RealLoud;           # error: unknown attribute
 271         sub metal : RealLoud {...}      # error: unknown attribute</pre>
 272 <p>You can, of course, declare separate handlers for these types as well
 273 (but you'll need to specify <code>no warnings 'redefine'</code> to do it quietly):</p>
 274 <pre>
 275         package LoudDecl;
 276         use Attribute::Handlers;
 277         no warnings 'redefine';</pre>
 278 <pre>
 279         sub RealLoud :ATTR(SCALAR) { print &quot;Yeeeeow!&quot; }
 280         sub RealLoud :ATTR(ARRAY) { print &quot;Urrrrrrrrrr!&quot; }
 281         sub RealLoud :ATTR(HASH) { print &quot;Arrrrrgggghhhhhh!&quot; }
 282         sub RealLoud :ATTR(CODE) { croak &quot;Real loud sub torpedoed&quot; }</pre>
 283 <p>You can also explicitly indicate that a single handler is meant to be
 284 used for all types of referents like so:</p>
 285 <pre>
 286         package LoudDecl;
 287         use Attribute::Handlers;</pre>
 288 <pre>
 289         sub SeriousLoud :ATTR(ANY) { warn &quot;Hearing loss imminent&quot; }</pre>
 290 <p>(I.e. <a href="#item_attr"><code>ATTR(ANY)</code></a> is a synonym for <code>:ATTR</code>).</p>
 291 <p>
 292 </p>
 293 <h2><a name="noninterpretive_attribute_handlers">Non-interpretive attribute handlers</a></h2>
 294 <p>Occasionally the strenuous efforts Attribute::Handlers makes to convert
 295 the data argument (<code>$_[4]</code>) to a useable form before passing it to
 296 the handler get in the way.</p>
 297 <p>You can turn off that eagerness-to-help by declaring
 298 an attribute handler with the keyword <code>RAWDATA</code>. For example:</p>
 299 <pre>
 300         sub Raw          : ATTR(RAWDATA) {...}
 301         sub Nekkid       : ATTR(SCALAR,RAWDATA) {...}
 302         sub Au::Naturale : ATTR(RAWDATA,ANY) {...}</pre>
 303 <p>Then the handler makes absolutely no attempt to interpret the data it
 304 receives and simply passes it as a string:</p>
 305 <pre>
 306         my $power : Raw(1..100);        # handlers receives &quot;1..100&quot;</pre>
 307 <p>
 308 </p>
 309 <h2><a name="phasespecific_attribute_handlers">Phase-specific attribute handlers</a></h2>
 310 <p>By default, attribute handlers are called at the end of the compilation
 311 phase (in a <code>CHECK</code> block). This seems to be optimal in most cases because
 312 most things that can be defined are defined by that point but nothing has
 313 been executed.</p>
 314 <p>However, it is possible to set up attribute handlers that are called at
 315 other points in the program's compilation or execution, by explicitly
 316 stating the phase (or phases) in which you wish the attribute handler to
 317 be called. For example:</p>
 318 <pre>
 319         sub Early    :ATTR(SCALAR,BEGIN) {...}
 320         sub Normal   :ATTR(SCALAR,CHECK) {...}
 321         sub Late     :ATTR(SCALAR,INIT) {...}
 322         sub Final    :ATTR(SCALAR,END) {...}
 323         sub Bookends :ATTR(SCALAR,BEGIN,END) {...}</pre>
 324 <p>As the last example indicates, a handler may be set up to be (re)called in
 325 two or more phases. The phase name is passed as the handler's final argument.</p>
 326 <p>Note that attribute handlers that are scheduled for the <code>BEGIN</code> phase
 327 are handled as soon as the attribute is detected (i.e. before any
 328 subsequently defined <code>BEGIN</code> blocks are executed).</p>
 329 <p>
 330 </p>
 331 <h2><a name="attributes_as_tie_interfaces">Attributes as <code>tie</code> interfaces</a></h2>
 332 <p>Attributes make an excellent and intuitive interface through which to tie
 333 variables. For example:</p>
 334 <pre>
 335         use Attribute::Handlers;
 336         use Tie::Cycle;</pre>
 337 <pre>
 338         sub UNIVERSAL::Cycle : ATTR(SCALAR) {
 339                 my ($package, $symbol, $referent, $attr, $data, $phase) = @_;
 340                 $data = [ $data ] unless ref $data eq 'ARRAY';
 341                 tie $$referent, 'Tie::Cycle', $data;
 342         }</pre>
 343 <pre>
 344         # and thereafter...</pre>
 345 <pre>
 346         package main;</pre>
 347 <pre>
 348         my $next : Cycle('A'..'Z');     # $next is now a tied variable</pre>
 349 <pre>
 350         while (&lt;&gt;) {
 351                 print $next;
 352         }</pre>
 353 <p>Note that, because the <code>Cycle</code> attribute receives its arguments in the
 354 <code>$data</code> variable, if the attribute is given a list of arguments, <code>$data</code>
 355 will consist of a single array reference; otherwise, it will consist of the
 356 single argument directly. Since Tie::Cycle requires its cycling values to
 357 be passed as an array reference, this means that we need to wrap
 358 non-array-reference arguments in an array constructor:</p>
 359 <pre>
 360         $data = [ $data ] unless ref $data eq 'ARRAY';</pre>
 361 <p>Typically, however, things are the other way around: the tieable class expects
 362 its arguments as a flattened list, so the attribute looks like:</p>
 363 <pre>
 364         sub UNIVERSAL::Cycle : ATTR(SCALAR) {
 365                 my ($package, $symbol, $referent, $attr, $data, $phase) = @_;
 366                 my @data = ref $data eq 'ARRAY' ? @$data : $data;
 367                 tie $$referent, 'Tie::Whatever', @data;
 368         }</pre>
 369 <p>This software pattern is so widely applicable that Attribute::Handlers
 370 provides a way to automate it: specifying <code>'autotie'</code> in the
 371 <code>use Attribute::Handlers</code> statement. So, the cycling example,
 372 could also be written:</p>
 373 <pre>
 374         use Attribute::Handlers autotie =&gt; { Cycle =&gt; 'Tie::Cycle' };</pre>
 375 <pre>
 376         # and thereafter...</pre>
 377 <pre>
 378         package main;</pre>
 379 <pre>
 380         my $next : Cycle(['A'..'Z']);     # $next is now a tied variable</pre>
 381 <pre>
 382         while (&lt;&gt;) {
 383                 print $next;</pre>
 384 <p>Note that we now have to pass the cycling values as an array reference,
 385 since the <code>autotie</code> mechanism passes <code>tie</code> a list of arguments as a list
 386 (as in the Tie::Whatever example), <em>not</em> as an array reference (as in
 387 the original Tie::Cycle example at the start of this section).</p>
 388 <p>The argument after <code>'autotie'</code> is a reference to a hash in which each key is
 389 the name of an attribute to be created, and each value is the class to which
 390 variables ascribed that attribute should be tied.</p>
 391 <p>Note that there is no longer any need to import the Tie::Cycle module --
 392 Attribute::Handlers takes care of that automagically. You can even pass
 393 arguments to the module's <code>import</code> subroutine, by appending them to the
 394 class name. For example:</p>
 395 <pre>
 396         use Attribute::Handlers
 397                 autotie =&gt; { Dir =&gt; 'Tie::Dir qw(DIR_UNLINK)' };</pre>
 398 <p>If the attribute name is unqualified, the attribute is installed in the
 399 current package. Otherwise it is installed in the qualifier's package:</p>
 400 <pre>
 401         package Here;</pre>
 402 <pre>
 403         use Attribute::Handlers autotie =&gt; {
 404                 Other::Good =&gt; Tie::SecureHash, # tie attr installed in Other::
 405                         Bad =&gt; Tie::Taxes,      # tie attr installed in Here::
 406             UNIVERSAL::Ugly =&gt; Software::Patent # tie attr installed everywhere
 407         };</pre>
 408 <p>Autoties are most commonly used in the module to which they actually tie,
 409 and need to export their attributes to any module that calls them. To
 410 facilitate this, Attribute::Handlers recognizes a special ``pseudo-class'' --
 411 <code>__CALLER__</code>, which may be specified as the qualifier of an attribute:</p>
 412 <pre>
 413         package Tie::Me::Kangaroo:Down::Sport;</pre>
 414 <pre>
 415         use Attribute::Handlers autotie =&gt; { '__CALLER__::Roo' =&gt; __PACKAGE__ };</pre>
 416 <p>This causes Attribute::Handlers to define the <code>Roo</code> attribute in the package
 417 that imports the Tie::Me::Kangaroo:Down::Sport module.</p>
 418 <p>Note that it is important to quote the __CALLER__::Roo identifier because
 419 a bug in perl 5.8 will refuse to parse it and cause an unknown error.</p>
 420 <p>
 421 </p>
 422 <h3><a name="passing_the_tied_object_to_tie">Passing the tied object to <code>tie</code></a></h3>
 423 <p>Occasionally it is important to pass a reference to the object being tied
 424 to the TIESCALAR, TIEHASH, etc. that ties it.</p>
 425 <p>The <code>autotie</code> mechanism supports this too. The following code:</p>
 426 <pre>
 427         use Attribute::Handlers autotieref =&gt; { Selfish =&gt; Tie::Selfish };
 428         my $var : Selfish(@args);</pre>
 429 <p>has the same effect as:</p>
 430 <pre>
 431         tie my $var, 'Tie::Selfish', @args;</pre>
 432 <p>But when <code>&quot;autotieref&quot;</code> is used instead of <code>&quot;autotie&quot;</code>:</p>
 433 <pre>
 434         use Attribute::Handlers autotieref =&gt; { Selfish =&gt; Tie::Selfish };
 435         my $var : Selfish(@args);</pre>
 436 <p>the effect is to pass the <code>tie</code> call an extra reference to the variable
 437 being tied:</p>
 438 <pre>
 439         tie my $var, 'Tie::Selfish', \$var, @args;</pre>
 440 <p>
 441 </p>
 442 <hr />
 443 <h1><a name="examples">EXAMPLES</a></h1>
 444 <p>If the class shown in <em>SYNOPSIS</em> were placed in the MyClass.pm
 445 module, then the following code:</p>
 446 <pre>
 447         package main;
 448         use MyClass;</pre>
 449 <pre>
 450         my MyClass $slr :Good :Bad(1**1-1) :Omni(-vorous);</pre>
 451 <pre>
 452         package SomeOtherClass;
 453         use base MyClass;</pre>
 454 <pre>
 455         sub tent { 'acle' }</pre>
 456 <pre>
 457         sub fn :Ugly(sister) :Omni('po',tent()) {...}
 458         my @arr :Good :Omni(s/cie/nt/);
 459         my %hsh :Good(q/bye) :Omni(q/bus/);</pre>
 460 <p>would cause the following handlers to be invoked:</p>
 461 <pre>
 462         # my MyClass $slr :Good :Bad(1**1-1) :Omni(-vorous);</pre>
 463 <pre>
 464         MyClass::Good:ATTR(SCALAR)( 'MyClass',          # class
 465                                     'LEXICAL',          # no typeglob
 466                                     \$slr,              # referent
 467                                     'Good',             # attr name
 468                                     undef               # no attr data
 469                                     'CHECK',            # compiler phase
 470                                   );</pre>
 471 <pre>
 472         MyClass::Bad:ATTR(SCALAR)( 'MyClass',           # class
 473                                    'LEXICAL',           # no typeglob
 474                                    \$slr,               # referent
 475                                    'Bad',               # attr name
 476                                    0                    # eval'd attr data
 477                                    'CHECK',             # compiler phase
 478                                  );</pre>
 479 <pre>
 480         MyClass::Omni:ATTR(SCALAR)( 'MyClass',          # class
 481                                     'LEXICAL',          # no typeglob
 482                                     \$slr,              # referent
 483                                     'Omni',             # attr name
 484                                     '-vorous'           # eval'd attr data
 485                                     'CHECK',            # compiler phase
 486                                   );</pre>
 487 <pre>
 488         # sub fn :Ugly(sister) :Omni('po',tent()) {...}</pre>
 489 <pre>
 490         MyClass::UGLY:ATTR(CODE)( 'SomeOtherClass',     # class
 491                                   \*SomeOtherClass::fn, # typeglob
 492                                   \&amp;SomeOtherClass::fn, # referent
 493                                   'Ugly',               # attr name
 494                                   'sister'              # eval'd attr data
 495                                   'CHECK',              # compiler phase
 496                                 );</pre>
 497 <pre>
 498         MyClass::Omni:ATTR(CODE)( 'SomeOtherClass',     # class
 499                                   \*SomeOtherClass::fn, # typeglob
 500                                   \&amp;SomeOtherClass::fn, # referent
 501                                   'Omni',               # attr name
 502                                   ['po','acle']         # eval'd attr data
 503                                   'CHECK',              # compiler phase
 504                                 );</pre>
 505 <pre>
 506         # my @arr :Good :Omni(s/cie/nt/);</pre>
 507 <pre>
 508         MyClass::Good:ATTR(ARRAY)( 'SomeOtherClass',    # class
 509                                    'LEXICAL',           # no typeglob
 510                                    \@arr,               # referent
 511                                    'Good',              # attr name
 512                                    undef                # no attr data
 513                                    'CHECK',             # compiler phase
 514                                  );</pre>
 515 <pre>
 516         MyClass::Omni:ATTR(ARRAY)( 'SomeOtherClass',    # class
 517                                    'LEXICAL',           # no typeglob
 518                                    \@arr,               # referent
 519                                    'Omni',              # attr name
 520                                    &quot;&quot;                   # eval'd attr data
 521                                    'CHECK',             # compiler phase
 522                                  );</pre>
 523 <pre>
 524         # my %hsh :Good(q/bye) :Omni(q/bus/);
 525
 526         MyClass::Good:ATTR(HASH)( 'SomeOtherClass',     # class
 527                                   'LEXICAL',            # no typeglob
 528                                   \%hsh,                # referent
 529                                   'Good',               # attr name
 530                                   'q/bye'               # raw attr data
 531                                   'CHECK',              # compiler phase
 532                                 );
 533
 534         MyClass::Omni:ATTR(HASH)( 'SomeOtherClass',     # class
 535                                   'LEXICAL',            # no typeglob
 536                                   \%hsh,                # referent
 537                                   'Omni',               # attr name
 538                                   'bus'                 # eval'd attr data
 539                                   'CHECK',              # compiler phase
 540                                 );</pre>
 541 <p>Installing handlers into UNIVERSAL, makes them...err..universal.
 542 For example:</p>
 543 <pre>
 544         package Descriptions;
 545         use Attribute::Handlers;</pre>
 546 <pre>
 547         my %name;
 548         sub name { return $name{$_[2]}||*{$_[1]}{NAME} }</pre>
 549 <pre>
 550         sub UNIVERSAL::Name :ATTR {
 551                 $name{$_[2]} = $_[4];
 552         }</pre>
 553 <pre>
 554         sub UNIVERSAL::Purpose :ATTR {
 555                 print STDERR &quot;Purpose of &quot;, &amp;name, &quot; is $_[4]\n&quot;;
 556         }</pre>
 557 <pre>
 558         sub UNIVERSAL::Unit :ATTR {
 559                 print STDERR &amp;name, &quot; measured in $_[4]\n&quot;;
 560         }</pre>
 561 <p>Let's you write:</p>
 562 <pre>
 563         use Descriptions;</pre>
 564 <pre>
 565         my $capacity : Name(capacity)
 566                      : Purpose(to store max storage capacity for files)
 567                      : Unit(Gb);</pre>
 568 <pre>
 569         package Other;</pre>
 570 <pre>
 571         sub foo : Purpose(to foo all data before barring it) { }</pre>
 572 <pre>
 573         # etc.</pre>
 574 <p>
 575 </p>
 576 <hr />
 577 <h1><a name="diagnostics">DIAGNOSTICS</a></h1>
 578 <dl>
 579 <dt><strong><a name="item_attr"><code>Bad attribute type: ATTR(%s)</code></a></strong>
 580
 581 <dd>
 582 <p>An attribute handler was specified with an <a href="#item_attr"><code>:ATTR(ref_type)</code></a>, but the
 583 type of referent it was defined to handle wasn't one of the five permitted:
 584 <code>SCALAR</code>, <code>ARRAY</code>, <code>HASH</code>, <code>CODE</code>, or <code>ANY</code>.</p>
 585 </dd>
 586 </li>
 587 <dt><strong><a name="item_attribute_handler__25s_doesn_27t_handle__25s_attri"><code>Attribute handler %s doesn't handle %s attributes</code></a></strong>
 588
 589 <dd>
 590 <p>A handler for attributes of the specified name <em>was</em> defined, but not
 591 for the specified type of declaration. Typically encountered whe trying
 592 to apply a <code>VAR</code> attribute handler to a subroutine, or a <code>SCALAR</code>
 593 attribute handler to some other type of variable.</p>
 594 </dd>
 595 </li>
 596 <dt><strong><a name="item_declaration_of__25s_attribute_in_package__25s_may_"><code>Declaration of %s attribute in package %s may clash with future reserved word</code></a></strong>
 597
 598 <dd>
 599 <p>A handler for an attributes with an all-lowercase name was declared. An
 600 attribute with an all-lowercase name might have a meaning to Perl
 601 itself some day, even though most don't yet. Use a mixed-case attribute
 602 name, instead.</p>
 603 </dd>
 604 </li>
 605 <dt><strong><a name="item_can_27t_have_two_attr_specifiers_on_one_subroutine"><code>Can't have two ATTR specifiers on one subroutine</code></a></strong>
 606
 607 <dd>
 608 <p>You just can't, okay?
 609 Instead, put all the specifications together with commas between them
 610 in a single <a href="#item_attr"><code>ATTR(specification)</code></a>.</p>
 611 </dd>
 612 </li>
 613 <dt><strong><a name="item_can_27t_autotie_a__25s"><code>Can't autotie a %s</code></a></strong>
 614
 615 <dd>
 616 <p>You can only declare autoties for types <code>&quot;SCALAR&quot;</code>, <code>&quot;ARRAY&quot;</code>, and
 617 <code>&quot;HASH&quot;</code>. They're the only things (apart from typeglobs -- which are
 618 not declarable) that Perl can tie.</p>
 619 </dd>
 620 </li>
 621 <dt><strong><a name="item_internal_error_3a__25s_symbol_went_missing"><code>Internal error: %s symbol went missing</code></a></strong>
 622
 623 <dd>
 624 <p>Something is rotten in the state of the program. An attributed
 625 subroutine ceased to exist between the point it was declared and the point
 626 at which its attribute <code>handler(s)</code> would have been called.</p>
 627 </dd>
 628 </li>
 629 <dt><strong><a name="item_won_27t_be_able_to_apply_end_handler"><code>Won't be able to apply END handler</code></a></strong>
 630
 631 <dd>
 632 <p>You have defined an END handler for an attribute that is being applied
 633 to a lexical variable.  Since the variable may not be available during END
 634 this won't happen.</p>
 635 </dd>
 636 </li>
 637 </dl>
 638 <p>
 639 </p>
 640 <hr />
 641 <h1><a name="author">AUTHOR</a></h1>
 642 <p>Damian Conway (<a href="mailto:damian@conway.org">damian@conway.org</a>)</p>
 643 <p>
 644 </p>
 645 <hr />
 646 <h1><a name="bugs">BUGS</a></h1>
 647 <p>There are undoubtedly serious bugs lurking somewhere in code this funky :-)
 648 Bug reports and other feedback are most welcome.</p>
 649 <p>
 650 </p>
 651 <hr />
 652 <h1><a name="copyright">COPYRIGHT</a></h1>
 653 <pre>
 654          Copyright (c) 2001, Damian Conway. All Rights Reserved.
 655        This module is free software. It may be used, redistributed
 656            and/or modified under the same terms as Perl itself.
 657 </pre>
 658 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 659 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 660 <big><strong><span class="block">&nbsp;Attribute::Handlers - Simpler definition of attribute handlers</span></strong></big>
 661 </td></tr>
 662 </table>
 663
 664 </body>
 665
 666 </html>