1Template::Iterator(3) User Contributed Perl DocumentationTemplate::Iterator(3)
2
6 Template::Iterator - Data iterator used by the FOREACH directive
7
9 my $iter = Template::Iterator->new(\@data, \%options);
10
12 The "Template::Iterator" module defines a generic data iterator for use
13 by the "FOREACH" directive.
14 It may be used as the base class for custom iterators.
16
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 my $iter = Template::Iterator->new([ 'foo', 'bar', 'baz' ]);
24 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 my $iter = Template::Iterator->new({
30 foo => 'Foo Item',
31 bar => 'Bar Item',
32 });
33 This is equivalent to:
35 my $iter = Template::Iterator->new([
37 { key => 'bar', value => 'Bar Item' },
38 { key => 'foo', value => 'Foo Item' },
39 ]);
40 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 my $iter = Template::Iterator->new('foo');
46 This is equivalent to:
48 my $iter = Template::Iterator->new([ 'foo' ]);
50 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 my $list = bless [ 'foo', 'bar' ], 'MyListClass';
56 my $iter = Template::Iterator->new($list);
57 equivalent to:
59 my $iter = Template::Iterator->new([ $list ]);
61 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 package MyListObject;
67 sub new {
69 my $class = shift;
70 bless [ @_ ], $class;
71 }
72 package main;
74 my $list = MyListObject->new('foo', 'bar');
76 my $iter = Template::Iterator->new($list);
77 This is then functionally equivalent to:
79 my $iter = Template::Iterator->new([ $list ]);
81 The iterator will return only one item, a reference to the
83 "MyListObject" object, $list.
84 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 package MyListObject;
90 ...
92 sub as_list {
94 my $self = shift;
95 return $self;
96 }
97 package main;
99 my $list = MyListObject->new('foo', 'bar');
101 my $iter = Template::Iterator->new($list);
102 The iterator will now return the two items, '"foo"' and '"bar"', which
104 the "MyObjectList" encapsulates.
105 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 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 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 size()
123 Returns the size of the data set or undef if unknown.
124 max()
126 Returns the maximum index number (i.e. the index of the last element)
127 which is equivalent to size() - 1.
128 index()
130 Returns the current index number which is in the range 0 to max().
131 count()
133 Returns the current iteration count in the range 1 to size(). This is
134 equivalent to index() + 1.
135 first()
137 Returns a boolean value to indicate if the iterator is currently on the
138 first iteration of the set.
139 last()
141 Returns a boolean value to indicate if the iterator is currently on the
142 last iteration of the set.
143 prev()
145 Returns the previous item in the data set, or "undef" if the iterator
146 is on the first item.
147 next()
149 Returns the next item in the data set or "undef" if the iterator is on
150 the last item.
151 number()
153 This is an alias to 'count' to provide backward compatibility. View
154 count.
155 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 <table>
162 [% FOREACH name IN ['Arthur', 'Ford', 'Trillian'] -%]
163 <tr class="[% loop.parity %]">
164 <td>[% name %]</td>
165 </tr>
166 [% END %]
167 </table>
168 This will produce the following output:
170 <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 You can then style the "tr.odd" and "tr.even" elements using CSS:
184 tr.odd td {
186 background-color: black;
187 color: white;
188 }
189 tr.even td {
191 background-color: white;
192 color: black;
193 }
194 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 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
206 Andy Wardley <abw@wardley.org> <http://wardley.org/>
207
209 Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved.
210 This module is free software; you can redistribute it and/or modify it
212 under the same terms as Perl itself.
213
215 Template
216perl v5.36.0 2023-01-20 Template::Iterator(3)