home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _5c182ac76416713236e41d72ff3cf4a5 < prev    next >
Text File  |  2000-03-23  |  15KB  |  324 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>attributes - get/set subroutine or variable attributes</TITLE>
  5. <LINK REL="stylesheet" HREF="../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> attributes - get/set subroutine or variable attributes</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  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. <H1><A NAME="name">NAME</A></H1>
  49. <P>attributes - get/set subroutine or variable attributes</P>
  50. <P>
  51. <HR>
  52. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  53. <UL>
  54. <LI>Linux</LI>
  55. <LI>Solaris</LI>
  56. <LI>Windows</LI>
  57. </UL>
  58. <HR>
  59. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  60. <PRE>
  61.   sub foo : method ;
  62.   my ($x,@y,%z) : Bent ;
  63.   my $s = sub : method { ... };</PRE>
  64. <PRE>
  65.   use attributes ();    # optional, to get subroutine declarations
  66.   my @attrlist = attributes::get(\&foo);</PRE>
  67. <PRE>
  68.   use attributes 'get'; # import the attributes::get subroutine
  69.   my @attrlist = get \&foo;</PRE>
  70. <P>
  71. <HR>
  72. <H1><A NAME="description">DESCRIPTION</A></H1>
  73. <P>Subroutine declarations and definitions may optionally have attribute lists
  74. associated with them.  (Variable <A HREF="../lib/Pod/perlfunc.html#item_my"><CODE>my</CODE></A> declarations also may, but see the
  75. warning below.)  Perl handles these declarations by passing some information
  76. about the call site and the thing being declared along with the attribute
  77. list to this module.  In particular, the first example above is equivalent to
  78. the following:</P>
  79. <PRE>
  80.     use attributes __PACKAGE__, \&foo, 'method';</PRE>
  81. <P>The second example in the synopsis does something equivalent to this:</P>
  82. <PRE>
  83.     use attributes __PACKAGE__, \$x, 'Bent';
  84.     use attributes __PACKAGE__, \@y, 'Bent';
  85.     use attributes __PACKAGE__, \%z, 'Bent';</PRE>
  86. <P>Yes, that's three invocations.</P>
  87. <P><STRONG>WARNING</STRONG>: attribute declarations for variables are an <EM>experimental</EM>
  88. feature.  The semantics of such declarations could change or be removed
  89. in future versions.  They are present for purposes of experimentation
  90. with what the semantics ought to be.  Do not rely on the current
  91. implementation of this feature.</P>
  92. <P>There are only a few attributes currently handled by Perl itself (or
  93. directly by this module, depending on how you look at it.)  However,
  94. package-specific attributes are allowed by an extension mechanism.
  95. (See <A HREF="#packagespecific attribute handling">Package-specific Attribute Handling</A> below.)</P>
  96. <P>The setting of attributes happens at compile time.  An attempt to set
  97. an unrecognized attribute is a fatal error.  (The error is trappable, but
  98. it still stops the compilation within that <A HREF="../lib/Pod/perlfunc.html#item_eval"><CODE>eval</CODE></A>.)  Setting an attribute
  99. with a name that's all lowercase letters that's not a built-in attribute
  100. (such as ``foo'')
  101. will result in a warning with <STRONG>-w</STRONG> or <CODE>use warnings 'reserved'</CODE>.</P>
  102. <P>
  103. <H2><A NAME="builtin attributes">Built-in Attributes</A></H2>
  104. <P>The following are the built-in attributes for subroutines:</P>
  105. <DL>
  106. <DT><STRONG><A NAME="item_locked">locked</A></STRONG><BR>
  107. <DD>
  108. Setting this attribute is only meaningful when the subroutine or
  109. method is to be called by multiple threads.  When set on a method
  110. subroutine (i.e., one marked with the <STRONG>method</STRONG> attribute below),
  111. Perl ensures that any invocation of it implicitly locks its first
  112. argument before execution.  When set on a non-method subroutine,
  113. Perl ensures that a lock is taken on the subroutine itself before
  114. execution.  The semantics of the lock are exactly those of one
  115. explicitly taken with the <A HREF="../lib/Pod/perlfunc.html#item_lock"><CODE>lock</CODE></A> operator immediately after the
  116. subroutine is entered.
  117. <P></P>
  118. <DT><STRONG><A NAME="item_method">method</A></STRONG><BR>
  119. <DD>
  120. Indicates that the referenced subroutine is a method.
  121. This has a meaning when taken together with the <STRONG>locked</STRONG> attribute,
  122. as described there.  It also means that a subroutine so marked
  123. will not trigger the ``Ambiguous call resolved as CORE::%s'' warning.
  124. <P></P>
  125. <DT><STRONG><A NAME="item_lvalue">lvalue</A></STRONG><BR>
  126. <DD>
  127. Indicates that the referenced subroutine is a valid lvalue and can
  128. be assigned to. The subroutine must return a modifiable value such
  129. as a scalar variable, as described in <A HREF="../lib/Pod/perlsub.html">the perlsub manpage</A>.
  130. <P></P></DL>
  131. <P>There are no built-in attributes for anything other than subroutines.</P>
  132. <P>
  133. <H2><A NAME="available subroutines">Available Subroutines</A></H2>
  134. <P>The following subroutines are available for general use once this module
  135. has been loaded:</P>
  136. <DL>
  137. <DT><STRONG><A NAME="item_get">get</A></STRONG><BR>
  138. <DD>
  139. This routine expects a single parameter--a reference to a
  140. subroutine or variable.  It returns a list of attributes, which may be
  141. empty.  If passed invalid arguments, it uses <A HREF="../lib/Pod/perlfunc.html#item_die"><CODE>die()</CODE></A> (via <A HREF="../lib/Carp.html">Carp::croak</A>)
  142. to raise a fatal exception.  If it can find an appropriate package name
  143. for a class method lookup, it will include the results from a
  144. <A HREF="#item_FETCH_type_ATTRIBUTES"><CODE>FETCH_type_ATTRIBUTES</CODE></A> call in its return list, as described in
  145. <A HREF="#packagespecific attribute handling">Package-specific Attribute Handling</A> below.
  146. Otherwise, only <A HREF="#builtin attributes">built-in attributes</A> will be returned.
  147. <P></P>
  148. <DT><STRONG><A NAME="item_reftype">reftype</A></STRONG><BR>
  149. <DD>
  150. This routine expects a single parameter--a reference to a subroutine or
  151. variable.  It returns the built-in type of the referenced variable,
  152. ignoring any package into which it might have been blessed.
  153. This can be useful for determining the <EM>type</EM> value which forms part of
  154. the method names described in <A HREF="#packagespecific attribute handling">Package-specific Attribute Handling</A> below.
  155. <P></P></DL>
  156. <P>Note that these routines are <EM>not</EM> exported by default.</P>
  157. <P>
  158. <H2><A NAME="packagespecific attribute handling">Package-specific Attribute Handling</A></H2>
  159. <P><STRONG>WARNING</STRONG>: the mechanisms described here are still experimental.  Do not
  160. rely on the current implementation.  In particular, there is no provision
  161. for applying package attributes to 'cloned' copies of subroutines used as
  162. closures.  (See <A HREF="../lib/Pod/perlref.html#making references">Making References in the perlref manpage</A> for information on closures.)
  163. Package-specific attribute handling may change incompatibly in a future
  164. release.</P>
  165. <P>When an attribute list is present in a declaration, a check is made to see
  166. whether an attribute 'modify' handler is present in the appropriate package
  167. (or its @ISA inheritance tree).  Similarly, when <CODE>attributes::get</CODE> is
  168. called on a valid reference, a check is made for an appropriate attribute
  169. 'fetch' handler.  See <A HREF="#examples">EXAMPLES</A> to see how the ``appropriate package''
  170. determination works.</P>
  171. <P>The handler names are based on the underlying type of the variable being
  172. declared or of the reference passed.  Because these attributes are
  173. associated with subroutine or variable declarations, this deliberately
  174. ignores any possibility of being blessed into some package.  Thus, a
  175. subroutine declaration uses ``CODE'' as its <EM>type</EM>, and even a blessed
  176. hash reference uses ``HASH'' as its <EM>type</EM>.</P>
  177. <P>The class methods invoked for modifying and fetching are these:</P>
  178. <DL>
  179. <DT><STRONG><A NAME="item_FETCH_type_ATTRIBUTES">FETCH_<EM>type</EM>_ATTRIBUTES</A></STRONG><BR>
  180. <DD>
  181. This method receives a single argument, which is a reference to the
  182. variable or subroutine for which package-defined attributes are desired.
  183. The expected return value is a list of associated attributes.
  184. This list may be empty.
  185. <P></P>
  186. <DT><STRONG><A NAME="item_MODIFY_type_ATTRIBUTES">MODIFY_<EM>type</EM>_ATTRIBUTES</A></STRONG><BR>
  187. <DD>
  188. This method is called with two fixed arguments, followed by the list of
  189. attributes from the relevant declaration.  The two fixed arguments are
  190. the relevant package name and a reference to the declared subroutine or
  191. variable.  The expected return value as a list of attributes which were
  192. not recognized by this handler.  Note that this allows for a derived class
  193. to delegate a call to its base class, and then only examine the attributes
  194. which the base class didn't already handle for it.
  195. <P>The call to this method is currently made <EM>during</EM> the processing of the
  196. declaration.  In particular, this means that a subroutine reference will
  197. probably be for an undefined subroutine, even if this declaration is
  198. actually part of the definition.</P>
  199. <P></P></DL>
  200. <P>Calling <A HREF="#item_get"><CODE>attributes::get()</CODE></A> from within the scope of a null package
  201. declaration <CODE>package ;</CODE> for an unblessed variable reference will
  202. not provide any starting package name for the 'fetch' method lookup.
  203. Thus, this circumstance will not result in a method call for package-defined
  204. attributes.  A named subroutine knows to which symbol table entry it belongs
  205. (or originally belonged), and it will use the corresponding package.
  206. An anonymous subroutine knows the package name into which it was compiled
  207. (unless it was also compiled with a null package declaration), and so it
  208. will use that package name.</P>
  209. <P>
  210. <H2><A NAME="syntax of attribute lists">Syntax of Attribute Lists</A></H2>
  211. <P>An attribute list is a sequence of attribute specifications, separated by
  212. whitespace or a colon (with optional whitespace).
  213. Each attribute specification is a simple
  214. name, optionally followed by a parenthesised parameter list.
  215. If such a parameter list is present, it is scanned past as for the rules
  216. for the <A HREF="../lib/Pod/perlfunc.html#item_q"><CODE>q()</CODE></A> operator.  (See <A HREF="../lib/Pod/perlop.html#quote and quotelike operators">Quote and Quote-like Operators in the perlop manpage</A>.)
  217. The parameter list is passed as it was found, however, and not as per <A HREF="../lib/Pod/perlfunc.html#item_q"><CODE>q()</CODE></A>.</P>
  218. <P>Some examples of syntactically valid attribute lists:</P>
  219. <PRE>
  220.     switch(10,foo(7,3))  :  expensive
  221.     Ugly('\(") :Bad
  222.     _5x5
  223.     locked method</PRE>
  224. <P>Some examples of syntactically invalid attribute lists (with annotation):</P>
  225. <PRE>
  226.     switch(10,foo()             # ()-string not balanced
  227.     Ugly('(')                   # ()-string not balanced
  228.     5x5                         # "5x5" not a valid identifier
  229.     Y2::north                   # "Y2::north" not a simple identifier
  230.     foo + bar                   # "+" neither a colon nor whitespace</PRE>
  231. <P>
  232. <HR>
  233. <H1><A NAME="exports">EXPORTS</A></H1>
  234. <P>
  235. <H2><A NAME="default exports">Default exports</A></H2>
  236. <P>None.</P>
  237. <P>
  238. <H2><A NAME="available exports">Available exports</A></H2>
  239. <P>The routines <A HREF="#item_get"><CODE>get</CODE></A> and <A HREF="#item_reftype"><CODE>reftype</CODE></A> are exportable.</P>
  240. <P>
  241. <H2><A NAME="export tags defined">Export tags defined</A></H2>
  242. <P>The <CODE>:ALL</CODE> tag will get all of the above exports.</P>
  243. <P>
  244. <HR>
  245. <H1><A NAME="examples">EXAMPLES</A></H1>
  246. <P>Here are some samples of syntactically valid declarations, with annotation
  247. as to how they resolve internally into <CODE>use attributes</CODE> invocations by
  248. perl.  These examples are primarily useful to see how the ``appropriate
  249. package'' is found for the possible method lookups for package-defined
  250. attributes.</P>
  251. <OL>
  252. <LI>
  253. Code:
  254. <PRE>
  255.     package Canine;
  256.     package Dog;
  257.     my Canine $spot : Watchful ;</PRE>
  258. <P>Effect:</P>
  259. <PRE>
  260.     use attributes Canine => \$spot, "Watchful";</PRE>
  261. <P></P>
  262. <LI>
  263. Code:
  264. <PRE>
  265.     package Felis;
  266.     my $cat : Nervous;</PRE>
  267. <P>Effect:</P>
  268. <PRE>
  269.     use attributes Felis => \$cat, "Nervous";</PRE>
  270. <P></P>
  271. <LI>
  272. Code:
  273. <PRE>
  274.     package X;
  275.     sub foo : locked ;</PRE>
  276. <P>Effect:</P>
  277. <PRE>
  278.     use attributes X => \&foo, "locked";</PRE>
  279. <P></P>
  280. <LI>
  281. Code:
  282. <PRE>
  283.     package X;
  284.     sub Y::x : locked { 1 }</PRE>
  285. <P>Effect:</P>
  286. <PRE>
  287.     use attributes Y => \&Y::x, "locked";</PRE>
  288. <P></P>
  289. <LI>
  290. Code:
  291. <PRE>
  292.     package X;
  293.     sub foo { 1 }</PRE>
  294. <PRE>
  295.     package Y;
  296.     BEGIN { *bar = \&X::foo; }</PRE>
  297. <PRE>
  298.     package Z;
  299.     sub Y::bar : locked ;</PRE>
  300. <P>Effect:</P>
  301. <PRE>
  302.     use attributes X => \&X::foo, "locked";</PRE>
  303. <P></P></OL>
  304. <P>This last example is purely for purposes of completeness.  You should not
  305. be trying to mess with the attributes of something in a package that's
  306. not your own.</P>
  307. <P>
  308. <HR>
  309. <H1><A NAME="see also">SEE ALSO</A></H1>
  310. <P><A HREF="../lib/Pod/perlsub.html#private variables via my()">Private Variables via my() in the perlsub manpage</A> and
  311. <A HREF="../lib/Pod/perlsub.html#subroutine attributes">Subroutine Attributes in the perlsub manpage</A> for details on the basic declarations;
  312. <A HREF="../lib/attrs.html">the attrs manpage</A> for the obsolescent form of subroutine attribute specification
  313. which this module replaces;
  314. <A HREF="../lib/Pod/perlfunc.html#use">use in the perlfunc manpage</A> for details on the normal invocation mechanism.</P>
  315. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  316. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  317. <STRONG><P CLASS=block> attributes - get/set subroutine or variable attributes</P></STRONG>
  318. </TD></TR>
  319. </TABLE>
  320.  
  321. </BODY>
  322.  
  323. </HTML>
  324.