Ricardo SIGNES > Sub-Pipeline-0.010 > Sub::Pipeline

Download:
Sub-Pipeline-0.010.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.010   Source   Latest Release: Sub-Pipeline-0.011

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):

TODO ^

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.

syntax highlighting: