NAME

Ekorn::Pipeline::Sinks - ready-made sinks, needing only Perl

SYNOPSIS

use Ekorn::Pipeline::Sinks qw(:all);

my @all   = Ekorn::Pipeline->new(keep_all)->(@values);          # every value
my $all   = Ekorn::Pipeline->new(keep_all)->(@values);          # the same, as an array reference
my $n     = Ekorn::Pipeline->new(count_items)->(@values);       # how many
my $first = Ekorn::Pipeline->new(keep_first)->iterator($source)->();    # stops at the first

my $copied = Ekorn::Pipeline->new(to_file('copy.txt'))->iterator(from_file('original.txt'))->();

DESCRIPTION

Sinks, each usually given last in a pipeline, so that its result is what a run gives (see Ekorn::Pipeline::Sink). Each is made afresh for each run. Nothing is exported by default; ask for each, or for :all.

They come in two families. Those named for what they give, an item being a value, have names that can't clash with Perl's built-ins or List::Util's, which is why they're keep_first and keep_all, not first and all. The containers, named for where the items go, are the to_ sinks, each the counterpart of a from_ source in Ekorn::Pipeline::Sources: what one reads, the other writes.

Asked for one value, in scalar context, a sink giving a list gives it as an array reference. An array reference is true even when it's empty, so test for no items with @$all, or use count_items.

A sink that stops the pull early is told done: it decided the run had enough. The source and the stages before it are told stopped.

Each sink taking no arguments has an empty prototype, so that count_items + 0 reads as count_items() + 0.

FUNCTIONS

keep_all

Gives every item, as a list. It's a sink of many.

keep

keep($n)

Gives the first $n items, as a list, as take($n) would pass on, and stops the run once it has them. It's a sink of many. It croaks "Expected a count of 0 or more", as take does, given anything but a whole number.

keep_first

Gives the first item, or undef if there was none, and stops the run there.

keep_single

Gives the one item, or undef if there was none. At a second, it warns "Expected only one item, but there were more", and stops the run, giving the first: for when you meant one item, and forgot to limit it to one.

keep_last

Gives the last item, reading every one to find it, or undef if there was none.

count_items

Gives how many items there were.

to_fh

to_fh($fh)

Prints each item to $fh, a filehandle you opened, followed by $/, and gives how many. It leaves the filehandle open, for you to close. It croaks "Expected an open filehandle" given anything else.

to_file

to_file($path)
to_file($path, $layers)

Writes each item to the file at $path, followed by $/, and gives how many. The file is opened, emptied, as the run starts, through the I/O layers given, if any, such as ':raw' or ':encoding(UTF-8)', and closed once the run has ended, however it ended.

from_fh and from_file take $/ off each record, and to_fh and to_file add it back, so a file read with one is written unchanged by the other. With $/ undefined, or a reference to a record size, nothing is added; with it empty, for paragraphs, a blank line is.

DIAGNOSTICS

Expected a count of 0 or more

"keep" was given something other than a whole number.

Expected only one item, but there were more

A warning: "keep_single" was given a second item, and stopped the run, giving the first.

Expected an open filehandle

"to_fh" was given something other than an open filehandle.

Can't write %s: %s

"to_fh" or "to_file" couldn't write, or "to_file" couldn't open or close its file; the second part says why. The first is the file's path, or "the filehandle".

SEE ALSO

Ekorn::Pipeline, Ekorn::Pipeline::Sink, Ekorn::Pipeline::Sources, Ekorn::Pipeline::Stages::Flow, whose take stages match the keep 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.