1Iterator::Simple::LookaUhseeard(C3o)ntributed Perl DocumIetnetraattioorn::Simple::Lookahead(3)
2
3
4

NAME

6       Iterator::Simple::Lookahead - Simple iterator with lookahead and unget
7

SYNOPSIS

9         use Iterator::Simple::Lookahead;
10         my $iter = Iterator::Simple::Lookahead->new( sub {}, @values );
11         my $first = $iter->peek();
12         my $second = $iter->peek(1);
13         my $next = $iter->next; # or $iter->()
14         $iter->unget( sub {}, @values );
15

DESCRIPTION

17       This module encapsulates an iterator function. An iterator function
18       returns the next element in the stream on each call, and returns
19       "undef" on end of input.
20
21       The iterator can return a code reference - this new iterator is
22       inserted at the head of the queue.
23
24       The object allows the user to "peek()" the Nth element of the stream
25       without consuming it, or to get it and remove from the stream.
26
27       A list of items can also be pushed back to the stream by "unget()", to
28       be retrieved in the subsequent "next()" calls. The next item can also
29       be retrieved by calling "$iter->()".
30
31       The input list to the constructor and to "unget()" contains items to be
32       retrieved on each "next()" call, or code references to be called to
33       extract the next item from the stream.
34
35       Other types of input can be converted to a code reference by "iter()"
36       of Iterator::Simple.
37
38       This module is built on top of Iterator::Simple and returns iterators
39       that are compatible with the former, i.e. an object of type
40       "Iterator::Simple::Lookahead" can be used as an input to "iter()".
41

FUNCTIONS

43   new
44       Creates a new object ready to retrieve elements from the given input
45       list. The list contains either values to be returned in a subsequent
46       "next()" call, or code references to be called to extract the next item
47       from the stream.
48
49       Other types of input can be converted to a code reference by "iter()"
50       of Iterator::Simple.
51
52   peek
53       Retrieves the Nth-element at the head of the stream, but keeps it in
54       the stream to be retrieved by "next()".
55
56       Calls the iterator function to compute the items up to the Nth element,
57       returns "undef" if the stream is exhausted before reaching N.
58
59       As a special case, "peek()" retrieves the element at the head of the
60       stream, or "undef" if the stream is empty.
61
62   next
63       Retrieves the element at the head of the stream and removes it from the
64       stream.
65
66       Returns "undef" if the stream is empty
67
68   unget
69       Pushes back a list of values and/or iterators to the stream, that will
70       be retrieved on the subsequent calls to "next()".
71
72       Can be called from within an iterator, to insert values that will be
73       returned before the current call, e.g. calling from the iterator:
74
75         $stream->unget(1..3); return 4;
76
77       will result in the values 4,1,2,3 being returned from the stream.
78

EXPORT

80       None.
81

AUTHOR

83       Paulo Custodio, "<pscust at cpan.org>"
84

BUGS and FEEDBACK

86       Please report any bugs or feature requests through the web interface at
87       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Iterator-Simple-Lookahead>.
88

ACKNOWLEDGEMENTS

90       Inspired in HOP::Stream and Iterator::Simple.
91

93       Copyright (C) 2013 by Paulo Custodio
94
95       This library is free software; you can redistribute it and/or modify it
96       under the same terms as Perl itself, either Perl version 5.16.1 or, at
97       your option, any later version of Perl 5 you may have available.
98
99
100
101perl v5.36.0                      2022-07-22    Iterator::Simple::Lookahead(3)
Impressum