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:

  • done if the source was read to its end;

  • stopped if the reading was cut short, by a stop anywhere, such as take(5)'s, or by "finish", or if "finish" dropped values still to be handed out;

  • died if 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.