attributes.html 42.5 KB
Newer Older
1 2 3
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
4 5
<head>
  <title>attributes - perldoc.perl.org</title>
6 7
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  <meta http-equiv="Content-Language" content="en-gb">
8 9 10
  <link rel="search" type="application/opensearchdescription+xml" title="Search perldoc.perl.org" href="/static/search.xml"/>
  <link href="static/css-20100830.css" rel="stylesheet" rev="stylesheet" type="text/css" media="screen">
  <link href="static/exploreperl.css" rel="stylesheet" rev="stylesheet" type="text/css">
11 12
</head>

13 14 15 16 17 18 19
<body onLoad="perldoc.startup();" onPageShow="if (event.persisted) perldoc.startup();">
    <div id="page">
      
      <div id="header">
	<div id="homepage_link">
	  <a href="index.html"></a>
	</div>
20 21 22 23 24 25 26 27 28
	<div id="strapline">
	  Perl Programming Documentation
	</div>
	<div id="download_link" class="download">
	  <a href="http://www.perl.org/get.html">Download Perl</a>
	</div>
	<div id="explore_link" class="download">
	  <a id="explore_anchor" href="#">Explore</a>
	</div>
29
      </div>
30 31 32 33
      
      <div id="body">
        <div id="left_column">
          <div class="side_group">
34 35
            
	    <div class="side_panel doc_panel">
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
              <p>Manual</p>
              <ul>
                <li><a href="index-overview.html">Overview</a>
                <li><a href="index-tutorials.html">Tutorials</a>
                <li><a href="index-faq.html">FAQs</a>
                <li><a href="index-history.html">History / Changes</a>
                <li><a href="index-licence.html">License</a>
              </ul>
            </div>
            <div class="side_panel doc_panel">
              <p>Reference</p>
              <ul>
                <li><a href="index-language.html">Language</a>
                <li><a href="index-functions.html">Functions</a>
                <li><a href="perlop.html">Operators</a>
                <li><a href="perlvar.html">Special Variables</a>
                <li><a href="index-pragmas.html">Pragmas</a>
                <li><a href="index-utilities.html">Utilities</a>
54
                <li><a href="index-internals.html">Internals</a>
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276
                <li><a href="index-platforms.html">Platform Specific</a>
              </ul>
            </div>
            <div class="side_panel doc_panel">
              <p>Modules</p>
              <ul>
		<li>
		
                
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		    
		  
		
                  
		
                  
		
                  
		    
		  
		
                  
		
                  
		
		
                    <a href="index-modules-A.html">A</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-B.html">B</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-C.html">C</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-D.html">D</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-E.html">E</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-F.html">F</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-G.html">G</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-H.html">H</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-I.html">I</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-L.html">L</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-M.html">M</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-N.html">N</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-O.html">O</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-P.html">P</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-S.html">S</a>
                    
                      
                        <li>
                      
                    
                
                    <a href="index-modules-T.html">T</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-U.html">U</a>
                    
                      
                        &bull;
                      
                    
                
                    <a href="index-modules-X.html">X</a>
                    
                
              </ul>
            </div>
277 278 279 280 281 282 283 284
            
	      <div class="side_panel doc_panel">
		<p>Tools</p>
		<ul>
		  <li><a href="preferences.html">Preferences</a>
		</ul>
	      </div>
            
285 286 287 288 289 290 291 292 293
          </div>
        </div>
        <div id="centre_column">
          <div id="content_header">
            <div id="title_bar">
              <div id="page_name">
                <h1>attributes</h1>
              </div>
              <div id="perl_version">
294
                Perl 5 version 26.0 documentation
295
              </div>
296
              <div class="page_links" id="page_links_top">
297 298
                <a href="#" onClick="toolbar.goToTop();return false;">Go to top</a>
		
299 300
              </div>
	      <div class="page_links" id="page_links_bottom">
301
		
302
                  <a href="#" id="page_index_toggle">Show page index</a> &bull;
303
		
304 305 306 307 308 309 310
                <a href="#" id="recent_pages_toggle">Show recent pages</a>		
	      </div>
	      <div id="search_form">
		<form action="search.html" method="GET" id="search">
		  <input type="text" name="q" id="search_box" alt="Search">
		</form>
	      </div>
311 312 313 314 315 316 317 318 319 320 321
            </div>
            <div id="breadcrumbs">
                
    <a href="index.html">Home</a> &gt;
    
      
        <a href="index-pragmas.html">Pragmas</a> &gt;
      
    
    attributes
  
322

323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362
            </div>
          </div>
          <div id="content_body">
	    <!--[if lt IE 7]>
 <div class="noscript">
   <p>
     <strong>It looks like you're using Internet Explorer 6. This is a very old
     browser which does not offer full support for modern websites.</strong>
   </p>
   <p>
     Unfortunately this means that this website will not work on
     your computer.
   </p>
   <p>
     Don't miss out though! To view the site (and get a better experience from
     many other websites), simply upgrade to
     <a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet
