| 1 | 27 | ▶ | use v5.36; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 2 | |||||||||||
| 3 | package Ekorn::Pipeline::Iterator; | ||||||||||
| 4 | |||||||||||
| 5 | 27 | ▶ | use parent 'Ekorn::Pipeline::Element'; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 6 | |||||||||||
| 7 | 27 | ▶ | use Carp qw(); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 8 | 27 | ▶ | use Ekorn::Pipeline::Errors qw(croakf); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 9 | 27 | ▶ | use namespace::clean; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 10 | |||||||||||
| 11 | # Croak at the line that called Ekorn::Pipeline. | ||||||||||
| 12 | 27 | our @CARP_NOT = @Ekorn::Pipeline::Errors::INTERNAL; | |||||||||
| 13 | |||||||||||
| 14 | # Return an iterator, calling $next for each value, whose run $end_run | ||||||||||
| 15 | # ends from outside, $context is the context its run's source gave, | ||||||||||
| 16 | # $ended says how its run ended, $spent whether it has handed out | ||||||||||
| 17 | # everything it will, and $all, if given, gives every value still to | ||||||||||
| 18 | # come in one call, as calling $next until it gives none would. | ||||||||||
| 19 | 980 | ▶ | sub new ( | ||||||||
|
Subroutine
new: called CC=5 SCAR=16.1
Pod
documented
| |||||||||||
| 20 | 980 | ▶ | $class, $next, $end_run, $context = undef, $ended = sub () { return }, | ||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||
| 21 | 980 | ▶ | $spent = sub () { return }, $all = undef, | ||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||
| 22 | ) { | ||||||||||
| 23 | 980 | return bless { | |||||||||
| 24 | call => $next, | ||||||||||
| 25 | end_run => $end_run, | ||||||||||
| 26 | context => $context, | ||||||||||
| 27 | ended => $ended, | ||||||||||
| 28 | spent => $spent, | ||||||||||
| 29 | all => $all, | ||||||||||
| 30 | }, $class; | ||||||||||
| 31 | } | ||||||||||
| 32 | |||||||||||
| 33 | |||||||||||
| 34 | # Return how the run ended: "done" if its source was read to its end, | ||||||||||
| 35 | # "stopped" if the reading was cut short, by a stop or from outside, or | ||||||||||
| 36 | # values still to be handed out were dropped, and "died" if anything in | ||||||||||
| 37 | # it died; nothing until the iterator has given all it will. | ||||||||||
| 38 | 2013 | ▶ | sub ended ($self) { | ||||||||
|
Subroutine
ended: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 39 | 2013 | return $self->{ended}->(); | |||||||||
| 40 | } | ||||||||||
| 41 | |||||||||||
| 42 | |||||||||||
| 43 | # End the run, if it hasn't ended, as from outside: each part is told | ||||||||||
| 44 | # how from where it stands, and nothing more is handed out. | ||||||||||
| 45 | 51 | ▶ | sub finish ($self) { | ||||||||
|
Subroutine
finish: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 46 | 50 | $self->{end_run}->(); | |||||||||
| 47 | 50 | return; | |||||||||
| 48 | } | ||||||||||
| 49 | |||||||||||
| 50 | |||||||||||
| 51 | # Return the values still to be handed out, reading the run to its end: | ||||||||||
| 52 | # as a list, or, asked for one value, an array reference of them. A | ||||||||||
| 53 | # method, only ever called as $iterator->all, so it can't be mistaken | ||||||||||
| 54 | # for Perl's all, a keyword from 5.42. | ||||||||||
| 55 | 724 | ▶ | sub all ($self) { ## no critic (Subroutines::ProhibitBuiltinHomonyms) | ||||||||
|
Subroutine
all: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||
| 56 | 724 | my @all; | |||||||||
| 57 | 724 | ▶ | if (my $all = $self->{all}) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 58 | 723 | @all = $all->(); | |||||||||
| 59 | } | ||||||||||
| 60 | else { | ||||||||||
| 61 | 1 | my $next = $self->{call}; | |||||||||
| 62 | 1 | ▶ | while (my($value) = $next->()) { push @all, $value } | ||||||||
|
Branch: 1 branch
| |||||||||||
| 63 | } | ||||||||||
| 64 | 659 | ▶ | return wantarray ? @all : \@all; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 65 | } | ||||||||||
| 66 | |||||||||||
| 67 | |||||||||||
| 68 | # Return the next value, or undef if there's none, and end the run, so | ||||||||||
| 69 | # nothing more is read. | ||||||||||
| 70 | 3 | ▶ | sub first ($self) { | ||||||||
|
Subroutine
first: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 71 | 3 | my($value) = $self->{call}->(); | |||||||||
| 72 | 3 | $self->finish; | |||||||||
| 73 | 3 | return $value; | |||||||||
| 74 | } | ||||||||||
| 75 | |||||||||||
| 76 | |||||||||||
| 77 | # Return the next value, or undef if there's none, asserting it's the | ||||||||||
| 78 | # only one: if there's another, warn. The run ends either way. | ||||||||||
| 79 | 3 | ▶ | sub single ($self) { | ||||||||
|
Subroutine
single: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||
| 80 | 3 | my $next = $self->{call}; | |||||||||
| 81 | 3 | my($value) = $next->(); | |||||||||
| 82 | 3 | ▶ | Carp::carp 'Expected only one item, but there were more' | ||||||||
|
Branch: 1 branch
| |||||||||||
| 83 | if my($more) = $next->(); | ||||||||||
| 84 | 3 | $self->finish; | |||||||||
| 85 | 3 | return $value; | |||||||||
| 86 | } | ||||||||||
| 87 | |||||||||||
| 88 | |||||||||||
| 89 | # An iterator is a source: of the values its run gives, the run ended | ||||||||||
| 90 | # from outside when the run reading it ends, passing on its context. | ||||||||||
| 91 | 15 | ▶ | sub EKORN_SOURCE ($self) { | ||||||||
|
Subroutine
EKORN_SOURCE: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||
| 92 | croakf | ||||||||||
| 93 | 'Expected a source with values still to give: an iterator is one run, and this one is spent' | ||||||||||
| 94 | 15 | ▶ | if $self->{spent}->(); | ||||||||
|
Branch: 1 branch
| |||||||||||
| 95 | 11 | my $next = $self->{call}; | |||||||||
| 96 | return { | ||||||||||
| 97 | # Without a signature, as it's called for each value. | ||||||||||
| 98 | 23 | ▶ | step => sub { $next->() }, | ||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||
| 99 | # $how is how the reading run ended, which this one doesn't take | ||||||||||
| 100 | # on: it's ended as from outside, and each of its parts is told | ||||||||||
| 101 | # how from where it stands, so "stopped", not "died", if the | ||||||||||
| 102 | # reading run died while this one still had values to give. | ||||||||||
| 103 | 11 | ▶ | end => sub ($how) { $self->finish }, | ||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||
| 104 | context => $self->{context}, | ||||||||||
| 105 | 11 | }; | |||||||||
| 106 | } | ||||||||||
| 107 | |||||||||||
| 108 | |||||||||||
| 109 | # An iterator let go ends its run. | ||||||||||
| 110 | 980 | ▶ | sub DESTROY ($self) { | ||||||||
|
Subroutine
DESTROY: called CC=1 SCAR=0.0
| |||||||||||
| 111 | 980 | local $@ = undef; | |||||||||
| 112 | 980 | $self->{end_run}->(); | |||||||||
| 113 | 980 | return; | |||||||||
| 114 | } | ||||||||||
| 115 | |||||||||||
| 116 | 27 | 1; | |||||||||
| 117 | |||||||||||
| 118 | __END__ | ||||||||||