NAME
Sub::Lib - Stuff sub-routines into a run-time namespace. Because.
Reasons.
SYNOPSIS
use Sub::Lib;
# create a library
my $lib = Sub::Lib->new({
'log' => sub {print join(' ', localtime. ':', @_), "\n"},
});
# add methods
$lib->('info', sub {$lib->('log')->('info:', @_)});
$lib->('warn', sub {$lib->('log')->('warn:', @_)});
# call them directly
$lib->('info')->('This is for information');
# or via some sugar
$lib->run('warn', 'This is for warnings');
# or via some oo sugar
$lib->('method', sub {
my ($self, $name, @args) = @_;
$self->run($name, @args);
});
# calls the 'method' sub-routine from the library as an object
# method on $lib. attaches to objects like a virus.
$lib->call('method', $lib, 'info', "Have you seen? Oh I've seen.");
# cheeseburger
{
my $sub = $lib->has('warn');
$sub->('I can has.')
if $sub;
}
# in case you don't like exceptions
$lib->void('info')->('This has a high probability of working');
$lib->void('ofni')->('Hidden messages go here');
# why not?
$lib->curry('warn', 'I know stuff now')->('and later');
# why not? for objects.
my $o = $lib->o('method', $lib, 'info');
$o->('I think I am confused');
# closures allow bending time
my $y = $lib->y('apex', sub {
my ($sub, @args) = @_;
$sub->('I can see forever', @args);
}, 'or something.');
$lib->('apex', sub {$lib->('log')->('apex:', @_)});
$y->('can you?');
# you have been warned
$lib->('info')->('installed subs:', join(', ', keys %{$lib->()}));
DESCRIPTION
Sub::Lib allows you to store sub-routines into a common library which
can then passed around as a variable. It's a run-time namespace.
USAGE
"new([HASHREF | LIST])"
Creates a library object and initializes it with entries that may be
passed in as either a "HASH" reference or "LIST" of key-value pairs. The
object created is itself a sub-routine that can be called directly in
order to run sub-routines stored in the library:
$lib->('sub-routine name goes here')->(qw(sub routine args go here));
Additional sub-routines may be added by providing a "CODE" reference:
$lib->('a new sub-routine', sub {
# code goes here
});
If no arguments are passed, the internal library is returned:
my $_lib = $lib->();
"has($name)"
Returns the sub-routine installed in the library identified by $name or
undef if it does not exist.
"run($name, [LIST])"
Runs the sub-routine stored in the library identified by $name. An
exception will be thrown if no sub-routine by that name can be found.
Any additional arguments are passed to the sub-routine.
"call($object, $name, [LIST])"
Calls the sub-routine stored in the library identified by $name as a
method to the object in $object. This is similar to "run()" above but
uses Perl's object semantics. Additional arguments are passed to the
method.
"void($name)"
Either returns the sub-routine installed in the library identified by
$name or returns a void sub-routine. This is useful if you want to
blindly call sub-routines and not worry if they exist. It is debatable
how useful that is in itself.
"curry($name, [LIST])"
Returns a sub-routine that, when called, will execute the sub-routine
installed in the library identified by $name with arguments in "LIST"
prepended. Additional arguments to the call itself are also appended.
"o($name, $object, [LIST])"
Similar to "curry()" but the sub-routine that is returned will execute a
method call on the object specified by $object.
"y($name, $sub, [LIST])"
Creates an anonymous sub-routine that, when executed, will run the
"CODE" reference identified by $sub passing in the sub-routine installed
in the library under $name. Arguments passed in "LIST" will be curried
along with arguments to the call itself. Unlike other methods, "y()"
does not require $name to be installed when called in order to delay
execution for as long as possible.
AUTHOR
jason hord <pravus@cpan.org>
LICENSE
This software is information. It is subject only to local laws of
physics.