X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Fattributes.pm;h=2dacd02751ec77bea6399d96197ff67a25554f48;hb=702fa71c711a708b512dca4870841461f8f582ee;hp=28f7eee68dc6026996417ef1d88d1c6225f58214;hpb=592f596992fbcfa7e7c135f9212d2ec2def553a6;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/lib/attributes.pm b/lib/attributes.pm
index 28f7eee..2dacd02 100644
--- a/lib/attributes.pm
+++ b/lib/attributes.pm
@@ -1,6 +1,6 @@
 package attributes;
 
-$VERSION = 0.03;
+our $VERSION = 0.05;
 
 @EXPORT_OK = qw(get reftype);
 @EXPORT = ();
@@ -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,30 +120,42 @@ 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. Variable attributes are currently
-not usable for tieing.
+implementation of this feature.
 
 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.
 (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
 
@@ -178,7 +190,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
 
@@ -330,7 +342,8 @@ Code:
 
 Effect:
 
-    use attributes Canine => \$spot, "Watchful";
+    use attributes ();
+    attributes::->import(Canine => \$spot, "Watchful");
 
 =item 2.
 
@@ -341,7 +354,8 @@ Code:
 
 Effect:
 
-    use attributes Felis => \$cat, "Nervous";
+    use attributes ();
+    attributes::->import(Felis => \$cat, "Nervous");
 
 =item 3.