package attributes;
-$VERSION = 0.03;
+our $VERSION = 0.09;
@EXPORT_OK = qw(get reftype);
@EXPORT = ();
#sub _fetch_attrs ($) ;
#sub _guess_stash ($) ;
#sub _modify_attrs ;
-#sub _warn_reserved () ;
#
# 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 {
my @badattrs;
if ($pkgmeth) {
my @pkgattrs = _modify_attrs($svref, @attrs);
- @badattrs = $pkgmeth->($home_stash, $svref, @attrs);
+ @badattrs = $pkgmeth->($home_stash, $svref, @pkgattrs);
if (!@badattrs && @pkgattrs) {
- return unless _warn_reserved;
+ require warnings;
+ return unless warnings::enabled('reserved');
@pkgattrs = grep { m/\A[[:lower:]]+(?:\z|\()/ } @pkgattrs;
if (@pkgattrs) {
for my $attr (@pkgattrs) {
=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
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.
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 What C<import> does
+
+In the description it is mentioned that
+
+ sub foo : method;
+
+is equivalent to
+
+ use attributes __PACKAGE__, \&foo, 'method';
+
+As you might know this calls the C<import> function of C<attributes> at compile
+time with these parameters: 'attributes', the caller's package name, the reference
+to the code and 'method'.
+
+ attributes->import( __PACKAGE__, \&foo, 'method' );
+
+So you want to know what C<import> actually does?
+
+First of all C<import> gets the type of the third parameter ('CODE' in this case).
+C<attributes.pm> checks if there is a subroutine called C<< MODIFY_<reftype>_ATTRIBUTES >>
+in the caller's namespace (here: 'main'). In this case a subroutine C<MODIFY_CODE_ATTRIBUTES> is
+required. Then this method is called to check if you have used a "bad attribute".
+The subroutine call in this example would look like
+
+ MODIFY_CODE_ATTRIBUTES( 'main', \&foo, 'method' );
+
+C<< MODIFY_<reftype>_ATTRIBUTES >> has to return a list of all "bad attributes".
+If there are any bad attributes C<import> croaks.
+
+(See L<"Package-specific Attribute Handling"> below.)
=head2 Built-in Attributes
=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),
=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
=item FETCH_I<type>_ATTRIBUTES
-This method receives a single argument, which is a reference to the
-variable or subroutine for which package-defined attributes are desired.
-The expected return value is a list of associated attributes.
-This list may be empty.
+This method is called with two arguments: the relevant package name,
+and a reference to a variable or subroutine for which package-defined
+attributes are desired. The expected return value is a list of
+associated attributes. This list may be empty.
=item MODIFY_I<type>_ATTRIBUTES
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.
Effect:
- use attributes Canine => \$spot, "Watchful";
+ use attributes ();
+ attributes::->import(Canine => \$spot, "Watchful");
=item 2.
Effect:
- use attributes Felis => \$cat, "Nervous";
+ use attributes ();
+ attributes::->import(Felis => \$cat, "Nervous");
=item 3.
be trying to mess with the attributes of something in a package that's
not your own.
+=head1 MORE EXAMPLES
+
+=over 4
+
+=item 1.
+
+ sub MODIFY_CODE_ATTRIBUTES {
+ my ($class,$code,@attrs) = @_;
+
+ my $allowed = 'MyAttribute';
+ my @bad = grep { $_ ne $allowed } @attrs;
+
+ return @bad;
+ }
+
+ sub foo : MyAttribute {
+ print "foo\n";
+ }
+
+This example runs. At compile time C<MODIFY_CODE_ATTRIBUTES> is called. In that
+subroutine, we check if any attribute is disallowed and we return a list of
+these "bad attributes".
+
+As we return an empty list, everything is fine.
+
+=item 2.
+
+ sub MODIFY_CODE_ATTRIBUTES {
+ my ($class,$code,@attrs) = @_;
+
+ my $allowed = 'MyAttribute';
+ my @bad = grep{ $_ ne $allowed }@attrs;
+
+ return @bad;
+ }
+
+ sub foo : MyAttribute Test {
+ print "foo\n";
+ }
+
+This example is aborted at compile time as we use the attribute "Test" which
+isn't allowed. C<MODIFY_CODE_ATTRIBUTES> returns a list that contains a single
+element ('Test').
+
+=back
+
=head1 SEE ALSO
L<perlsub/"Private Variables via my()"> and
https://perl5.git.perl.org / perl5.git / blobdiff