NAME

Params::Callbacks - callback helper and topicalizer tools

SYNOPSIS

# Using the object oriented calling style...

use Params::Callbacks;

sub counted {
    my ($callbacks, @args) = Params::Callbacks->extract(@_);
    $callbacks->filter(@args);
}

my $size = counted 1, 2, 3, sub {
    print "> $_\n" for @_;
    return @_;
};

print "$size items\n";

# > 1
# > 2
# > 3
# 3 items

# Or, just mix-in the "callbacks" function...

use Params::Callbacks qw/callbacks/;

sub counted {
    my ($callbacks, @args) = &callbacks;
    $callbacks->filter(@args);
}

my $size = counted 'A', 'B', 'C', sub {
    print "> $_\n" for @_;
    return @_;
};

print "$size items\n";

# > A
# > B
# > C
# 3 items

# Or, use my pre-cooked topicalizer. It's like "map" but with 
# the topic up-front and in your face instead of further down 
# in the source, somewhere...

use Params::Callbacks qw/:with/;

with { 'A', 'B', 'C' } 
    item { print "> $_\n" }             # Process each item
    list { print @_ . " items\n" };     # Process entire list

# > A
# > B
# > C
# 3 items

DESCRIPTION

Provides a very simple mechanism for converting an ordinary function into a function that will allow its result to be filtered through, and possibly altered by, an optional callback queue before it is passed the caller.

TRAINING FUNCTIONS TO HANDLE CALLBACKS

( $callbacks, @params ) = Params::Callbacks->extract( @_ );

( $callbacks, @params ) = callbacks( @_ );

( $callbacks, @params ) = &callbacks;

Takes a list (here it is @_) and creates a callback queue ($callbacks) from any trailing code references and/or anonymous subs in that list. A new list is returned containing a reference to the callback queue followed by all those items in the original list that were not callbacks.

For purposes of illustration, I'm using Perl's built-in @_, which is probably typical given the nature of the task at hand. Nevertheless, any list may be processed; though, prefixing the callbacks function call with an ampersand "&" is probably only relevant when working with @_.

A callback queue may be empty, i.e. contain no callbacks. That's ok.

OUTPUT = $callbacks->filter( [INPUT] );

Passes a "would be" result (INPUT) into the head of the callback queue. The final stage of the queue yields the final result (OUTPUT). Both, INPUT and OUTPUT may be lists of zero, one or more scalars. Passing no arguments to the filter method causes $_ to be used.

An empty callback queue yields the same result that was passed into it.

USING THE with TOPICALIZER AND THE item / list STAGES

[RESULT = ]with BLOCK [STAGE [STAGE [STAGE [...]]]]

The with function takes a BLOCK as its first argument, which may be followed by zero or more stages. Each stage may be a per-item-oriented item BLOCK stage, or the list-oriented list BLOCK and sub BLOCK stages.

Per-item-oriented stages process the result of the previous stage on item at a time, i.e. if the previous stage issued a list, each item in that list is processed separately. List-oriented stages process the entire result from the previous stage; if the previous stage is an item-oriented stage then all the results are gathered together before being passed on. So, item and list stages can be mixed freely.

The sub BLOCK stage works just like the list BLOCK stage, but requires a comma to separate it from anything that follows. If that's too much ugly, just use list BLOCK.

Essentially, you end up with something looking like this:

with { ... }
    item { ... }
    list { ... }
    # etc
;

It's a beautiful structure, allowing the developer to constrain logic and temporary state within an inner block and away from the main flow, and process the results in a similar fashion.

Sure, we have map and grep but they're back-to-front and sometimes that just doesn't look right.

EXPORTS

@EXPORT

None.

@EXPORT_OK

callbacks, with, list, item.

%EXPORT_TAGS

:all

Everything in @EXPORT_OK.

:with

with, list, item.

BUGS AND FEATURE REQUESTS

Too many features; not enough bugs? Just drop me a line and I'll see what I can do to help.

AUTHOR

Iain Campbell <cpanic@cpan.org>

COPYRIGHT AND LICENCE

Copyright (C) 2012 by Iain Campbell

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.