1Template::Manual::VMethUosdesr(3C)ontributed Perl DocumeTnetmaptliaotne::Manual::VMethods(3)
2
3
4

NAME

6       Template::Manual::VMethods - Virtual Methods
7

Scalar Virtual Methods

9   chunk(size)
10       Splits the value into a list of chunks of a certain size.
11
12           [% ccard_no = "1234567824683579";
13              ccard_no.chunk(4).join
14           %]
15
16       Output:
17
18           1234 5678 2468 3579
19
20       If the size is specified as a negative number then the text will be
21       chunked from right-to-left.  This gives the correct grouping for
22       numbers, for example.
23
24           [% number = 1234567;
25              number.chunk(-3).join(',')
26           %]
27
28       Output:
29
30           1,234,567
31
32   collapse
33       Returns the text with any leading and trailing whitespace removed and
34       any internal sequences of whitespace converted to a single space
35
36           [% text = "  The bird\n  is the word" %]
37           [% text.collapse %]       # The bird is the word
38
39   defined
40       Returns true if the value is defined.
41
42           [% user = get_user(uid) IF uid.defined %]
43
44   dquote
45       Returns the text with any double quote characters escaped with a
46       backslash prefix.  Any newline characters in the text will be replaced
47       with "\n".
48
49           [% quote = 'He said "Oh really?"' %]
50           [% quote.dquote %]        # He said \"Oh really?\"
51
52   hash
53       Return the value as a hash reference containing a single entry with the
54       key "value" indicating the original scalar value.  As with the "list"
55       virtual method, this is generally used to help massage data into
56       different formats.
57
58   lcfirst
59       Returns the text with the first letter converted to lower case.
60
61           [% word = 'BIRD' %]
62           [% word.lcfirst %]        # bIRD
63
64   length
65       Returns the length of the string representation of the item:
66
67           [% IF password.length < 8 %]
68              Password too short, dumbass!
69           [% END %]
70
71   empty
72       Returns true if the string is empty:
73
74           [% IF details.empty %]
75              No details specified
76           [% END %]
77
78   list
79       Return the value as a single element list.  This can be useful if you
80       have a variable which may contain a single item or a list and you want
81       to treat them equally.  The "list" method can be called against a list
82       reference and will simply return the original reference, effectively a
83       no-op.
84
85           [% thing.list.size %]     # thing can be a scalar or a list
86
87   lower
88       Returns the text in lower case.
89
90           [% word = 'BIRD' %]
91           [% word.lower %]          # bird
92
93   match(pattern, global)
94       Performs a regular expression match on the string using the pattern
95       passed as an argument.  If the pattern matches the string then the
96       method returns a reference to a list of any strings captured within
97       parenthesis in the pattern.
98
99           [% name = 'Larry Wall' %]
100           [% matches = name.match('(\w+) (\w+)') %]
101           [% matches.1 %], [% matches.0 %]    # Wall, Larry
102
103       If the pattern does not match then the method returns false, rather
104       than returning an empty list which Perl and the Template Toolkit both
105       consider to be a true value.  This allows you to write expression like
106       this.
107
108           [% "We're not worthy!" IF name.match('Larry Wall') %]
109
110           [% IF (matches = name.match('(\w+) (\w+)')) %]
111              pattern matches: [% matches.join(', ') %]
112           [% ELSE %]
113              pattern does not match
114           [% END %]
115
116       Any regex modifiers, like "/s", should be added in the regex using the
117       "(?s)" syntax.  For example, to modify the regex to disregard
118       whitespace (the "/x" switch), use:
119
120           [% re = '(?x)
121                      (\w+)
122                      [ ]
123                      (\w+)
124                    ';
125             matches = name.match(re);
126           %]
127
128       To perform a global search to match the pattern as many times as it
129       appears in the source string, provide a true value for the "global"
130       argument following the pattern.
131
132           [% text = 'bandanna';
133              text.match('an+', 1).join(', ')      # an, ann
134           %]
135
136   repeat(n)
137       Repeat the string a specified number of times.
138
139           [% name = 'foo' %]
140           [% name.repeat(3) %]                # foofoofoo
141
142   replace(search, replace)
143       Outputs the string with all instances of the first argument (specified
144       as a Perl regular expression) with the second.
145
146           [% name = 'foo, bar & baz' %]
147           [% name.replace('\W+', '_') %]        # foo_bar_baz
148
149       You can use $1, $2, etc., to reference captured parts (in parentheses)
150       in the regular expression.  Just be careful to single quote the
151       replacement string.  If you use double quotes then TT will try and
152       interpolate the variables before passing the string to the "replace"
153       vmethod.
154
155           [% name = 'FooBarBaz' %]
156           [% name.replace('([A-Z])', ' $1') %]  # Foo Bar Baz
157
158   remove(pattern)
159       Outputs the string with all instances of the pattern (specified as a
160       Perl regular expression) removed.
161
162           [% name = 'foo, bar & baz' %]
163           [% name.remove('\W+') %]    # foobarbaz
164
165   search(pattern)
166       Performs a similar function to match but simply returns true if the
167       string matches the regular expression pattern passed as an argument.
168
169           [% name = 'foo bar baz' %]
170           [% name.search('bar') ? 'bar' : 'no bar' %]     # bar
171
172       This virtual method is now deprecated in favour of match.  Move along
173       now, there's nothing more to see here.
174
175   size
176       Always returns 1 for scalar values.  This method is provided for
177       consistency with the hash and list size methods.
178
179   split(pattern)
180       Calls Perl's "split()" function to split a string into a list of
181       strings.
182
183           [% FOREACH dir IN mypath.split(':') %]
184              [% dir %]
185           [% END %]
186
187   substr(offset, length, replacement)
188       Returns a substring starting at "offset", for "length" characters.
189
190           [% str 'foo bar baz wiz waz woz') %]
191           [% str.substr(4, 3) %]    # bar
192
193       If "length" is not specified then it returns everything from the
194       "offset" to the end of the string.
195
196           [% str.substr(12) %]      # wiz waz woz
197
198       If both "length" and "replacement" are specified, then the method
199       replaces everything from "offset" for "length" characters with
200       $replacement.  The substring removed from the string is then returned.
201
202           [% str.substr(0, 11, 'FOO') %]   # foo bar baz
203           [% str %]                        # FOO wiz waz woz
204
205   squote
206       Returns the text with any single quote characters escaped with a
207       backslash prefix.
208
209           [% tim = "Tim O'Reilly" %]
210           [% tim.squote %]          # Tim O\'Reilly
211
212   trim
213       Returns the text with any leading and trailing whitespace removed.
214
215           [% text = '  hello  world  ' %]
216           [% text.trim %]           # hello  world
217
218   ucfirst
219       Returns the text with the first letter converted to upper case.
220
221           [% word = 'bird' %]
222           [% word.ucfirst %]        # Bird
223
224   upper
225       Returns the text in upper case.
226
227           [% word = 'bird' %]
228           [% word.upper %]          # BIRD
229

