perldoc > Template::Iterator

man perldoc info pydoc3 ri search

📘 NAME

Template::Iterator — Data iterator used by the FOREACH directive

🚀 Quick Reference

Use Case	Command	Description
Create iterator from array	Template::Iterator->new(\@data)	Constructor; returns iterator for list of values
Create iterator from hash	Template::Iterator->new(\%hash)	Expands hash into sorted list of key/value pairs
Get first item	$iter->get_first()	Returns ($value, $error) for first element
Get next item	$iter->get_next()	Returns ($value, $error) for next element
Get all remaining items	$iter->get_all()	Returns (\@values, $error) for all remaining
Check if first or last	$iter->first() / $iter->last()	Boolean true if on first/last iteration
Get current index	$iter->index()	Zero-based index (0 .. max)
Get iteration count	$iter->count()	One-based count (1 .. size)
Get parity string	$iter->parity()	Returns "even" or "odd" for zebra-striping
Check odd/even	$iter->odd() / $iter->even()	Boolean true if current count is odd/even
Get previous/next item	$iter->prev() / $iter->next()	Returns previous/next item or undef
Get size and max index	$iter->size() / $iter->max()	Size of data set; max = size - 1

📂 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 AT wardley.org> <http://wardley.org/>

©️ COPYRIGHT

Copyright (C) 1996-2007 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

📘 NAME 🚀 Quick Reference 📂 SYNOPSIS 📝 DESCRIPTION 🔧 PUBLIC METHODS 👤 AUTHOR ©️ COPYRIGHT 📚 SEE ALSO