Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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
       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 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.

   number()
       This is an alias	to 'count' to provide backward compatibility.  View
       count.

   parity()
       Returns the text	string "even" or "odd" to indicate the parity of the
       current iteration count (starting at 1).	 This is typically used	to
       create striped zebra tables.

	   <table>
	   [% FOREACH name IN ['Arthur', 'Ford', 'Trillian'] -%]
	     <tr class="[% loop.parity %]">
	       <td>[% name %]</td>
	     </tr>
	   [% END %]
	   </table>

       This will produce the following output:

	   <table>
	     <tr class="odd">
	       <td>Arthur</td>
	     </tr>
	     <tr class="even">
	       <td>Ford</td>
	     </tr>
	     <tr class="odd">
	       <td>Trillian</td>
	     </tr>
	   </table>

       You can then style the "tr.odd" and "tr.even" elements using CSS:

	   tr.odd td {
	       background-color: black;
	       color: white;
	   }

	   tr.even td {
	       background-color: white;
	       color: black;
	   }

   odd()
       Returns a boolean (0/1) value to	indicate if the	current	iterator count
       (starting at 1) is an odd number. In other words, this will return a
       true value for the first	iterator, the third, fifth, and	so on.

   even()
       Returns a boolean (0/1) value to	indicate if the	current	iterator count
       (starting at 1) is an even number. In other words, this will return a
       true value for the second iteration, the	fourth,	sixth, and so on.

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.32.1			  2020-07-13		 Template::Iterator(3)

NAME | SYNOPSIS | DESCRIPTION | PUBLIC METHODS | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Template::Iterator&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help