NAME

Params::Callbacks - Enable functions to accept blocking callbacks

SYNOPSIS

    # Using the object oriented calling style...

    use Params::Callbacks;

    sub counted {
        my ($callbacks, @args) = Params::Callbacks->extract(@_);
        $callbacks->yield(@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->yield(@args);
    }

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

    print "$size items\n";

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

DESCRIPTION

This package provides the developer with an easy and consistent method for converting a function that returns a result, into a function that will allow its result to pass through one or more blocking callbacks, before it is delivered to the caller.

It is up to the function's author to decide how and where in the function's flow those callbacks should be invoked. This is could be important during the creation of sets of results: one could apply the callbacks to a finished set, or apply them to each element of the result set as it is added.

TRAINING FUNCTIONS TO HANDLE CALLBACKS

( $callbacks, LIST ) = Params::Callbacks->extract( LIST );

( $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 up to the callback queue, returning whatever comes out at the other end.

A result will pass through an empty callback queue unmodified.

list BLOCK [CALLBACK-LIST]

sub STATEMENT-BLOCK[, CALLBACK-LIST]

On their own, callbacks receive their input result as a list; @_, to be precise, since they're really only functions.

When invoking a function that accepts callbacks, you might string a sequence of code-references, or anonymous sub blocks together, being careful to separate each witha comma (,), e.g:

    function ARGUMENTS, sub {
        ...
    }, sub {
        ...
    }, sub {
        ...
    };

Alternatively, use the list function to do exactly the same but dispense line-noise altogether:

    function ARGUMENTS, list {
        ...
    } list {
        ...
    } list {
        ...
    }

Yes, much easier on the eye!

item STATEMENT-BLOCK [CALLBACK-LIST]

Use in place of list when you want the input result one item at a time, i.e. even though the result is a list, the callback is called once for each item in the list and all items are gathered before being passed on.

Both the item and list callbacks may be mixed freely.

EXPORTS

@EXPORT

None.

@EXPORT_OK

callbacks, list, item, (DEPRECATED: extract_callbacks)

%EXPORT_TAGS

:all

Everything in @EXPORT_OK.

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.