The value from caller doesn't change, so my $pkg = caller;

[perl5.git] / lib / attributes.pm

diff --git a/lib/attributes.pm b/lib/attributes.pm
index f111645..714cb26 100644 (file)
--- a/lib/attributes.pm
+++ b/lib/attributes.pm
@@ -1,6 +1,6 @@
 package attributes;
 
-$VERSION = 0.03;
+our $VERSION = 0.06;
 
 @EXPORT_OK = qw(get reftype);
 @EXPORT = ();
@@ -27,7 +27,7 @@ sub carp {
 #
 # The extra trips through newATTRSUB in the interpreter wipe out any savings
 # from avoiding the BEGIN block.  Just do the bootstrap now.
-BEGIN { bootstrap }
+BEGIN { bootstrap attributes }
 
 sub import {
     @_ > 2 && ref $_[2] or do {
@@ -98,7 +98,7 @@ attributes - get/set subroutine or variable attributes
 =head1 SYNOPSIS
 
   sub foo : method ;
-  my ($x,@y,%z) : Bent ;
+  my ($x,@y,%z) : Bent = 1;
   my $s = sub : method { ... };
 
   use attributes ();   # optional, to get subroutine declarations
@@ -120,15 +120,18 @@ the following:
 
 The second example in the synopsis does something equivalent to this:
 
-    use attributes __PACKAGE__, \$x, 'Bent';
-    use attributes __PACKAGE__, \@y, 'Bent';
-    use attributes __PACKAGE__, \%z, 'Bent';
+    use attributes ();
+    my ($x,@y,%z);
+    attributes::->import(__PACKAGE__, \$x, 'Bent');
+    attributes::->import(__PACKAGE__, \@y, 'Bent');
+    attributes::->import(__PACKAGE__, \%z, 'Bent');
+    ($x,@y,%z) = 1;
 
-Yes, that's three invocations.
+Yes, that's a lot of expansion.
 
-B<WARNING>: attribute declarations for variables are an I<experimental>
-feature.  The semantics of such declarations could change or be removed
-in future versions.  They are present for purposes of experimentation
+B<WARNING>: 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.
 
@@ -137,12 +140,22 @@ directly by this module, depending on how you look at it.)  However,
 package-specific attributes are allowed by an extension mechanism.
 (See L<"Package-specific Attribute Handling"> below.)
 
-The setting of attributes happens at compile time.  An attempt to set
-an unrecognized attribute is a fatal error.  (The error is trappable, but
-it still stops the compilation within that C<eval>.)  Setting an attribute
-with a name that's all lowercase letters that's not a built-in attribute
-(such as "foo")
-will result in a warning with B<-w> or C<use warnings 'reserved'>.
+The setting of subroutine attributes happens at compile time.
+Variable attributes in C<our> declarations are also applied at compile time.
+However, C<my> variables get their attributes applied at run-time.
+This means that you have to I<reach> the run-time component of the C<my>
+before those attributes will get applied.  For example:
+
+    my $x : Bent = 42 if 0;
+
+will neither assign 42 to $x I<nor> will it apply the C<Bent> attribute
+to the variable.
+
+An attempt to set an unrecognized attribute is a fatal error.  (The
+error is trappable, but it still stops the compilation within that
+C<eval>.)  Setting an attribute with a name that's all lowercase
+letters that's not a built-in attribute (such as "foo") will result in
+a warning with B<-w> or C<use warnings 'reserved'>.
 
 =head2 Built-in Attributes
 
@@ -152,6 +165,10 @@ The following are the built-in attributes for subroutines:
 
 =item locked
 
+B<5.005 threads only!  The use of the "locked" attribute currently
+only makes sense if you are using the deprecated "Perl 5.005 threads"
+implementation of threads.>
+
 Setting this attribute is only meaningful when the subroutine or
 method is to be called by multiple threads.  When set on a method
 subroutine (i.e., one marked with the B<method> attribute below),
@@ -177,7 +194,7 @@ as a scalar variable, as described in L<perlsub>.
 
 =back
 
-There are no built-in attributes for anything other than subroutines.
+For global variables there is C<unique> attribute: see L<perlfunc/our>.
 
 =head2 Available Subroutines
 
@@ -248,7 +265,7 @@ This list may be empty.
 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 as a list of attributes which were
+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
 which the base class didn't already handle for it.
@@ -329,7 +346,8 @@ Code:
 
 Effect:
 
-    use attributes Canine => \$spot, "Watchful";
+    use attributes ();
+    attributes::->import(Canine => \$spot, "Watchful");
 
 =item 2.
 
@@ -340,7 +358,8 @@ Code:
 
 Effect:
 
-    use attributes Felis => \$cat, "Nervous";
+    use attributes ();
+    attributes::->import(Felis => \$cat, "Nervous");
 
 =item 3.