|  | Tutorial |  |
|  | Manual |  |
|  | Modules |  |
|  | Library |  |
|  | Tools |  |
|  | FAQ |  |
|  | Release |  |
| Template Toolkit | Modules | Template::Iterator |

## Template::Iterator |
| Template::Filters
Template::Namespace::Constants |

Data iterator used by the FOREACH directive

### Table of Contents

- SYNOPSIS
- DESCRIPTION
- PUBLIC METHODS
  - new($data)
  - get_first()
  - get_next()
  - get_all()
  - size()
  - max()
  - index()
  - count()
  - first()
  - last()
  - prev()
  - next()
- AUTHOR
- VERSION
- COPYRIGHT
- SEE ALSO

SYNOPSIS | [ Index ] [ Modules ] [ Top ]

        my $iter = Template::Iterator->new(\@data, \%options);

DESCRIPTION | [ Index ] [ Modules ] [ Top ]

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 | [ Index ] [ Modules ] [ Top ]

### 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. ### 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. Note that number() is supported as an alias for count() for backwards compatability. ### 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 | [ Index ] [ Modules ] [ Top ]

Andy Wardley <abw@andywardley.com> http://www.andywardley.com/

VERSION | [ Index ] [ Modules ] [ Top ]

2.65, distributed as part of the Template Toolkit version 2.14, released on 04 October 2004.

COPYRIGHT | [ Index ] [ Modules ] [ Top ]

      Copyright (C) 1996-2004 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.

SEE ALSO | [ Index ] [ Modules ] [ Top ]

Template

| Template::Filters
Template::Namespace::Constants |

| Tutorial |
| Manual |
| Modules |
| Library |
| Tools |
| FAQ |
| Release |

| http://www.template-toolkit.org/ |