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 . SEE ALSO attributes, Attribute::Handlers. AUTHOR Toby Inkster . 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.