NAME
Sub::Talisman - use attributes to tag or classify subs
SYNOPSIS
package Local::Example;
use Sub::Talisman qw( Awesome Info );
sub mysub :Awesome {
...;
}
sub othersub :Info("Hello World") {
...;
}
my @awesome_subs = Sub::Talisman->get_subs("Local::Example::Awesome");
print Sub::Talisman # prints "Hello World"
-> get_attribute_parameters(\&othersub, "Local::Example::Info")
-> [0];
DESCRIPTION
Sub::Talisman allows you to define "talisman" attibutes for your subs, and
provides a basic introspection API for these talismans.
Class Methods
Sub::Talisman's methods are designed to be called as class methods.
`setup_for $package, \%options`
This is used by `import` to setup a single attribute. As an example,
to create a "Purpose" talisman in UNIVERSAL, then:
Sub::Talisman->setup_for(
'UNIVERSAL',
{ attribute => 'Purpose' },
);
The only option understood is "attribute" which provides the name of
the attribute.
`get_attributes($sub)`
Gets a list of attributes associated with the sub. Each attribute is a
package-qualified name, such as "Local::Example::Awesome" from the
SYNPOSIS.
$sub can be a code ref or a sub name. In the case of subs which have
been exported and imported between packages, using the sub name may
not be very reliable. Using a code reference is recommended.
This function only returns attributes defined via Sub::Talisman. For
other attributes such as the Perl built-in `:lvalue` attribute, see
the `get` function in the attributes package.
`get_attribute_parameters($sub, $attr)`
Given a sub and an attribute name, retrieves the parenthesized list of
parameters. For example:
sub foo :Info("Hello World") { ... }
my $params = Sub::Talisman->get_attribute_parameters(\&foo, "Info");
The attribute name can be package-qualified. If it is not, then the
caller package is assumed.
The list of parameters retrieved is a simple arrayref (or undef if the
attribute was used without parentheses). For a more structured
approach including compile-time validation of the parameters, see
Sub::Talisman::Struct.
`get_subs($attr)`
Finds all subs which have the attribute, and returns a list of their
names. Anonymous subs are not returned.
CAVEATS
Anonymous subs
Talisman attributes may be added to anonymous subs too, but it is
suspected that this may not be thread-safe...
my $sub = sub :Awesome { ... };
Anonymous subs can of course be assigned into the symbol tables, a la:
*foo = sub :Awesome { ... };
But as far as Sub::Talisman is concerned, they were anonymous at the time
of definition, so remain anonymous. A workaround would be:
no warnings 'redefine';
sub foo :Awesome;
*foo = sub :Awesome { ... };
Talisman naming
Perl reserves lower-case attributes for its own future use; lower-cased
talisman attributes may work, but will probably spew warnings. Try to name
your talisman attributes in UpperCamelCase.
Talisman subs
Be aware that creating an attribute Foo will also create a sub called
"Foo" in your package. Sub::Talisman uses namespace::clean to later wipe
that sub away, but that temporary sub does need to exist during
compile-time, so you won't be able to use that name for your own subs.
BUGS
Please report any bugs to
<
http://rt.cpan.org/Dist/Display.html?Queue=Sub-Talisman>.
SEE ALSO
attributes, Attribute::Handlers, Sub::Talisman::Struct.
AUTHOR
Toby Inkster <
[email protected]>.
COPYRIGHT AND LICENCE
This software is copyright (c) 2012 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under the
same terms as the Perl 5 programming language system itself.
DISCLAIMER OF WARRANTIES
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
