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
63 Template::Iterator constructor will call that method to return the list
64 of data. For 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
86 force the "Template::Iterator" constructor to treat the object as a
87 list and 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 parity()
153 Returns the text string "even" or "odd" to indicate the parity of the
154 current iteration count (starting at 1). This is typically used to
155 create striped zebra tables.
156 <table>
158 [% FOREACH name IN ['Arthur', 'Ford', 'Trillian'] -%]
159 <tr class="[% loop.parity %]">
160 <td>[% name %]</td>
161 </tr>
162 [% END %]
163 </table>
164 This will produce the following output:
166 <table>
168 <tr class="odd">
169 <td>Arthur</td>
170 </tr>
171 <tr class="even">
172 <td>Ford</td>
173 </tr>
174 <tr class="odd">
175 <td>Trillian</td>
176 </tr>
177 </table>
178 You can then style the "tr.odd" and "tr.even" elements using CSS:
180 tr.odd td {
182 background-color: black;
183 color: white;
184 }
185 tr.even td {
187 background-color: white;
188 color: black;
189 }
190 odd()
192 Returns a boolean (0/1) value to indicate if the current iterator count
193 (starting at 1) is an odd number. In other words, this will return a
194 true value for the first iterator, the third, fifth, and so on.
195 even()
197 Returns a boolean (0/1) value to indicate if the current iterator count
198 (starting at 1) is an even number. In other words, this will return a
199 true value for the second iteration, the fourth, sixth, and so on.
200
202 Andy Wardley <abw@wardley.org> <http://wardley.org/>
203
205 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
206 This module is free software; you can redistribute it and/or modify it
208 under the same terms as Perl itself.
209
211 Template
212perl v5.28.1 2018-10-05 Template::Iterator(3)