/ 
Sub-Talisman-0.006
River stage one • 3 direct dependents • 5 total dependents
/ Sub::Talisman

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 <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2012, 2017 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.