Hash Virtual Methods

231   keys
232       Returns a list of keys in the hash.  They are not returned in any
233       particular order, but the order is the same as for the corresponding
234       values method.
235
236           [% FOREACH key IN hash.keys %]
237              * [% key %]
238           [% END %]
239
240       If you want the keys in sorted order, use the list "sort" method.
241
242           [% FOREACH key IN hash.keys.sort %]
243              * [% key %]
244           [% END %]
245
246       Having got the keys in sorted order, you can then use variable
247       interpolation to fetch the value.  This is shown in the following
248       example by the use of $key to fetch the item from "hash" whose key is
249       stored in the "key" variable.
250
251           [% FOREACH key IN hash.keys.sort %]
252              * [% key %] = [% hash.$key %]
253           [% END %]
254
255       Alternately, you can use the "pairs" method to get a list of key/value
256       pairs in sorted order.
257
258   values
259       Returns a list of the values in the hash.  As with the "keys" method,
260       they are not returned in any particular order, although it is the same
261       order that the keys are returned in.
262
263           [% hash.values.join(', ') %]
264
265   items
266       Returns a list of both the keys and the values expanded into a single
267       list.
268
269           [% hash = {
270                 a = 10
271                 b = 20
272              };
273
274              hash.items.join(', ')    # a, 10, b, 20
275           %]
276
277   each
278       This method currently returns the same thing as the "items" method.
279
280       However, please note that this method will change in the next major
281       version of the Template Toolkit (v3) to return the same thing as the
282       "pairs" method.  This will be done in an effort to make these virtual
283       method more consistent with each other and how Perl works.
284
285       In anticipation of this, we recommend that you stop using "hash.each"
286       and instead use "hash.items".
287
288   pairs
289       This method returns a list of key/value pairs.  They are returned in
290       sorted order according to the keys.
291
292           [% FOREACH pair IN product.pairs %]
293              * [% pair.key %] is [% pair.value %]
294           [% END %]
295
296   list
297       Returns the contents of the hash in list form.  An argument can be
298       passed to indicate the desired items required in the list: "keys" to
299       return a list of the keys (same as "hash.keys"), "values" to return a
300       list of the values (same as "hash.values"), "each" to return as list of
301       key and values (same as "hash.each"), or "pairs" to return a list of
302       key/value pairs (same as "hash.pairs").
303
304           [% keys   = hash.list('keys') %]
305           [% values = hash.list('values') %]
306           [% items  = hash.list('each') %]
307           [% pairs  = hash.list('pairs') %]
308
309       When called without an argument it currently returns the same thing as
310       the "pairs" method.  However, please note that this method will change
311       in the next major version of the Template Toolkit (v3) to return a
312       reference to a list containing the single hash reference (as per the
313       scalar list method).
314
315       In anticipation of this, we recommend that you stop using "hash.list"
316       and instead use "hash.pairs".
317
318   sort, nsort
319       Return a list of the keys, sorted alphabetically ("sort") or
320       numerically ("nsort") according to the corresponding values in the
321       hash.
322
323           [% FOREACH n IN phones.sort %]
324              [% phones.$n %] is [% n %],
325           [% END %]
326
327   import
328       The "import" method can be called on a hash array to import the
329       contents of another hash array.
330
331           [% hash1 = {
332                foo = 'Foo'
333                bar = 'Bar'
334              }
335              hash2 = {
336                  wiz = 'Wiz'
337                  woz = 'Woz'
338              }
339           %]
340
341           [% hash1.import(hash2) %]
342           [% hash1.wiz %]             # Wiz
343
344       You can also call the "import()" method by itself to import a hash
345       array into the current namespace hash.
346
347           [% user = { id => 'lwall', name => 'Larry Wall' } %]
348           [% import(user) %]
349           [% id %]: [% name %]        # lwall: Larry Wall
350
351   defined, exists
352       Returns a true or false value if an item in the hash denoted by the key
353       passed as an argument is defined or exists, respectively.
354
355           [% hash.defined('somekey') ? 'yes' : 'no' %]
356           [% hash.exists('somekey') ? 'yes' : 'no' %]
357
358       When called without any argument, "hash.defined" returns true if the
359       hash itself is defined (e.g. the same effect as "scalar.defined").
360
361   delete
362       Delete one or more items from the hash.
363
364           [% hash.delete('foo', 'bar') %]
365
366   size
367       Returns the number of key/value pairs in the hash.
368
369   empty
370       Returns true if the hash is empty:
371
372           [% IF config.empty %]
373              No configuration available
374           [% END %]
375
376   item
377       Returns an item from the hash using a key passed as an argument.
378
379           [% hash.item('foo') %]  # same as hash.foo
380

