README
1Iterator version 0.03
2=====================
3
4This module is meant to be the definitive implementation of iterators,
5as popularized by Mark Jason Dominus's lectures and recent book
6(_Higher Order Perl_, Morgan Kauffman, 2005).
7
8An "iterator" is an object, represented as a code block that generates
9the "next value" of a sequence, and generally implemented as a
10closure. Iterator.pm provides a class that simplifies creation and
11use of these iterator objects.
12
13EXAMPLES
14
15Synopsis:
16
17 $it = Iterator->new( sub { some code } );
18
19Simple "upto" counter (Dominus, p. 121):
20
21 sub upto
22 {
23 my ($m, $n) = @_;
24
25 return Iterator->new( sub {
26 return $m++ if $m <= $n;
27 Iterator::X::Am_Now_Exhausted->throw();
28 });
29 }
30
31 my $it = upto (3, 5);
32
33 $i = $it->value; # returns 3
34 $i = $it->value; # returns 4
35 $i = $it->value; # returns 5
36 $i = $it->value; # throws an Iterator::X::Exhausted exception.
37
38 $another_it = upto (7, 10);
39 while ($another_it->isnt_exhausted)
40 {
41 print $another_it->value, "\n";
42 }
43 # The above prints 7, 8, 9, 10 and throws no exceptions.
44 # Another call to $another_it->value would throw an exception.
45
46DEVELOPMENT STATE
47
48This is a brand-new module. It has a decent test suite, but has
49not been extensively field-tested. Therefore, it should be considered
50"beta" software, and used with care.
51
52If you find any bugs, or if any behavior of Iterator surprises you,
53I would be grateful if you could send me an email message about it.
54Thanks.
55
56
57INSTALLATION
58
59To install this module, do the standard Perl module four-step:
60
61 perl Makefile.PL or perl Makefile.pl LIB='my/install/path'
62 make
63 make test
64 make install
65
66DEPENDENCIES
67
68This module requires these other modules and libraries:
69
70 Exception::Class
71 Test::Simple
72
73COPYRIGHT AND LICENSE
74
75Eric J. Roode, roode@cpan.org
76
77To avoid my spam filter, please include "Perl", "module", or this
78module's name in the message's subject line, and/or GPG-sign your
79message.
80
81Copyright (c) 2005 by Eric J. Roode. All Rights Reserved.
82This module is free software; you can redistribute it and/or modify it
83under the same terms as Perl itself.
84