NAME
Ekorn::Pipeline::Iterator - one run, handing out its values as they're pulled
SYNOPSIS
my $next = Ekorn::Pipeline->new(@stages)->iterator($source);
while (my($value) = $next->()) { ... } # one value per call
my @rest = $next->all; # every value still to come
my $first = $next->first; # the next value; then the run ends
my $one = $next->single; # the same, warning if there's another
$next->finish; # end the run now
say $next->ended; # done, stopped or died
DESCRIPTION
An iterator is one run of a pipeline, made by "iterator" in Ekorn::Pipeline. Called as a code reference, with nothing, it hands out the next value to come out of the stages, pulling its source only as it needs more. It returns an empty list once the values run out, and on every call after. Read it in list context, so that an undef value isn't taken for the end.
The run ends as soon as nothing in it can still act on a value: once its source has run out or been stopped, and every value has gone through the stages. Then each part's end is called, told how the run ended from where it stands, as "How a run ends" in Ekorn::Pipeline describes. A run that dies ends there too, and every call after returns an empty list.
An iterator left unfinished
An iterator let go before its values run out ends its run when the last reference to it goes, as "finish" does. So a source that opened a file closes it there and then:
my($first) = Ekorn::Pipeline->new(sub { uc })->iterator($lines)->();
Perl destroys a lexical iterator as soon as it goes out of scope. One kept until the program ends is destroyed during global destruction, when the order in which objects are destroyed isn't guaranteed, so an end mustn't rely on other objects then.
Pulling many values
An iterator is an object, so each call goes through Perl's overloading of &{} to find its code. A loop pulling many values can take the code reference once, and call it directly:
my $pull = \&$next; # the iterator's code, found once
while (my($value) = $pull->()) { ... }
Keep $next while you use $pull: the code reference doesn't keep the iterator, and an iterator let go ends its run, after which $pull gives nothing. Over 300,000 values, this saves about 0.02 s.
An iterator as a source
An iterator can be given to another pipeline's "iterator" in Ekorn::Pipeline as its source, as it has an "EKORN_SOURCE" method. The values it hands out go through the second pipeline's stages, and when the second run ends, it ends the first, so its source is told. The second run's stages see the first run's context, through "run_context" in Ekorn::Pipeline.
An iterator is one run, so it can be a source only once, and only before it has handed out everything it will.
METHODS
new
Iterators are made by "iterator" in Ekorn::Pipeline, not by calling new.
all
my @rest = $next->all;
my $rest = $next->all; # the same, as an array reference
Returns every value still to come, reading the run to its end. In scalar context, it returns them as an array reference. Where values are already waiting at the end of the stages, such as a sink of many's result, or a step's many values, where there are no stages, it takes them all at once, rather than one call at a time.
first
my $first = $next->first;
Returns the next value, or undef if there's none, and ends the run, as "finish" does, so nothing more is read.
single
my $one = $next->single;
Returns the next value, or undef if there's none, and ends the run, as "first" does. It pulls one value more first, to check there's no other, and warns "Expected only one item, but there were more" if there is.
finish
$next->finish;
Ends the run now, if it hasn't ended: nothing more is read, and nothing waiting is handed out. Each part's end is told how the run ended from where it stands: stopped, if its input hadn't run out. Every call after returns an empty list.
ended
my $how = $next->ended;
Returns how the run ended, once the iterator has handed out all it will, been finished, or died; until then, nothing:
doneif the source was read to its end;stoppedif the reading was cut short, by a stop anywhere, such astake(5)'s, or by "finish", or if "finish" dropped values still to be handed out;diedif anything in the run died, an end included.
It says how the run ended for whoever is reading it: each part's end is told how it ended from where that part stands, which may differ.
EKORN_SOURCE
my $parts = $next->EKORN_SOURCE;
Returns the iterator as a source's parts, by name, as "An iterator as a source" describes: a step pulling it, an end finishing it, and its run's context. A run calls it as it starts; you needn't.
DIAGNOSTICS
- Expected only one item, but there were more
-
A warning: "single" found more than one value to come.
- Expected a source with values still to give: an iterator is one run, and this one is spent
-
An iterator was given as a source after it had handed out everything it will, been finished, or died.
SEE ALSO
Ekorn::Pipeline, Ekorn::Pipeline::Source
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.