NAME

DBIx::Squirrel::Gather - a stage made afresh for each run, told when the values run out

SYNOPSIS

use DBIx::Squirrel::Gather;

# Rows in batches of $size, the last batch given at the end
sub batches_of ($size) {
    return gather {
        my @batch;    # this run's
        return (
            sub ($row) { push @batch, $row; @batch == $size ? [splice @batch] : () },
            sub ()     { @batch ? [@batch] : () },
        );
    };
}

my $batches = $dbh->iterate('SELECT id, name FROM track', batches_of(500));
while (my($batch) = $batches->next) { ... }

DESCRIPTION

DBIx::Squirrel's name for Ekorn::Pipeline::Gather, which describes gather in full. It exports gather by default. That's Ekorn's function, from a list of DBIx::Squirrel's own. The module is here to stay, so code written with it keeps working.

gather makes a stage afresh at the start of each run of a pipeline: each execution of an iterator or result set, and each call of a Sugar statement or of a pipeline itself. Its block returns the stage, which can be a pipeline, and optionally a flush and an end. The flush is called once the values have run out, and what it returns goes through the rest of the stages. The end is called once the run has ended, and told how: done, stopped or died. The block can return them as a list, in that order, or by name, as one hash reference with the keys step, flush and end, giving only those it has.

The stage it makes is an Ekorn::Pipeline::Gather, an object that can go wherever a stage can. To test for one, test for that class, not this one.

Inside a flush, and the stages it sends values to, "result_number" in DBIx::Squirrel::Context is the number of the result being made, as in any stage. "result_original" in DBIx::Squirrel::Context is undef, as what a flush gives comes from many rows, not one.

To keep gather out of your namespace:

use DBIx::Squirrel::Gather ();

SEE ALSO

Ekorn::Pipeline::Gather, DBIx::Squirrel, DBIx::Squirrel::Context

AUTHOR

Iain Campbell <cpanic@cpan.org>

LICENSE

Copyright (c) 2024-2026 by Iain Campbell.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.