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.

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.