NAME
Ekorn::Pipeline::Factories - words that make Ekorn's types
SYNOPSIS
use Ekorn::Pipeline::Factories qw(:all);
my $p = pipeline(
stage { uc },
'clean',
take(5),
); # a pipeline, names looked up here
my $lines = source {
open my $fh, '<', $path or die "Can't read $path: $!\n"; # this run's
return (
sub () { my $line = readline $fh; defined $line ? $line : () },
sub ($how) { close $fh },
);
};
my $pairs = generator {
for my $x (1 .. 3) { yield [$x, $_] for $x .. 3 }
};
my $total = sink_one {
my $sum = 0;
return (sub ($x) { $sum += $x }, sub () { $sum });
};
my $kept = sink_many {
my @kept;
return (sub ($x) { push @kept, $x }, sub () { @kept });
};
DESCRIPTION
The words make Ekorn's types from what you write. Each is a short, keyword-like function, one line over a class method: syntax, not behaviour, so it lives here, not in the class it makes. Nothing is exported by default; ask for each word, or for :all.
pipeline(@stages), a pipeline, its stages able to name pipelines;stage {...}, a Ekorn::Pipeline::Stage;gather {...}, a Ekorn::Pipeline::Gather;source {...}andgenerator {...}, a Ekorn::Pipeline::Source, withyieldfor a generator;sink_one {...}andsink_many {...}, a Ekorn::Pipeline::Sink of one or of many.
A package built on Ekorn uses them as they are, rather than making words of its own for Ekorn's types.
FUNCTIONS
pipeline
pipeline(@stages)
Returns a new pipeline of @stages, each a code reference, a pipeline, or the name of one, looked up now, in the package that called pipeline, unless it's qualified; or, given one name alone, the pipeline it names, itself. It's Ekorn::Pipeline->pipeline_in(scalar caller, @stages), as "pipeline_in" in Ekorn::Pipeline describes, with named pipelines.
stage
stage { BLOCK }
stage sub ($row) { ... }
Returns a stage of the block: called with each value, as any stage is. It's an Ekorn::Pipeline::Stage, an object called as a code reference. To give it a signature, give it a sub. A Stage keeps what it's given, so stage(\&trim) never changes trim itself.
gather
gather { SET-UP }
Returns a stage made afresh for each run, whose set-up returns its step, and, optionally, its flush and its end, as Ekorn::Pipeline::Gather describes. It's the same gather Ekorn::Pipeline::Gather exports.
source
source { SET-UP }
Returns a source made afresh for each run. Its set-up returns its step, called with nothing, again and again, giving the next value or values, or an empty list when there are no more; optionally, its end, told how the run ended; and, optionally, a context for the run, which its stages ask for with "run_context" in Ekorn::Pipeline. With a context but no end, give undef for the end, or return the parts by name, as "Made for a run" in Ekorn::Pipeline describes. It's an Ekorn::Pipeline::Source.
sub up_to ($last) {
return source {
my $n = 0; # this run's
return sub () { $n < $last ? ++$n : () };
};
}
A source with nothing to set up or end needs no word: any code reference is a source.
generator
generator { BLOCK }
Returns a source giving what its block passes to "yield", as a Python generator does. Perl can't pause a sub at yield, so each run calls the block once, to its end, and gives every value it yielded in one step. So the block mustn't loop without end, and runs to its end even when a stage after it takes only some. For a producer without end, write a "source" whose step gives a value each call.
Two of Perl's parsing rules apply: an empty block, generator {}, reads as an empty hash, so write generator { return }; and @{ generator {...} | ... } reads as a hash slice, so keep the generator in a variable first.
yield
yield(@values)
Adds @values to what the generator whose block is running gives. It croaks outside one. A generator read inside another's block keeps its own.
sink_one
sink_one { SET-UP }
Returns a sink of one, made afresh for each run: its set-up returns its step, called with each value, whose return is ignored; its flush, called when its input runs out, giving its result, one value; and, optionally, its end, told how the run ended. It's an Ekorn::Pipeline::Sink, made with new_sink_one.
my $longest = sink_one {
my $max;
return (
sub ($s) { $max = $s if length $s > length($max // '') },
sub () { $max },
);
};
say Ekorn::Pipeline->new($longest)->(qw(a bbb cc)); # bbb
sink_many
sink_many { SET-UP }
Returns a sink of many, as "sink_one" does, whose flush gives a list. Asked for one value, a pipeline ending in it gives the list as an array reference, so write a sink of one value with sink_one.
DIAGNOSTICS
- Expected yield to be called inside a generator
-
"yield" was called with no generator's block running.
- Expected a code reference
-
A word was given something other than a block or code reference.
The words pass on the diagnostics of the classes they make, and "pipeline" those of "pipeline_in" in Ekorn::Pipeline.
SEE ALSO
Ekorn::Pipeline, Ekorn::Pipeline::Gather, Ekorn::Pipeline::Source, Ekorn::Pipeline::Sink, Ekorn::Pipeline::Stage
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.