File Coverage

blib/lib/List/Gather.pm

Criterion	Covered	Total	%
statement	19	19	100.0
branch			n/a
condition			n/a
subroutine	7	7	100.0
pod			n/a
total	26	26	100.0

package List::Gather; # git description: 0.13-9-g4c4e5d3
# ABSTRACT: Construct lists procedurally without temporary variables

use strict;
use warnings;

our $VERSION = '0.14';

use Devel::CallParser;
use Devel::CallChecker;

use XSLoader;

XSLoader::load(
    __PACKAGE__,
    $VERSION,
);

require B::Hooks::EndOfScope
    unless _QPARSE_DIRECTLY();

my @keywords;
BEGIN { @keywords = qw(gather take gathered) }

use Sub::Exporter -setup => {
    exports => [@keywords],
    groups  => { default => [@keywords] },
};

#pod =head1 SYNOPSIS
#pod
#pod   use List::Gather;
#pod
#pod   my @list = gather {
#pod       while (<$fh>) {
#pod           next if /^\s*$/;
#pod           next if /^\s*#/;
#pod           last if /^(?:__END__|__DATA__)$/;
#pod           take $_ if some_predicate($_);
#pod       }
#pod
#pod       take @defaults unless gathered;
#pod   };
#pod
#pod =head1 DESCRIPTION
#pod
#pod This module provides a C keyword that allows lists to be constructed
#pod procedurally, without the need for a temporary variable.
#pod
#pod Within the block controlled by a C any call to C pushes that
#pod call's argument list to an implicitly created array.
#pod
#pod C returns the list of values taken during its block's execution.
#pod
#pod =head1 EXAMPLES
#pod
#pod   my @interesting_child_nodes = gather for my $n (@nodes) {
#pod       take $n->all_children
#pod           if $n->is_interesting;
#pod   };
#pod
#pod   my @last_10_events = gather {
#pod       while ($log->has_event) {
#pod           take $log->next_event;
#pod       }
#pod
#pod       shift gathered while gathered > 10;
#pod   };
#pod
#pod   my @search_results = gather {
#pod       $user_interface->register_status_callback(sub {
#pod           sprintf "Searching... Found %d matches so far", scalar gathered;
#pod       });
#pod
#pod       wait_for_search_results(sub {
#pod           my ($result) = @_;
#pod           take $result;
#pod       }, @search_terms);
#pod
#pod       $user_interface->register_status_callback(sub {
#pod           sprintf "Found a total of %d", scalar gathered;
#pod       });
#pod   };
#pod
#pod   my @leaf_nodes = gather {
#pod       $graph->visit_all_nodes_recursively(sub {
#pod           my ($node) = @_;
#pod           take $node if $node->is_leaf;
#pod       });
#pod   };
#pod
#pod =func gather
#pod
#pod   gather { ... }
#pod   gather({ ... })
#pod   gather STMT
#pod
#pod Executes the block it has been provided with, collecting all arguments passed to
#pod C calls within it. After execution, the list of values collected is
#pod returned.
#pod
#pod Note that block C executes is equivalent to a C. It is neither
#pod a code nor a loop. Loop control keywords, such as C and C, as well
#pod as C will behave accordingly.
#pod
#pod Parens around the C block are optional.
#pod
#pod =func take
#pod
#pod   take LIST
#pod
#pod Collects a C of values within the C block it has been compiled in.
#pod
#pod C returns all its arguments.
#pod
#pod C calls outside of the lexical scope of a C block are compile time
#pod errors. Calling C is only legal within the dynamic scope its associated
#pod C block.
#pod
#pod =func gathered
#pod
#pod   gathered
#pod
#pod Returns the list of items collected so far during the execution of a C
#pod block.
#pod
#pod C calls outside of the lexical scope of a C block are compile
#pod time errors. Calling C outside of the dynamic scope of its associated
#pod C block is legal.
#pod
#pod =head1 SEE ALSO
#pod
#pod =for :list
#pod = L
#pod A non-lexical gather/take implementation that's otherwise very similar to this one
#pod = L
#pod An experimental implementation of a lazily evaluating gather/take
#pod = L
#pod A very simple gather/take implementation without lexical scoping
#pod = L
#pod Like L, but reliant on L
#pod = L
#pod A comprehensive suit list generation functions featuring a non-lexical gather/take
#pod
#pod =head1 ACKNOWLEDGEMENTS
#pod
#pod =for :list
#pod * Andrew Main (Zefram) [e-mail]
#pod for providing his input in both the design and implementation of this module,
#pod and writing much of the infrastructure that made this module possible in the
#pod first place
#pod * Arthur Axel "fREW" Schmidt [e-mail]
#pod for his input on various aspects of this module as well as the many tests of his
#pod L module that this module shamelessly stole
#pod * Dave (autarch) Rolsky  and Jesse (doy) Luehrs [e-mail]
#pod for helping to improve both documentation and test coverage
#pod
#pod =cut

1;

__END__