template::iterator(3)
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 iter
ator 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 contain
ing 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 Tem
plate::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 item, '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 unde
fined 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. Note that number() is supported as an alias for count() for back wards compatability. - 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.
AUTHOR
Andy Wardley <abw@andywardley.com>
<http://www.andywardley.com/|http://www.andywardley.com/>
VERSION
2.52, distributed as part of the Template Toolkit version
2.08, released on 30 July 2002.
COPYRIGHT
- Copyright (C) 1996-2002 Andy Wardley. All Rights Re
- served.
Copyright (C) 1998-2002 Canon Research Centre Europe - Ltd.
- This module is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
SEE ALSO
- Template