WWWWWW

Current Directory: /usr/local/share/man/man3
Viewing File: /usr/local/share/man/man3/Template::Iterator.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Template::Iterator 3"
.TH Template::Iterator 3 "2024-06-21" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Template::Iterator \- Data iterator used by the FOREACH directive
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    my $iter = Template::Iterator\->new(\e@data, \e%options);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \f(CW\*(C`Template::Iterator\*(C'\fR module defines a generic data iterator for use
by the \f(CW\*(C`FOREACH\*(C'\fR directive.
.PP
It may be used as the base class for custom iterators.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
.SS "new($data)"
.IX Subsection "new($data)"
Constructor method.  A reference to a list of values is passed as the
first parameter.  Subsequent calls to \fBget_first()\fR and \fBget_next()\fR calls
will return each element from the list.
.PP
.Vb 1
\&    my $iter = Template::Iterator\->new([ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq ]);
.Ve
.PP
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 '\f(CW\*(C`key\*(C'\fR' and '\f(CW\*(C`value\*(C'\fR' item, sorted according to the hash keys.
.PP
.Vb 4
\&    my $iter = Template::Iterator\->new({
\&        foo => \*(AqFoo Item\*(Aq,
\&        bar => \*(AqBar Item\*(Aq,
\&    });
.Ve
.PP
This is equivalent to:
.PP
.Vb 4
\&    my $iter = Template::Iterator\->new([
\&        { key => \*(Aqbar\*(Aq, value => \*(AqBar Item\*(Aq },
\&        { key => \*(Aqfoo\*(Aq, value => \*(AqFoo Item\*(Aq },
\&    ]);
.Ve
.PP
When passed a single item which is not an array reference, the constructor
will automatically create a list containing that single item.
.PP
.Vb 1
\&    my $iter = Template::Iterator\->new(\*(Aqfoo\*(Aq);
.Ve
.PP
This is equivalent to:
.PP
.Vb 1
\&    my $iter = Template::Iterator\->new([ \*(Aqfoo\*(Aq ]);
.Ve
.PP
Note that a single item which is an object based on a blessed \s-1ARRAY\s0
references will \s-1NOT\s0 be treated as an array and will be folded into
a list containing that one object reference.
.PP
.Vb 2
\&    my $list = bless [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ], \*(AqMyListClass\*(Aq;
\&    my $iter = Template::Iterator\->new($list);
.Ve
.PP
equivalent to:
.PP
.Vb 1
\&    my $iter = Template::Iterator\->new([ $list ]);
.Ve
.PP
If the object provides an \f(CW\*(C`as_list()\*(C'\fR method then the Template::Iterator
constructor will call that method to return the list of data.  For example:
.PP
.Vb 1
\&    package MyListObject;
\&
\&    sub new {
\&        my $class = shift;
\&        bless [ @_ ], $class;
\&    }
\&
\&    package main;
\&
\&    my $list = MyListObject\->new(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq);
\&    my $iter = Template::Iterator\->new($list);
.Ve
.PP
This is then functionally equivalent to:
.PP
.Vb 1
\&    my $iter = Template::Iterator\->new([ $list ]);
.Ve
.PP
The iterator will return only one item, a reference to the \f(CW\*(C`MyListObject\*(C'\fR
object, \f(CW$list\fR.
.PP
By adding an \f(CW\*(C`as_list()\*(C'\fR method to the \f(CW\*(C`MyListObject\*(C'\fR class, we can force
the \f(CW\*(C`Template::Iterator\*(C'\fR constructor to treat the object as a list and
use the data contained within.
.PP
.Vb 1
\&    package MyListObject;
\&
\&    ...
\&
\&    sub as_list {
\&        my $self = shift;
\&        return $self;
\&    }
\&
\&    package main;
\&
\&    my $list = MyListObject\->new(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq);
\&    my $iter = Template::Iterator\->new($list);
.Ve
.PP
The iterator will now return the two items, '\f(CW\*(C`foo\*(C'\fR' and '\f(CW\*(C`bar\*(C'\fR', which the
\&\f(CW\*(C`MyObjectList\*(C'\fR encapsulates.
.SS "\fBget_first()\fP"
.IX Subsection "get_first()"
Returns a \f(CW\*(C`($value, $error)\*(C'\fR pair for the first item in the iterator set.
The \f(CW$error\fR returned may be zero or undefined to indicate a valid datum
was successfully returned.  Returns an error of \f(CW\*(C`STATUS_DONE\*(C'\fR if the list
is empty.
.SS "\fBget_next()\fP"
.IX Subsection "get_next()"
Returns a \f(CW\*(C`($value, $error)\*(C'\fR pair for the next item in the iterator set.
Returns an error of \f(CW\*(C`STATUS_DONE\*(C'\fR if all items in the list have been
visited.
.SS "\fBget_all()\fP"
.IX Subsection "get_all()"
Returns a \f(CW\*(C`(\e@values, $error)\*(C'\fR pair for all remaining items in the iterator
set.  Returns an error of \f(CW\*(C`STATUS_DONE\*(C'\fR if all items in the list have been
visited.
.SS "\fBsize()\fP"
.IX Subsection "size()"
Returns the size of the data set or undef if unknown.
.SS "\fBmax()\fP"
.IX Subsection "max()"
Returns the maximum index number (i.e. the index of the last element)
which is equivalent to \fBsize()\fR \- \f(CW1\fR.
.SS "\fBindex()\fP"
.IX Subsection "index()"
Returns the current index number which is in the range \f(CW0\fR to \fBmax()\fR.
.SS "\fBcount()\fP"
.IX Subsection "count()"
Returns the current iteration count in the range \f(CW1\fR to \fBsize()\fR.  This is
equivalent to \fBindex()\fR + \f(CW1\fR.
.SS "\fBfirst()\fP"
.IX Subsection "first()"
Returns a boolean value to indicate if the iterator is currently on
the first iteration of the set.
.SS "\fBlast()\fP"
.IX Subsection "last()"
Returns a boolean value to indicate if the iterator is currently on
the last iteration of the set.
.SS "\fBprev()\fP"
.IX Subsection "prev()"
Returns the previous item in the data set, or \f(CW\*(C`undef\*(C'\fR if the iterator is
on the first item.
.SS "\fBnext()\fP"
.IX Subsection "next()"
Returns the next item in the data set or \f(CW\*(C`undef\*(C'\fR if the iterator is on the
last item.
.SS "\fBnumber()\fP"
.IX Subsection "number()"
This is an alias to 'count' to provide backward compatibility.
View count.
.SS "\fBparity()\fP"
.IX Subsection "parity()"
Returns the text string \f(CW\*(C`even\*(C'\fR or \f(CW\*(C`odd\*(C'\fR to indicate the parity of the
current iteration count (starting at 1).  This is typically used to create
striped \fIzebra tables\fR.
.PP
.Vb 7
\&    <table>
\&    [% FOREACH name IN [\*(AqArthur\*(Aq, \*(AqFord\*(Aq, \*(AqTrillian\*(Aq] \-%]
\&      <tr class="[% loop.parity %]">
\&        <td>[% name %]</td>
\&      </tr>
\&    [% END %]
\&    </table>
.Ve
.PP
This will produce the following output:
.PP
.Vb 11
\&    <table>
\&      <tr class="odd">
\&        <td>Arthur</td>
\&      </tr>
\&      <tr class="even">
\&        <td>Ford</td>
\&      </tr>
\&      <tr class="odd">
\&        <td>Trillian</td>
\&      </tr>
\&    </table>
.Ve
.PP
You can then style the \f(CW\*(C`tr.odd\*(C'\fR and \f(CW\*(C`tr.even\*(C'\fR elements using \s-1CSS:\s0
.PP
.Vb 4
\&    tr.odd td {
\&        background\-color: black;
\&        color: white;
\&    }
\&
\&    tr.even td {
\&        background\-color: white;
\&        color: black;
\&    }
.Ve
.SS "\fBodd()\fP"
.IX Subsection "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.
.SS "\fBeven()\fP"
.IX Subsection "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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Wardley <abw@wardley.org> <http://wardley.org/>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 1996\-2022 Andy Wardley.  All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Template
F1l3 Manager
