NAME

Ekorn::Pipeline::Sugar - name pipelines as the program compiles, each with a function

SYNOPSIS

use Ekorn::Pipeline::Sugar pipeline => {
    titles => [sub { $_->{title} }],
    top    => ['titles', take(3)],
};

my @titles = titles(@tracks);    # values in, a list out
my @top    = top(@tracks);       # the first three titles
my @loud   = top(@tracks, pipeline(sub { uc }));    # and more stages

my $next = pipeline('top')->iterator($source);    # pulled

DESCRIPTION

A pipeline used in several places can be named once, as the program compiles, rather than kept in a variable or wrapped in a sub. use Ekorn::Pipeline::Sugar takes pipeline and the definitions after it, each a name and an array of stages. Each pipeline is named in the package that uses the module, as "named" in Ekorn::Pipeline names it, so pipeline('name') finds it, and the package gets a function of each name.

The definitions are a hash, {...}, or an array of pairs, [...], to read in order. A string where a stage goes names a pipeline, as it does in pipeline and named: one from the same use, or one defined before it. A definition can name any other in the same use, in either order: each is defined once those it names are.

Nothing is exported: use defines the names it's given, and nothing else. A mistake croaks as the use is compiled, at its line.

FUNCTIONS

A function of each name

my @results = name(@values);
my @results = name(@values, $pipeline);

Runs the values through the pipeline of that name, and returns what comes out, in the caller's context, as calling the pipeline does: a list in list context; in scalar context, a sink's result, or how many values came out. Given a pipeline last, such as one made with the word pipeline, it runs them through that too, after the named one, so a caller can add stages of their own. A pipeline is taken for stages only last, so any other value, a code reference included, is a value.

Joining the two pipelines costs more than running a few values through them, so the function keeps the last one it was given, joined, and uses it again while that's the one given. Keep a pipeline you add stages with in a variable, such as in a loop, rather than making it in the call, and it's joined once. The function holds the last one given until it's given another.

To pull values through it from a source, use the pipeline itself: pipeline('name')->iterator($source).

METHODS

import_into

Ekorn::Pipeline::Sugar->import_into($package, pipeline => {...});

Does what use does, for $package in place of its caller: for a module whose own sugar takes pipelines, and hands them on, so they're named in, and given to, the package that uses that module. The names are read in $package, as is a string naming a pipeline.

The names, and the functions the package has already, are checked before any pipeline is defined. A stage that isn't one, or a name another pipeline has, is found only as its definition is made, so the definitions made before it stay made. For use, that doesn't matter, as the program stops; a module calling this inside an eval should know it.

DIAGNOSTICS

Expected pipeline, not %s

use was given something other than pipeline and its definitions.

Expected the pipelines after pipeline in a HASH or an ARRAY of pairs

pipeline was followed by something else.

Expected the pipelines after pipeline in pairs of a name and an ARRAY

An array of definitions had an odd number of items.

Expected a name for a pipeline (%s)

A name can't be a function's: it's a word, of letters, digits and underscores, not starting with a digit.

Expected a pipeline defined once (%s)

An array of definitions gave the name twice.

Expected the pipeline %s in an ARRAY

A definition wasn't an array reference of stages.

Expected no function of the name in %s already (%s)

The package has a function of that name already, its own or one it inherits.

Expected pipelines that don't name each other in a circle (%s)

The definitions named, those left undefined, name each other, through others or not, so none can be defined first.

Ekorn::Pipeline's messages for stages and names are raised for a definition as for pipeline, such as "No pipeline named %s", for a name defined nowhere, and "A pipeline named %s is already defined".

SEE ALSO

Ekorn::Pipeline, whose named names a pipeline as the program runs; Ekorn::Pipeline::Factories, whose pipeline fetches one by its name; and DBIx::Squirrel::Sugar, which names databases and statements the same way.

AUTHOR

Iain Campbell <cpanic@cpan.org>

LICENSE

Copyright (c) 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.