Template::Iterator(3pm)

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.
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.

<table>
[% FOREACH name IN ['Arthur', 'Ford', 'Trillian'] -%]
<tr class="[% loop.parity %]">
<td>[% name %]</td>

</tr>

[% END %]
</table>; This will produce the following output:

<table>
<tr class="odd">
<td>Arthur</td>

</tr>
<tr class="even">

<td>Ford</td>

</tr>
<tr class="odd">

<td>Trillian</td>

</tr>

</table>; 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 <abw@wardley.org> <http://wardley.org/>

COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

docs.sk

comprehensive documentation repository

In section