Randy Stauner > Sub-Chain > Sub::Chain

Download:
Sub-Chain-0.012.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.012   Source  

NAME ^

Sub::Chain - Chain subs together and call in succession

VERSION ^

version 0.012

SYNOPSIS ^

  my $chain = Sub::Chain->new();

  $chain->append(\&wash, ['cold']);
  $chain->append(\&dry,  [{tumble => 'low'}]);
  $chain->append(\&fold);

  my @clean_laundry = $chain->call(@clothes);

  # if only it were that easy

DESCRIPTION ^

This module aims to provide a simple interface for chaining multiple subs (coderefs) together and executing them one after the other in a single call.

It was specifically designed to be built dynamically from a list of specifications provided at runtime to filter data through the specified list of functions.

Also see Sub::Chain::Named which appends subs to the chain by name rather than coderef.

METHODS ^

new

  my $chain = Sub::Chain->new();
  my $chain = Sub::Chain->new( option => $value );
  my $chain = Sub::Chain->new({option => $value});

Constructor. Takes a hash or hashref of arguments.

Accepts values as described in OPTIONS that will be used as defaults for any sub that doesn't override them.

append

  $chain->append(\&sub, \@args, \%opts);

Append a sub to the chain. The \@args arrayref will be flattened and passed to the \&sub after any arguments to "call".

  sub sum { my $s = 0; $s += $_ for @_; $s; }

  $chain->append(\&sum, [3, 4]);

  $chain->call(1, 2);
  # returns 10
  # equivalent to: sum(1, 2, 3, 4)

If you don't want to send any additional arguments to the sub an empty arrayref ([]) can be used.

This method returns the object so that it can be chained for simplicity:

  $chain->append(\&sub, \@args)->append(\&sub2)->append(\&sub3, [], \%opts);

The \%opts hashref can be any of the options described in "OPTIONS" to override the defaults on the object for this particular sub.

call

  $chain->call(@args);

Calls each method in the chain with the supplied (and any predetermined) arguments according to any predefined options.

coderef

  my $sub = $chain->coderef;
  $sub->(@args);

Wrap $self->call in a closure. This is used to overload the function dereference operator so you can pretend the instance is a coderef: $chain->(@args)

OPTIONS ^

These options can define how a sub should be handled. Specified in the options hashref for "append" they apply to that particular sub. Specified in the constructor they can set the default for how to handle any sub that doesn't override the option.

RATIONALE ^

This module started out as Data::Transform::Named, a named wrapper (like Sub::Chain::Named) around Data::Transform (and specifically Data::Transform::Map).

As the module was nearly finished I realized I was using very little of Data::Transform (and its documentation suggested that I probably wouldn't want to use the only part that I was using). I also found that the output was not always what I expected. I decided that it seemed reasonable according to the likely purpose of Data::Transform, and this module simply needed to be different.

So I attempted to think more abstractly and realized that the essence of the module was not tied to data transformation, but merely the succession of simple subroutine calls.

I then found and considered Sub::Pipeline but needed to be able to use the same named subroutine with different arguments in a single chain, so it seemed easier to me to stick with the code I had written and just rename it and abstract it a bit further.

I also looked into Rule::Engine which was beginning development at the time I was searching. However, like Data::Transform, it seemed more complex than what I needed. When I saw that Rule::Engine was using [the very excellent] Moose I decided to pass since I was doing work on a number of very old machines with old distros and old perls and constrained resources. Again, it just seemed to be much more than what I was looking for.

TODO ^

SEE ALSO ^

SUPPORT ^

Perldoc

You can find documentation for this module with the perldoc command.

  perldoc Sub::Chain

Websites

The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

Bugs / Feature Requests

Please report any bugs or feature requests by email to bug-sub-chain at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Chain. You will be automatically notified of any progress on the request by the system.

Source Code

http://github.com/rwstauner/Sub-Chain

  git clone http://github.com/rwstauner/Sub-Chain

AUTHOR ^

Randy Stauner <rwstauner@cpan.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2010 by Randy Stauner.

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

syntax highlighting: