Template::Iterator(3) User Contributed Perl Documentation Template::Iterator(3)
# [NAME](#NAME)
Template::Iterator - Data iterator used by the FOREACH directive
# [SYNOPSIS](#SYNOPSIS)
```
my $iter = Template::Iterator->new(\@data, \%options);
```
# [DESCRIPTION](#DESCRIPTION)
The "Template::Iterator" module defines a generic data iterator for use by the "FOREACH" directive.
It may be used as the base class for custom iterators.
# [PUBLIC METHODS](#PUBLIC_METHODS)
## [new($data)](#new%28$data%29)
Constructor method. A reference to a list of values is passed as the first parameter. Subsequent calls to **get\_first()** and **get\_next()** calls will return each element from the list.
```
my $iter = Template::Iterator->new([ 'foo', 'bar', 'baz' ]);
```
The constructor will also accept a reference to a hash array and will expand it into a list in which each entry is a hash array containing a '"key"' and '"value"' item, sorted according to the hash keys.
```
my $iter = Template::Iterator->new({
foo => 'Foo Item',
bar => 'Bar Item',
});
```
This is equivalent to:
```
my $iter = Template::Iterator->new([
{ key => 'bar', value => 'Bar Item' },
{ key => 'foo', value => 'Foo Item' },
]);
```
When passed a single item which is not an array reference, the constructor will automatically create a list containing that single item.
```
my $iter = Template::Iterator->new('foo');
```
This is equivalent to:
```
my $iter = Template::Iterator->new([ 'foo' ]);
```
Note that a single item which is an object based on a blessed ARRAY references will NOT be treated as an array and will be folded into a list containing that one object reference.
```
my $list = bless [ 'foo', 'bar' ], 'MyListClass';
my $iter = Template::Iterator->new($list);
```
equivalent to:
```
my $iter = Template::Iterator->new([ $list ]);
```
If the object provides an as\_list() method then the Template::Iterator constructor will call that method to return the list of data. For example:
```
package MyListObject;
sub new {
my $class = shift;
bless [ @_ ], $class;
}
package main;
my $list = MyListObject->new('foo', 'bar');
my $iter = Template::Iterator->new($list);
```
This is then functionally equivalent to:
```
my $iter = Template::Iterator->new([ $list ]);
```
The iterator will return only one item, a reference to the "MyListObject" object, $list.
By adding an as\_list() method to the "MyListObject" class, we can force the "Template::Iterator" constructor to treat the object as a list and use the data contained within.
```
package MyListObject;
...
sub as_list {
my $self = shift;
return $self;
}
package main;
my $list = MyListObject->new('foo', 'bar');
my $iter = Template::Iterator->new($list);
```
The iterator will now return the two items, '"foo"' and '"bar"', which the "MyObjectList" encapsulates.
## **get\_first()**
Returns a "($value, $error)" pair for the first item in the iterator set. The $error returned may be zero or undefined to indicate a valid datum was successfully returned. Returns an error of "STATUS\_DONE" if the list is empty.
## **get\_next()**
Returns a "($value, $error)" pair for the next item in the iterator set. Returns an error of "STATUS\_DONE" if all items in the list have been visited.
## **get\_all()**
Returns a "(\\@values, $error)" pair for all remaining items in the iterator set. Returns an error of "STATUS\_DONE" if all items in the list have been visited.
## **size()**
Returns the size of the data set or undef if unknown.
## **max()**
Returns the maximum index number (i.e. the index of the last element) which is equivalent to **size()** - 1.
## **index()**
Returns the current index number which is in the range 0 to **max()**.
## **count()**
Returns the current iteration count in the range 1 to **size()**. This is equivalent to **index()** + 1.
## **first()**
Returns a boolean value to indicate if the iterator is currently on the first iteration of the set.
## **last()**
Returns a boolean value to indicate if the iterator is currently on the last iteration of the set.
## **prev()**
Returns the previous item in the data set, or "undef" if the iterator is on the first item.
## **next()**
Returns the next item in the data set or "undef" if the iterator is on the last item.
## **number()**
This is an alias to 'count' to provide backward compatibility. View count.
## **parity()**
Returns the text string "even" or "odd" to indicate the parity of the current iteration count (starting at 1). This is typically used to create striped *zebra tables*.
```
[% FOREACH name IN ['Arthur', 'Ford', 'Trillian'] -%]
| [% name %] |
[% END %]
```
This will produce the following output:
```
```
You can then style the "tr.odd" and "tr.even" elements using CSS:
```
tr.odd td {
background-color: black;
color: white;
}
tr.even td {
background-color: white;
color: black;
}
```
## **odd()**
Returns a boolean (0/1) value to indicate if the current iterator count (starting at 1) is an odd number. In other words, this will return a true value for the first iterator, the third, fifth, and so on.
## **even()**
Returns a boolean (0/1) value to indicate if the current iterator count (starting at 1) is an even number. In other words, this will return a true value for the second iteration, the fourth, sixth, and so on.
# [AUTHOR](#AUTHOR)
Andy Wardley <abw@wardley.org> <http://wardley.org/>
# [COPYRIGHT](#COPYRIGHT)
Copyright (C) 1996-2022 Andy Wardley. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
# [SEE ALSO](#SEE_ALSO)
Template
2026-08-30 perl v5.44.0
---
Document: Template::Iterator(3pm) from perl-template-toolkit 3.106-r2 (Chainguard OS)
Source: https://github.com/abw/Template2.git