NAME

Ekorn::Pipeline::Operators - |, |= and @{} for Ekorn's types

SYNOPSIS

use Ekorn::Pipeline::Operators;
use Ekorn::Pipeline::Factories qw(stage);
use Ekorn::Pipeline::Sources   qw(from_array);
use Ekorn::Pipeline::Sinks     qw(keep_all count_items);

my $blur = stage { $_->{artist} eq 'Blur' ? $_ : () };

my $n = from_array(@tracks)
    | $blur
    | count_items;    # a number
my $titles = from_array(@tracks)
    | $blur
    | stage { $_->{title} }
    | keep_all;    # an array reference
my @all = @{ from_array(@tracks) | $blur };    # every value, read through

DESCRIPTION

It puts |, |= and @{} in force for Ekorn's sources, stages, gathers, sinks and chains, for the rest of the scope it's used in; no Ekorn::Pipeline::Operators takes them out again. Written where they're not in force, they croak. They're a shorthand for the commonest shapes, not the whole of Ekorn: a pipeline made with "new" in Ekorn::Pipeline can have stages after a sink, give a list as a list, and, pulled with iterator, be a source that gives a sink's result, none of which a chain can.

  • $stage | $stage gives a chain of both stages: a pipeline, which | can extend, and which goes wherever a pipeline does.

  • $source | $stage gives a source: the source's values, through the stage.

  • $source | ... | $sink gives the sink's result, at once, not a source. For a source of the result, use iterator.

  • $chain |= $stage makes a new chain with the stage added, and puts it in the variable. Nothing made is changed.

  • @{ $source } gives every value the source gives, read through anew each time (see "READING A SOURCE THROUGH").

Start a chain with one of Ekorn's types

A chain starts with a source, or a stage made with a word, such as stage { uc }, or a ready-made one, such as take(5). What follows can be anything that goes where a stage goes, a plain code reference or a package's own part included.

Never start a chain with a plain code reference. Perl calls an overload only when one side is an object, so sub { ... } | sub { ... } is Perl's bitwise OR of two addresses: a meaningless number, with no error. Write stage { uc }, never sub { uc }, first. A pipeline made with new has no operators.

What a chain gives

An operator gives one scalar, so a chain ending in a sink gives one value: the result of a sink of one, such as count_items, or the list of a sink of many, such as keep_all, as an array reference. So my @titles = $source | keep_all gets one element, the reference: write my @titles = @{ $source | keep_all }. Nothing can be chained after a sink that ends a chain from a source: the chain has run, and given its result.

| binds more loosely than . and +, so put a chain inside a larger expression in parentheses: 'Blur: ' . ($source | $blur | count_items).

Keep a chain's result, even one run for what its sink does: my $copied = $source | to_file($path). Written as a statement of its own, the chain runs, but Perl warns "Useless use of numeric bitwise or (|) in void context" as it compiles the line, which Ekorn can't stop.

READING A SOURCE THROUGH

@{ $source } gives every value a source gives, with no sink. It looks like a dereference, but a source holds no array: Operators gives sources an @{} that runs the source from its start, collects every value into a new array, and hands Perl a reference to it. So:

  • each use is a run of its own, reading the source to its end: $source->[0], scalar @$source and $#$source read every value, to give one value, a count or an index;

  • for (@$source) reads every value before the loop starts: pull from an iterator to take each as it comes;

  • an iterator is one run, so it's read through once, and croaks the second time;

  • only a source has it: on a stage, or a chain of stages, Perl says "Not an ARRAY reference", and a chain ending in a sink is already its result;

  • in @{ $source | keep_all }, the braces are Perl's own, dereferencing the array reference the sink gave.

For the first value, use keep_first, which reads only one; for how many, count_items; for the first few, take(5) | keep_all.

FUNCTIONS

For a package whose own source class should chain as Ekorn's do. It loads Operators with an empty import list, which defines these without putting the operators in force in its own scope, and overloads with them:

use Ekorn::Pipeline::Operators ();
use overload
    '|'   => \&Ekorn::Pipeline::Operators::chain,
    '@{}' => \&Ekorn::Pipeline::Operators::drain;

Each reads the hints of the line that used the operator, so it croaks where the operators aren't in force there.

chain

Ekorn::Pipeline::Operators::chain($before, $after, $swapped)

The | of two parts, as "DESCRIPTION" describes. $swapped is true when Perl swapped them, as it does to call the overload of the right side.

drain

Ekorn::Pipeline::Operators::drain($source)

A reference to an array of every value the source gives, as "READING A SOURCE THROUGH" describes.

DIAGNOSTICS

Expected use Ekorn::Pipeline::Operators in scope, for %s

| or @{} was used on Ekorn's types where Operators isn't in force.

Expected a source, or a stage made with a word, on the left of |

A chain started with something else, such as a pipeline made with new, or an object of another class.

Expected a stage or a sink on the right of |

What followed | can't go where a stage goes.

SEE ALSO

Ekorn::Pipeline, Ekorn::Pipeline::Factories, Ekorn::Pipeline::Sources, Ekorn::Pipeline::Sinks

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.