Template::Iterator(3pm)

1Template::Iterator(3) User Contributed Perl DocumentationTemplate::Iterator(3)
2
3
4

NAME

6       Template::Iterator - Data iterator used by the FOREACH directive
7

SYNOPSIS

9           my $iter = Template::Iterator->new(\@data, \%options);
10

DESCRIPTION

12       The Template::Iterator module defines a generic data iterator for use
13       by the FOREACH directive.
14
15       It may be used as the base class for custom iterators.
16

PUBLIC METHODS

18       new($data)
19
20       Constructor method.  A reference to a list of values is passed as the
21       first parameter.  Subsequent calls to get_first() and get_next() calls
22       will return each element from the list.
23
24           my $iter = Template::Iterator->new([ 'foo', 'bar', 'baz' ]);
25
26       The constructor will also accept a reference to a hash array and will
27       expand it into a list in which each entry is a hash array containing a
28       'key' and 'value' item, sorted according to the hash keys.
29
30           my $iter = Template::Iterator->new({
31               foo => 'Foo Item',
32               bar => 'Bar Item',
33           });
34
35       This is equivalent to:
36
37           my $iter = Template::Iterator->new([
38               { key => 'bar', value => 'Bar Item' },
39               { key => 'foo', value => 'Foo Item' },
40           ]);
41
42       When passed a single item which is not an array reference, the con‐
43       structor will automatically create a list containing that single item.
44
45           my $iter = Template::Iterator->new('foo');
46
47       This is equivalent to:
48
49           my $iter = Template::Iterator->new([ 'foo' ]);
50
51       Note that a single item which is an object based on a blessed ARRAY
52       references will NOT be treated as an array and will be folded into a
53       list containing that one object reference.
54
55           my $list = bless [ 'foo', 'bar' ], 'MyListClass';
56           my $iter = Template::Iterator->new($list);
57
58       equivalent to:
59
60           my $iter = Template::Iterator->new([ $list ]);
61
62       If the object provides an as_list() method then the Template::Iterator
63       constructor will call that method to return the list of data.  For
64       example:
65
66           package MyListObject;
67
68           sub new {
69               my $class = shift;
70               bless [ @_ ], $class;
71           }
72
73           package main;
74
75           my $list = MyListObject->new('foo', 'bar');
76           my $iter = Template::Iterator->new($list);
77
78       This is then functionally equivalent to:
79
80           my $iter = Template::Iterator->new([ $list ]);
81
82       The iterator will return only one item, a reference to the MyListObject
83       object, $list.
84
85       By adding an as_list() method to the MyListObject class, we can force
86       the Template::Iterator constructor to treat the object as a list and
87       use the data contained within.
88
89           package MyListObject;
90
91           ...
92
93           sub as_list {
94               my $self = shift;
95               return $self;
96           }
97
98           package main;
99
100           my $list = MyListObject->new('foo', 'bar');
101           my $iter = Template::Iterator->new($list);
102
103       The iterator will now return the two item, 'foo' and 'bar', which the
104       MyObjectList encapsulates.
105
106       get_first()
107
108       Returns a ($value, $error) pair for the first item in the iterator set.
109       The $error returned may be zero or undefined to indicate a valid datum
110       was successfully returned.  Returns an error of STATUS_DONE if the list
111       is empty.
112
113       get_next()
114
115       Returns a ($value, $error) pair for the next item in the iterator set.
116       Returns an error of STATUS_DONE if all items in the list have been vis‐
117       ited.
118
119       get_all()
120
121       Returns a (\@values, $error) pair for all remaining items in the itera‐
122       tor set.  Returns an error of STATUS_DONE if all items in the list have
123       been visited.
124
125       size()
126
127       Returns the size of the data set or undef if unknown.
128
129       max()
130
131       Returns the maximum index number (i.e. the index of the last element)
132       which is equivalent to size() - 1.
133
134       index()
135
136       Returns the current index number which is in the range 0 to max().
137
138       count()
139
140       Returns the current iteration count in the range 1 to size().  This is
141       equivalent to index() + 1.  Note that number() is supported as an alias
142       for count() for backwards compatability.
143
144       first()
145
146       Returns a boolean value to indicate if the iterator is currently on the
147       first iteration of the set.
148
149       last()
150
151       Returns a boolean value to indicate if the iterator is currently on the
152       last iteration of the set.
153
154       prev()
155
156       Returns the previous item in the data set, or undef if the iterator is
157       on the first item.
158
159       next()
160
161       Returns the next item in the data set or undef if the iterator is on
162       the last item.
163

AUTHOR

165       Andy Wardley <abw@wardley.org>
166
167       <http://wardley.org/⎪http://wardley.org/>
168

VERSION

170       2.68, distributed as part of the Template Toolkit version 2.18,
171       released on 09 February 2007.
172

COPYRIGHT

174         Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
175
176       This module is free software; you can redistribute it and/or modify it
177       under the same terms as Perl itself.
178