NAME
Ekorn::Pipeline::Source - a source made afresh for each run
SYNOPSIS
use Ekorn::Pipeline::Source;
sub lines_of ($path) {
return Ekorn::Pipeline::Source->new(sub {
open my $fh, '<', $path or die "Can't read $path: $!\n"; # this run's
return (
sub () { my $line = readline $fh; defined $line ? $line : () },
sub ($how) { close $fh },
);
});
}
my $next = Ekorn::Pipeline->new(take(2))->iterator(lines_of('names.txt'));
# reads two lines, then closes the file
DESCRIPTION
A source gives the values a run starts with, one pull at a time. Any code reference is one: called with nothing, it returns the next value or values, and an empty list once there are no more. But a code reference is the same closure in every run, and is never told when the run has ended, so it can't close what it opened.
A source made with this class is made afresh for each run, by its set-up, a code reference called at the start of the run. The set-up declares, with my, whatever the run needs, such as a filehandle, and returns closures sharing it:
the step, called with nothing each time the run wants more values, returning the next value or values, or an empty list at the end. It's required;
optionally, the end, called once, when the run has ended, however it ended, told how, as its argument:
doneif the source was read to its end,stoppedif the run was cut short before it was, anddiedif the run died. What it returns is dropped;optionally, a context: anything the run's stages may ask for with "run_context" in Ekorn::Pipeline, such as a statement's columns.
It returns them as a list, in that order, giving undef for the end to give only a context, or by name, as a hash reference, as in {step => $step, context => $columns}: "Made for a run" in Ekorn::Pipeline has how.
So two iterators of the same pipeline, reading the same source, each get their own filehandle, and each closes its own, when its run ends. "How a run ends" in Ekorn::Pipeline says when that is, and what each part is told.
The step can stop the run with Ekorn::Pipeline::Stop, when it has had enough. The values the stop carries are its last, and it's told done.
A source goes where a source goes: given to "iterator" in Ekorn::Pipeline. It isn't a stage, and given to "new" in Ekorn::Pipeline as one, it croaks. Called directly, as a code reference, it croaks too: a run of its own would never be ended, so what it opened would stay open.
The word source {...}, in Ekorn::Pipeline::Factories, makes one of these from a block.
A class of your own needn't be one of these to be a source. Any object with an EKORN_SOURCE method, returning the step and optionally the end and the context, as a list or by name, is one.
METHODS
new
my $source = Ekorn::Pipeline::Source->new($setup);
Returns a source made afresh for each run by $setup, a code reference, as "DESCRIPTION" describes. Anything else croaks.
EKORN_SOURCE
my @parts = $source->EKORN_SOURCE;
Calls the set-up, for a new run, and returns what it returns: the parts, as a list or by name. A run calls it as it starts; you needn't.
DIAGNOSTICS
- Expected a code reference
-
"new" was given something other than a code reference.
- Expected a source to be read through iterator
-
A source was called as a code reference. Give it to "iterator" in Ekorn::Pipeline instead.
- Expected the source to return a code reference, and optionally an end and a context
-
The set-up returned something else: no step, or a step or end that isn't a code reference. It's reported as the run starts.
SEE ALSO
Ekorn::Pipeline, Ekorn::Pipeline::Sink, Ekorn::Pipeline::Iterator, and the ready-made sources in Ekorn::Pipeline::Sources
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.