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;
#
# 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);
my $s = ((@pkgattrs == 1) ? '' : 's');
carp "$svtype package attribute$s " .
"may clash with future reserved word$s: " .
- join(' , ' , @pkgattrs);
+ join(' : ' , @pkgattrs);
}
}
}
croak "Invalid $svtype attribute" .
(( @badattrs == 1 ) ? '' : 's') .
": " .
- join(' , ', @badattrs);
+ join(' : ', @badattrs);
}
}
;
}
-#sub export {
-# require Exporter;
-# goto &Exporter::import;
-#}
-#
-#sub require_version { goto &UNIVERSAL::VERSION }
+sub require_version { goto &UNIVERSAL::VERSION }
1;
__END__
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';
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,
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.
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
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
=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">.)
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
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