NAME
DBIx::Squirrel::Iterator - an iterator over a statement's results
SYNOPSIS
my $it = $dbh->iterate(
'SELECT id, name FROM artist WHERE name LIKE :pattern',
pattern => 'A%',
sub ($row) { $row->[1] },
);
while (my($name) = $it->next) {
say $name;
}
# A stage can leave its signature out, and use $_
my @names = $dbh->iterate('SELECT id, name FROM artist', sub { $_->[1] })->all;
my $sth = $dbh->prepare(
'SELECT * FROM artist WHERE id = $1',
{ekorn_slice => {}},
);
my $artist = $sth->iterate(42)->single;
DESCRIPTION
An iterator executes a statement and hands out its rows one at a time, each run through a pipeline of stages, as DBIx::Squirrel::Pipeline runs them: a stage can change a row, drop it, return several values in its place, or stop the iteration with DBIx::Squirrel::Stop. A result is whatever comes out of the stages; with none, it's the row. A stage can ask about the result it's making with DBIx::Squirrel::Context.
An iterator is made by "iterate" in DBIx::Squirrel::db or "iterate" in DBIx::Squirrel::st. It executes the statement when its first result is asked for, and finishes the statement when the results run out.
Rows are fetched 100 at a time, with "fetchall_arrayref" in DBI, each as an array, or, with the ekorn_slice attribute, in the shape it gives:
$dbh = DBIx::Squirrel->connect($dsn, $user, $pass, {ekorn_slice => {}});
$sth = $dbh->prepare($statement, {ekorn_slice => {}});
ekorn_slice is a slice as "fetchall_arrayref" in DBI takes it: an array reference, for rows as arrays, or a hash reference, for rows as hashes. Given to connect, it's the default for each statement the handle prepares; given to prepare, it's for that statement.
One statement handle can have one iterator going through its results at a time.
METHODS
new
$it = DBIx::Squirrel::Iterator->new($sth, @bind_values, @stages);
Returns an iterator over the rows of $sth, a DBIx::Squirrel::st, executed with @bind_values, in any form "execute" in DBIx::Squirrel::st takes, and run through @stages, the code references at the end of the arguments. It doesn't execute the statement.
next
while (my($result) = $it->next) { ... }
Returns the next result, or an empty list when there are no more. A stage can return undef as a result, so read next in list context, as above, rather than testing whether what it returns is defined.
all
@results = $it->all;
$count = $it->all;
Returns the results not yet fetched, or, in scalar context, how many there were. Either way, they're fetched, and next returns nothing after.
single
$result = $it->single;
Executes the statement again, and returns its one result, or nothing if it has none. It croaks if there's more than one. Either way, it's done: next returns nothing after.
reset
$it = $it->reset;
$it = $it->reset(@bind_values, @stages);
Executes the statement again, ready to iterate from its first row, finishing it first if it's still active, and returns the iterator. Bind values given replace those given before. Stages given are added to those given to "new". Both are kept until others are given.
count
$n = $it->count;
Returns the number of results fetched so far.
sth
$sth = $it->sth;
Returns the statement handle.
DIAGNOSTICS
- Expected a statement handle
-
"new" wasn't given a DBIx::Squirrel::st.
- Expected one result, not more
-
"single" found a second result.
- Expected the statement handle's other iterator to be finished
-
The iterator's statement handle has another iterator, which has results left to hand out. Read that one to the end, or let it go out of scope, before executing this one.
SEE ALSO
DBIx::Squirrel, DBIx::Squirrel::Context, DBIx::Squirrel::Pipeline
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.