| Current File : //proc/self/root/usr/share/doc/perl-Template-Toolkit-2.24/modules/Template/Iterator.html |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Strict//EN">
<html>
<head>
<title>Template::Iterator</title>
<link rel="stylesheet" type="text/css" href="../../css/blue.css" title="Clear Blue">
<link rel="alternate stylesheet" type="text/css" href="../../css/orange.css" title="Clear Orange">
<link rel="alternate stylesheet" type="text/css" href="../../css/green.css" title="Clear Green">
<link rel="alternate stylesheet" type="text/css" href="../../css/purple.css" title="Clear Purple">
<link rel="alternate stylesheet" type="text/css" href="../../css/grey.css" title="Clear Grey">
<link rel="alternate stylesheet" type="text/css" href="../../css/print.css" title="Print">
<!--[if IE 6]>
<link rel="stylesheet" type="text/css" href="../../css/ie6.css" />
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="../../css/ie7.css" />
<![endif]-->
<link rel="stylesheet" type="text/css" href="../../css/print.css" media="print">
<script type="text/javascript" src="../../js/tt2.js"></script>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta name="author" content="Andy Wardley">
</head>
<body id="body">
<div id="layout">
<div id="header">
<a href="../../index.html" id="logo" alt="" title="Click for the Home Page"><span class="alt">TT2 Home Page</span></a>
<ul id="trail">
<li><a href="../../modules/index.html">Modules</a></li>
<li><a href="../../modules/Template/index.html">Template::*</a></li>
<li class="last"><a href="../../modules/Template/Iterator.html">Iterator.pm</a></li>
</ul>
<div class="controls">
<a href="#" class="menu show" onclick="widescreen_off(); return false" title="Show Menu">
<span class="about">Click to view the menu. It's very nice.</span>
</a>
<a href="#" class="menu hide" onclick="widescreen_on(); return false" title="Hide Menu">
<span class="about">Click to hide the menu and go all widescreen!</span>
</a>
<div class="pager">
<a href="../../modules/Template/Grammar.html" title="Template::Grammar" class="go back">Back<span class="about"><h4>Template::Grammar</h4>Parser state/rule tables for the TT grammar</span></a>
<a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
<a href="../../modules/Template/Namespace/index.html" title="Template::Namespace::* Modules" class="go next">Next<span class="about"><h4>Template::Namespace::* Modules</h4></span></a>
</div>
</div>
<h1 class="headline">Template::Iterator</h1>
<h2 class="subhead">Data iterator used by the FOREACH directive</h1>
</div>
<div id="page">
<div id="sidebar">
<a href="../../index.html" id="logo"></a>
<div id="menu">
<ul class="menu">
<li class="l0 first"><a href="../../manual/index.html">Manual</a></li>
<li class="l0"><a href="../../modules/index.html" class="warm">Modules</a></li>
<li class="l1"><a href="../../modules/Template.html">Template.pm</a></li>
<li class="l1"><a href="../../modules/Template/index.html" class="warm">Template::*</a></li>
<li class="l2"><a href="../../modules/Template/Base.html">Base.pm</a></li>
<li class="l2"><a href="../../modules/Template/Config.html">Config.pm</a></li>
<li class="l2"><a href="../../modules/Template/Constants.html">Constants.pm</a></li>
<li class="l2"><a href="../../modules/Template/Context.html">Context.pm</a></li>
<li class="l2"><a href="../../modules/Template/Directive.html">Directive.pm</a></li>
<li class="l2"><a href="../../modules/Template/Document.html">Document.pm</a></li>
<li class="l2"><a href="../../modules/Template/Exception.html">Exception.pm</a></li>
<li class="l2"><a href="../../modules/Template/Filters.html">Filters.pm</a></li>
<li class="l2"><a href="../../modules/Template/Grammar.html">Grammar.pm</a></li>
<li class="l2"><a href="../../modules/Template/Iterator.html" class="warm">Iterator.pm</a></li>
<li class="l2"><a href="../../modules/Template/Namespace/index.html">Namespace::*</a></li>
<li class="l2"><a href="../../modules/Template/Parser.html">Parser.pm</a></li>
<li class="l2"><a href="../../modules/Template/Plugin.html">Plugin.pm</a></li>
<li class="l2"><a href="../../modules/Template/Plugin/index.html">Plugin::*</a></li>
<li class="l2"><a href="../../modules/Template/Plugins.html">Plugins.pm</a></li>
<li class="l2"><a href="../../modules/Template/Provider.html">Provider.pm</a></li>
<li class="l2"><a href="../../modules/Template/Service.html">Service.pm</a></li>
<li class="l2"><a href="../../modules/Template/Stash.html">Stash.pm</a></li>
<li class="l2"><a href="../../modules/Template/Stash/index.html">Stash::*</a></li>
<li class="l2"><a href="../../modules/Template/Test.html">Test.pm</a></li>
<li class="l2"><a href="../../modules/Template/VMethods.html">VMethods.pm</a></li>
<li class="l2"><a href="../../modules/Template/View.html">View.pm</a></li>
<li class="l0"><a href="../../tools/index.html">Tools</a></li>
<li class="l0"><a href="../../tutorial/index.html">Tutorial</a></li>
<li class="l0 last"><a href="../../faq/index.html">FAQ</a></li>
</ul>
<div class="foot"></div>
</div>
</div>
<div id="content">
<div class="section">
<div class="head">
<h1 id="contents" onclick="switch_section(this)" title="Click title to show/hide section content.">Contents</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<ul class="toc">
<li class=""><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li class=""><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li class=""><a href="#PUBLIC_METHODS">PUBLIC METHODS</a></li>
<li class="sub"><a href="#method_new">new($data)</a></li>
<li class="sub"><a href="#method_get_first">get_first()</a></li>
<li class="sub"><a href="#method_get_next">get_next()</a></li>
<li class="sub"><a href="#method_get_all">get_all()</a></li>
<li class="sub"><a href="#method_size">size()</a></li>
<li class="sub"><a href="#method_max">max()</a></li>
<li class="sub"><a href="#method_index">index()</a></li>
<li class="sub"><a href="#method_count">count()</a></li>
<li class="sub"><a href="#method_first">first()</a></li>
<li class="sub"><a href="#method_last">last()</a></li>
<li class="sub"><a href="#method_prev">prev()</a></li>
<li class="sub"><a href="#method_next">next()</a></li>
<li class="sub"><a href="#method_parity">parity()</a></li>
<li class="sub"><a href="#method_odd">odd()</a></li>
<li class="sub"><a href="#method_even">even()</a></li>
<li class=""><a href="#AUTHOR">AUTHOR</a></li>
<li class=""><a href="#COPYRIGHT">COPYRIGHT</a></li>
<li class=""><a href="#SEE_ALSO">SEE ALSO</a></li>
</ul>
</div>
</div>
<div class="pod">
<div class="section">
<div class="head">
<h1 id="SYNOPSIS" onclick="switch_section(this)" title="Click title to show/hide section content.">SYNOPSIS</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<pre>my $iter = Template::Iterator->new(\@data, \%options);</pre>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="DESCRIPTION" onclick="switch_section(this)" title="Click title to show/hide section content.">DESCRIPTION</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
The <code>Template::Iterator</code> module defines a generic data
iterator for use by the <code>FOREACH</code> directive.
</p>
<p>
It may be used as the base class for custom iterators.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="PUBLIC_METHODS" onclick="switch_section(this)" title="Click title to show/hide section content.">PUBLIC METHODS</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<div class="subsection">
<div class="head">
<h2 id="method_new" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">new($data)</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Constructor method. A reference to a list of values is passed as the
first parameter. Subsequent calls to <a
href="#method_get_first">get_first()</a> and <a
href="#method_get_next">get_next()</a> calls will return each element
from the list.
</p>
<pre>my $iter = Template::Iterator->new([ 'foo', 'bar', 'baz' ]);</pre>
<p>
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
'<code>key</code>' and '<code>value</code>' item, sorted according to the
hash keys.
</p>
<pre>my $iter = Template::Iterator->new({
foo => 'Foo Item',
bar => 'Bar Item',
});</pre>
<p>
This is equivalent to:
</p>
<pre>my $iter = Template::Iterator->new([
{ key => 'bar', value => 'Bar Item' },
{ key => 'foo', value => 'Foo Item' },
]);</pre>
<p>
When passed a single item which is not an array reference, the
constructor will automatically create a list containing that single item.
</p>
<pre>my $iter = Template::Iterator->new('foo');</pre>
<p>
This is equivalent to:
</p>
<pre>my $iter = Template::Iterator->new([ 'foo' ]);</pre>
<p>
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.
</p>
<pre>my $list = bless [ 'foo', 'bar' ], 'MyListClass';
my $iter = Template::Iterator->new($list);</pre>
<p>
equivalent to:
</p>
<pre>my $iter = Template::Iterator->new([ $list ]);</pre>
<p>
If the object provides an <code>as_list()</code> method then the <a
href="../../modules/Template/Iterator.html">Template::Iterator</a>
constructor will call that method to return the list of data. For
example:
</p>
<pre>package MyListObject;
sub new {
my $class = shift;
bless [ @_ ], $class;
}
package main;
my $list = MyListObject->new('foo', 'bar');
my $iter = Template::Iterator->new($list);</pre>
<p>
This is then functionally equivalent to:
</p>
<pre>my $iter = Template::Iterator->new([ $list ]);</pre>
<p>
The iterator will return only one item, a reference to the
<code>MyListObject</code> object, <code>$list</code>.
</p>
<p>
By adding an <code>as_list()</code> method to the
<code>MyListObject</code> class, we can force the
<code>Template::Iterator</code> constructor to treat the object as a list
and use the data contained within.
</p>
<pre>package MyListObject;
...
sub as_list {
my $self = shift;
return $self;
}
package main;
my $list = MyListObject->new('foo', 'bar');
my $iter = Template::Iterator->new($list);</pre>
<p>
The iterator will now return the two items, '<code>foo</code>' and
'<code>bar</code>', which the <code>MyObjectList</code> encapsulates.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_get_first" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">get_first()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns a <code>($value, $error)</code> pair for the first item in the
iterator set. The <code>$error</code> returned may be zero or undefined
to indicate a valid datum was successfully returned. Returns an error of
<code>STATUS_DONE</code> if the list is empty.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_get_next" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">get_next()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns a <code>($value, $error)</code> pair for the next item in the
iterator set. Returns an error of <code>STATUS_DONE</code> if all items
in the list have been visited.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_get_all" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">get_all()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns a <code>(\@values, $error)</code> pair for all remaining items in
the iterator set. Returns an error of <code>STATUS_DONE</code> if all
items in the list have been visited.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_size" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">size()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns the size of the data set or undef if unknown.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_max" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">max()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns the maximum index number (i.e. the index of the last element)
which is equivalent to <a href="#method_size">size()</a> -
<code>1</code>.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_index" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">index()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns the current index number which is in the range <code>0</code> to
<a href="#method_max">max()</a>.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_count" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">count()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns the current iteration count in the range <code>1</code> to <a
href="#method_size">size()</a>. This is equivalent to <a
href="#method_index">index()</a> + <code>1</code>.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_first" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">first()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns a boolean value to indicate if the iterator is currently on the
first iteration of the set.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_last" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">last()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns a boolean value to indicate if the iterator is currently on the
last iteration of the set.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_prev" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">prev()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns the previous item in the data set, or <code>undef</code> if the
iterator is on the first item.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_next" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">next()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns the next item in the data set or <code>undef</code> if the
iterator is on the last item.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_parity" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">parity()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Returns the text string <code>even</code> or <code>odd</code> to indicate
the parity of the current iteration count (starting at 1). This is
typically used to create striped <i>zebra tables</i>.
</p>
<pre><table>
<span class="tt">[% FOREACH name IN ['Arthur', 'Ford', 'Trillian'] -%]</span>
<tr class="<span class="tt">[% loop.parity %]</span>">
<td><span class="tt">[% name %]</span></td>
</tr>
<span class="tt">[% END %]</span>
</table></pre>
<p>
This will produce the following output:
</p>
<pre><table>
<tr class="odd">
<td>Arthur</td>
</tr>
<tr class="even">
<td>Ford</td>
</tr>
<tr class="odd">
<td>Trillian</td>
</tr>
</table></pre>
<p>
You can then style the <code>tr.odd</code> and <code>tr.even</code>
elements using CSS:
</p>
<pre>tr.odd td {
background-color: black;
color: white;
}
tr.even td {
background-color: white;
color: black;
}</pre>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_odd" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">odd()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
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.
</p>
</div>
</div> <div class="subsection">
<div class="head">
<h2 id="method_even" class="method" onclick="switch_subsection(this)" title="Click title to show/hide sub-section content.">even()</h2>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
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.
</p>
</div>
</div>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="AUTHOR" onclick="switch_section(this)" title="Click title to show/hide section content.">AUTHOR</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Andy Wardley <abw@wardley.org> <a
href="http://wardley.org/">http://wardley.org/</a>
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="COPYRIGHT" onclick="switch_section(this)" title="Click title to show/hide section content.">COPYRIGHT</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
</p>
<p>
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
</p>
</div>
</div>
<div class="section">
<div class="head">
<h1 id="SEE_ALSO" onclick="switch_section(this)" title="Click title to show/hide section content.">SEE ALSO</h1>
<a href="#body" class="top" title="Back up to the top of the page" >Top</a>
</div>
<div class="body">
<p>
<a href="../../modules/Template.html">Template</a>
</p>
</div>
</div>
</div></div>
<br class="clear" />
<div class="pageinfo">
<a href="http://template-toolkit.org/docs/modules/Template/Iterator.html">http://template-toolkit.org/docs/modules/Template/Iterator.html</a>
</div>
</div>
<div id="footer">
<a href="http://opensource.org/" class="osi"></a>
<div class="controls">
<div class="pager">
<a href="../../modules/Template/Grammar.html" title="Template::Grammar" class="go back">Back<span class="about"><h4>Template::Grammar</h4></span></a>
<a href="../../modules/Template/index.html" title="Template::* Modules" class="go up">Up<span class="about"><h4>Template::* Modules</h4></span></a>
<a href="../../modules/Template/Namespace/index.html" title="Template::Namespace::* Modules" class="go next">Next<span class="about"><h4>Template::Namespace::* Modules</h4></span></a>
</div>
</div>
<div class="copyright">
Copyright © 1996-2012 <a href="http://wardley.org/">Andy Wardley</a>. All Rights Reserved.
</div>
<div class="licence">
The <a href="http://template-toolkit.org/">Template Toolkit</a> is <a href="http://opensource.org/">Open Source</a> software.
You can redistribute and/or modify it under the terms of the <a href="http://www.opensource.org/licenses/gpl-license.php">GNU Public Licence</a>
or the <a href="http://www.opensource.org/licenses/artistic-license.php">Perl Artistic Licence</a>.
</div>
</div>
<div id="palette">
<ul>
<li class="first"><a href="#" class="blue" onclick="set_style('Clear Blue')"></a></li>
<li><a href="#" class="orange" onclick="set_style('Clear Orange')"></a></li>
<li><a href="#" class="green" onclick="set_style('Clear Green')"></a></li>
<li><a href="#" class="purple" onclick="set_style('Clear Purple')"></a></li>
<li><a href="#" class="grey" onclick="set_style('Clear Grey')"></a></li>
</ul>
</div>
</div> </body>
</html>