NAME
DBIx::Squirrel::Pipeline - run values through a list of stages
SYNOPSIS
use DBIx::Squirrel::Pipeline;
my $p = DBIx::Squirrel::Pipeline->new(
sub { $_->{active} ? $_ : () }, # filter
sub ($row) { @{ $row->{tags} } }, # flatMap
sub { uc }, # map
);
# Push: values in, a list out
my @tags = $p->(@rows);
# Pull: one value per call, from a source
my $next = $p->iterator(sub { $sth->fetchrow_hashref // () });
while (my($tag) = $next->()) { ... }
DESCRIPTION
A pipeline is a list of stages, each a code reference. A stage is called with one value, as its argument and in $_, so it can name the value with a signature, sub ($row) { $row->[1] }, or leave the signature out and use $_, sub { $_->[1] }. $_ is localised for each call, so the caller's is left as it was. A stage returns a list:
nothing, to drop the value (a filter);
one value, to pass it on (a map);
several, each of which goes through the rest of the stages on its own (a flatMap).
Each value goes through every stage before the next one starts, so the values come out in order, and a stage sees them in the order a for loop would.
A stage can end the pipeline early with DBIx::Squirrel::Stop. The values already out are kept, any values the stop carries go on through the rest of the stages, and nothing else is processed:
sub ($row) { $row->{id} == $wanted ? Stop($row) : () }
A stage made with DBIx::Squirrel::Gather is made afresh for each run of the pipeline, and can have a function called once the values run out, whose values go through the rest of the stages. Each push of values, and each iterator, is a run.
A pipeline isn't only for rows. Loading it doesn't load the DBI, so a function of your own can take stages from its caller, as iterate does, and run what it returns through them:
sub bands (@stages) {
return DBIx::Squirrel::Pipeline->new(@stages)->(load_bands());
}
my @names = bands(pluck('name'), take(5));
The canned stages work there too, except those needing a statement's column names, which need an iterator, as DBIx::Squirrel::Stages::Rows says. Outside an iterator, DBIx::Squirrel::Context's functions return undef.
METHODS
new
my $p = DBIx::Squirrel::Pipeline->new(@stages);
Returns a pipeline running values through @stages, in order. It croaks if a stage isn't a code reference. With no stages, a pipeline returns its values as they are.
A pipeline is an object that can be called as a code reference. Called with values, it returns the list that comes out of the last stage:
my @results = $p->(@values);
iterator
my $next = $p->iterator($source);
Returns a closure handing out, one per call, the values that come out of the stages. $source is a code reference returning the next value or values on each call, and an empty list when there are no more; it's called only when the values from its last call have all been handed out.
The closure returns an empty list when the values run out, or once a stage has stopped the pipeline and the values its stop carried are handed out, and on every call after that. After a stop, the source isn't called again. Read it in list context, so an undef value isn't mistaken as the end:
while (my($x) = $next->()) { ... }
The end functions of stages made with DBIx::Squirrel::Gather are called once the source runs out, or after a stop, before the closure returns an empty list.
FUNCTIONS
ending
For DBIx::Squirrel::Context, which reads it; not for use elsewhere. True while the values going through the stages come from an end function, rather than from the source.
DIAGNOSTICS
- Expected stage #%d to be a code reference
-
A stage given to "new" wasn't a code reference.
- Expected a code reference
-
The source given to "iterator" wasn't a code reference.
- Expected stage #%d, made with gather, to return one or two code references
-
The block given to "gather" in DBIx::Squirrel::Gather for that stage returned something other than a stage, or a stage and an end function.
- Pipeline stage #%d failed at %s line %d:
-
A stage, or its end function, died. The message it died with follows, indented. An exception object is passed on as it is.
SEE ALSO
DBIx::Squirrel, DBIx::Squirrel::Gather, DBIx::Squirrel::Stop
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.