New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
attributes.pm documentation is recursive and incomplete #8014
Comments
From mark@summersault.comHello, This bug report is valid at least until Perl 5.8.7. I was just trying to understand the 'attributes.pm' documentation. My first problem was that the documentation was recursive. As an use attributes __PACKAGE__, \&foo, 'method'; But I can't see that it explains what this syntax does. As if to further clarify, it uses an example of calling its import method, attributes::->import(__PACKAGE__, \$x, 'Bent'); Mark -- |
From module@renee-baecker.dePatch is attached... |
From module@renee-baecker.deattributes.patch--- attributes.pm.orig 2008-05-23 20:06:38.000000000 +0200
+++ attributes.pm.new 2008-05-23 20:04:42.000000000 +0200
@@ -157,6 +157,37 @@
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 >> have 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
The following are the built-in attributes for subroutines:
@@ -406,6 +437,56 @@
be trying to mess with the attributes of something in a package that's
not your own.
+=head1 MORE EXAMPLES
+
+=over 4
+
+=item 1.
+
+ #!/usr/bin/perl
+
+ 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 not allowed and we return a list of
+these "bad attributes".
+
+As we return an empty list, everything is fine.
+
+=item 2.
+
+ #!/usr/bin/perl
+
+ 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 one single
+element ('Test').
+
+=back
+
=head1 SEE ALSO
L<perlsub/"Private Variables via my()"> and
|
The RT System itself - Status changed from 'new' to 'open' |
From @rgs2008/5/25 reneeb via RT <perlbug-followup@perl.org>:
Thanks, applied as #33985. |
@rgs - Status changed from 'open' to 'resolved' |
Migrated from rt.perl.org#36516 (status was 'resolved')
Searchable as RT36516$
The text was updated successfully, but these errors were encountered: