Template::Iterator(3)

💖 Template::Iterator(3) 💖

okay so this is the User Contributed Perl Documentation page for Template::Iterator, and it’s genuinely such a useful little thing. It’s the data iterator that the FOREACH directive uses, and you can also use it as the base class for your own custom iterators. 🎀

✨ 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. You pass a reference to a list of values as the first parameter. Later calls to get_first() and get_next() 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 reference 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. 🦓

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

This masterpiece is by Andy Wardley — <abw@wardley.org> — <http://wardley.org/> 🫶

🎀 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

---

🌸 That’s the whole page, bestie — it comes from perl v5.42.0, dated 2024-06-23. 🌸