List Virtual Methods

382   first, last
383       Returns the first/last item in the list.  The item is not removed from
384       the list.
385
386           [% results.first %] to [% results.last %]
387
388       If either is given a numeric argument "n", they return the first or
389       last "n" elements:
390
391           The first 5 results are [% results.first(5).join(", ") %].
392
393   size, max
394       Returns the size of a list (number of elements) and the maximum index
395       number (size - 1), respectively.
396
397           [% results.size %] search results matched your query
398
399   empty
400       Returns true if the list is empty:
401
402           [% IF results.empty %]
403              No results found
404           [% END %]
405
406   defined
407       Returns a true or false value if the item in the list denoted by the
408       argument is defined.
409
410           [% list.defined(3) ? 'yes' : 'no' %]
411
412       When called without any argument, "list.defined" returns true if the
413       list itself is defined (e.g. the same effect as "scalar.defined").
414
415   reverse
416       Returns the items of the list in reverse order.
417
418           [% FOREACH s IN scores.reverse %]
419              ...
420           [% END %]
421
422   join
423       Joins the items in the list into a single string, using Perl's "join()"
424       function.
425
426           [% items.join(', ') %]
427
428   grep
429       Returns a list of the items in the list that match a regular expression
430       pattern.
431
432           [% FOREACH directory.files.grep('\.txt$') %]
433              ...
434           [% END %]
435
436   sort, nsort
437       Returns the items in alpha ("sort") or numerical ("nsort") order.
438
439           [% library = books.sort %]
440
441       An argument can be provided to specify a search key.  Where an item in
442       the list is a hash reference, the search key will be used to retrieve a
443       value from the hash which will then be used as the comparison value.
444       Where an item is an object which implements a method of that name, the
445       method will be called to return a comparison value.
446
447           [% library = books.sort('author') %]
448
449       In the example, the "books" list can contains hash references with an
450       "author" key or objects with an "author" method.
451
452       You can also specify multiple sort keys.
453
454           [% library = books.sort('author', 'title') %]
455
456       In this case the books will be sorted primarily by author.  If two or
457       more books have authors with the same name then they will be sorted by
458       title.
459
460   unshift(item), push(item)
461       The "push()" method adds an item or items to the end of list.
462
463           [% mylist.push(foo) %]
464           [% mylist.push(foo, bar) %]
465
466       The "unshift()" method adds an item or items to the start of a list.
467
468           [% mylist.unshift(foo) %]
469           [% mylist.push(foo, bar)    %]
470
471   shift, pop
472       Removes the first/last item from the list and returns it.
473
474           [% first = mylist.shift %]
475           [% last  = mylist.pop   %]
476
477   unique
478       Returns a list of the unique elements in a list, in the same order as
479       in the list itself.
480
481           [% mylist = [ 1, 2, 3, 2, 3, 4, 1, 4, 3, 4, 5 ] %]
482           [% numbers = mylist.unique %]
483
484       While this can be explicitly sorted, it is not required that the list
485       be sorted before the unique elements are pulled out (unlike the Unix
486       command line utility).
487
488           [% numbers = mylist.unique.sort %]
489
490   import
491       Appends the contents of one or more other lists to the end of the
492       current list.
493
494           [% one   = [ 1 2 3 ];
495              two   = [ 4 5 6 ];
496              three = [ 7 8 9 ];
497              one.import(two, three);
498              one.join(', ');     # 1, 2, 3, 4, 5, 6, 7, 8, 9
499           %]
500
501   merge
502       Returns a list composed of zero or more other lists:
503
504           [% list_one = [ 1 2 3 ];
505              list_two = [ 4 5 6 ];
506              list_three = [ 7 8 9 ];
507              list_four = list_one.merge(list_two, list_three);
508           %]
509
510       The original lists are not modified.
511
512   slice(from, to)
513       Returns a slice of items in the list between the bounds passed as
514       arguments.  If the second argument, "to", isn't specified, then it
515       defaults to the last item in the list.  The original list is not
516       modified.
517
518           [% first_three = list.slice(0,2) %]
519           [% last_three  = list.slice(-3, -1) %]
520
521   splice(offset, length, list)
522       Behaves just like Perl's "splice()" function allowing you to
523       selectively remove and/or replace elements in a list.  It removes
524       "length" items from the list, starting at "offset" and replaces them
525       with the items in "list".
526
527           [% play_game = [ 'play', 'scrabble' ];
528              ping_pong = [ 'ping', 'pong' ];
529              redundant = play_game.splice(1, 1, ping_pong);
530              redundant.join;     # scrabble
531              play_game.join;     # play ping pong
532           %]
533
534       The method returns a list of the items removed by the splice.  You can
535       use the "CALL" directive to ignore the output if you're not planning to
536       do anything with it.
537
538           [% CALL play_game.splice(1, 1, ping_pong) %]
539
540       As well as providing a reference to a list of replacement values, you
541       can pass in a list of items.
542
543           [% CALL list.splice(-1, 0, 'foo', 'bar') %]
544
545       Be careful about passing just one item in as a replacement value.  If
546       it is a reference to a list then the contents of the list will be used.
547       If it's not a list, then it will be treated as a single value.  You can
548       use square brackets around a single item if you need to be explicit:
549
550           [% # push a single item, an_item
551              CALL list.splice(-1, 0, an_item);
552
553              # push the items from another_list
554              CALL list.splice(-1, 0, another_list);
555
556              # push a reference to another_list
557              CALL list.splice(-1, 0, [ another_list ]);
558           %]
559
560   hash
561       Returns a reference to a hash array comprised of the elements in the
562       list.  The even-numbered elements (0, 2, 4, etc) become the keys and
563       the odd-numbered elements (1, 3, 5, etc) the values.
564
565           [% list = ['pi', 3.14, 'e', 2.718] %]
566           [% hash = list.hash %]
567           [% hash.pi %]               # 3.14
568           [% hash.e  %]               # 2.718
569
570       If a numerical argument is provided then the hash returned will have
571       keys generated for each item starting at the number specified.
572
573           [% list = ['beer', 'peanuts'] %]
574           [% hash = list.hash(1) %]
575           [% hash.1  %]               # beer
576           [% hash.2  %]               # peanuts
577
578   item
579       Returns an item from the list using an index passed as an argument.
580
581           [% list.item(0) %]  # same as list.0
582

