NAME

Topicalizer::Block - Topicalizer built around Params::Callbacks

SYNOPSIS

use Topicalizer::Block qw/:all/;

# Give me odd numbers between 1 and 10, along block some witty banter

my @odds = block { 1..10 } item { 
    $_ % 2 ? $_ : (); 
} item { 
    printf "%2d\n", $_; 
    return $_; 
} list {
    printf "--\n%2d items\n", scalar @_;
    return @_;
};

# Ask for numbers, tell me about the odd ones

block {
    block {
        my @set;

        print "Enter some numbers, or just Enter to stop\n\n"; 
        
        while (chomp(my $number = <STDIN>)) {
            last unless $number;
            next unless $number =~ /^\d+$/;
            push @set, yield $number;
        }

        return @set;
    } item { 
        $_ % 2 ? $_ : () 
    };
}
item { 
    printf "%4d\n", $_; 
    return $_;
} list {
    printf "----\n%4d items\n", scalar @_;
    return @_;
};

DESCRIPTION

This package introduces a topicalizer function, called block. The function complements such Perl built-ins as map, grep and sort.

RESULT = block STATEMENT-BLOCK CALLBACK-LIST;

Execute a block of statements to arrive at a result that can be processed by the listed callbacks.

RESULT = yield LIST;

Normally, the result of the block is yielded automatically once the block terminates, or once you use the return statement. That is, your result is yielded to the callback queue for processing before being delivered to the caller.

But what about those situations in which you would like to yield result to the callback queue, returning the processed result back to the block block?

The yield function despatches its arguments immediately to the callback queue, returning whatever comes out of the other end. The block's execution then continues.

Yielding early, cancels automatic dispatch to the callback queue.

list STATEMENT-BLOCK [CALLBACK-LIST]

The list function introduces a callback that consumes an entire result set in @_.

@result = block {
    @result_out;
} list {
    @result_in = @_;
    ...
    @result_out;
} list {
    @result_in = @_;
    ...
    @result_out;
} list {
    @result_in = @_;
    ...
    @final_result;
};

item STATEMENT-BLOCK [CALLBACK-LIST]

Use in place of list when you want to introduce a callback that consumes an result set one item at a time, or a callback that works on a scalar result in $_ or $_[0].

   @result = block {
       @result_out;
   } item {
       $result_in = shift;
       ...
       $resul_out;
   } item {
       $result_in = shift;
       ...
       $result_out;
   } item {
       $result_in = shift;
       ...
       $result_out;
   };

Results processed using the item blocks are always gathered up into a list before being passed on. Therefore, both the item and list callbacks may be mixed freely.

EXPORTS

@EXPORT

None.

@EXPORT_OK

block, yield, list, item

%EXPORT_TAGS

:all

Everything in @EXPORT_OK.

BUGS 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.