/ 
Params-Callbacks-2.001002
/ Params::Callbacks

NAME

Params::Callbacks - Make your subroutines accept blocking callbacks

SYNOPSIS

use Params::Callbacks 'callbacks', 'callback';  # Or use ':all' tag
use Data::Dumper;

$Data::Dumper::Indent = 0;
$Data::Dumper::Terse  = 1;

sub foo
{
    my ( $callbacks, @params ) = &callbacks;    # If &callbacks makes the hairs on 
                                                # your neck stand up, replace it with
                                                # the cleaner alternative:
                                                #
                                                # Params::Callbacks->new(@_)
    return $callbacks->transform(@params);
}

# No callbacks; no change to result!
my @result_1 = foo( 0, 1, 2, 3 );
print Dumper( [@result_1] ), "\n";  # [0,1,2,3]

# With callback, result is transformed before being returned!
my @result_2 = foo( 0, 1, 2, 3, callback { 0 + 2 ** $_ } );
print Dumper( [@result_2] ), "\n";  # [1,2,4,8]

# With multiple callbacks, result is transformed in multiple stages
my @result_3 = foo( 0, 1, 2, 3, callback { 0 + 2 ** $_ } callback { 0 + 10 * $_ });
print Dumper( [@result_3] ), "\n";  # [10,20,40,80];

DESCRIPTION

Use this package to enable your function or method to optionally transform its return value, by filtering it through zero or more blocking callbacks passed by the caller at the end of the parameter list.

At the very least, it's a bit like "map" without needing to slam your brain into reverse.

METHODS

new

Accepts a list of arguments (usually @_), stripping off any trailing callbacks and placing them in a list blessed as a Params::Callbacks object. A new list is returned, beginning with the callbacks object and followed by any arguments that were not callbacks:

sub my_function 
{
    ( $callbacks, @params ) = Params::Callbacks->new(@_);
    ...
}

Callbacks in this sense are zero or more blessed code references appearing at the end of an argument list. They are announced using a callback keyword:

my @result = my_function(1, 2, 3, callback { 'a callback' });

my @result = my_function(1, 2, 3, callback { 'a callback' }
                                  callback { 'a second callback' });

Callbacks need not be separated by commas, but use commas if you prefer.

Unblessed code references and code references (blessed or not) followed by standard arguments are treated as standard arguments.

transform

Transform a result set by passing it through all the stages of the callbacks pipeline. The transformation terminates if the result set is reduced to nothing, and an empty result set is returned.

Empty or not, this method always returns a list.

smart_transform

Transform a result set by passing it through all the stages of the callbacks pipeline. The transformation terminates if the result set is reduced to nothing, and an empty result set is returned.

Empty or not, this method always returns a list if a list was wanted.

If a scalar is required, a scalar is returned. If the result set contains a single element then the value of that element will be returned, otherwise a count of the number of elements is returned.

EXPORTED FUNCTIONS

callbacks

Accepts a list of arguments (usually @_), stripping off any trailing callbacks and placing them in a list blessed as a Params::Callbacks object. A new list is returned, beginning with the callbacks object and followed by any arguments that were not callbacks:

sub my_function 
{
    ( $callbacks, @params ) = callbacks(@_);
    ( $callbacks, @params ) = &callbacks;       # Alternative invocation
    ...
}

Callbacks in this sense are zero or more blessed code references appearing at the end of an argument list. They are announced using a callback keyword:

my @result = my_function(1, 2, 3, callback { 'a callback' });

my @result = my_function(1, 2, 3, callback { 'a callback' }
                                  callback { 'a second callback' });

Callbacks need not be separated by commas, but use commas if you prefer.

Unblessed code references and code references (blessed or not) followed by standard arguments are treated as standard arguments.

callback

A simple piece of syntactic sugar that announces a callback. The code reference it precedes is blessed as a Params::Callbacks::Callback object, disambiguating it from unblessed subs that are being passed as standard arguments.

Multiple callbacks may be chained together with or without comma separators:

callback { ... }, callback { ... }, callback { ... }    # Valid
callback { ... }  callback { ... }  callback { ... }    # Valid, too!

REPOSITORY

https://github.com/cpanic/Params-Callbacks

BUG REPORTS

Please report any bugs to http://rt.cpan.org/

AUTHOR

Iain Campbell <cpanic@cpan.org>

COPYRIGHT AND LICENCE

Copyright (C) 2012-2015 by Iain Campbell

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