=head1 NAME
Template::Iterator - Base iterator class used by the FOREACH directive.
=head1 SYNOPSIS
my $iter = Template::Iterator->new(\@data, \%options);
=head1 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.
=head1 PUBLIC METHODS
=head2 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 item, 'foo' and 'bar', which the
MyObjectList encapsulates.
=head2 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.
=head2 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.
=head2 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.
=head2 size()
Returns the size of the data set or undef if unknown.
=head2 max()
Returns the maximum index number (i.e. the index of the last element)
which is equivalent to size() - 1.
=head2 index()
Returns the current index number which is in the range 0 to max().
=head2 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 backwards compatability.
=head2 first()
Returns a boolean value to indicate if the iterator is currently on
the first iteration of the set.
=head2 last()
Returns a boolean value to indicate if the iterator is currently on
the last iteration of the set.
=head2 prev()
Returns the previous item in the data set, or undef if the iterator is
on the first item.
=head2 next()
Returns the next item in the data set or undef if the iterator is on the
last item.
=head1 AUTHOR
Andy Wardley E<lt>abw@kfs.orgE<gt>
http://www.template-toolkit.org/
http://www.kfs.org/~abw/
=head1 REVISION
$Revision: 1.3 $
=head1 COPYRIGHT
Copyright (C) 1996-2000 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2000 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.
=head1 SEE ALSO
L<Template|Template>