[%#
# 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
%]
<!-- Pod to HTML conversion by the Template Toolkit version 2 -->
[% WRAPPER section
title="SYNOPSIS"
-%]<pre> my $iter = Template::Iterator->new(\@data, \%options);</pre>
[%- END %]
[% WRAPPER section
title="DESCRIPTION"
-%]<p>
The Template::Iterator module defines a generic data iterator for use
by the FOREACH directive.
</p>
<p>
It may be used as the base class for custom iterators.
</p>
[%- END %]
[% WRAPPER section
title="PUBLIC METHODS"
-%][% WRAPPER subsection
title = "new(\$data) "
-%]<p>
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.
</p>
<pre> my $iter = Template::Iterator->new([ 'foo', 'bar', 'baz' ]);</pre>
<p>
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.
</p>
<pre> my $iter = Template::Iterator->new({
foo => 'Foo Item',
bar => 'Bar Item',
});</pre>
<p>
This is equivalent to:
</p>
<pre> my $iter = Template::Iterator->new([
{ key => 'bar', value => 'Bar Item' },
{ key => 'foo', value => 'Foo Item' },
]);</pre>
<p>
When passed a single item which is not an array reference, the constructor
will automatically create a list containing that single item.
</p>
<pre> my $iter = Template::Iterator->new('foo');</pre>
<p>
This is equivalent to:
</p>
<pre> my $iter = Template::Iterator->new([ 'foo' ]);</pre>
<p>
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.
</p>
<pre> my $list = bless [ 'foo', 'bar' ], 'MyListClass';
my $iter = Template::Iterator->new($list);</pre>
<p>
equivalent to:
</p>
<pre> my $iter = Template::Iterator->new([ $list ]);</pre>
<p>
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:
</p>
<pre> package MyListObject;</pre>
<pre> sub new {
my $class = shift;
bless [ @_ ], $class;
}</pre>
<pre> package main;</pre>
<pre> my $list = MyListObject->new('foo', 'bar');
my $iter = Template::Iterator->new($list);</pre>
<p>
This is then functionally equivalent to:
</p>
<pre> my $iter = Template::Iterator->new([ $list ]);</pre>
<p>
The iterator will return only one item, a reference to the MyListObject
object, $list.
</p>
<p>
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.
</p>
<pre> package MyListObject;</pre>
<pre> ...</pre>
<pre> sub as_list {
my $self = shift;
return $self;
}</pre>
<pre> package main;</pre>
<pre> my $list = MyListObject->new('foo', 'bar');
my $iter = Template::Iterator->new($list);</pre>
<p>
The iterator will now return the two item, 'foo' and 'bar', which the
MyObjectList encapsulates.
</p>
[%- END %]
[% WRAPPER subsection
title = "get_first()"
-%]<p>
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.
</p>
[%- END %]
[% WRAPPER subsection
title = "get_next()"
-%]<p>
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.
</p>
[%- END %]
[% WRAPPER subsection
title = "get_all()"
-%]<p>
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.
</p>
[%- END %]
[% WRAPPER subsection
title = "size()"
-%]<p>
Returns the size of the data set or undef if unknown.
</p>
[%- END %]
[% WRAPPER subsection
title = "max()"
-%]<p>
Returns the maximum index number (i.e. the index of the last element)
which is equivalent to size() - 1.
</p>
[%- END %]
[% WRAPPER subsection
title = "index()"
-%]<p>
Returns the current index number which is in the range 0 to max().
</p>
[%- END %]
[% WRAPPER subsection
title = "count()"
-%]<p>
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.
</p>
[%- END %]
[% WRAPPER subsection
title = "first()"
-%]<p>
Returns a boolean value to indicate if the iterator is currently on
the first iteration of the set.
</p>
[%- END %]
[% WRAPPER subsection
title = "last()"
-%]<p>
Returns a boolean value to indicate if the iterator is currently on
the last iteration of the set.
</p>
[%- END %]
[% WRAPPER subsection
title = "prev()"
-%]<p>
Returns the previous item in the data set, or undef if the iterator is
on the first item.
</p>
[%- END %]
[% WRAPPER subsection
title = "next()"
-%]<p>
Returns the next item in the data set or undef if the iterator is on the
last item.
</p>
[%- END %]
[%- END %]
[% WRAPPER section
title="AUTHOR"
-%]<p>
Andy Wardley <abw@andywardley.com>
</p>
<p>
[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]
</p>
[%- END %]
[% WRAPPER section
title="VERSION"
-%]<p>
2.60, distributed as part of the
Template Toolkit version 2.11, released on 06 January 2004.
</p>
[%- END %]
[% WRAPPER section
title="COPYRIGHT"
-%]<pre> Copyright (C) 1996-2004 Andy Wardley. All Rights Reserved.
Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.</pre>
<p>
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
</p>
[%- END %]
[% WRAPPER section
title="SEE ALSO"
-%]<p>
[% ttlink('Template', 'Template') -%]
</p>
[%- END %]