X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Fattributes.pm;h=3a6b3d5e0fef1d8d7c134d779b27b5fc32b5cf79;hb=d6ec9fa3b3319f35131489112ca8c41e368dd1c8;hp=e49204fc76fd6302047f2466b756f624482a5534;hpb=09bef84370e90d727656ea11ba5ee8be80e361d3;p=p5sagit%2Fp5-mst-13.2.git diff --git a/lib/attributes.pm b/lib/attributes.pm index e49204f..3a6b3d5 100644 --- 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 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: attribute declarations for variables are an I 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 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. + =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) 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_ATTRIBUTES> call in its return list, as described in -L"Package-specific Attribute Handling"> below. +L<"Package-specific Attribute Handling"> below. Otherwise, only L 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 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 exported. This is primarily because -the C mechanism which would normally import them is already in use -by Perl itself to implement the C syntax. +Note that these routines are I 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 operator. (See L.) @@ -276,8 +283,8 @@ The parameter list is passed as it was found, however, and not as per C. 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 and C are exportable. + +=head2 Export tags defined + +The C<:ALL> tag will get all of the above exports. =head1 EXAMPLES