Contents
TopSYNOPSIS
Topmy $iter = Template::Iterator->new(\@data, \%options);
DESCRIPTION
Top
                      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
Topnew($data)
TopConstructor 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()
Top
                          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()
Top
                          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()
Top
                          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()
TopReturns the size of the data set or undef if unknown.
max()
Top
                          Returns the maximum index number (i.e. the index of the last element)
                          which is equivalent to size() -
                          1.
                        
count()
Topfirst()
TopReturns a boolean value to indicate if the iterator is currently on the first iteration of the set.
last()
TopReturns a boolean value to indicate if the iterator is currently on the last iteration of the set.
prev()
Top
                          Returns the previous item in the data set, or undef if the
                          iterator is on the first item.
                        
next()
Top
                          Returns the next item in the data set or undef if the
                          iterator is on the last item.
                        
parity()
Top
                          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()
TopReturns 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()
TopReturns 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
TopAndy Wardley <abw@wardley.org> http://wardley.org/
COPYRIGHT
TopCopyright (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.