Template::Iterator

Template::Iterator(3)User Contributed Perl DocumentationTemplate::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 iterator 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 con-
       structor 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::Itera-
       tor 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 "MyListOb-
       ject" 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 items, ’"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 undefined 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.

       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@wardley.org> <http://wardley.org/>

COPYRIGHT
       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.

       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

SEE ALSO
       Template



perl v5.8.8			  2008-08-07		Template::Iterator(3)