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.

cpanm Sub::Lib

perl -MCPAN -e shell
install Sub::Lib