Commit | Line | Data |
3fea05b9 |
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 |