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
-
usewas given something other thanpipelineand its definitions. - Expected the pipelines after pipeline in a HASH or an ARRAY of pairs
-
pipelinewas 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.