1Template::Alloy::VMethoUds(e3r)Contributed Perl DocumentTaetmipolnate::Alloy::VMethod(3)
2
3
4

NAME

6       Template::Alloy::VMethod - VMethod role.
7

DESCRIPTION

9       The Template::Alloy::VMethod role provides all of the extra vmethods,
10       filters, and virtual objects that add to the base featureset of
11       Template::Alloy.  Most of the vmethods listed here are similar to those
12       provided by Template::Toolkit.  We will try to keep Template::Alloy's
13       in sync.  Template::Alloy also provides several extra methods that are
14       needed for HTML::Template::Expr support.
15

ROLE METHODS

17       define_vmethod
18           Defines a vmethod.  See Template::Alloy for more details.
19
20       "vmethod_*"
21           Methods by these names implement virtual methods that are more
22           complex than oneliners.  These methods are not exposed via the
23           role.
24
25       "filter_*"
26           Methods by these names implement filters that are more complex than
27           one liners.  These methods are not exposed via the role.
28

VIRTUAL METHOD LIST

30       The following is the list of builtin virtual methods and filters that
31       can be called on each type of data.
32
33       In Template::Alloy, the "|" operator can be used to call virtual
34       methods just the same way that the "." operator can.  The main
35       difference between the two is that on access to hashrefs or objects,
36       the "|" means to always call the virtual method or filter rather than
37       looking in the hashref for a key by that name, or trying to call that
38       method on the object.  This is similar to how TT3 will function.
39
40       Virtual methods are also made available via Virtual Objects which are
41       discussed in a later section.
42
43   SCALAR VIRTUAL METHODS AND FILTERS
44       The following is the list of builtin virtual methods and filters that
45       can be called on scalar data types.  In Alloy and TT3, filters and
46       virtual methods are more closely related than in TT2.  In general
47       anywhere a virtual method can be used a filter can be used also - and
48       likewise all scalar virtual methods can be used as filters.
49
50       In addition to the filters listed below, Alloy will automatically load
51       Template::Filters and use them if Template::Toolkit is installed.
52
53       In addition to the scalar virtual methods, any scalar will be
54       automatically converted to a single item list if a list virtual method
55       is called on it.
56
57       Scalar virtual methods are also available through the "Text" virtual
58       object (except for true filters such as eval and redirect).
59
60       All scalar virtual methods are available as top level functions as
61       well.  This is not true of TT2.  In Template::Alloy the following are
62       equivalent:
63
64           [% "abc".length %]
65           [% length("abc") %]
66
67       You may set VMETHOD_FUNCTIONS to 0 to disable this behavior.
68
69       '0'
70               [% item = 'foo' %][% item.0 %] Returns foo.
71
72           Allows for scalars to mask as arrays (scalars already will, but
73           this allows for more direct access).
74
75           Not available in TT.
76
77       abs
78               [% -1.abs %] Returns the absolute value
79
80       atan2
81               [% pi = 4 * 1.atan2(1) %]
82
83           Returns the arctangent.  The item itself represents Y, the passed
84           argument represents X.
85
86           Not available in TT - available in HTML::Template::Expr.
87
88       chunk
89               [% item.chunk(60).join("\n") %] Split string up into a list of chunks of text 60 chars wide.
90
91       collapse
92               [% item.collapse %] Strip leading and trailing whitespace and collapse all other space to one space.
93
94       cos
95               [% item.cos %] Returns the cosine of the item.
96
97           Not available in TT - available in HTML::Template::Expr.
98
99       defined
100               [% item.defined %] Always true - because the undef sub translates all undefs to ''.
101
102       eval
103               [% item.eval %]
104
105           Process the string as though it was a template.  This will start
106           the parsing engine and will use the same configuration as the
107           current process.  Alloy is several times faster at doing this than
108           TT is and is considered acceptable.
109
110           This is a filter and is not available via the Text virtual object.
111
112           Template::Alloy has attempted to make the compile process painless
113           and fast.  By default an MD5 sum of evaled is taken and used to
114           cache the AST.  This behavior can be disabled using the
115           CACHE_STR_REFS configuration item.
116
117           Template::Alloy also allows for named parameters to be passed to
118           the eval filter.
119
120               [% '[% 1 + 2 %]'.eval %]
121
122               [% '${ 1 + 2 }'.eval(interpolate => 1) %]
123
124               [% "#get( 1 + 2)"|eval(syntax => 'velocity') %]
125
126               [% '<TMPL_VAR EXPR="1 + 2">'.eval(syntax => 'hte') %]
127
128               [% '<TMPL_VAR EXPR="1 + 2">'.eval(syntax => 'hte') %]
129
130       evaltt
131               Same as the eval filter.
132
133       exp
134               [% 1.exp %] Something like 2.71828182845905
135
136           Returns "e" to the power of the item.
137
138       file
139               Same as the redirect filter.
140
141       fmt
142               [% item.fmt('%d') %]
143               [% item.fmt('%6s') %]
144               [% item.fmt('%*s', 6) %]
145
146           Similar to format.  Returns a string formatted with the passed
147           pattern.  Default pattern is %s.  Opposite from of the sprintf
148           vmethod.
149
150       format
151               [% item.format('%d') %]
152               [% item.format('%6s') %]
153               [% item.format('%*s', 6) %]
154
155           Print the string out in the specified format.  It is similar to the
156           "fmt" virtual method, except that the item is split on newline and
157           each line is processed separately.
158
159       hash
160               [% item.hash %] Returns a one item hash with a key of "value" and a value of the item.
161
162       hex
163               [% "FF".hex %]
164
165           Returns the decimal value of the passed hex numbers.  Note that you
166           may also just use [% 0xFF %].
167
168           Not available in TT - available in HTML::Template::Expr.
169
170       html
171               [% item.html %] Performs a very basic html encoding (swaps out &, <, >, ' and " with the corresponding html entities)
172
173       indent
174               [% item.indent(3) %] Indent by that number of spaces if an integer is passed (default is 4).
175
176               [% item.indent("Foo: ") %] Add the string "Foo: " to the beginning of every line.
177
178       int
179               [% item.int %] Return the integer portion of the value (0 if none).
180
181       lc  Same as the lower vmethod.  Returns the lowercased version of the
182           item.
183
184       lcfirst
185               [% item.lcfirst %] Lowercase the leading letter.
186
187       length
188               [% item.length %] Return the length of the string.
189
190       list
191               [% item.list %] Returns a list (arrayref) with a single value of the item.
192
193       log
194               [% 8.exp.log %] Equal to 8.
195
196           Returns the natural log base "e" of the item.
197
198           Not available in TT - available in HTML::Template::Expr.
199
200       lower
201               [% item.lower %] Return the string lowercased.
202
203       match
204               [% item.match("(\w+) (\w+)") %] Return a list of items matching the pattern.
205
206               [% item.match("(\w+) (\w+)", 1) %] Same as before - but match globally.
207
208           In Template::Alloy and TT3 you can use regular expressions notation
209           as well.
210
211               [% item.match( /(\w+) (\w+)/ ) %] Same as before.
212
213               [% item.match( m{(\w+) (\w+)} ) %] Same as before.
214
215           Note that you can't use the 'g' regex modifier - you must pass the
216           second argument to turn on global match.
217
218       null
219               [% item.null %] Return nonthing.
220
221           If the item contains a coderef it will still be executed, but the
222           result would be ignored.
223
224       oct
225               [% "377".oct %]
226
227           Returns the decimal value of the octal string.  On recent versions
228           of perl you may also pass numbers starting with 0x which will be
229           interpreted as hexidecimal, and starting with 0b which will be
230           interpreted as binary.
231
232           Not available in TT - available in HTML::Template::Expr.
233
234       rand
235               [% item = 10; item.rand %] Returns a number greater or equal to 0 but less than 10.
236               [% 1.rand %]
237
238           Note: This filter is not available as of TT2.15.
239
240       remove
241               [% item.remove("\s+") %] Same as replace - but is global and replaces with nothing.
242
243       redirect
244               [% item.redirect("output_file.html") %]
245
246           Writes the contents out to the specified file.  The filename must
247           be relative to the OUTPUT_PATH configuration variable and the
248           OUTPUT_PATH variable must be set.
249
250           This is a filter and is not available via the Text virtual object.
251
252       repeat
253               [% item.repeat(3) %] Repeat the item 3 times
254
255               [% item.repeat(3, ' | ') %] Repeat the item 3 times separated with ' | '
256
257       replace
258               [% item.replace("\s+", "&nbsp;") %] Globally replace all space with &nbsp;
259
260               [% item.replace("foo", "bar", 0) %] Replace only the first instance of foo with bar.
261
262               [% item.replace("(\w+)", "($1)") %] Surround all words with parenthesis.
263
264           In Template::Alloy and TT3 you may also use normal regular
265           expression notation.
266
267               [% item.replace(/(\w+)/, "($1)") %] Same as before.
268
269           Note that you can't use the 'g' regex modifier - global match is on
270           by default.  You must pass the third argument of false to turn off
271           global match.
272
273       return
274           Returns the item from the inner most block, macro, or file.
275           Similar to the RETURN directive.
276
277               [% item.return %]
278               [% RETURN item %]
279
280       search
281               [% item.search("(\w+)") %] Tests if the given pattern is in the string.
282
283           In Template::Alloy and TT3 you may also use normal regular
284           expression notation.
285
286               [% item.search(/(\w+)/) %] Same as before.
287
288       sin
289               [% item.sin %] Returns the sine of the item.
290
291       size
292               [% item.size %] Always returns 1.
293
294       split
295               [% item.split %] Returns an arrayref from the item split on " "
296
297               [% item.split("\s+") %] Returns an arrayref from the item split on /\s+/
298
299               [% item.split("\s+", 3) %] Returns an arrayref from the item split on /\s+/ splitting until 3 elements are found.
300
301           In Template::Alloy and TT3 you may also use normal regular
302           expression notation.
303
304               [% item.split( /\s+/, 3 ) %] Same as before.
305
306       sprintf
307               [% item = "%d %d" %]
308               [% item.sprintf(7, 8) %]
309
310           Uses the pattern stored in self, and passes it to sprintf with the
311           passed arguments.  Opposite from the fmt vmethod.
312
313       sqrt
314               [% item.sqrt %]
315
316           Returns the square root of the number.
317
318       srand
319           Calls the perl srand function to set the interal random seed.  This
320           will affect future calls to the rand vmethod.
321
322       stderr
323               [% item.stderr %] Print the item to the current STDERR handle.
324
325       substr
326               [% item.substr(i) %] Returns a substring of item starting at i and going to the end of the string.
327
328               [% item.substr(i, n) %] Returns a substring of item starting at i and going n characters.
329
330       trim
331               [% item.trim %] Strips leading and trailing whitespace.
332
333       uc  Same as the upper command.  Returns uppercased string.
334
335       ucfirst
336               [% item.ucfirst %] Uppercase the leading letter.
337
338       upper
339               [% item.upper %] Return the string uppercased.
340
341       uri
342               [% item.uri %] Perform a very basic URI encoding.
343
344       url
345               [% item.url %] Perform a URI encoding - but some characters such
346                              as : and / are left intact.
347
348   LIST VIRTUAL METHODS
349       The following methods can be called on an arrayref type data structures
350       (scalar types will automatically promote to a single element list and
351       call these methods if needed):
352
353       Additionally, list virtual methods can be accessed via the List Virtual
354       Object.
355
356       fmt
357               [% mylist.fmt('%s', ', ') %]
358               [% mylist.fmt('%6s', ', ') %]
359               [% mylist.fmt('%*s', ', ', 6) %]
360
361           Passed a pattern and an string to join on.  Returns a string of the
362           values of the list formatted with the passed pattern and joined
363           with the passed string.  Default pattern is %s and the default join
364           string is a space.
365
366       first
367               [% mylist.first(3) %]  Returns a list of the first 3 items in the list.
368
369       grep
370               [% mylist.grep("^\w+\.\w+$") %] Returns a list of all items matching the pattern.
371
372           In Template::Alloy and TT3 you may also use normal regular
373           expression notation.
374
375               [% mylist.grep(/^\w+\.\w+$/) %] Same as before.
376
377               [% mylist.grep(->(a){ a.foo.bar }
378
379       hash
380               [% mylist.hash %] Returns a hashref with the array indexes as keys and the values as values.
381
382       join
383               [% mylist.join %] Joins on space.
384               [% mylist.join(", ") Joins on the passed argument.
385
386       last
387               [% mylist.last(3) %]  Returns a list of the last 3 items in the list.
388
389       list
390               [% mylist.list %] Returns a reference to the list.
391
392       map (Not in TT2)
393               [% mylist.map(->{ this.upper }) %] Returns a list with the macro played on each item.
394               [% mylist.map(->(a){ a.upper }) %] Same thing
395
396           The RETURN directive or return list, item, and hash vmethods allow
397           for returning more interesing items.
398
399               [% [1..3].map(->(a){ [1..a].return }) %]
400
401       max
402               [% mylist.max %] Returns the last item in the array.
403
404       merge
405               [% mylist.merge(list2) %] Returns a new list with all defined items from list2 added.
406
407       nsort
408               [% mylist.nsort %] Returns the numerically sorted items of the list.  If the items are
409               hashrefs, a key containing the field to sort on can be passed.
410
411       pop
412               [% mylist.pop %] Removes and returns the last element from the arrayref (the stash is modified).
413
414       push
415               [% mylist.push(23) %] Adds an element to the end of the arrayref (the stash is modified).
416
417       pick
418               [% mylist.pick %] Returns a random item from the list.
419               [% ['a' .. 'z'].pick %]
420
421           An additional numeric argument is how many items to return.
422
423               [% ['a' .. 'z'].pick(8).join('') %]
424
425           Note: This filter is not available as of TT2.15.
426
427       return
428           Returns the list from the inner most block, macro, or file.
429           Similar to the RETURN directive.
430
431               [% mylist.return %]
432               [% RETURN mylist %]
433
434       reverse
435               [% mylist.reverse %] Returns the list in reverse order.
436
437       shift
438               [% mylist.shift %] Removes and returns the first element of the arrayref (the stash is modified).
439
440       size
441               [% mylist.size %] Returns the number of elements in the array.
442
443       slice
444               [% mylist.slice(i, n) %] Returns a list from the arrayref beginning at index i and continuing for n items.
445
446       sort
447               [% mylist.sort %] Returns the alphabetically sorted items of the list.  If the items are
448               hashrefs, a key containing the field to sort on can be passed.
449
450       splice
451               [% mylist.splice(i, n) %] Removes items from array beginning at i and continuing for n items.
452
453               [% mylist.splice(i, n, list2) %] Same as before, but replaces removed items with the items
454               from list2.
455
456       unique
457               [% mylist.unique %] Return a list of the unique items in the array.
458
459       unshift
460               [% mylist.unshift(23) %] Adds an item to the beginning of the arrayref.
461
462   HASH VIRTUAL METHODS
463       The following methods can be called on hash type data structures:
464
465       Additionally, list virtual methods can be accessed via the Hash Virtual
466       Object.
467
468       fmt
469               [% myhash.fmt('%s => %s', "\n") %]
470               [% myhash.fmt('%4s => %5s', "\n") %]
471               [% myhash.fmt('%*s => %*s', "\n", 4, 5) %]
472
473           Passed a pattern and an string to join on.  Returns a string of the
474           key/value pairs of the hash formatted with the passed pattern and
475           joined with the passed string.  Default pattern is "%s\t%s" and the
476           default join string is a newline.
477
478       defined
479               [% myhash.defined('a') %]  Checks if a is defined in the hash.
480
481       delete
482               [% myhash.delete('a') %]  Deletes the item from the hash.
483
484           Unlink Perl the value is not returned.  Multiple values may be
485           passed and represent the keys to be deleted.
486
487       each
488               [% myhash.each.join(", ") %]  Turns the contents of the hash into a list - subject
489               to change as TT is changing the operations of each and list.
490
491       exists
492               [% myhash.exists('a') %]  Checks if a is in the hash.
493
494       hash
495               [% myhash.hash %]  Returns a reference to the hash.
496
497       import
498               [% myhash.import(hash2) %]  Overlays the keys of hash2 over the keys of myhash.
499
500       item
501               [% myhash.item(key) %] Returns the hashes value for that key.
502
503       items
504               [% myhash.items %] Returns a list of the key and values (flattened hash)
505
506       keys
507               [% myhash.keys.join(', ') %] Returns an arrayref of the keys of the hash.
508
509       list
510               [% myhash.list %] Returns an arrayref with the hash as a single value (subject to change).
511
512       pairs
513               [% myhash.pairs %] Returns an arrayref of hashrefs where each hash contains {key => $key, value => $value}
514               for each value of the hash.
515
516       nsort
517               [% myhash.nsort.join(", ") %] Returns a list of keys numerically sorted by the values.
518
519       return
520           Returns the hash from the inner most block, macro, or file.
521           Similar to the RETURN directive.
522
523               [% myhash.return %]
524               [% RETURN myhash %]
525
526       size
527               [% myhash.size %] Returns the number of key/value pairs in the hash.
528
529       sort
530               [% myhash.sort.join(", ") Returns a list of keys alphabetically sorted by the values.
531
532       values
533               [% myhash.values.join(', ') %] Returns an arrayref of the values of the hash.
534

VIRTUAL OBJECTS

536       TT3 has a concept of Text, List, and Hash virtual objects which provide
537       direct access to the scalar, list, and hash virtual methods.  In the
538       TT3 engine this will allow for more concise generated code.  Because
539       Alloy does not generated perl code to be executed later, Alloy provides
540       for these virtual objects but does so as more of a namespace (using the
541       methods does not provide a speed optimization in your template - just
542       may help clarify things).
543
544           [% a = "foo"; a.length %] => 3
545
546           [% a = "foo"; Text.length(a) %] => 3
547
548           [% a = Text.new("foo"); a.length %] => 3
549
550
551           [% a = [1 .. 30]; a.size %] => 30
552
553           [% a = [1 .. 30]; List.size(a) %] => 30
554
555           [% a = List.new(1 .. 30); a.size %] => 30
556
557
558           [% a = {a => 1, b => 2}; a.size %] => 2
559
560           [% a = {a => 1, b => 2}; Hash.size(a) %] => 2
561
562           [% a = Hash.new({a => 1, b => 2}); a.size %] => 2
563
564           [% a = Hash.new(a => 1, b => 2); a.size %] => 2
565
566           [% a = Hash.new(a = 1, b = 2); a.size %] => 2
567
568           [% a = Hash.new('a', 1, 'b', 2); a.size %] => 2
569
570       One limitation is that if you pass a key named "Text", "List", or
571       "Hash" in your variable stash - the corresponding virtual object will
572       be hidden.
573
574       Additionally, you can use all of the Virtual object methods with the
575       pipe operator.
576
577           [% {a => 1, b => 2}
578              | Hash.keys
579              | List.join(", ") %] => a, b
580
581       Again, there aren't any speed optimizations to using the virtual
582       objects in Alloy, but it can help clarify the intent in some cases.
583
584       Note: these aren't really objects.  All of the "virtual objects" are
585       references to the $SCALAR_OPS, $LIST_OPS, and $HASH_OPS hashes found in
586       the $VOBJS hash of Template::Alloy.
587

AUTHOR

589       Paul Seamons <perl at seamons dot com>
590

LICENSE

592       This module may be distributed under the same terms as Perl itself.
593

POD ERRORS

595       Hey! The above document had some coding errors, which are explained
596       below:
597
598       Around line 427:
599           You forgot a '=back' before '=head1'
600
601       Around line 933:
602           =back doesn't take any parameters, but you said =back 4
603
604
605
606perl v5.12.0                      2008-04-10       Template::Alloy::VMethod(3)