[%# # IMPORTANT NOTE # This documentation is generated automatically from source # templates. Any changes you make here may be lost. # # The 'docsrc' documentation source bundle is available for download # from http://www.template-toolkit.org/docs.html and contains all # the source templates, XML files, scripts, etc., from which the # documentation for the Template Toolkit is built. -%] [% META book = 'Modules' page = 'Iterator' %] [% WRAPPER toc; PROCESS tocitem title ="SYNOPSIS" subs = []; PROCESS tocitem title ="DESCRIPTION" subs = []; PROCESS tocitem title ="PUBLIC METHODS" subs = [ "new(\$data) ", "get_first()", "get_next()", "get_all()", "size()", "max()", "index()", "count()", "first()", "last()", "prev()", "next()" ]; PROCESS tocitem title ="AUTHOR" subs = []; PROCESS tocitem title ="VERSION" subs = []; PROCESS tocitem title ="COPYRIGHT" subs = []; PROCESS tocitem title ="SEE ALSO" subs = []; END %] [% WRAPPER section title="SYNOPSIS" -%]
my $iter = Template::Iterator->new(\@data, \%options);[%- END %] [% WRAPPER section title="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.
[%- END %] [% WRAPPER section title="PUBLIC METHODS" -%][% WRAPPER subsection title = "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.
[%- END %] [% WRAPPER subsection title = "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.
[%- END %] [% WRAPPER subsection title = "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.
[%- END %] [% WRAPPER subsection title = "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.
[%- END %] [% WRAPPER subsection title = "size()" -%]Returns the size of the data set or undef if unknown.
[%- END %] [% WRAPPER subsection title = "max()" -%]Returns the maximum index number (i.e. the index of the last element) which is equivalent to size() - 1.
[%- END %] [% WRAPPER subsection title = "index()" -%]Returns the current index number which is in the range 0 to max().
[%- END %] [% WRAPPER subsection title = "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.
[%- END %] [% WRAPPER subsection title = "first()" -%]Returns a boolean value to indicate if the iterator is currently on the first iteration of the set.
[%- END %] [% WRAPPER subsection title = "last()" -%]Returns a boolean value to indicate if the iterator is currently on the last iteration of the set.
[%- END %] [% WRAPPER subsection title = "prev()" -%]Returns the previous item in the data set, or undef if the iterator is on the first item.
[%- END %] [% WRAPPER subsection title = "next()" -%]Returns the next item in the data set or undef if the iterator is on the last item.
[%- END %] [%- END %] [% WRAPPER section title="AUTHOR" -%]Andy Wardley <abw@andywardley.com>
[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
[%- END %] [% WRAPPER section title="VERSION" -%]2.52, distributed as part of the Template Toolkit version 2.08, released on 30 July 2002.
[%- END %] [% WRAPPER section title="COPYRIGHT" -%]Copyright (C) 1996-2002 Andy Wardley. All Rights Reserved. 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.
[%- END %] [% WRAPPER section title="SEE ALSO" -%][% ttlink('Template', 'Template') -%]
[%- END %]