NAME

Ekorn::Pipeline::Sources - ready-made sources, needing only Perl

SYNOPSIS

use Ekorn::Pipeline::Sources qw(from_array from_fh from_file counter);

my $next = Ekorn::Pipeline->new(take(2))->iterator(from_file('tracks.txt'));
# reads two lines, then closes the file

my @evens = Ekorn::Pipeline->new(take(3))->iterator(counter(2, 2))->all;    # 2 4 6

DESCRIPTION

Sources for "iterator" in Ekorn::Pipeline, needing nothing beyond Perl. Each returns an Ekorn::Pipeline::Source, made afresh for each run, so each run reads from the start. Nothing is exported by default; ask for each, or for :all.

from_fh and from_file read with $/ as it is at each read, as readline does: lines, unless it's changed; a paragraph at a time, with $/ set to ''; records of a fixed size, with a reference to a number, as \4096; and all of what's left as one record, slurped, with $/ undefined, an empty file giving none, though readline gives one empty string. Each record is given without its separator, as chomp removes it.

FUNCTIONS

from_array

from_array(@values)

Gives the values given, in order, from the first, on each run. A hash's pairs are from_array(map { [$_, $hash{$_}] } keys %hash). It has no end.

from_fh

from_fh($fh)

Gives the records read from $fh, a filehandle you opened, which it leaves open, for you to close. Each run reads on from where the last left off. It croaks "Expected an open filehandle" given anything else.

from_file

from_file($path)
from_file($path, $layers)

Gives the records of the file at $path, opening it for each run, and closing it once the run has ended, however it ended: when the records ran out, when a stage stopped the run, or when one died. It's opened through the I/O layers given, if any: ':raw' reads bytes, unchanged on any platform, and ':encoding(UTF-8)' decodes text. Without them, Perl opens it as it does by default, which on Windows translates line endings, and so corrupts a binary file. A file that can't be opened croaks "Can't read %s: %s" as the run starts.

counter

counter($start, $step)
counter()

Gives $start, then on by $step, without end: 1, 2, 3 and on, by default. Give it a take, or a stage that stops. It croaks "Expected a number to start from, and one to step by" given anything else.

DIAGNOSTICS

Expected an open filehandle

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

Can't read %s: %s

"from_file" couldn't open the file, as a run started; the second part says why.

Expected a number to start from, and one to step by

"counter" was given something other than numbers.

SEE ALSO

Ekorn::Pipeline, Ekorn::Pipeline::Source, Ekorn::Pipeline::Factories, 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.