/ 
With-1.01
/ With

NAME

With - Topicalizer built around Params::Callbacks

SYNOPSIS

use With qw/:all/;

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

my @odds = with { 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

with {
    with {
        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 with. The function complements such Perl built-ins as map, grep and sort.

RESULT = with 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 with 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 with block?

The yield function despatches its arguments immediately to the callback queue, returning whatever comes out of the other end. The with 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 = with {
    @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 = with {
       @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

with, yield, list, item

%EXPORT_TAGS

:all

Everything in @EXPORT_OK.

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.