/ 
Sub-Lib-0.03
River stage zero No dependents
/ Sub::Lib

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.