Explorer 8</a>
     or download an alternative browser such as
     <a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>,
     <a href="http://www.apple.com/safari/download/">Safari</a>, or
     <a href="http://www.google.co.uk/chrome">Google Chrome</a>.
   </p>
   <p>
     All of these browsers are free. If you're using a PC at work, you may
     need to contact your IT administrator.
   </p>
 </div>
<![endif]-->
	    <noscript>
	      <div class="noscript">
	      <p>
                <strong>Please note: Many features of this site require JavaScript. You appear to have JavaScript disabled,
	        or are running a non-JavaScript capable web browser.</strong>
	      </p>
	      <p>
		To get the best experience, please enable JavaScript or download a modern web browser such as <a href="http://www.microsoft.com/windows/Internet-explorer/default.aspx">Internet Explorer 8</a>, <a href="http://www.mozilla.com/en-US/firefox/firefox.html">Firefox</a>, <a href="http://www.apple.com/safari/download/">Safari</a>, or <a href="http://www.google.co.uk/chrome">Google Chrome</a>.
              </p>
	      </div>
	    </noscript>
363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378

	    <div id="recent_pages" class="hud_container">
	      <div id="recent_pages_header" class="hud_header">
		<div id="recent_pages_close" class="hud_close"><a href="#" onClick="recentPages.hide();return false;"></a></div>
		<div id="recent_pages_title" class="hud_title"><span class="hud_span_top">Recently read</span></div>
		<div id="recent_pages_topright" class="hud_topright"></div>
	      </div>
	      <div id="recent_pages_content" class="hud_content">
	      </div>
	      <div id="recent_pages_footer" class="hud_footer">
		<div id="recent_pages_bottomleft" class="hud_bottomleft"></div>
		<div id="recent_pages_bottom" class="hud_bottom"><span class="hud_span_bottom"></span></div>
		<div id="recent_pages_resize" class="hud_resize"></div>
	      </div>
	    </div>
  
379 380 381 382 383 384
	    <div id="from_search"></div>
            <h1>attributes</h1>


  <!--    -->
