make PPPort/harness build on VMS

[p5sagit/p5-mst-13.2.git] / lib / attributes.pm

diff --git a/lib/attributes.pm b/lib/attributes.pm
index e49204f..3a6b3d5 100644 (file)
--- a/lib/attributes.pm
+++ b/lib/attributes.pm
@@ -1,9 +1,10 @@
 package attributes;
 
-$VERSION = 0.01;
+our $VERSION = 0.04;
 
-#@EXPORT_OK = qw(get reftype);
-#@EXPORT = ();
+@EXPORT_OK = qw(get reftype);
+@EXPORT = ();
+%EXPORT_TAGS = (ALL => [@EXPORT, @EXPORT_OK]);
 
 use strict;
 
@@ -26,11 +27,13 @@ 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
-       croak 'Usage: use '.__PACKAGE__.' $home_stash, $ref, @attrlist';
+    @_ > 2 && ref $_[2] or do {
+       require Exporter;
+       goto &Exporter::import;
+    };
     my (undef,$home_stash,$svref,@attrs) = @_;
 
     my $svtype = uc reftype($svref);
@@ -51,7 +54,7 @@ sub import {
                my $s = ((@pkgattrs == 1) ? '' : 's');
                carp "$svtype package attribute$s " .
                    "may clash with future reserved word$s: " .
-                   join(' , ' , @pkgattrs);
+                   join(' : ' , @pkgattrs);
            }
        }
     }
@@ -62,7 +65,7 @@ sub import {
        croak "Invalid $svtype attribute" .
            (( @badattrs == 1 ) ? '' : 's') .
            ": " .
-           join(' , ', @badattrs);
+           join(' : ', @badattrs);
     }
 }
 
@@ -82,12 +85,7 @@ sub get ($) {
        ;
 }
 
-#sub export {
-#    require Exporter;
-#    goto &Exporter::import;
-#}
-#
-#sub require_version { goto &UNIVERSAL::VERSION }
+sub require_version { goto &UNIVERSAL::VERSION }
 
 1;
 __END__
@@ -106,13 +104,16 @@ attributes - get/set subroutine or variable attributes
   use attributes ();   # optional, to get subroutine declarations
   my @attrlist = attributes::get(\&foo);
 
+  use attributes 'get'; # import the attributes::get subroutine
+  my @attrlist = get \&foo;
+
 =head1 DESCRIPTION
 
 Subroutine declarations and definitions may optionally have attribute lists
 associated with them.  (Variable C<my> 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, first example above is equivalent to
+list to this module.  In particular, the first example above is equivalent to
 the following:
 
     use attributes __PACKAGE__, \&foo, 'method';
@@ -129,7 +130,8 @@ 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
 with what the semantics ought to be.  Do not rely on the current
-implementation of this feature.
+implementation of this feature. Variable attributes are currently
+not usable for tieing.
 
 There are only a few attributes currently handled by Perl itself (or
 directly by this module, depending on how you look at it.)  However,
@@ -168,6 +170,12 @@ This has a meaning when taken together with the B<locked> attribute,
 as described there.  It also means that a subroutine so marked
 will not trigger the "Ambiguous call resolved as CORE::%s" warning.
 
+=item lvalue
+
+Indicates that the referenced subroutine is a valid lvalue and can
+be assigned to. The subroutine must return a modifiable value such
+as a scalar variable, as described in L<perlsub>.
+
 =back
 
 There are no built-in attributes for anything other than subroutines.
@@ -187,7 +195,7 @@ empty.  If passed invalid arguments, it uses die() (via L<Carp::croak|Carp>)
 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
 C<FETCH_I<type>_ATTRIBUTES> call in its return list, as described in
-L"Package-specific Attribute Handling"> below.
+L<"Package-specific Attribute Handling"> below.
 Otherwise, only L<built-in attributes|"Built-in Attributes"> will be returned.
 
 =item reftype
@@ -196,13 +204,11 @@ 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> value which forms part of
-the method names described in L"Package-specific Attribute Handling"> below.
+the method names described in L<"Package-specific Attribute Handling"> below.
 
 =back
 
-Note that these routines are I<not> exported.  This is primarily because
-the C<use> mechanism which would normally import them is already in use
-by Perl itself to implement the C<sub : attributes> syntax.
+Note that these routines are I<not> exported by default.
 
 =head2 Package-specific Attribute Handling
 
@@ -268,7 +274,8 @@ will use that package name.
 =head2 Syntax of Attribute Lists
 
 An attribute list is a sequence of attribute specifications, separated by
-whitespace, commas, or both.  Each attribute specification is a simple
+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
 for the C<q()> operator.  (See L<perlop/"Quote and Quote-like Operators">.)
@@ -276,8 +283,8 @@ The parameter list is passed as it was found, however, and not as per C<q()>.
 
 Some examples of syntactically valid attribute lists:
 
-    switch(10,foo(7,3)) , ,  expensive
-    Ugly('\(") , Bad
+    switch(10,foo(7,3))  :  expensive
+    Ugly('\(") :Bad
     _5x5
     locked method
 
@@ -287,7 +294,21 @@ Some examples of syntactically invalid attribute lists (with annotation):
     Ugly('(')                  # ()-string not balanced
     5x5                                # "5x5" not a valid identifier
     Y2::north                  # "Y2::north" not a simple identifier
-    foo + bar                  # "+" neither a comma nor whitespace
+    foo + bar                  # "+" neither a colon nor whitespace
+
+=head1 EXPORTS
+
+=head2 Default exports
+
+None.
+
+=head2 Available exports
+
+The routines C<get> and C<reftype> are exportable.
+
+=head2 Export tags defined
+
+The C<:ALL> tag will get all of the above exports.
 
 =head1 EXAMPLES