---
name: "Template::Iterator"
section: "3pm"
platform: "linux"
package: "perl-template-toolkit"
version: "3.106-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Template::Iterator"
---
# Template::Iterator(3pm)
Data iterator used by the FOREACH directive
## NAME
Template::Iterator - Data iterator used by the FOREACH directive
## SYNOPSIS
```
my $iter = Template::Iterator->new(\@data, \%options);
```
## 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
### new($data)
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
Andy Wardley \ \
## 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
Template