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: done if the source was read to its end, stopped if the run was cut short before it was, and died if 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.