NAME

Sub::Pipeline - subs composed of sequential pieces

VERSION

version 0.010

 $Id: /my/cs/projects/subpipe/trunk/lib/Sub/Pipeline.pm 27893 2006-11-13T15:11:24.618700Z rjbs  $

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>

BUGS

Please report any bugs or feature requests to bug-sub-pipeline@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT

Copyright 2005-2006 Ricardo Signes, All Rights Reserved.

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