[%# # 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; INCLUDE tocitem title='SYNOPSIS'; INCLUDE tocitem title='DESCRIPTION'; INCLUDE tocitem title='PUBLIC METHODS' subs=['new($data) ', 'get_first()', 'get_next()', 'get_all()', 'size()', 'max()', 'index()', 'count()', 'first()', 'last()', 'prev()', 'next()']; INCLUDE tocitem title='AUTHOR'; INCLUDE tocitem title='VERSION'; INCLUDE tocitem title='COPYRIGHT'; INCLUDE tocitem title='SEE ALSO'; 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@kfs.org>

[% ttlink('http://www.andywardley.com/', 'http://www.andywardley.com/') -%]

[%- END %] [% WRAPPER section title='VERSION' -%]

Template Toolkit version 2.01, released on 30th March 2001.

[%- END %] [% WRAPPER section title='COPYRIGHT' -%]
  Copyright (C) 1996-2001 Andy Wardley.  All Rights Reserved.
  Copyright (C) 1998-2001 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 %]