mingw/html/lib/attributes.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>attributes - get/set subroutine or variable attributes</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;attributes - get/set subroutine or variable attributes</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="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <ul>
  26
  27                 <li><a href="#builtin_attributes">Built-in Attributes</a></li>
  28                 <li><a href="#available_subroutines">Available Subroutines</a></li>
  29                 <li><a href="#packagespecific_attribute_handling">Package-specific Attribute Handling</a></li>
  30                 <li><a href="#syntax_of_attribute_lists">Syntax of Attribute Lists</a></li>
  31         </ul>
  32
  33         <li><a href="#exports">EXPORTS</a></li>
  34         <ul>
  35
  36                 <li><a href="#default_exports">Default exports</a></li>
  37                 <li><a href="#available_exports">Available exports</a></li>
  38                 <li><a href="#export_tags_defined">Export tags defined</a></li>
  39         </ul>
  40
  41         <li><a href="#examples">EXAMPLES</a></li>
  42         <li><a href="#see_also">SEE ALSO</a></li>
  43 </ul>
  44 <!-- INDEX END -->
  45
  46 <hr />
  47 <p>
  48 </p>
  49 <h1><a name="name">NAME</a></h1>
  50 <p>attributes - get/set subroutine or variable attributes</p>
  51 <p>
  52 </p>
  53 <hr />
  54 <h1><a name="synopsis">SYNOPSIS</a></h1>
  55 <pre>
  56   sub foo : method ;
  57   my ($x,@y,%z) : Bent = 1;
  58   my $s = sub : method { ... };</pre>
  59 <pre>
  60   use attributes ();    # optional, to get subroutine declarations
  61   my @attrlist = attributes::get(\&amp;foo);</pre>
  62 <pre>
  63   use attributes 'get'; # import the attributes::get subroutine
  64   my @attrlist = get \&amp;foo;</pre>
  65 <p>
  66 </p>
  67 <hr />
  68 <h1><a name="description">DESCRIPTION</a></h1>
  69 <p>Subroutine declarations and definitions may optionally have attribute lists
  70 associated with them.  (Variable <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_my"><code>my</code></a> declarations also may, but see the
  71 warning below.)  Perl handles these declarations by passing some information
  72 about the call site and the thing being declared along with the attribute
  73 list to this module.  In particular, the first example above is equivalent to
  74 the following:</p>
  75 <pre>
  76     use attributes __PACKAGE__, \&amp;foo, 'method';</pre>
  77 <p>The second example in the synopsis does something equivalent to this:</p>
  78 <pre>
  79     use attributes ();
  80     my ($x,@y,%z);
  81     attributes::-&gt;import(__PACKAGE__, \$x, 'Bent');
  82     attributes::-&gt;import(__PACKAGE__, \@y, 'Bent');
  83     attributes::-&gt;import(__PACKAGE__, \%z, 'Bent');
  84     ($x,@y,%z) = 1;</pre>
  85 <p>Yes, that's a lot of expansion.</p>
  86 <p><strong>WARNING</strong>: attribute declarations for variables are still evolving.
  87 The semantics and interfaces of such declarations could change in
  88 future versions.  They are present for purposes of experimentation
  89 with what the semantics ought to be.  Do not rely on the current
  90 implementation of this feature.</p>
  91 <p>There are only a few attributes currently handled by Perl itself (or
  92 directly by this module, depending on how you look at it.)  However,
  93 package-specific attributes are allowed by an extension mechanism.
  94 (See <a href="#packagespecific_attribute_handling">Package-specific Attribute Handling</a> below.)</p>
  95 <p>The setting of subroutine attributes happens at compile time.
  96 Variable attributes in <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_our"><code>our</code></a> declarations are also applied at compile time.
  97 However, <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_my"><code>my</code></a> variables get their attributes applied at run-time.
  98 This means that you have to <em>reach</em> the run-time component of the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_my"><code>my</code></a>
  99 before those attributes will get applied.  For example:</p>
 100 <pre>
 101     my $x : Bent = 42 if 0;</pre>
 102 <p>will neither assign 42 to $x <em>nor</em> will it apply the <code>Bent</code> attribute
 103 to the variable.</p>
 104 <p>An attempt to set an unrecognized attribute is a fatal error.  (The
 105 error is trappable, but it still stops the compilation within that
 106 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_eval"><code>eval</code></a>.)  Setting an attribute with a name that's all lowercase
 107 letters that's not a built-in attribute (such as ``foo'') will result in
 108 a warning with <strong>-w</strong> or <code>use warnings 'reserved'</code>.</p>
 109 <p>
 110 </p>
 111 <h2><a name="builtin_attributes">Built-in Attributes</a></h2>
 112 <p>The following are the built-in attributes for subroutines:</p>
 113 <dl>
 114 <dt><strong><a name="item_locked">locked</a></strong>
 115
 116 <dd>
 117 <p><strong>5.005 threads only!  The use of the ``locked'' attribute currently
 118 only makes sense if you are using the deprecated ``Perl 5.005 threads''
 119 implementation of threads.</strong></p>
 120 </dd>
 121 <dd>
 122 <p>Setting this attribute is only meaningful when the subroutine or
 123 method is to be called by multiple threads.  When set on a method
 124 subroutine (i.e., one marked with the <strong>method</strong> attribute below),
 125 Perl ensures that any invocation of it implicitly locks its first
 126 argument before execution.  When set on a non-method subroutine,
 127 Perl ensures that a lock is taken on the subroutine itself before
 128 execution.  The semantics of the lock are exactly those of one
 129 explicitly taken with the <code>lock</code> operator immediately after the
 130 subroutine is entered.</p>
 131 </dd>
 132 </li>
 133 <dt><strong><a name="item_method">method</a></strong>
 134
 135 <dd>
 136 <p>Indicates that the referenced subroutine is a method.
 137 This has a meaning when taken together with the <strong>locked</strong> attribute,
 138 as described there.  It also means that a subroutine so marked
 139 will not trigger the ``Ambiguous call resolved as CORE::%s'' warning.</p>
 140 </dd>
 141 </li>
 142 <dt><strong><a name="item_lvalue">lvalue</a></strong>
 143
 144 <dd>
 145 <p>Indicates that the referenced subroutine is a valid lvalue and can
 146 be assigned to. The subroutine must return a modifiable value such
 147 as a scalar variable, as described in <a href="file://C|\msysgit\mingw\html/pod/perlsub.html">the perlsub manpage</a>.</p>
 148 </dd>
 149 </li>
 150 </dl>
 151 <p>For global variables there is <code>unique</code> attribute: see <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_our">our in the perlfunc manpage</a>.</p>
 152 <p>
 153 </p>
 154 <h2><a name="available_subroutines">Available Subroutines</a></h2>
 155 <p>The following subroutines are available for general use once this module
 156 has been loaded:</p>
 157 <dl>
 158 <dt><strong><a name="item_get">get</a></strong>
 159
 160 <dd>
 161 <p>This routine expects a single parameter--a reference to a
 162 subroutine or variable.  It returns a list of attributes, which may be
 163 empty.  If passed invalid arguments, it uses <code>die()</code> (via <a href="file://C|\msysgit\mingw\html/lib/Carp.html">Carp::croak</a>)
 164 to raise a fatal exception.  If it can find an appropriate package name
 165 for a class method lookup, it will include the results from a
 166 <a href="#item_fetch_type_attributes"><code>FETCH_type_ATTRIBUTES</code></a> call in its return list, as described in
 167 <a href="#packagespecific_attribute_handling">Package-specific Attribute Handling</a> below.
 168 Otherwise, only <a href="#builtin_attributes">built-in attributes</a> will be returned.</p>
 169 </dd>
 170 </li>
 171 <dt><strong><a name="item_reftype">reftype</a></strong>
 172
 173 <dd>
 174 <p>This routine expects a single parameter--a reference to a subroutine or
 175 variable.  It returns the built-in type of the referenced variable,
 176 ignoring any package into which it might have been blessed.
 177 This can be useful for determining the <em>type</em> value which forms part of
 178 the method names described in <a href="#packagespecific_attribute_handling">Package-specific Attribute Handling</a> below.</p>
 179 </dd>
 180 </li>
 181 </dl>
 182 <p>Note that these routines are <em>not</em> exported by default.</p>
 183 <p>
 184 </p>
 185 <h2><a name="packagespecific_attribute_handling">Package-specific Attribute Handling</a></h2>
 186 <p><strong>WARNING</strong>: the mechanisms described here are still experimental.  Do not
 187 rely on the current implementation.  In particular, there is no provision
 188 for applying package attributes to 'cloned' copies of subroutines used as
 189 closures.  (See <a href="file://C|\msysgit\mingw\html/pod/perlref.html#making_references">Making References in the perlref manpage</a> for information on closures.)
 190 Package-specific attribute handling may change incompatibly in a future
 191 release.</p>
 192 <p>When an attribute list is present in a declaration, a check is made to see
 193 whether an attribute 'modify' handler is present in the appropriate package
 194 (or its @ISA inheritance tree).  Similarly, when <code>attributes::get</code> is
 195 called on a valid reference, a check is made for an appropriate attribute
 196 'fetch' handler.  See <a href="#examples">EXAMPLES</a> to see how the ``appropriate package''
 197 determination works.</p>
 198 <p>The handler names are based on the underlying type of the variable being
 199 declared or of the reference passed.  Because these attributes are
 200 associated with subroutine or variable declarations, this deliberately
 201 ignores any possibility of being blessed into some package.  Thus, a
 202 subroutine declaration uses ``CODE'' as its <em>type</em>, and even a blessed
 203 hash reference uses ``HASH'' as its <em>type</em>.</p>
 204 <p>The class methods invoked for modifying and fetching are these:</p>
 205 <dl>
 206 <dt><strong><a name="item_fetch_type_attributes">FETCH_<em>type</em>_ATTRIBUTES</a></strong>
 207
 208 <dd>
 209 <p>This method receives a single argument, which is a reference to the
 210 variable or subroutine for which package-defined attributes are desired.
 211 The expected return value is a list of associated attributes.
 212 This list may be empty.</p>
 213 </dd>
 214 </li>
 215 <dt><strong><a name="item_modify_type_attributes">MODIFY_<em>type</em>_ATTRIBUTES</a></strong>
 216
 217 <dd>
 218 <p>This method is called with two fixed arguments, followed by the list of
 219 attributes from the relevant declaration.  The two fixed arguments are
 220 the relevant package name and a reference to the declared subroutine or
 221 variable.  The expected return value is a list of attributes which were
 222 not recognized by this handler.  Note that this allows for a derived class
 223 to delegate a call to its base class, and then only examine the attributes
 224 which the base class didn't already handle for it.</p>
 225 </dd>
 226 <dd>
 227 <p>The call to this method is currently made <em>during</em> the processing of the
 228 declaration.  In particular, this means that a subroutine reference will
 229 probably be for an undefined subroutine, even if this declaration is
 230 actually part of the definition.</p>
 231 </dd>
 232 </li>
 233 </dl>
 234 <p>Calling <a href="#item_get"><code>attributes::get()</code></a> from within the scope of a null package
 235 declaration <code>package ;</code> for an unblessed variable reference will
 236 not provide any starting package name for the 'fetch' method lookup.
 237 Thus, this circumstance will not result in a method call for package-defined
 238 attributes.  A named subroutine knows to which symbol table entry it belongs
 239 (or originally belonged), and it will use the corresponding package.
 240 An anonymous subroutine knows the package name into which it was compiled
 241 (unless it was also compiled with a null package declaration), and so it
 242 will use that package name.</p>
 243 <p>
 244 </p>
 245 <h2><a name="syntax_of_attribute_lists">Syntax of Attribute Lists</a></h2>
 246 <p>An attribute list is a sequence of attribute specifications, separated by
 247 whitespace or a colon (with optional whitespace).
 248 Each attribute specification is a simple
 249 name, optionally followed by a parenthesised parameter list.
 250 If such a parameter list is present, it is scanned past as for the rules
 251 for the <code>q()</code> operator.  (See <a href="file://C|\msysgit\mingw\html/pod/perlop.html#quote_and_quotelike_operators">Quote and Quote-like Operators in the perlop manpage</a>.)
 252 The parameter list is passed as it was found, however, and not as per <code>q()</code>.</p>
 253 <p>Some examples of syntactically valid attribute lists:</p>
 254 <pre>
 255     switch(10,foo(7,3))  :  expensive
 256     Ugly('\(&quot;) :Bad
 257     _5x5
 258     locked method</pre>
 259 <p>Some examples of syntactically invalid attribute lists (with annotation):</p>
 260 <pre>
 261     switch(10,foo()             # ()-string not balanced
 262     Ugly('(')                   # ()-string not balanced
 263     5x5                         # &quot;5x5&quot; not a valid identifier
 264     Y2::north                   # &quot;Y2::north&quot; not a simple identifier
 265     foo + bar                   # &quot;+&quot; neither a colon nor whitespace</pre>
 266 <p>
 267 </p>
 268 <hr />
 269 <h1><a name="exports">EXPORTS</a></h1>
 270 <p>
 271 </p>
 272 <h2><a name="default_exports">Default exports</a></h2>
 273 <p>None.</p>
 274 <p>
 275 </p>
 276 <h2><a name="available_exports">Available exports</a></h2>
 277 <p>The routines <a href="#item_get"><code>get</code></a> and <a href="#item_reftype"><code>reftype</code></a> are exportable.</p>
 278 <p>
 279 </p>
 280 <h2><a name="export_tags_defined">Export tags defined</a></h2>
 281 <p>The <code>:ALL</code> tag will get all of the above exports.</p>
 282 <p>
 283 </p>
 284 <hr />
 285 <h1><a name="examples">EXAMPLES</a></h1>
 286 <p>Here are some samples of syntactically valid declarations, with annotation
 287 as to how they resolve internally into <code>use attributes</code> invocations by
 288 perl.  These examples are primarily useful to see how the ``appropriate
 289 package'' is found for the possible method lookups for package-defined
 290 attributes.</p>
 291 <ol>
 292 <li>
 293 <p>Code:</p>
 294 <pre>
 295     package Canine;
 296     package Dog;
 297     my Canine $spot : Watchful ;</pre>
 298 <p>Effect:</p>
 299 <pre>
 300     use attributes ();
 301     attributes::-&gt;import(Canine =&gt; \$spot, &quot;Watchful&quot;);</pre>
 302 </li>
 303 <li>
 304 <p>Code:</p>
 305 <pre>
 306     package Felis;
 307     my $cat : Nervous;</pre>
 308 <p>Effect:</p>
 309 <pre>
 310     use attributes ();
 311     attributes::-&gt;import(Felis =&gt; \$cat, &quot;Nervous&quot;);</pre>
 312 </li>
 313 <li>
 314 <p>Code:</p>
 315 <pre>
 316     package X;
 317     sub foo : locked ;</pre>
 318 <p>Effect:</p>
 319 <pre>
 320     use attributes X =&gt; \&amp;foo, &quot;locked&quot;;</pre>
 321 </li>
 322 <li>
 323 <p>Code:</p>
 324 <pre>
 325     package X;
 326     sub Y::x : locked { 1 }</pre>
 327 <p>Effect:</p>
 328 <pre>
 329     use attributes Y =&gt; \&amp;Y::x, &quot;locked&quot;;</pre>
 330 </li>
 331 <li>
 332 <p>Code:</p>
 333 <pre>
 334     package X;
 335     sub foo { 1 }</pre>
 336 <pre>
 337     package Y;
 338     BEGIN { *bar = \&amp;X::foo; }</pre>
 339 <pre>
 340     package Z;
 341     sub Y::bar : locked ;</pre>
 342 <p>Effect:</p>
 343 <pre>
 344     use attributes X =&gt; \&amp;X::foo, &quot;locked&quot;;</pre>
 345 </li>
 346 </ol>
 347 <p>This last example is purely for purposes of completeness.  You should not
 348 be trying to mess with the attributes of something in a package that's
 349 not your own.</p>
 350 <p>
 351 </p>
 352 <hr />
 353 <h1><a name="see_also">SEE ALSO</a></h1>
 354 <p><a href="file://C|\msysgit\mingw\html/pod/perlsub.html#private_variables_via_my__">Private Variables via my() in the perlsub manpage</a> and
 355 <a href="file://C|\msysgit\mingw\html/pod/perlsub.html#subroutine_attributes">Subroutine Attributes in the perlsub manpage</a> for details on the basic declarations;
 356 <a href="file://C|\msysgit\mingw\html/lib/attrs.html">the attrs manpage</a> for the obsolescent form of subroutine attribute specification
 357 which this module replaces;
 358 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_use">use in the perlfunc manpage</a> for details on the normal invocation mechanism.</p>
 359 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 360 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 361 <big><strong><span class="block">&nbsp;attributes - get/set subroutine or variable attributes</span></strong></big>
 362 </td></tr>
 363 </table>
 364
 365 </body>
 366
 367 </html>