local-lib5/man/man3/Template::Manual::VMethods.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::Manual::VMethods 3"
 132 .TH Template::Manual::VMethods 3 "2009-07-04" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Template::Manual::VMethods \- Virtual Methods
 135 .SH "Scalar Virtual Methods"
 136 .IX Header "Scalar Virtual Methods"
 137 .Sh "defined"
 138 .IX Subsection "defined"
 139 Returns true if the value is defined.
 140 .PP
 141 .Vb 1
 142 \&    [% user = get_user(uid) IF uid.defined %]
 143 .Ve
 144 .Sh "length"
 145 .IX Subsection "length"
 146 Returns the length of the string representation of the item:
 147 .PP
 148 .Vb 3
 149 \&    [% IF password.length < 8 %]
 150 \&       Password too short, dumbass!
 151 \&    [% END %]
 152 .Ve
 153 .Sh "repeat(n)"
 154 .IX Subsection "repeat(n)"
 155 Repeat the string a specified number of times.
 156 .PP
 157 .Vb 2
 158 \&    [% name = 'foo' %]
 159 \&    [% name.repeat(3) %]                # foofoofoo
 160 .Ve
 161 .Sh "replace(search, replace)"
 162 .IX Subsection "replace(search, replace)"
 163 Outputs the string with all instances of the first argument (specified
 164 as a Perl regular expression) with the second.
 165 .PP
 166 .Vb 2
 167 \&    [% name = 'foo, bar & baz' %]
 168 \&    [% name.replace('\eW+', '_') %]        # foo_bar_baz
 169 .Ve
 170 .PP
 171 You can use \f(CW$1\fR, \f(CW$2\fR, etc., to reference captured parts (in parentheses)
 172 in the regular expression.  Just be careful to \fIsingle\fR quote the replacement
 173 string.  If you use \fIdouble\fR quotes then \s-1TT\s0 will try and interpolate the
 174 variables before passing the string to the \f(CW\*(C`replace\*(C'\fR vmethod.
 175 .PP
 176 .Vb 2
 177 \&    [% name = 'FooBarBaz' %]
 178 \&    [% name.replace('([A\-Z])', ' $1') %]  # Foo Bar Baz
 179 .Ve
 180 .Sh "remove(pattern)"
 181 .IX Subsection "remove(pattern)"
 182 Outputs the string with all instances of the pattern (specified
 183 as a Perl regular expression) removed.
 184 .PP
 185 .Vb 2
 186 \&    [% name = 'foo, bar & baz' %]
 187 \&    [% name.remove('\eW+') %]    # foobarbaz
 188 .Ve
 189 .Sh "match(pattern, global)"
 190 .IX Subsection "match(pattern, global)"
 191 Performs a regular expression match on the string using the pattern
 192 passed as an argument.  If the pattern matches the string then the
 193 method returns a reference to a list of any strings captured within
 194 parenthesis in the pattern.
 195 .PP
 196 .Vb 3
 197 \&    [% name = 'Larry Wall' %]
 198 \&    [% matches = name.match('(\ew+) (\ew+)') %]
 199 \&    [% matches.1 %], [% matches.0 %]            # Wall, Larry
 200 .Ve
 201 .PP
 202 If the pattern does not match then the method returns false, rather
 203 than returning an empty list which Perl and the Template Toolkit both
 204 consider to be a true value.  This allows you to write expression like
 205 this.
 206 .PP
 207 .Vb 1
 208 \&    [% "We're not worthy!" IF name.match('Larry Wall') %]
 209 .Ve
 210 .PP
 211 .Vb 5
 212 \&    [% IF (matches = name.match('(\ew+) (\ew+)')) %]
 213 \&       pattern matches: [% matches.join(', ') %]
 214 \&    [% ELSE %]
 215 \&       pattern does not match
 216 \&    [% END %]
 217 .Ve
 218 .PP
 219 Any regex modifiers, like \f(CW\*(C`/s\*(C'\fR, should be added in the regex using
 220 the \f(CW\*(C`(?s)\*(C'\fR syntax.  For example, to modify the regex to disregard
 221 whitespace (the \f(CW\*(C`/x\*(C'\fR switch), use:
 222 .PP
 223 .Vb 7
 224 \&    [% re = '(?x)
 225 \&               (\ew+)
 226 \&               [ ]
 227 \&               (\ew+)
 228 \&             ';
 229 \&      matches = name.match(re);
 230 \&    %]
 231 .Ve
 232 .PP
 233 To perform a global search to match the pattern as many times as it
 234 appears in the source string, provide a true value for the \f(CW\*(C`global\*(C'\fR
 235 argument following the pattern.
 236 .PP
 237 .Vb 3
 238 \&    [% text = 'bandanna';
 239 \&       text.match('an+', 1).join(', )      # an, ann
 240 \&    %]
 241 .Ve
 242 .Sh "search(pattern)"
 243 .IX Subsection "search(pattern)"
 244 Performs a similar function to match but simply returns true if the
 245 string matches the regular expression pattern passed as an argument.
 246 .PP
 247 .Vb 2
 248 \&    [% name = 'foo bar baz' %]
 249 \&    [% name.search('bar') ? 'bar' : 'no bar' %]     # bar
 250 .Ve
 251 .PP
 252 This virtual method is now deprecated in favour of match.  Move along
 253 now, there's nothing more to see here.
 254 .Sh "split(pattern)"
 255 .IX Subsection "split(pattern)"
 256 Calls Perl's \f(CW\*(C`split()\*(C'\fR function to split a string into a list of
 257 strings.
 258 .PP
 259 .Vb 3
 260 \&    [% FOREACH dir IN mypath.split(':') %]
 261 \&       [% dir %]
 262 \&    [% END %]
 263 .Ve
 264 .Sh "chunk(size)"
 265 .IX Subsection "chunk(size)"
 266 Splits the value into a list of chunks of a certain size.
 267 .PP
 268 .Vb 3
 269 \&    [% ccard_no = "1234567824683579";
 270 \&       ccard_no.chunk(4).join
 271 \&    %]
 272 .Ve
 273 .PP
 274 Output:
 275 .PP
 276 .Vb 1
 277 \&    1234 5678 2468 3579
 278 .Ve
 279 .PP
 280 If the size is specified as a negative number then the text will
 281 be chunked from right\-to\-left.  This gives the correct grouping
 282 for numbers, for example.
 283 .PP
 284 .Vb 3
 285 \&    [% number = 1234567;
 286 \&       number.chunk(\-3).join(',')
 287 \&    %]
 288 .Ve
 289 .PP
 290 Output:
 291 .PP
 292 .Vb 1
 293 \&    1,234,567
 294 .Ve
 295 .Sh "substr(offset, length, replacement)"
 296 .IX Subsection "substr(offset, length, replacement)"
 297 Returns a substring starting at \f(CW\*(C`offset\*(C'\fR, for \f(CW\*(C`length\*(C'\fR characters.
 298 .PP
 299 .Vb 2
 300 \&    [% str 'foo bar baz wiz waz woz') %]
 301 \&    [% str.substr(4, 3) %]    # bar
 302 .Ve
 303 .PP
 304 If \f(CW\*(C`length\*(C'\fR is not specified then it returns everything from the
 305 \&\f(CW\*(C`offset\*(C'\fR to the end of the string.
 306 .PP
 307 .Vb 1
 308 \&    [% str.substr(12) %]      # wiz waz woz
 309 .Ve
 310 .PP
 311 If both \f(CW\*(C`length\*(C'\fR and \f(CW\*(C`replacement\*(C'\fR are specified, then the method
 312 replaces everything from \f(CW\*(C`offset\*(C'\fR for \f(CW\*(C`length\*(C'\fR characters with
 313 \&\f(CW$replacement\fR.  The substring removed from the string is then returned.
 314 .PP
 315 .Vb 2
 316 \&    [% str.substr(0, 11, 'FOO') %]   # foo bar baz
 317 \&    [% str %]                        # FOO wiz waz woz
 318 .Ve
 319 .Sh "list"
 320 .IX Subsection "list"
 321 Return the value as a single element list.  This can be useful if you
 322 have a variable which may contain a single item or a list and you want
 323 to treat them equally.  The \f(CW\*(C`list\*(C'\fR method can be called against a list
 324 reference and will simply return the original reference, effectively
 325 a no\-op.
 326 .PP
 327 .Vb 1
 328 \&    [% thing.list.size %]  # thing can be a scalar or a list
 329 .Ve
 330 .Sh "hash"
 331 .IX Subsection "hash"
 332 Return the value as a hash reference containing a single entry with
 333 the key \f(CW\*(C`value\*(C'\fR indicating the original scalar value.  As with the
 334 \&\f(CW\*(C`list\*(C'\fR virtual method, this is generally used to help massage data
 335 into different formats.
 336 .Sh "size"
 337 .IX Subsection "size"
 338 Always returns 1 for scalar values.  This method is provided for
 339 consistency with the hash and list size methods.
 340 .SH "Hash Virtual Methods"
 341 .IX Header "Hash Virtual Methods"
 342 .Sh "keys"
 343 .IX Subsection "keys"
 344 Returns a list of keys in the hash.  They are not returned in any
 345 particular order, but the order is the same as for the corresponding
 346 values method.
 347 .PP
 348 .Vb 3
 349 \&    [% FOREACH key IN hash.keys %]
 350 \&       * [% key %]
 351 \&    [% END %]
 352 .Ve
 353 .PP
 354 If you want the keys in sorted order, use the list \f(CW\*(C`sort\*(C'\fR method.
 355 .PP
 356 .Vb 3
 357 \&    [% FOREACH key IN hash.keys.sort %]
 358 \&       * [% key %]
 359 \&    [% END %]
 360 .Ve
 361 .PP
 362 Having got the keys in sorted order, you can then use variable
 363 interpolation to fetch the value.  This is shown in the following
 364 example by the use of \f(CW$key\fR to fetch the item from \f(CW\*(C`hash\*(C'\fR whose
 365 key is stored in the \f(CW\*(C`key\*(C'\fR variable.
 366 .PP
 367 .Vb 3
 368 \&    [% FOREACH key IN hash.keys.sort %]
 369 \&       * [% key %] = [% hash.$key %]
 370 \&    [% END %]
 371 .Ve
 372 .PP
 373 Alternately, you can use the \f(CW\*(C`pairs\*(C'\fR method to get a list of
 374 key/value pairs in sorted order.
 375 .Sh "values"
 376 .IX Subsection "values"
 377 Returns a list of the values in the hash.  As with the \f(CW\*(C`keys\*(C'\fR method,
 378 they are not returned in any particular order, although it is the same
 379 order that the keys are returned in.
 380 .PP
 381 .Vb 1
 382 \&    [% hash.values.join(', ') %]
 383 .Ve
 384 .Sh "items"
 385 .IX Subsection "items"
 386 Returns a list of both the keys and the values expanded into a single list.
 387 .PP
 388 .Vb 4
 389 \&    [% hash = {
 390 \&          a = 10
 391 \&          b = 20
 392 \&       };
 393 .Ve
 394 .PP
 395 .Vb 2
 396 \&       hash.items.join(', ')    # a, 10, b, 20
 397 \&    %]
 398 .Ve
 399 .Sh "each"
 400 .IX Subsection "each"
 401 This method currently returns the same thing as the \f(CW\*(C`items\*(C'\fR method.
 402 .PP
 403 However, please note that this method will change in the next major
 404 version of the Template Toolkit (v3) to return the same thing as the
 405 \&\f(CW\*(C`pairs\*(C'\fR method.  This will be done in an effort to make these virtual
 406 method more consistent with each other and how Perl works.
 407 .PP
 408 In anticipation of this, we recommend that you stop using \f(CW\*(C`hash.each\*(C'\fR
 409 and instead use \f(CW\*(C`hash.items\*(C'\fR.
 410 .Sh "pairs"
 411 .IX Subsection "pairs"
 412 This method returns a list of key/value pairs.  They are returned in
 413 sorted order according to the keys.
 414 .PP
 415 .Vb 3
 416 \&    [% FOREACH pair IN product.pairs %]
 417 \&       * [% pair.key %] is [% pair.value %]
 418 \&    [% END %]
 419 .Ve
 420 .Sh "list"
 421 .IX Subsection "list"
 422 Returns the contents of the hash in list form.  An argument can be
 423 passed to indicate the desired items required in the list: \f(CW\*(C`keys\*(C'\fR to
 424 return a list of the keys (same as \f(CW\*(C`hash.keys\*(C'\fR), \f(CW\*(C`values\*(C'\fR to return a
 425 list of the values (same as \f(CW\*(C`hash.values\*(C'\fR), \f(CW\*(C`each\*(C'\fR to return as list
 426 of key and values (same as \f(CW\*(C`hash.each\*(C'\fR), or \f(CW\*(C`pairs\*(C'\fR to return a list
 427 of key/value pairs (same as \f(CW\*(C`hash.pairs\*(C'\fR).
 428 .PP
 429 .Vb 4
 430 \&    [% keys   = hash.list('keys') %]
 431 \&    [% values = hash.list('values') %]
 432 \&    [% items  = hash.list('each') %]
 433 \&    [% pairs  = hash.list('pairs') %]
 434 .Ve
 435 .PP
 436 When called without an argument it currently returns the same thing as
 437 the \f(CW\*(C`pairs\*(C'\fR method.  However, please note that this method will change
 438 in the next major version of the Template Toolkit (v3) to return a
 439 reference to a list containing the single hash reference (as per the
 440 scalar list method).
 441 .PP
 442 In anticipation of this, we recommend that you stop using \f(CW\*(C`hash.list\*(C'\fR
 443 and instead use \f(CW\*(C`hash.pairs\*(C'\fR.
 444 .Sh "sort, nsort"
 445 .IX Subsection "sort, nsort"
 446 Return a list of the keys, sorted alphabetically (\f(CW\*(C`sort\*(C'\fR) or numerically
 447 (\f(CW\*(C`nsort\*(C'\fR) according to the corresponding values in the hash.
 448 .PP
 449 .Vb 3
 450 \&    [% FOREACH n IN phones.sort %]
 451 \&       [% phones.$n %] is [% n %],
 452 \&    [% END %]
 453 .Ve
 454 .Sh "import"
 455 .IX Subsection "import"
 456 The \f(CW\*(C`import\*(C'\fR method can be called on a hash array to import the contents
 457 of another hash array.
 458 .PP
 459 .Vb 9
 460 \&    [% hash1 = {
 461 \&         foo = 'Foo'
 462 \&         bar = 'Bar'
 463 \&       }
 464 \&       hash2 = {
 465 \&           wiz = 'Wiz'
 466 \&           woz = 'Woz'
 467 \&       }
 468 \&    %]
 469 .Ve
 470 .PP
 471 .Vb 2
 472 \&    [% hash1.import(hash2) %]
 473 \&    [% hash1.wiz %]             # Wiz
 474 .Ve
 475 .PP
 476 You can also call the \f(CW\*(C`import()\*(C'\fR method by itself to import a hash array
 477 into the current namespace hash.
 478 .PP
 479 .Vb 3
 480 \&    [% user = { id => 'lwall', name => 'Larry Wall' } %]
 481 \&    [% import(user) %]
 482 \&    [% id %]: [% name %]        # lwall: Larry Wall
 483 .Ve
 484 .Sh "defined, exists"
 485 .IX Subsection "defined, exists"
 486 Returns a true or false value if an item in the hash denoted by the key
 487 passed as an argument is defined or exists, respectively.
 488 .PP
 489 .Vb 2
 490 \&    [% hash.defined('somekey') ? 'yes' : 'no' %]
 491 \&    [% hash.exists('somekey') ? 'yes' : 'no' %]
 492 .Ve
 493 .PP
 494 When called without any argument, \f(CW\*(C`hash.defined\*(C'\fR returns true if the hash
 495 itself is defined (e.g. the same effect as \f(CW\*(C`scalar.defined\*(C'\fR).
 496 .Sh "delete"
 497 .IX Subsection "delete"
 498 Delete one or more items from the hash.
 499 .PP
 500 .Vb 1
 501 \&    [% hash.delete('foo', 'bar') %]
 502 .Ve
 503 .Sh "size"
 504 .IX Subsection "size"
 505 Returns the number of key/value pairs in the hash.
 506 .Sh "item"
 507 .IX Subsection "item"
 508 Returns an item from the hash using a key passed as an argument.
 509 .PP
 510 .Vb 1
 511 \&    [% hash.item('foo') %]  # same as hash.foo
 512 .Ve
 513 .SH "List Virtual Methods"
 514 .IX Header "List Virtual Methods"
 515 .Sh "first, last"
 516 .IX Subsection "first, last"
 517 Returns the first/last item in the list.  The item is not removed from the
 518 list.
 519 .PP
 520 .Vb 1
 521 \&    [% results.first %] to [% results.last %]
 522 .Ve
 523 .PP
 524 If either is given a numeric argument \f(CW\*(C`n\*(C'\fR, they return the first or
 525 last \f(CW\*(C`n\*(C'\fR elements:
 526 .PP
 527 .Vb 1
 528 \&    The first 5 results are [% results.first(5).join(", ") %].
 529 .Ve
 530 .Sh "size, max"
 531 .IX Subsection "size, max"
 532 Returns the size of a list (number of elements) and the maximum
 533 index number (size \- 1), respectively.
 534 .PP
 535 .Vb 1
 536 \&    [% results.size %] search results matched your query
 537 .Ve
 538 .Sh "defined"
 539 .IX Subsection "defined"
 540 Returns a true or false value if the item in the list denoted by the
 541 argument is defined.
 542 .PP
 543 .Vb 1
 544 \&    [% list.defined(3) ? 'yes' : 'no' %]
 545 .Ve
 546 .PP
 547 When called without any argument, \f(CW\*(C`list.defined\*(C'\fR returns true if the list
 548 itself is defined (e.g. the same effect as \f(CW\*(C`scalar.defined\*(C'\fR).
 549 .Sh "reverse"
 550 .IX Subsection "reverse"
 551 Returns the items of the list in reverse order.
 552 .PP
 553 .Vb 3
 554 \&    [% FOREACH s IN scores.reverse %]
 555 \&       ...
 556 \&    [% END %]
 557 .Ve
 558 .Sh "join"
 559 .IX Subsection "join"
 560 Joins the items in the list into a single string, using Perl's \f(CW\*(C`join()\*(C'\fR
 561 function.
 562 .PP
 563 .Vb 1
 564 \&    [% items.join(', ') %]
 565 .Ve
 566 .Sh "grep"
 567 .IX Subsection "grep"
 568 Returns a list of the items in the list that match a regular expression
 569 pattern.
 570 .PP
 571 .Vb 3
 572 \&    [% FOREACH directory.files.grep('\e.txt$') %]
 573 \&       ...
 574 \&    [% END %]
 575 .Ve
 576 .Sh "sort, nsort"
 577 .IX Subsection "sort, nsort"
 578 Returns the items in alpha (\f(CW\*(C`sort\*(C'\fR) or numerical (\f(CW\*(C`nsort\*(C'\fR) order.
 579 .PP
 580 .Vb 1
 581 \&    [% library = books.sort %]
 582 .Ve
 583 .PP
 584 An argument can be provided to specify a search key.  Where an item in
 585 the list is a hash reference, the search key will be used to retrieve a
 586 value from the hash which will then be used as the comparison value.
 587 Where an item is an object which implements a method of that name, the
 588 method will be called to return a comparison value.
 589 .PP
 590 .Vb 1
 591 \&    [% library = books.sort('author') %]
 592 .Ve
 593 .PP
 594 In the example, the \f(CW\*(C`books\*(C'\fR list can contains hash references with
 595 an \f(CW\*(C`author\*(C'\fR key or objects with an \f(CW\*(C`author\*(C'\fR method.
 596 .PP
 597 You can also specify multiple sort keys.
 598 .PP
 599 .Vb 1
 600 \&    [% library = books.sort('author', 'title') %]
 601 .Ve
 602 .PP
 603 In this case the books will be sorted primarily by author.  If two or more
 604 books have authors with the same name then they will be sorted by title.
 605 .Sh "unshift(item), push(item)"
 606 .IX Subsection "unshift(item), push(item)"
 607 The \f(CW\*(C`push()\*(C'\fR method adds an item or items to the end of list.
 608 .PP
 609 .Vb 2
 610 \&    [% mylist.push(foo) %]
 611 \&    [% mylist.push(foo, bar) %]
 612 .Ve
 613 .PP
 614 The \f(CW\*(C`unshift()\*(C'\fR method adds an item or items to the start of a list.
 615 .PP
 616 .Vb 2
 617 \&    [% mylist.unshift(foo) %]
 618 \&    [% mylist.push(foo, bar)    %]
 619 .Ve
 620 .Sh "shift, pop"
 621 .IX Subsection "shift, pop"
 622 Removes the first/last item from the list and returns it.
 623 .PP
 624 .Vb 2
 625 \&    [% first = mylist.shift %]
 626 \&    [% last  = mylist.pop   %]
 627 .Ve
 628 .Sh "unique"
 629 .IX Subsection "unique"
 630 Returns a list of the unique elements in a list, in the same order
 631 as in the list itself.
 632 .PP
 633 .Vb 2
 634 \&    [% mylist = [ 1, 2, 3, 2, 3, 4, 1, 4, 3, 4, 5 ] %]
 635 \&    [% numbers = mylist.unique %]
 636 .Ve
 637 .PP
 638 While this can be explicitly sorted, it is not required that the list
 639 be sorted before the unique elements are pulled out (unlike the Unix
 640 command line utility).
 641 .PP
 642 .Vb 1
 643 \&    [% numbers = mylist.unique.sort %]
 644 .Ve
 645 .Sh "import"
 646 .IX Subsection "import"
 647 Appends the contents of one or more other lists to the end of the
 648 current list.
 649 .PP
 650 .Vb 6
 651 \&    [% one   = [ 1 2 3 ];
 652 \&       two   = [ 4 5 6 ];
 653 \&       three = [ 7 8 9 ];
 654 \&       one.import(two, three);
 655 \&       one.join(', );     # 1, 2, 3, 4, 5, 6, 7, 8, 9
 656 \&    %]
 657 .Ve
 658 .Sh "merge"
 659 .IX Subsection "merge"
 660 Returns a list composed of zero or more other lists:
 661 .PP
 662 .Vb 5
 663 \&    [% list_one = [ 1 2 3 ];
 664 \&       list_two = [ 4 5 6 ];
 665 \&       list_three = [ 7 8 9 ];
 666 \&       list_four = list_one.merge(list_two, list_three);
 667 \&    %]
 668 .Ve
 669 .PP
 670 The original lists are not modified.
 671 .Sh "slice(from, to)"
 672 .IX Subsection "slice(from, to)"
 673 Returns a slice of items in the list between the bounds passed as
 674 arguments.  If the second argument, \f(CW\*(C`to\*(C'\fR, isn't specified, then it
 675 defaults to the last item in the list.  The original list is not
 676 modified.
 677 .PP
 678 .Vb 2
 679 \&    [% first_three = list.slice(0,2) %]
 680 \&    [% last_three  = list.slice(\-3, \-1) %]
 681 .Ve
 682 .Sh "splice(offset, length, list)"
 683 .IX Subsection "splice(offset, length, list)"
 684 Behaves just like Perl's \f(CW\*(C`splice()\*(C'\fR function allowing you to selectively
 685 remove and/or replace elements in a list.  It removes \f(CW\*(C`length\*(C'\fR items
 686 from the list, starting at \f(CW\*(C`offset\*(C'\fR and replaces them with the items
 687 in \f(CW\*(C`list\*(C'\fR.
 688 .PP
 689 .Vb 6
 690 \&    [% play_game = [ 'play', 'scrabble' ];
 691 \&       ping_pong = [ 'ping', 'pong' ];
 692 \&       redundant = play_game.splice(1, 1, ping_pong);
 693 \&       redundant.join;     # scrabble
 694 \&       play_game.join;     # play ping pong
 695 \&    %]
 696 .Ve
 697 .PP
 698 The method returns a list of the items removed by the splice.
 699 You can use the \f(CW\*(C`CALL\*(C'\fR directive to ignore the output if you're
 700 not planning to do anything with it.
 701 .PP
 702 .Vb 1
 703 \&    [% CALL play_game.splice(1, 1, ping_pong) %]
 704 .Ve
 705 .PP
 706 As well as providing a reference to a list of replacement values,
 707 you can pass in a list of items.
 708 .PP
 709 .Vb 1
 710 \&    [% CALL list.splice(\-1, 0, 'foo', 'bar') %]
 711 .Ve
 712 .PP
 713 Be careful about passing just one item in as a replacement value.
 714 If it is a reference to a list then the contents of the list will
 715 be used.  If it's not a list, then it will be treated as a single
 716 value.  You can use square brackets around a single item if you
 717 need to be explicit:
 718 .PP
 719 .Vb 2
 720 \&    [% # push a single item, an_item
 721 \&       CALL list.splice(\-1, 0, an_item);
 722 .Ve
 723 .PP
 724 .Vb 2
 725 \&       # push the items from another_list
 726 \&       CALL list.splice(\-1, 0, another_list);
 727 .Ve
 728 .PP
 729 .Vb 3
 730 \&       # push a reference to another_list
 731 \&       CALL list.splice(\-1, 0, [ another_list ]);
 732 \&    %]
 733 .Ve
 734 .Sh "hash"
 735 .IX Subsection "hash"
 736 Returns a reference to a hash array comprised of the elements in the
 737 list.  The even-numbered elements (0, 2, 4, etc) become the keys and
 738 the odd-numbered elements (1, 3, 5, etc) the values.
 739 .PP
 740 .Vb 4
 741 \&    [% list = ['pi', 3.14, 'e', 2.718] %]
 742 \&    [% hash = list.hash %]
 743 \&    [% hash.pi %]               # 3.14
 744 \&    [% hash.e  %]               # 2.718
 745 .Ve
 746 .PP
 747 If a numerical argument is provided then the hash returned will have
 748 keys generated for each item starting at the number specified.
 749 .PP
 750 .Vb 4
 751 \&    [% list = ['beer', 'peanuts'] %]
 752 \&    [% hash = list.hash(1) %]
 753 \&    [% hash.1  %]               # beer
 754 \&    [% hash.2  %]               # peanuts
 755 .Ve
 756 .SH "Automagic Promotion of Scalar to List for Virtual Methods"
 757 .IX Header "Automagic Promotion of Scalar to List for Virtual Methods"
 758 In addition to the scalar virtual methods listed in the previous
 759 section, you can also call any list virtual method against a scalar.
 760 The item will be automagically promoted to a single element list and
 761 the appropriate list virtual method will be called.
 762 .PP
 763 One particular benefit of this comes when calling subroutines or
 764 object methods that return a list of items, rather than the
 765 preferred reference to a list of items.  In this case, the
 766 Template Toolkit automatically folds the items returned into
 767 a list.
 768 .PP
 769 The upshot is that you can continue to use existing Perl modules or
 770 code that returns lists of items, without having to refactor it
 771 just to keep the Template Toolkit happy (by returning references
 772 to list).  \f(CW\*(C`Class::DBI\*(C'\fR module is just one example of a particularly
 773 useful module which returns values this way.
 774 .PP
 775 If only a single item is returned from a subroutine then the
 776 Template Toolkit assumes it meant to return a single item (rather
 777 than a list of 1 item) and leaves it well alone, returning the
 778 single value as it is.  If you're executing a database query,
 779 for example, you might get 1 item returned, or perhaps many
 780 items which are then folded into a list.
 781 .PP
 782 The \f(CW\*(C`FOREACH\*(C'\fR directive will happily accept either a list or a single item
 783 which it will treat as a list. So it's safe to write directives like this,
 784 where we assume that the \f(CW\*(C`something\*(C'\fR variable is bound to a subroutine which
 785 may return one or more items:
 786 .PP
 787 .Vb 3
 788 \&    [% FOREACH item IN something %]
 789 \&       ...
 790 \&    [% END %]
 791 .Ve
 792 .PP
 793 The automagic promotion of scalars to single item lists means
 794 that you can also use list virtual methods safely, even if you
 795 only get one item returned.  For example:
 796 .PP
 797 .Vb 3
 798 \&    [% something.first   %]
 799 \&    [% something.join    %]
 800 \&    [% something.reverse.join(', ') %]
 801 .Ve
 802 .PP
 803 Note that this is very much a last-ditch behaviour.  If the single
 804 item return is an object with a \f(CW\*(C`first\*(C'\fR method, for example, then that
 805 will be called, as expected, in preference to the list virtual method.
 806 .SH "Defining Custom Virtual Methods"
 807 .IX Header "Defining Custom Virtual Methods"
 808 You can define your own virtual methods for scalars, lists and hash arrays.
 809 The Template::Stash package variables \f(CW$SCALAR_OPS\fR, \f(CW$LIST_OPS\fR and
 810 \&\f(CW$HASH_OPS\fR are references to hash arrays that define these virtual methods.
 811 \&\f(CW\*(C`HASH_OPS\*(C'\fR and \f(CW\*(C`LIST_OPS\*(C'\fR methods are subroutines that accept a hash/list
 812 reference as the first item. \f(CW\*(C`SCALAR_OPS\*(C'\fR are subroutines that accept a scalar
 813 value as the first item. Any other arguments specified when the method is
 814 called will be passed to the subroutine.
 815 .PP
 816 .Vb 2
 817 \&    # load Template::Stash to make method tables visible
 818 \&    use Template::Stash;
 819 .Ve
 820 .PP
 821 .Vb 5
 822 \&    # define list method to return new list of odd numbers only
 823 \&    $Template::Stash::LIST_OPS\->{ odd } = sub {
 824 \&        my $list = shift;
 825 \&        return [ grep { $_ % 2 } @$list ];
 826 \&    };
 827 .Ve
 828 .PP
 829 Example template:
 830 .PP
 831 .Vb 2
 832 \&    [% primes = [ 2, 3, 5, 7, 9 ] %]
 833 \&    [% primes.odd.join(', ') %]         # 3, 5, 7, 9
 834 .Ve
 835 .PP
 836 \&\s-1TODO:\s0 document the \fIdefine_vmethod()\fR method which makes this even easier