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.