Automagic Promotion of Scalar to List for Virtual Methods

584       In addition to the scalar virtual methods listed in the previous
585       section, you can also call any list virtual method against a scalar.
586       The item will be automagically promoted to a single element list and
587       the appropriate list virtual method will be called.
588
589       One particular benefit of this comes when calling subroutines or object
590       methods that return a list of items, rather than the preferred
591       reference to a list of items.  In this case, the Template Toolkit
592       automatically folds the items returned into a list.
593
594       The upshot is that you can continue to use existing Perl modules or
595       code that returns lists of items, without having to refactor it just to
596       keep the Template Toolkit happy (by returning references to list).
597       "Class::DBI" module is just one example of a particularly useful module
598       which returns values this way.
599
600       If only a single item is returned from a subroutine then the Template
601       Toolkit assumes it meant to return a single item (rather than a list of
602       1 item) and leaves it well alone, returning the single value as it is.
603       If you're executing a database query, for example, you might get 1 item
604       returned, or perhaps many items which are then folded into a list.
605
606       The "FOREACH" directive will happily accept either a list or a single
607       item which it will treat as a list. So it's safe to write directives
608       like this, where we assume that the "something" variable is bound to a
609       subroutine which may return one or more items:
610
611           [% FOREACH item IN something %]
612              ...
613           [% END %]
614
615       The automagic promotion of scalars to single item lists means that you
616       can also use list virtual methods safely, even if you only get one item
617       returned.  For example:
618
619           [% something.first   %]
620           [% something.join    %]
621           [% something.reverse.join(', ') %]
622
623       Note that this is very much a last-ditch behaviour.  If the single item
624       return is an object with a "first" method, for example, then that will
625       be called, as expected, in preference to the list virtual method.
626

Defining Custom Virtual Methods

628       You can define your own virtual methods for scalars, lists and hash
629       arrays.  The Template::Stash package variables $SCALAR_OPS, $LIST_OPS
630       and $HASH_OPS are references to hash arrays that define these virtual
631       methods.  "HASH_OPS" and "LIST_OPS" methods are subroutines that accept
632       a hash/list reference as the first item. "SCALAR_OPS" are subroutines
633       that accept a scalar value as the first item. Any other arguments
634       specified when the method is called will be passed to the subroutine.
635
636           # load Template::Stash to make method tables visible
637           use Template::Stash;
638
639           # define list method to return new list of odd numbers only
640           $Template::Stash::LIST_OPS->{ odd } = sub {
641               my $list = shift;
642               return [ grep { $_ % 2 } @$list ];
643           };
644
645       Example template:
646
647           [% primes = [ 2, 3, 5, 7, 9 ] %]
648           [% primes.odd.join(', ') %]         # 3, 5, 7, 9
649
650       TODO: document the define_vmethod() method which makes this even easier
651
652
653
654perl v5.28.1                      2018-10-05     Template::Manual::VMethods(3)
Impressum