Params::Callbacks(3)

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.