NAME

Params::Callbacks - Enable functions to accept blocking callbacks

SYNOPSIS

# A simple filter, which does nothing on its own:

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

# Invoke the filter, allowing only odd numbered items to 
# pass through then render the result before returning
# the filtered list:

filter 1, 2, 3, 4, 5, bleach {
    $_[0] % 2 != 0 ? @_ : ();
} block {
    print join(', ', @_), "\n";
    return @_;
};

DESCRIPTION

This package provides a simple method for converting a standard function into a function that can filter its result through one or more callbacks provided by the caller.

CONFIGURING A FUNCTION TO ACCEPT CALLBACKS

Your function must do two things in order to be able to filter its results through a list of callbacks. It must first separate callbacks from the data passed to the function when it was invoked. After completion, the function's result must be passed to the callbacks for further processing before being delivered to the caller.

These two tasks are completed using the callbacks function and the yield method, like so:

sub minimalist_function
{
    # Create a callback queue and list of function parameters
    # from @_:
    #
    my ($callbacks, @params) = &callbacks;

    ...

    # Yield a result via the callback queue:
    #
    $callbacks->yield(@params);
}

( $callbacks, LIST ) = callbacks LIST;

Accepts a list of values and strips off any trailing code-references, which are used to create a callback queue. A new list is returned consisting of a reference to the callback queue, followed by the originally listed items that were not callbacks. Note that only trailing code-references are considered callbacks; once an inelligible items is encountered the collection stops.

A callback queue may be empty and that's fine.

( $callbacks, @params ) = &callbacks;

A special form of call to callbacks, using the current @_.

RESULT = $callbacks->yield(RESULT);

Yields a result via the callback queue, returning whatever comes out at the other end.

A result will pass through an empty callback queue unmodified.

block BLOCK [CALLBACK-LIST]

Introduces a blocking callback that processes the entire result set as a list.

If the terminating expression is an empty list, an empty list is passed along the callback queue to the caller unless something more meaningful is added.

bleach STATEMENT-BLOCK [CALLBACK-LIST]

Introduces a blocking callback that processes the entire result set an item at a time.

If the terminating express is an empty list, the item is removed from the result. Conversely, lists may be returned resulting in additional elements appearing in the result.

BUG REPORTS

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

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.