/ 
Sub-Pipeline-0.011
River stage zero No dependents
/ Sub::Pipeline

NAME

Sub::Pipeline - subs composed of sequential pieces

VERSION

version 0.011

SYNOPSIS

use Sub::Pipeline;

my $pipeline = Sub::Pipeline->new({
  on_success => 'return',
  order => [ qw(init validate check_acl do) ],
  pipe  => {
    init      => sub { die "can't initialize"  unless do_init; },
    validate  => sub { die "validatione error" unless validate_args(@_); },
    check_acl => sub { die "permission error"  unless get_user->may(@_); },
    do        => sub {
      my $result = do_something_complicated(@_);
      Sub::Pipeline::Sucess->throw($result)
    },
  },
});

$pipeline->install_pipeline({ as => "transmogrify", into => "Origami" });

my $result = Origami->transmogrify(10, 20, 99);

DESCRIPTION

This module makes it easy to construct routines out of smaller routines which can be swapped in and out, have their exception handling altered, or cause early successful return.

METHODS

new

This method constructs and initializes a new Sub::Pipeline.

Valid arguments are:

order - a reference to an array of names of pipes to be run, in order
pipe  - a reference to a hash of pipe names and implementations (code refs)
on_success - what to do on success (default 'value'; see 'on_success' below)

order

my @old_order = $pipeline->order;
my @new_order = $pipeline->order(qw(begin check init run end));

This method sets the order in which the pipe pieces are run.

pipe

my $code = $pipeline->pipe($name);

$pipeline->pipe($name => sub { });

This method sets the named pipe piece to the given code reference.

on_success

$pipeline->on_success('throw');

This method sets the behavior for handling the Sub::Pipeline::Success exception. That exception is thrown by a pipe piece to indicate completion.

Valid values are:

throw  - the thrown exception is rethrown
return - the thrown exception is returned
value  - the value of the exception is returned

check

This method checks whether the pipe is complete and intact. If any pipe piece is missing, a Sub::Pipeline::PipeMissing exception is thrown. Its pipe field is set to the name of the first missing pipe.

call

This method calls each piece of the pipeline in order. Non-success exceptions are rethrown. Success exceptions are handled according to the defined "on_success" behavior.

If a pipeline piece is missing, a Sub::Pipeline::PipeMissing exception is thrown. This method does not implement this in terms of "check", so multiple pipe pieces may be called before this exception is thrown.

as_code

This method returns a code reference which, if called, is equivalent to calling the pipeline's call method.

load_from_package

$pipeline->load_from_package($package_name);

This method loads the pipeline's pipes by looking for subs with the pipe names in the given package.

save_to_package

$pipeline->save_to_package($package_name, \%arg);

This method saves the pipeline to a package. It installs each of its pipe pieces as a named subroutine in the package, and installs a call routine in the package to invoke the pipeline.

An named argument, reinstall, may be passed as a true value to suppress warnings on redefining existing subs in the package.

install_pipeline

$pipeline->install_pipeline({ into => $package, as => $method_name });

This method installs the pipeline into the named package with the given method name. A reinstall parameter may also be passed. If true, warnings for redefining over an existing sub are suppressed.

install_new

Sub::Pipeline->install_new(\%arg);

This method creates a new pipeline and installs it. The into, as, and reinstall arguments are passed to install_pipeline. All other arguments are passed to new.

DIAGNOSTICS

This method defines two exception classes (via Exception::Class):

  • Sub::Pipeline::Success

    This exception is thrown by a pipeline piece that wishes to indicate that the pipeline is done.

  • Sub::Pipeline::PipeMissing

    This exception is thrown by "check" or "call" when a pipeline piece listed in the pipeline's calling order is undefined or not callable.

TODO

  • urgent: supply a method for passing data between pipeline segments

AUTHOR

Ricardo SIGNES <rjbs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2005 by Ricardo SIGNES.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.