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       Constructor method.  A reference to a list of values is passed as the
20       first parameter.  Subsequent calls to get_first() and get_next() calls
21       will return each element from the list.
22
23           my $iter = Template::Iterator->new([ 'foo', 'bar', 'baz' ]);
24
25       The constructor will also accept a reference to a hash array and will
26       expand it into a list in which each entry is a hash array containing a
27       '"key"' and '"value"' item, sorted according to the hash keys.
28
29           my $iter = Template::Iterator->new({
30               foo => 'Foo Item',
31               bar => 'Bar Item',
32           });
33
34       This is equivalent to:
35
36           my $iter = Template::Iterator->new([
37               { key => 'bar', value => 'Bar Item' },
38               { key => 'foo', value => 'Foo Item' },
39           ]);
40
41       When passed a single item which is not an array reference, the
42       constructor will automatically create a list containing that single
43       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
63       Template::Iterator constructor will call that method to return the list
64       of data.  For 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
83       "MyListObject" object, $list.
84
85       By adding an "as_list()" method to the "MyListObject" class, we can
86       force the "Template::Iterator" constructor to treat the object as a
87       list and 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 items, '"foo"' and '"bar"', which
104       the "MyObjectList" encapsulates.
105
106   get_first()
107       Returns a "($value, $error)" pair for the first item in the iterator
108       set.  The $error returned may be zero or undefined to indicate a valid
109       datum was successfully returned.  Returns an error of "STATUS_DONE" if
110       the list is empty.
111
112   get_next()
113       Returns a "($value, $error)" pair for the next item in the iterator
114       set.  Returns an error of "STATUS_DONE" if all items in the list have
115       been visited.
116
117   get_all()
118       Returns a "(\@values, $error)" pair for all remaining items in the
119       iterator set.  Returns an error of "STATUS_DONE" if all items in the
120       list have been visited.
121
122   size()
123       Returns the size of the data set or undef if unknown.
124
125   max()
126       Returns the maximum index number (i.e. the index of the last element)
127       which is equivalent to size() - 1.
128
129   index()
130       Returns the current index number which is in the range 0 to max().
131
132   count()
133       Returns the current iteration count in the range 1 to size().  This is
134       equivalent to index() + 1.
135
136   first()
137       Returns a boolean value to indicate if the iterator is currently on the
138       first iteration of the set.
139
140   last()
141       Returns a boolean value to indicate if the iterator is currently on the
142       last iteration of the set.
143
144   prev()
145       Returns the previous item in the data set, or "undef" if the iterator
146       is on the first item.
147
148   next()
149       Returns the next item in the data set or "undef" if the iterator is on
150       the last item.
151
152   number()
153       This is an alias to 'count' to provide backward compatibility.  View
154       count.
155
156   parity()
157       Returns the text string "even" or "odd" to indicate the parity of the
158       current iteration count (starting at 1).  This is typically used to
159       create striped zebra tables.
160
161           <table>
162           [% FOREACH name IN ['Arthur', 'Ford', 'Trillian'] -%]
163             <tr class="[% loop.parity %]">
164               <td>[% name %]</td>
165             </tr>
166           [% END %]
167           </table>
168
169       This will produce the following output:
170
171           <table>
172             <tr class="odd">
173               <td>Arthur</td>
174             </tr>
175             <tr class="even">
176               <td>Ford</td>
177             </tr>
178             <tr class="odd">
179               <td>Trillian</td>
180             </tr>
181           </table>
182
183       You can then style the "tr.odd" and "tr.even" elements using CSS:
184
185           tr.odd td {
186               background-color: black;
187               color: white;
188           }
189
190           tr.even td {
191               background-color: white;
192               color: black;
193           }
194
195   odd()
196       Returns a boolean (0/1) value to indicate if the current iterator count
197       (starting at 1) is an odd number. In other words, this will return a
198       true value for the first iterator, the third, fifth, and so on.
199
200   even()
201       Returns a boolean (0/1) value to indicate if the current iterator count
202       (starting at 1) is an even number. In other words, this will return a
203       true value for the second iteration, the fourth, sixth, and so on.
204

AUTHOR

206       Andy Wardley <abw@wardley.org> <http://wardley.org/>
207
209       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
210
211       This module is free software; you can redistribute it and/or modify it
212       under the same terms as Perl itself.
213

SEE ALSO

215       Template
216
217
218
219perl v5.30.1                      2020-01-30             Template::Iterator(3)
Impressum