<ul><li><a href="#NAME">NAME</a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><ul><li><a href="#What-import-does">What import does</a><li><a href="#Built-in-Attributes">Built-in Attributes</a><li><a href="#Available-Subroutines">Available Subroutines</a><li><a href="#Package-specific-Attribute-Handling">Package-specific Attribute Handling</a><li><a href="#Syntax-of-Attribute-Lists">Syntax of Attribute Lists</a></ul><li><a href="#EXPORTS">EXPORTS</a><ul><li><a href="#Default-exports">Default exports</a><li><a href="#Available-exports">Available exports</a><li><a href="#Export-tags-defined">Export tags defined</a></ul><li><a href="#EXAMPLES">EXAMPLES</a><li><a href="#MORE-EXAMPLES">MORE EXAMPLES</a><li><a href="#SEE-ALSO">SEE ALSO</a></ul><a name="NAME"></a><h1>NAME</h1>
385 386
<p>attributes - get/set subroutine or variable attributes</p>
<a name="SYNOPSIS"></a><h1>SYNOPSIS</h1>
387
<pre class="verbatim"><ol><li><a name="foo"></a>  sub <span class="m">foo</span> <span class="co">:</span> <span class="w">method</span> <span class="sc">;</span></li><li>  <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$x</span><span class="cm">,</span><span class="i">@y</span><span class="cm">,</span><span class="i">%z</span><span class="s">)</span> <span class="co">:</span> <span class="w">Bent</span> = <span class="n">1</span><span class="sc">;</span></li><li>  <a class="l_k" href="functions/my.html">my</a> <span class="i">$s</span> = <span class="i">sub </span><span class="co">:</span> <span class="w">method</span> <span class="s">{</span> ... <span class="s">}</span><span class="sc">;</span></li><li></li><li>  <a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span> <span class="s">(</span><span class="s">)</span><span class="sc">;</span>	<span class="c"># optional, to get subroutine declarations</span></li><li>  <a class="l_k" href="functions/my.html">my</a> <span class="i">@attrlist</span> = <span class="i">attributes::get</span><span class="s">(</span>\<span class="i">&amp;foo</span><span class="s">)</span><span class="sc">;</span></li><li></li><li>  <a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span> <span class="q">&#39;get&#39;</span><span class="sc">;</span> <span class="c"># import the attributes::get subroutine</span></li><li>  <a class="l_k" href="functions/my.html">my</a> <span class="i">@attrlist</span> = <span class="w">get</span> \<span class="i">&amp;foo</span><span class="sc">;</span></li></ol></pre><a name="DESCRIPTION"></a><h1>DESCRIPTION</h1>
388 389 390 391 392 393
<p>Subroutine declarations and definitions may optionally have attribute lists
associated with them.  (Variable <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> declarations also may, but see the
warning below.)  Perl handles these declarations by passing some information
about the call site and the thing being declared along with the attribute
list to this module.  In particular, the first example above is equivalent to
the following:</p>
394
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span> <span class="w">__PACKAGE__</span><span class="cm">,</span> \<span class="i">&amp;foo</span><span class="cm">,</span> <span class="q">&#39;method&#39;</span><span class="sc">;</span></li></ol></pre><p>The second example in the synopsis does something equivalent to this:</p>
395
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span> <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$x</span><span class="cm">,</span><span class="i">@y</span><span class="cm">,</span><span class="i">%z</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">attributes::-&gt;import</span><span class="s">(</span><span class="w">__PACKAGE__</span><span class="cm">,</span> \<span class="i">$x</span><span class="cm">,</span> <span class="q">&#39;Bent&#39;</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">attributes::-&gt;import</span><span class="s">(</span><span class="w">__PACKAGE__</span><span class="cm">,</span> \<span class="i">@y</span><span class="cm">,</span> <span class="q">&#39;Bent&#39;</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">attributes::-&gt;import</span><span class="s">(</span><span class="w">__PACKAGE__</span><span class="cm">,</span> \<span class="i">%z</span><span class="cm">,</span> <span class="q">&#39;Bent&#39;</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="s">(</span><span class="i">$x</span><span class="cm">,</span><span class="i">@y</span><span class="cm">,</span><span class="i">%z</span><span class="s">)</span> = <span class="n">1</span><span class="sc">;</span></li></ol></pre><p>Yes, that's a lot of expansion.</p>
396 397 398 399 400 401 402 403
<p><b>WARNING</b>: attribute declarations for variables are still evolving.
The semantics and interfaces of such declarations could change in
future versions.  They are present for purposes of experimentation
with what the semantics ought to be.  Do not rely on the current
implementation of this feature.</p>
<p>There are only a few attributes currently handled by Perl itself (or
directly by this module, depending on how you look at it.)  However,
package-specific attributes are allowed by an extension mechanism.
404
(See <a href="#Package-specific-Attribute-Handling">Package-specific Attribute Handling</a> below.)</p>
405 406 407 408 409
<p>The setting of subroutine attributes happens at compile time.
Variable attributes in <code class="inline"><a class="l_k" href="functions/our.html">our</a></code> declarations are also applied at compile time.
However, <code class="inline"><a class="l_k" href="functions/my.html">my</a></code> variables get their attributes applied at run-time.
This means that you have to <i>reach</i> the run-time component of the <code class="inline"><a class="l_k" href="functions/my.html">my</a></code>
before those attributes will get applied.  For example:</p>
410
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$x</span> <span class="co">:</span> <span class="w">Bent</span> = <span class="n">42</span> if <span class="n">0</span><span class="sc">;</span></li></ol></pre><p>will neither assign 42 to $x <i>nor</i> will it apply the <code class="inline"><span class="w">Bent</span></code>
411 412 413 414
 attribute
to the variable.</p>
<p>An attempt to set an unrecognized attribute is a fatal error.  (The
error is trappable, but it still stops the compilation within that
415 416
<code class="inline"><a class="l_k" href="functions/eval.html">eval</a></code>.)  Setting an attribute with a name that's all lowercase
letters that's not a built-in attribute (such as "foo") will result in
417
a warning with <b>-w</b> or <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">warnings</span> <span class="q">&#39;reserved&#39;</span></code>
418
.</p>
419 420 421 422 423
<a name="What-import-does"></a><h2>What <code class="inline"><a class="l_k" href="functions/import.html">import</a></code> does</h2>
<p>In the description it is mentioned that</p>
<pre class="verbatim"><ol><li><a name="foo"></a>  sub <span class="m">foo</span> <span class="co">:</span> <span class="w">method</span><span class="sc">;</span></li></ol></pre><p>is equivalent to</p>
<pre class="verbatim"><ol><li>  <a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span> <span class="w">__PACKAGE__</span><span class="cm">,</span> \<span class="i">&amp;foo</span><span class="cm">,</span> <span class="q">'method'</span><span class="sc">;</span></li></ol></pre><p>As you might know this calls the <code class="inline"><a class="l_k" href="functions/import.html">import</a></code> function of <code class="inline"><span class="w">attributes</span></code>
 at compile 
424 425
time with these parameters: 'attributes', the caller's package name, the reference 
to the code and 'method'.</p>
426
<pre class="verbatim"><ol><li>  <span class="w">attributes</span><span class="w">-&gt;import</span><span class="s">(</span> <span class="w">__PACKAGE__</span><span class="cm">,</span> \<span class="i">&amp;foo</span><span class="cm">,</span> <span class="q">'method'</span> <span class="s">)</span><span class="sc">;</span></li></ol></pre><p>So you want to know what <code class="inline"><a class="l_k" href="functions/import.html">import</a></code> actually does?</p>
427
<p>First of all <code class="inline"><a class="l_k" href="functions/import.html">import</a></code> gets the type of the third parameter ('CODE' in this case).
428 429
<code class="inline"><span class="w">attributes</span>.<span class="w">pm</span></code>
 checks if there is a subroutine called <code class="inline">MODIFY_&lt;reftype&gt;_ATTRIBUTES</code>
430 431 432 433
in the caller's namespace (here: 'main').  In this case a
subroutine <code class="inline"><span class="w">MODIFY_CODE_ATTRIBUTES</span></code>
 is required.  Then this
method is called to check if you have used a "bad attribute".
434
The subroutine call in this example would look like</p>
435
<pre class="verbatim"><ol><li>  <span class="i">MODIFY_CODE_ATTRIBUTES</span><span class="s">(</span> <span class="q">'main'</span><span class="cm">,</span> \<span class="i">&amp;foo</span><span class="cm">,</span> <span class="q">'method'</span> <span class="s">)</span><span class="sc">;</span></li></ol></pre><p><code class="inline">MODIFY_&lt;reftype&gt;_ATTRIBUTES</code> has to return a list of all "bad attributes".
436
If there are any bad attributes <code class="inline"><a class="l_k" href="functions/import.html">import</a></code> croaks.</p>
437
<p>(See <a href="#Package-specific-Attribute-Handling">Package-specific Attribute Handling</a> below.)</p>
438 439 440 441 442
<a name="Built-in-Attributes"></a><h2>Built-in Attributes</h2>
<p>The following are the built-in attributes for subroutines:</p>
<ul>
<li><a name="lvalue"></a><b>lvalue</b>
<p>Indicates that the referenced subroutine is a valid lvalue and can
443
be assigned to.  The subroutine must return a modifiable value such
444
as a scalar variable, as described in <a href="perlsub.html">perlsub</a>.</p>
445 446 447 448 449 450 451 452
<p>This module allows one to set this attribute on a subroutine that is
already defined.  For Perl subroutines (XSUBs are fine), it may or may not
do what you want, depending on the code inside the subroutine, with details
subject to change in future Perl versions.  You may run into problems with
lvalue context not being propagated properly into the subroutine, or maybe
even assertion failures.  For this reason, a warning is emitted if warnings
are enabled.  In other words, you should only do this if you really know
what you are doing.  You have been warned.</p>
453
</li>
454
<li><a name="method"></a><b>method</b>
455 456
<p>Indicates that the referenced subroutine
is a method.  A subroutine so marked
457 458
will not trigger the "Ambiguous call resolved as CORE::%s" warning.</p>
</li>
459 460 461 462 463 464 465 466 467 468 469 470
<li><a name="prototype(..)"></a><b>prototype(..)</b>
<p>The "prototype" attribute is an alternate means of specifying a prototype
on a sub.  The desired prototype is within the parens.</p>
<p>The prototype from the attribute is assigned to the sub immediately after
the prototype from the sub, which means that if both are declared at the
same time, the traditionally defined prototype is ignored.  In other words,
<code class="inline"><a name="foo"></a>sub <span class="m">foo($$)</span> <span class="co">:</span> <span class="q">prototype(@)</span> <span class="s">{</span><span class="s">}</span></code>
 is indistinguishable from <code class="inline"><a name="foo"></a>sub <span class="m">foo(@)</span><span class="s">{</span><span class="s">}</span></code>
.</p>
<p>If illegalproto warnings are enabled, the prototype declared inside this
attribute will be sanity checked at compile time.</p>
</li>
471
<li><a name="locked"></a><b>locked</b>
472
<p>The "locked" attribute is deprecated, and has no effect in 5.10.0 and later.
473 474
It was used as part of the now-removed "Perl 5.005 threads". It will
disappear in Perl 5.28, after which its use will be fatal.</p>
475
</li>
476 477 478 479 480 481
<li><a name="const"></a><b>const</b>
<p>This experimental attribute, introduced in Perl 5.22, only applies to
anonymous subroutines.  It causes the subroutine to be called as soon as
the <code class="inline"><a class="l_k" href="functions/sub.html">sub</a></code> expression is evaluated.  The return value is captured and
turned into a constant subroutine.</p>
</li>
482 483 484 485 486 487 488 489 490 491 492
</ul>
<p>The following are the built-in attributes for variables:</p>
<ul>
<li><a name="shared"></a><b>shared</b>
<p>Indicates that the referenced variable can be shared across different threads
when used in conjunction with the <a href="threads.html">threads</a> and <a href="threads/shared.html">threads::shared</a> modules.</p>
</li>
<li><a name="unique"></a><b>unique</b>
<p>The "unique" attribute is deprecated, and has no effect in 5.10.0 and later.
It used to indicate that a single copy of an <code class="inline"><a class="l_k" href="functions/our.html">our</a></code> variable was to be used by
all interpreters should the program happen to be running in a
493 494
multi-interpreter environment. It will disappear in 5.28, after which its
use will be fatal.</p>
495
</li>
496 497 498 499 500 501 502 503 504 505 506
</ul>
<a name="Available-Subroutines"></a><h2>Available Subroutines</h2>
<p>The following subroutines are available for general use once this module
has been loaded:</p>
<ul>
<li><a name="get"></a><b>get</b>
<p>This routine expects a single parameter--a reference to a
subroutine or variable.  It returns a list of attributes, which may be
empty.  If passed invalid arguments, it uses die() (via <a href="Carp.html">Carp::croak</a>)
to raise a fatal exception.  If it can find an appropriate package name
for a class method lookup, it will include the results from a
507 508
<code class="inline">FETCH_<i>type</i>_ATTRIBUTES</code> call in its return list, as described in
<a href="#Package-specific-Attribute-Handling">Package-specific Attribute Handling</a> below.
509 510 511 512 513 514 515
Otherwise, only <a href="#Built-in-Attributes">built-in attributes</a> will be returned.</p>
</li>
<li><a name="reftype"></a><b>reftype</b>
<p>This routine expects a single parameter--a reference to a subroutine or
variable.  It returns the built-in type of the referenced variable,
ignoring any package into which it might have been blessed.
This can be useful for determining the <i>type</i> value which forms part of
516
the method names described in <a href="#Package-specific-Attribute-Handling">Package-specific Attribute Handling</a> below.</p>
517 518 519 520 521 522
</li>
</ul>
<p>Note that these routines are <i>not</i> exported by default.</p>
<a name="Package-specific-Attribute-Handling"></a><h2>Package-specific Attribute Handling</h2>
<p><b>WARNING</b>: the mechanisms described here are still experimental.  Do not
rely on the current implementation.  In particular, there is no provision
523 524
for applying package attributes to 'cloned' copies of subroutines used as
closures.  (See <a href="perlref.html#Making-References">Making References in perlref</a> for information on closures.)
525 526 527
Package-specific attribute handling may change incompatibly in a future
release.</p>
<p>When an attribute list is present in a declaration, a check is made to see
528
whether an attribute 'modify' handler is present in the appropriate package
529
(or its @ISA inheritance tree).  Similarly, when <code class="inline"><span class="w">attributes::get</span></code>
530 531
 is
called on a valid reference, a check is made for an appropriate attribute
532
'fetch' handler.  See <a href="#EXAMPLES">EXAMPLES</a> to see how the "appropriate package"
533 534 535 536 537
determination works.</p>
<p>The handler names are based on the underlying type of the variable being
declared or of the reference passed.  Because these attributes are
associated with subroutine or variable declarations, this deliberately
ignores any possibility of being blessed into some package.  Thus, a
538 539
subroutine declaration uses "CODE" as its <i>type</i>, and even a blessed
hash reference uses "HASH" as its <i>type</i>.</p>
540 541 542
<p>The class methods invoked for modifying and fetching are these:</p>
<ul>
<li><a name="FETCH__type__ATTRIBUTES"></a><b>FETCH_<i>type</i>_ATTRIBUTES</b>
543 544 545 546
<p>This method is called with two arguments:  the relevant package name,
and a reference to a variable or subroutine for which package-defined
attributes are desired.  The expected return value is a list of
associated attributes.  This list may be empty.</p>
547 548 549 550 551 552 553 554
</li>
<li><a name="MODIFY__type__ATTRIBUTES"></a><b>MODIFY_<i>type</i>_ATTRIBUTES</b>
<p>This method is called with two fixed arguments, followed by the list of
attributes from the relevant declaration.  The two fixed arguments are
the relevant package name and a reference to the declared subroutine or
variable.  The expected return value is a list of attributes which were
not recognized by this handler.  Note that this allows for a derived class
to delegate a call to its base class, and then only examine the attributes
555
which the base class didn't already handle for it.</p>
556 557 558 559 560 561 562 563 564 565
<p>The call to this method is currently made <i>during</i> the processing of the
declaration.  In particular, this means that a subroutine reference will
probably be for an undefined subroutine, even if this declaration is
actually part of the definition.</p>
</li>
</ul>
<p>Calling <code class="inline"><span class="i">attributes::get</span><span class="s">(</span><span class="s">)</span></code>
 from within the scope of a null package
declaration <code class="inline"><a class="l_k" href="functions/package.html">package</a> <span class="sc">;</span></code>
 for an unblessed variable reference will
566
not provide any starting package name for the 'fetch' method lookup.
567 568 569 570 571 572 573 574 575 576 577 578
Thus, this circumstance will not result in a method call for package-defined
attributes.  A named subroutine knows to which symbol table entry it belongs
(or originally belonged), and it will use the corresponding package.
An anonymous subroutine knows the package name into which it was compiled
(unless it was also compiled with a null package declaration), and so it
will use that package name.</p>
<a name="Syntax-of-Attribute-Lists"></a><h2>Syntax of Attribute Lists</h2>
<p>An attribute list is a sequence of attribute specifications, separated by
whitespace or a colon (with optional whitespace).
Each attribute specification is a simple
name, optionally followed by a parenthesised parameter list.
If such a parameter list is present, it is scanned past as for the rules
579
for the <code class="inline"><a class="l_k" href="functions/q.html">q()</a></code> operator.  (See <a href="perlop.html#Quote-and-Quote-like-Operators">Quote and Quote-like Operators in perlop</a>.)
580 581
The parameter list is passed as it was found, however, and not as per <code class="inline"><a class="l_k" href="functions/q.html">q()</a></code>.</p>
<p>Some examples of syntactically valid attribute lists:</p>
582
<pre class="verbatim"><ol><li>    switch(10,foo(7,3))  :  expensive</li><li>    Ugly('\(") :Bad</li><li>    _5x5</li><li>    lvalue method</li></ol></pre><p>Some examples of syntactically invalid attribute lists (with annotation):</p>
583
<pre class="verbatim"><ol><li>    switch(10,foo()		# ()-string not balanced</li><li>    Ugly('(')			# ()-string not balanced</li><li>    5x5				# "5x5" not a valid identifier</li><li>    Y2::north			# "Y2::north" not a simple identifier</li><li>    foo + bar			# "+" neither a colon nor whitespace</li></ol></pre><a name="EXPORTS"></a><h1>EXPORTS</h1>
584 585 586
<a name="Default-exports"></a><h2>Default exports</h2>
<p>None.</p>
<a name="Available-exports"></a><h2>Available exports</h2>
587 588
<p>The routines <code class="inline"><span class="w">get</span></code>
 and <code class="inline"><span class="w">reftype</span></code>
589 590
 are exportable.</p>
<a name="Export-tags-defined"></a><h2>Export tags defined</h2>
591
<p>The <code class="inline"><span class="j">:</span><span class="w">ALL</span></code>
592 593 594
 tag will get all of the above exports.</p>
<a name="EXAMPLES"></a><h1>EXAMPLES</h1>
<p>Here are some samples of syntactically valid declarations, with annotation
595
as to how they resolve internally into <code class="inline"><a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span></code>
596
 invocations by
597 598
perl.  These examples are primarily useful to see how the "appropriate
package" is found for the possible method lookups for package-defined
599
attributes.</p>
600 601
<dl>
<dt>1.</dt><dd>
602
<p>Code:</p>
603
<pre class="verbatim"><ol><li><a name="package-Canine"></a>    package <span class="i">Canine</span><span class="sc">;</span></li><li><a name="package-Dog"></a>    package <span class="i">Dog</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="w">Canine</span> <span class="i">$spot</span> <span class="co">:</span> <span class="w">Watchful</span> <span class="sc">;</span></li></ol></pre><p>Effect:</p>
604 605
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span> <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">attributes::-&gt;import</span><span class="s">(</span><span class="w">Canine</span> <span class="cm">=&gt;</span> \<span class="i">$spot</span><span class="cm">,</span> <span class="q">&quot;Watchful&quot;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre></dd>
<dt>2.</dt><dd>
606
<p>Code:</p>
607
<pre class="verbatim"><ol><li><a name="package-Felis"></a>    package <span class="i">Felis</span><span class="sc">;</span></li><li>    <a class="l_k" href="functions/my.html">my</a> <span class="i">$cat</span> <span class="co">:</span> <span class="w">Nervous</span><span class="sc">;</span></li></ol></pre><p>Effect:</p>
608 609
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span> <span class="s">(</span><span class="s">)</span><span class="sc">;</span></li><li>    <span class="i">attributes::-&gt;import</span><span class="s">(</span><span class="w">Felis</span> <span class="cm">=&gt;</span> \<span class="i">$cat</span><span class="cm">,</span> <span class="q">&quot;Nervous&quot;</span><span class="s">)</span><span class="sc">;</span></li></ol></pre></dd>
<dt>3.</dt><dd>
610
<p>Code:</p>
611 612 613
<pre class="verbatim"><ol><li><a name="package-X"></a>    package <span class="i">X</span><span class="sc">;</span></li><li><a name="foo"></a>    sub <span class="m">foo</span> <span class="co">:</span> <span class="w">lvalue</span> <span class="sc">;</span></li></ol></pre><p>Effect:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span> <span class="w">X</span> <span class="cm">=&gt;</span> \<span class="i">&amp;foo</span><span class="cm">,</span> <span class="q">&quot;lvalue&quot;</span><span class="sc">;</span></li></ol></pre></dd>
<dt>4.</dt><dd>
614
<p>Code:</p>
615 616 617
<pre class="verbatim"><ol><li><a name="package-X"></a>    package <span class="i">X</span><span class="sc">;</span></li><li><a name="Y::x"></a>    sub <span class="m">Y::x</span> <span class="co">:</span> <span class="w">lvalue</span> <span class="s">{</span> <span class="n">1</span> <span class="s">}</span></li></ol></pre><p>Effect:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span> <span class="w">Y</span> <span class="cm">=&gt;</span> \<span class="i">&amp;Y::x</span><span class="cm">,</span> <span class="q">&quot;lvalue&quot;</span><span class="sc">;</span></li></ol></pre></dd>
<dt>5.</dt><dd>
618
<p>Code:</p>
619 620 621
<pre class="verbatim"><ol><li><a name="package-X"></a>    package <span class="i">X</span><span class="sc">;</span></li><li><a name="foo"></a>    sub <span class="m">foo</span> <span class="s">{</span> <span class="n">1</span> <span class="s">}</span></li><li></li><li><a name="package-Y"></a>    package <span class="i">Y</span><span class="sc">;</span></li><li>    BEGIN <span class="s">{</span> <span class="i">*bar</span> = \<span class="i">&amp;X::foo</span><span class="sc">;</span> <span class="s">}</span></li><li></li><li><a name="package-Z"></a>    package <span class="i">Z</span><span class="sc">;</span></li><li><a name="Y::bar"></a>    sub <span class="m">Y::bar</span> <span class="co">:</span> <span class="w">lvalue</span> <span class="sc">;</span></li></ol></pre><p>Effect:</p>
<pre class="verbatim"><ol><li>    <a class="l_k" href="functions/use.html">use</a> <span class="w">attributes</span> <span class="w">X</span> <span class="cm">=&gt;</span> \<span class="i">&amp;X::foo</span><span class="cm">,</span> <span class="q">&quot;lvalue&quot;</span><span class="sc">;</span></li></ol></pre></dd>
</dl>
622
<p>This last example is purely for purposes of completeness.  You should not
623
be trying to mess with the attributes of something in a package that's
624
not your own.</p>
625
<a name="MORE-EXAMPLES"></a><h1>MORE EXAMPLES</h1>
626 627
<dl>
<dt>1.</dt><dd>
628 629 630
<pre class="verbatim"><ol><li><a name="MODIFY_CODE_ATTRIBUTES"></a>    sub <span class="m">MODIFY_CODE_ATTRIBUTES</span> <span class="s">{</span></li><li>       <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$class</span><span class="cm">,</span><span class="i">$code</span><span class="cm">,</span><span class="i">@attrs</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li></li><li>       <a class="l_k" href="functions/my.html">my</a> <span class="i">$allowed</span> = <span class="q">'MyAttribute'</span><span class="sc">;</span></li><li>       <a class="l_k" href="functions/my.html">my</a> <span class="i">@bad</span> = <a class="l_k" href="functions/grep.html">grep</a> <span class="s">{</span> <span class="i">$_</span> ne <span class="i">$allowed</span> <span class="s">}</span> <span class="i">@attrs</span><span class="sc">;</span></li><li></li><li>       <a class="l_k" href="functions/return.html">return</a> <span class="i">@bad</span><span class="sc">;</span></li><li>    <span class="s">}</span></li><li></li><li><a name="foo"></a>    sub <span class="m">foo</span> <span class="co">:</span> <span class="w">MyAttribute</span> <span class="s">{</span></li><li>       <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;foo\n&quot;</span><span class="sc">;</span></li><li>    <span class="s">}</span></li></ol></pre><p>This example runs.  At compile time
<code class="inline"><span class="w">MODIFY_CODE_ATTRIBUTES</span></code>
 is called.  In that
631
subroutine, we check if any attribute is disallowed and we return a list of
632
these "bad attributes".</p>
633
<p>As we return an empty list, everything is fine.</p>
634 635 636
</dd>
<dt>2.</dt><dd>
<pre class="verbatim"><ol><li><a name="MODIFY_CODE_ATTRIBUTES"></a>  sub <span class="m">MODIFY_CODE_ATTRIBUTES</span> <span class="s">{</span></li><li>     <a class="l_k" href="functions/my.html">my</a> <span class="s">(</span><span class="i">$class</span><span class="cm">,</span><span class="i">$code</span><span class="cm">,</span><span class="i">@attrs</span><span class="s">)</span> = <span class="i">@_</span><span class="sc">;</span></li><li></li><li>     <a class="l_k" href="functions/my.html">my</a> <span class="i">$allowed</span> = <span class="q">'MyAttribute'</span><span class="sc">;</span></li><li>     <a class="l_k" href="functions/my.html">my</a> <span class="i">@bad</span> = <a class="l_k" href="functions/grep.html">grep</a><span class="s">{</span> <span class="i">$_</span> ne <span class="i">$allowed</span> <span class="s">}</span><span class="i">@attrs</span><span class="sc">;</span></li><li></li><li>     <a class="l_k" href="functions/return.html">return</a> <span class="i">@bad</span><span class="sc">;</span></li><li>  <span class="s">}</span></li><li></li><li><a name="foo"></a>  sub <span class="m">foo</span> <span class="co">:</span> <span class="w">MyAttribute</span> <span class="w">Test</span> <span class="s">{</span></li><li>     <a class="l_k" href="functions/print.html">print</a> <span class="q">&quot;foo\n&quot;</span><span class="sc">;</span></li><li>  <span class="s">}</span></li></ol></pre><p>This example is aborted at compile time as we use the attribute "Test" which
637 638 639
isn't allowed.  <code class="inline"><span class="w">MODIFY_CODE_ATTRIBUTES</span></code>

returns a list that contains a single
640 641 642
element ('Test').</p>
</dd>
</dl>
643
<a name="SEE-ALSO"></a><h1>SEE ALSO</h1>
644 645
<p><a href="perlsub.html#Private-Variables-via-my()">Private Variables via my() in perlsub</a> and
<a href="perlsub.html#Subroutine-Attributes">Subroutine Attributes in perlsub</a> for details on the basic declarations;
646
<a href="functions/use.html">use</a> for details on the normal invocation mechanism.</p>
647 648 649 650




651 652 653 654 655
  <div id="page_index" class="hud_container">
    <div id="page_index_header" class="hud_header">
      <div id="page_index_close" class="hud_close"><a href="#" onClick="pageIndex.hide();return false;"></a></div>
      <div id="page_index_title" class="hud_title"><span class="hud_span_top">Page index</span></div>
      <div id="page_index_topright" class="hud_topright"></div>
656
    </div>
657
    <div id="page_index_content" class="hud_content">
658 659
      <ul><li><a href="#NAME">NAME</a><li><a href="#SYNOPSIS">SYNOPSIS</a><li><a href="#DESCRIPTION">DESCRIPTION</a><ul><li><a href="#What-import-does">What import does</a><li><a href="#Built-in-Attributes">Built-in Attributes</a><li><a href="#Available-Subroutines">Available Subroutines</a><li><a href="#Package-specific-Attribute-Handling">Package-specific Attribute Handling</a><li><a href="#Syntax-of-Attribute-Lists">Syntax of Attribute Lists</a></ul><li><a href="#EXPORTS">EXPORTS</a><ul><li><a href="#Default-exports">Default exports</a><li><a href="#Available-exports">Available exports</a><li><a href="#Export-tags-defined">Export tags defined</a></ul><li><a href="#EXAMPLES">EXAMPLES</a><li><a href="#MORE-EXAMPLES">MORE EXAMPLES</a><li><a href="#SEE-ALSO">SEE ALSO</a></ul>
    </div>
660 661 662 663
    <div id="page_index_footer" class="hud_footer">
      <div id="page_index_bottomleft" class="hud_bottomleft"></div>
      <div id="page_index_bottom" class="hud_bottom"><span class="hud_span_bottom"></span></div>
      <div id="page_index_resize" class="hud_resize"></div>
664 665 666
    </div>
  </div>

667 668 669 670 671 672 673

	    &nbsp;
          </div>
          <div id="content_footer">
          </div>
        </div>
        <div class="clear"></div>
674
      </div>
675
      
676 677 678 679 680 681 682 683 684
    <div id="footer">
      <div id="footer_content">
        <div id="footer_strapline">
          perldoc.perl.org - Official documentation for the Perl programming language
        </div>
        <div id="footer_links">
          <div id="address">
            <p class="name">Contact details</p>
            <p class="address">
685
	      Site maintained by <a href="mailto:jj@jonallen.info">Jon Allen (JJ)</a><br>
686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721
	    </p>
            <p class="contact">
              Documentation maintained by the <a href="http://lists.cpan.org/showlist.cgi?name=perl5-porters">Perl 5 Porters</a>
            </p>
          </div>
          <ul class="f1">
            <li>Manual
              <ul class="f2">
                <li><a href="index-overview.html">Overview</a>
                <li><a href="index-tutorials.html">Tutorials</a>
                <li><a href="index-faq.html">FAQs</a>
                <li><a href="index-history.html">Changes</a>
              </ul>
            <li>Reference
              <ul class="f2">
                <li><a href="index-language.html">Language</a>
                <li><a href="index-functions.html">Functions</a>
                <li><a href="perlop.html">Operators</a>
                <li><a href="perlvar.html">Variables</a>
              </ul>
            <li>Modules
              <ul class="f2">
                <li><a href="index-modules-A.html">Modules</a>
                <li><a href="index-pragmas.html">Pragmas</a>
                <li><a href="index-utilities.html">Utilities</a>
              </ul>
            <li>Misc
              <ul class="f2">
                <li><a href="index-licence.html">License</a>
                <li><a href="index-internals.html">Internals</a>
                <li><a href="index-platforms.html">Platforms</a>
              </ul>          </ul>
          <div class="clear"></div>
        </div>
      </div>
      <div id="footer_end">
722
      </div>
723
    </div>
724
      
725
    </div>
726 727
      <script language="JavaScript" type="text/javascript" src="static/exploreperl.js"></script>
      <script language="JavaScript" src="static/combined-20100403.js" type="text/javascript"></script>
728 729 730 731 732
<script language="JavaScript" type="text/javascript">
  perldoc.setPath(0);
  perldoc.pageName    = 'attributes';
  perldoc.pageAddress = 'attributes.html';
  perldoc.contentPage = 1;
733 734
  explorePerl.render();
  explorePerl.addEvents('explore_anchor');
735 736 737
</script>
    
  </body>
738
</html>