local-lib5/man/man3/Template::Iterator.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Template::Iterator 3"
 132 .TH Template::Iterator 3 "2009-05-21" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Iterator \- Data iterator used by the FOREACH directive
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    my $iter = Template::Iterator\->new(\e@data, \e%options);
 139 .Ve
 140 .SH "DESCRIPTION"
 141 .IX Header "DESCRIPTION"
 142 The \f(CW\*(C`Template::Iterator\*(C'\fR module defines a generic data iterator for use
 143 by the \f(CW\*(C`FOREACH\*(C'\fR directive.
 144 .PP
 145 It may be used as the base class for custom iterators.
 146 .SH "PUBLIC METHODS"
 147 .IX Header "PUBLIC METHODS"
 148 .Sh "new($data)"
 149 .IX Subsection "new($data)"
 150 Constructor method.  A reference to a list of values is passed as the
 151 first parameter.  Subsequent calls to \fIget_first()\fR and \fIget_next()\fR calls
 152 will return each element from the list.
 153 .PP
 154 .Vb 1
 155 \&    my $iter = Template::Iterator\->new([ 'foo', 'bar', 'baz' ]);
 156 .Ve
 157 .PP
 158 The constructor will also accept a reference to a hash array and will
 159 expand it into a list in which each entry is a hash array containing
 160 a '\f(CW\*(C`key\*(C'\fR' and '\f(CW\*(C`value\*(C'\fR' item, sorted according to the hash keys.
 161 .PP
 162 .Vb 4
 163 \&    my $iter = Template::Iterator\->new({
 164 \&        foo => 'Foo Item',
 165 \&        bar => 'Bar Item',
 166 \&    });
 167 .Ve
 168 .PP
 169 This is equivalent to:
 170 .PP
 171 .Vb 4
 172 \&    my $iter = Template::Iterator\->new([
 173 \&        { key => 'bar', value => 'Bar Item' },
 174 \&        { key => 'foo', value => 'Foo Item' },
 175 \&    ]);
 176 .Ve
 177 .PP
 178 When passed a single item which is not an array reference, the constructor
 179 will automatically create a list containing that single item.
 180 .PP
 181 .Vb 1
 182 \&    my $iter = Template::Iterator\->new('foo');
 183 .Ve
 184 .PP
 185 This is equivalent to:
 186 .PP
 187 .Vb 1
 188 \&    my $iter = Template::Iterator\->new([ 'foo' ]);
 189 .Ve
 190 .PP
 191 Note that a single item which is an object based on a blessed \s-1ARRAY\s0
 192 references will \s-1NOT\s0 be treated as an array and will be folded into
 193 a list containing that one object reference.
 194 .PP
 195 .Vb 2
 196 \&    my $list = bless [ 'foo', 'bar' ], 'MyListClass';
 197 \&    my $iter = Template::Iterator\->new($list);
 198 .Ve
 199 .PP
 200 equivalent to:
 201 .PP
 202 .Vb 1
 203 \&    my $iter = Template::Iterator\->new([ $list ]);
 204 .Ve
 205 .PP
 206 If the object provides an \f(CW\*(C`as_list()\*(C'\fR method then the Template::Iterator
 207 constructor will call that method to return the list of data.  For example:
 208 .PP
 209 .Vb 1
 210 \&    package MyListObject;
 211 .Ve
 212 .PP
 213 .Vb 4
 214 \&    sub new {
 215 \&        my $class = shift;
 216 \&        bless [ @_ ], $class;
 217 \&    }
 218 .Ve
 219 .PP
 220 .Vb 1
 221 \&    package main;
 222 .Ve
 223 .PP
 224 .Vb 2
 225 \&    my $list = MyListObject\->new('foo', 'bar');
 226 \&    my $iter = Template::Iterator\->new($list);
 227 .Ve
 228 .PP
 229 This is then functionally equivalent to:
 230 .PP
 231 .Vb 1
 232 \&    my $iter = Template::Iterator\->new([ $list ]);
 233 .Ve
 234 .PP
 235 The iterator will return only one item, a reference to the \f(CW\*(C`MyListObject\*(C'\fR
 236 object, \f(CW$list\fR.
 237 .PP
 238 By adding an \f(CW\*(C`as_list()\*(C'\fR method to the \f(CW\*(C`MyListObject\*(C'\fR class, we can force
 239 the \f(CW\*(C`Template::Iterator\*(C'\fR constructor to treat the object as a list and
 240 use the data contained within.
 241 .PP
 242 .Vb 1
 243 \&    package MyListObject;
 244 .Ve
 245 .PP
 246 .Vb 1
 247 \&    ...
 248 .Ve
 249 .PP
 250 .Vb 4
 251 \&    sub as_list {
 252 \&        my $self = shift;
 253 \&        return $self;
 254 \&    }
 255 .Ve
 256 .PP
 257 .Vb 1
 258 \&    package main;
 259 .Ve
 260 .PP
 261 .Vb 2
 262 \&    my $list = MyListObject\->new('foo', 'bar');
 263 \&    my $iter = Template::Iterator\->new($list);
 264 .Ve
 265 .PP
 266 The iterator will now return the two items, '\f(CW\*(C`foo\*(C'\fR' and '\f(CW\*(C`bar\*(C'\fR', which the
 267 \&\f(CW\*(C`MyObjectList\*(C'\fR encapsulates.
 268 .Sh "\fIget_first()\fP"
 269 .IX Subsection "get_first()"
 270 Returns a \f(CW\*(C`($value, $error)\*(C'\fR pair for the first item in the iterator set.
 271 The \f(CW$error\fR returned may be zero or undefined to indicate a valid datum
 272 was successfully returned.  Returns an error of \f(CW\*(C`STATUS_DONE\*(C'\fR if the list
 273 is empty.
 274 .Sh "\fIget_next()\fP"
 275 .IX Subsection "get_next()"
 276 Returns a \f(CW\*(C`($value, $error)\*(C'\fR pair for the next item in the iterator set.
 277 Returns an error of \f(CW\*(C`STATUS_DONE\*(C'\fR if all items in the list have been
 278 visited.
 279 .Sh "\fIget_all()\fP"
 280 .IX Subsection "get_all()"
 281 Returns a \f(CW\*(C`(\e@values, $error)\*(C'\fR pair for all remaining items in the iterator
 282 set.  Returns an error of \f(CW\*(C`STATUS_DONE\*(C'\fR if all items in the list have been
 283 visited.
 284 .Sh "\fIsize()\fP"
 285 .IX Subsection "size()"
 286 Returns the size of the data set or undef if unknown.
 287 .Sh "\fImax()\fP"
 288 .IX Subsection "max()"
 289 Returns the maximum index number (i.e. the index of the last element)
 290 which is equivalent to \fIsize()\fR \- \f(CW1\fR.
 291 .Sh "\fIindex()\fP"
 292 .IX Subsection "index()"
 293 Returns the current index number which is in the range \f(CW0\fR to \fImax()\fR.
 294 .Sh "\fIcount()\fP"
 295 .IX Subsection "count()"
 296 Returns the current iteration count in the range \f(CW1\fR to \fIsize()\fR.  This is
 297 equivalent to \fIindex()\fR + \f(CW1\fR.
 298 .Sh "\fIfirst()\fP"
 299 .IX Subsection "first()"
 300 Returns a boolean value to indicate if the iterator is currently on
 301 the first iteration of the set.
 302 .Sh "\fIlast()\fP"
 303 .IX Subsection "last()"
 304 Returns a boolean value to indicate if the iterator is currently on
 305 the last iteration of the set.
 306 .Sh "\fIprev()\fP"
 307 .IX Subsection "prev()"
 308 Returns the previous item in the data set, or \f(CW\*(C`undef\*(C'\fR if the iterator is
 309 on the first item.
 310 .Sh "\fInext()\fP"
 311 .IX Subsection "next()"
 312 Returns the next item in the data set or \f(CW\*(C`undef\*(C'\fR if the iterator is on the
 313 last item.
 314 .Sh "\fIparity()\fP"
 315 .IX Subsection "parity()"
 316 Returns the text string \f(CW\*(C`even\*(C'\fR or \f(CW\*(C`odd\*(C'\fR to indicate the parity of the
 317 current iteration count (starting at 1).  This is typically used to create
 318 striped \fIzebra tables\fR.
 319 .PP
 320 .Vb 7
 321 \&    <table>
 322 \&    [% FOREACH name IN ['Arthur', 'Ford', 'Trillian'] \-%]
 323 \&      <tr class="[% loop.parity %]">
 324 \&        <td>[% name %]</td>
 325 \&      </tr>
 326 \&    [% END %]
 327 \&    </table>
 328 .Ve
 329 .PP
 330 This will produce the following output:
 331 .PP
 332 .Vb 11
 333 \&    <table>
 334 \&      <tr class="odd">
 335 \&        <td>Arthur</td>
 336 \&      </tr>
 337 \&      <tr class="even">
 338 \&        <td>Ford</td>
 339 \&      </tr>
 340 \&      <tr class="odd">
 341 \&        <td>Trillian</td>
 342 \&      </tr>
 343 \&    </table>
 344 .Ve
 345 .PP
 346 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
 347 .PP
 348 .Vb 4
 349 \&    tr.odd td {
 350 \&        background\-color: black;
 351 \&        color: white;
 352 \&    }
 353 .Ve
 354 .PP
 355 .Vb 4
 356 \&    tr.even td {
 357 \&        background\-color: white;
 358 \&        color: black;
 359 \&    }
 360 .Ve
 361 .Sh "\fIodd()\fP"
 362 .IX Subsection "odd()"
 363 Returns a boolean (0/1) value to indicate if the current iterator count
 364 (starting at 1) is an odd number. In other words, this will return a true
 365 value for the first iterator, the third, fifth, and so on.
 366 .Sh "\fIeven()\fP"
 367 .IX Subsection "even()"
 368 Returns a boolean (0/1) value to indicate if the current iterator count
 369 (starting at 1) is an even number. In other words, this will return a true
 370 value for the second iteration, the fourth, sixth, and so on.
 371 .SH "AUTHOR"
 372 .IX Header "AUTHOR"
 373 Andy Wardley <abw@wardley.org> <http://wardley.org/>
 374 .SH "COPYRIGHT"
 375 .IX Header "COPYRIGHT"
 376 Copyright (C) 1996\-2007 Andy Wardley.  All Rights Reserved.
 377 .PP
 378 This module is free software; you can redistribute it and/or
 379 modify it under the same terms as Perl itself.
 380 .SH "SEE ALSO"
 381 .IX Header "SEE ALSO"
 382 Template