1Template::Alloy::VMethoUds(e3r)Contributed Perl DocumentTaetmipolnate::Alloy::VMethod(3)
2
6 Template::Alloy::VMethod - VMethod role.
7
9 The Template::Alloy::VMethod role provides all of the extra vmethods,
10 filters, and virtual objects that add to the base feature set 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
17 define_vmethod
18 Defines a vmethod. See Template::Alloy for more details.
19 "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 "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
30 The following is the list of builtin virtual methods and filters that
31 can be called on each type of data.
32 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 Virtual methods are also made available via Virtual Objects which are
41 discussed in a later section.
42 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 In addition to the filters listed below, Alloy will automatically load
51 Template::Filters and use them if Template::Toolkit is installed.
52 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 Scalar virtual methods are also available through the "Text" virtual
58 object (except for true filters such as eval and redirect).
59 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 [% "abc".length %]
65 [% length("abc") %]
66 You may set VMETHOD_FUNCTIONS to 0 to disable this behavior.
68 '0'
70 [% item = 'foo' %][% item.0 %] Returns foo.
71 Allows for scalars to mask as arrays (scalars already will, but
73 this allows for more direct access).
74 Not available in TT.
76 abs
78 [% -1.abs %] Returns the absolute value
79 atan2
81 [% pi = 4 * 1.atan2(1) %]
82 Returns the arctangent. The item itself represents Y, the passed
84 argument represents X.
85 Not available in TT - available in HTML::Template::Expr.
87 chunk
89 [% item.chunk(60).join("\n") %] Split string up into a list of chunks of text 60 chars wide.
90 collapse
92 [% item.collapse %] Strip leading and trailing whitespace and collapse all other space to one space.
93 cos
95 [% item.cos %] Returns the cosine of the item.
96 Not available in TT - available in HTML::Template::Expr.
98 defined
100 [% item.defined %] Always true - because the undef sub translates all undefs to ''.
101 eval
103 [% item.eval %]
104 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 This is a filter and is not available via the Text virtual object.
111 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 Template::Alloy also allows for named parameters to be passed to
118 the eval filter.
119 [% '[% 1 + 2 %]'.eval %]
121 [% '${ 1 + 2 }'.eval(interpolate => 1) %]
123 [% "#get( 1 + 2)"|eval(syntax => 'velocity') %]
125 [% '<TMPL_VAR EXPR="1 + 2">'.eval(syntax => 'hte') %]
127 [% '<TMPL_VAR EXPR="1 + 2">'.eval(syntax => 'hte') %]
129 evaltt
131 Same as the eval filter.
132 exp
134 [% 1.exp %] Something like 2.71828182845905
135 Returns "e" to the power of the item.
137 file
139 Same as the redirect filter.
140 fmt
142 [% item.fmt('%d') %]
143 [% item.fmt('%6s') %]
144 [% item.fmt('%*s', 6) %]
145 Similar to format. Returns a string formatted with the passed
147 pattern. Default pattern is %s. Opposite from of the sprintf
148 vmethod.
149 format
151 [% item.format('%d') %]
152 [% item.format('%6s') %]
153 [% item.format('%*s', 6) %]
154 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 hash
160 [% item.hash %] Returns a one item hash with a key of "value" and a value of the item.
161 hex
163 [% "FF".hex %]
164 Returns the decimal value of the passed hex numbers. Note that you
166 may also just use [% 0xFF %].
167 Not available in TT - available in HTML::Template::Expr.
169 html
171 [% item.html %] Performs a very basic html encoding (swaps out &, <, > and " with the corresponding html entities)
172 Previously it also encoded the ' but this behavior did not match TT2's behavior. Use .xml to obtain that behavior.
173 indent
175 [% item.indent(3) %] Indent by that number of spaces if an integer is passed (default is 4).
176 [% item.indent("Foo: ") %] Add the string "Foo: " to the beginning of every line.
178 int
180 [% item.int %] Return the integer portion of the value (0 if none).
181 json
183 [% item.json %] Returns a JSON encoded representation.
184 [% item.json(1) %] Returns a pretty JSON encoded representation.
185 lc Same as the lower vmethod. Returns the lowercased version of the
187 item.
188 lcfirst
190 [% item.lcfirst %] Lowercase the leading letter.
191 length
193 [% item.length %] Return the length of the string.
194 list
196 [% item.list %] Returns a list (arrayref) with a single value of the item.
197 log
199 [% 8.exp.log %] Equal to 8.
200 Returns the natural log base "e" of the item.
202 Not available in TT - available in HTML::Template::Expr.
204 lower
206 [% item.lower %] Return the string lowercased.
207 match
209 [% item.match("(\w+) (\w+)") %] Return a list of items matching the pattern.
210 [% item.match("(\w+) (\w+)", 1) %] Same as before - but match globally.
212 In Template::Alloy and TT3 you can use regular expressions notation
214 as well.
215 [% item.match( /(\w+) (\w+)/ ) %] Same as before.
217 [% item.match( m{(\w+) (\w+)} ) %] Same as before.
219 Note that you can't use the 'g' regex modifier - you must pass the
221 second argument to turn on global match.
222 none
224 Returns the item without modification. This was added as a
225 compliment case when the AUTO_FILTER configuration is specified.
226 Note that it must be called as a filter to bypass the application
227 of the AUTO_FILTER.
228 [% item | none %] Returns the item without modification.
230 null
232 [% item.null %] Return nothing.
233 If the item contains a coderef it will still be executed, but the
235 result would be ignored.
236 oct
238 [% "377".oct %]
239 Returns the decimal value of the octal string. On recent versions
241 of perl you may also pass numbers starting with 0x which will be
242 interpreted as hexadecimal, and starting with 0b which will be
243 interpreted as binary.
244 Not available in TT - available in HTML::Template::Expr.
246 rand
248 [% item = 10; item.rand %] Returns a number greater or equal to 0 but less than 10.
249 [% 1.rand %]
250 Note: This filter is not available as of TT2.15.
252 remove
254 [% item.remove("\s+") %] Same as replace - but is global and replaces with nothing.
255 redirect
257 [% item.redirect("output_file.html") %]
258 Writes the contents out to the specified file. The filename must
260 be relative to the OUTPUT_PATH configuration variable and the
261 OUTPUT_PATH variable must be set.
262 This is a filter and is not available via the Text virtual object.
264 repeat
266 [% item.repeat(3) %] Repeat the item 3 times
267 [% item.repeat(3, ' | ') %] Repeat the item 3 times separated with ' | '
269 replace
271 [% item.replace("\s+", " ") %] Globally replace all space with
272 [% item.replace("foo", "bar", 0) %] Replace only the first instance of foo with bar.
274 [% item.replace("(\w+)", "($1)") %] Surround all words with parenthesis.
276 In Template::Alloy and TT3 you may also use normal regular
278 expression notation.
279 [% item.replace(/(\w+)/, "($1)") %] Same as before.
281 Note that you can't use the 'g' regex modifier - global match is on
283 by default. You must pass the third argument of false to turn off
284 global match.
285 return
287 Returns the item from the inner most block, macro, or file.
288 Similar to the RETURN directive.
289 [% item.return %]
291 [% RETURN item %]
292 search
294 [% item.search("(\w+)") %] Tests if the given pattern is in the string.
295 In Template::Alloy and TT3 you may also use normal regular
297 expression notation.
298 [% item.search(/(\w+)/) %] Same as before.
300 sin
302 [% item.sin %] Returns the sine of the item.
303 size
305 [% item.size %] Always returns 1.
306 split
308 [% item.split %] Returns an arrayref from the item split on " "
309 [% item.split("\s+") %] Returns an arrayref from the item split on /\s+/
311 [% item.split("\s+", 3) %] Returns an arrayref from the item split on /\s+/ splitting until 3 elements are found.
313 In Template::Alloy and TT3 you may also use normal regular
315 expression notation.
316 [% item.split( /\s+/, 3 ) %] Same as before.
318 sprintf
320 [% item = "%d %d" %]
321 [% item.sprintf(7, 8) %]
322 Uses the pattern stored in self, and passes it to sprintf with the
324 passed arguments. Opposite from the fmt vmethod.
325 sqrt
327 [% item.sqrt %]
328 Returns the square root of the number.
330 srand
332 Calls the perl srand function to set the internal random seed.
333 This will affect future calls to the rand vmethod.
334 stderr
336 [% item.stderr %] Print the item to the current STDERR handle.
337 substr
339 [% item.substr(i) %] Returns a substring of item starting at i and going to the end of the string.
340 [% item.substr(i, n) %] Returns a substring of item starting at i and going n characters.
342 trim
344 [% item.trim %] Strips leading and trailing whitespace.
345 uc Same as the upper command. Returns uppercased string.
347 ucfirst
349 [% item.ucfirst %] Uppercase the leading letter.
350 upper
352 [% item.upper %] Return the string uppercased.
353 uri
355 [% item.uri %] Perform a very basic URI encoding.
356 url
358 [% item.url %] Perform a URI encoding - but some characters such
359 as : and / are left intact.
360 xml
362 [% item.xml %] Performs a very basic xml encoding (swaps out &, <, >, ' and " with the corresponding xml entities)
363 LIST VIRTUAL METHODS
365 The following methods can be called on an arrayref type data structures
366 (scalar types will automatically promote to a single element list and
367 call these methods if needed):
368 Additionally, list virtual methods can be accessed via the List Virtual
370 Object.
371 fmt
373 [% mylist.fmt('%s', ', ') %]
374 [% mylist.fmt('%6s', ', ') %]
375 [% mylist.fmt('%*s', ', ', 6) %]
376 Passed a pattern and an string to join on. Returns a string of the
378 values of the list formatted with the passed pattern and joined
379 with the passed string. Default pattern is %s and the default join
380 string is a space.
381 first
383 [% mylist.first(3) %] Returns a list of the first 3 items in the list.
384 grep
386 [% mylist.grep("^\w+\.\w+$") %] Returns a list of all items matching the pattern.
387 In Template::Alloy and TT3 you may also use normal regular
389 expression notation.
390 [% mylist.grep(/^\w+\.\w+$/) %] Same as before.
392 [% mylist.grep(->(a){ a.foo.bar }
394 hash
396 [% mylist.hash %] Returns a hashref with the array indexes as keys and the values as values.
397 join
399 [% mylist.join %] Joins on space.
400 [% mylist.join(", ") Joins on the passed argument.
401 json
403 [% mylist.json %] Returns a JSON encoded representation.
404 [% mylist.json(1) %] Returns a pretty JSON encoded representation.
405 last
407 [% mylist.last(3) %] Returns a list of the last 3 items in the list.
408 list
410 [% mylist.list %] Returns a reference to the list.
411 map (Not in TT2)
413 [% mylist.map(->{ this.upper }) %] Returns a list with the macro played on each item.
414 [% mylist.map(->(a){ a.upper }) %] Same thing
415 The RETURN directive or return list, item, and hash vmethods allow
417 for returning more interesting items.
418 [% [1..3].map(->(a){ [1..a].return }) %]
420 max
422 [% mylist.max %] Returns the last item in the array.
423 merge
425 [% mylist.merge(list2) %] Returns a new list with all defined items from list2 added.
426 nsort
428 [% mylist.nsort %] Returns the numerically sorted items of the list. If the items are
429 hashrefs, a key containing the field to sort on can be passed.
430 pop
432 [% mylist.pop %] Removes and returns the last element from the arrayref (the stash is modified).
433 push
435 [% mylist.push(23) %] Adds an element to the end of the arrayref (the stash is modified).
436 pick
438 [% mylist.pick %] Returns a random item from the list.
439 [% ['a' .. 'z'].pick %]
440 An additional numeric argument is how many items to return.
442 [% ['a' .. 'z'].pick(8).join('') %]
444 Note: This filter is not available as of TT2.15.
446 return
448 Returns the list from the inner most block, macro, or file.
449 Similar to the RETURN directive.
450 [% mylist.return %]
452 [% RETURN mylist %]
453 reverse
455 [% mylist.reverse %] Returns the list in reverse order.
456 shift
458 [% mylist.shift %] Removes and returns the first element of the arrayref (the stash is modified).
459 size
461 [% mylist.size %] Returns the number of elements in the array.
462 slice
464 [% mylist.slice(i, n) %] Returns a list from the arrayref beginning at index i and continuing for n items.
465 sort
467 [% mylist.sort %] Returns the alphabetically sorted items of the list. If the items are
468 hashrefs, a key containing the field to sort on can be passed.
469 splice
471 [% mylist.splice(i, n) %] Removes items from array beginning at i and continuing for n items.
472 [% mylist.splice(i, n, list2) %] Same as before, but replaces removed items with the items
474 from list2.
475 unique
477 [% mylist.unique %] Return a list of the unique items in the array.
478 unshift
480 [% mylist.unshift(23) %] Adds an item to the beginning of the arrayref.
481 HASH VIRTUAL METHODS
483 The following methods can be called on hash type data structures:
484 Additionally, list virtual methods can be accessed via the Hash Virtual
486 Object.
487 fmt
489 [% myhash.fmt('%s => %s', "\n") %]
490 [% myhash.fmt('%4s => %5s', "\n") %]
491 [% myhash.fmt('%*s => %*s', "\n", 4, 5) %]
492 Passed a pattern and an string to join on. Returns a string of the
494 key/value pairs of the hash formatted with the passed pattern and
495 joined with the passed string. Default pattern is "%s\t%s" and the
496 default join string is a newline.
497 defined
499 [% myhash.defined('a') %] Checks if a is defined in the hash.
500 delete
502 [% myhash.delete('a') %] Deletes the item from the hash.
503 Unlink Perl the value is not returned. Multiple values may be
505 passed and represent the keys to be deleted.
506 each
508 [% myhash.each.join(", ") %] Turns the contents of the hash into a list - subject
509 to change as TT is changing the operations of each and list.
510 exists
512 [% myhash.exists('a') %] Checks if a is in the hash.
513 hash
515 [% myhash.hash %] Returns a reference to the hash.
516 import
518 [% myhash.import(hash2) %] Overlays the keys of hash2 over the keys of myhash.
519 item
521 [% myhash.item(key) %] Returns the hashes value for that key.
522 items
524 [% myhash.items %] Returns a list of the key and values (flattened hash)
525 json
527 [% myhash.json %] Returns a JSON encoded representation.
528 [% myhash.json(1) %] Returns a pretty JSON encoded representation.
529 keys
531 [% myhash.keys.join(', ') %] Returns an arrayref of the keys of the hash.
532 list
534 [% myhash.list %] Returns an arrayref with the hash as a single value (subject to change).
535 pairs
537 [% myhash.pairs %] Returns an arrayref of hashrefs where each hash contains {key => $key, value => $value}
538 for each value of the hash.
539 nsort
541 [% myhash.nsort.join(", ") %] Returns a list of keys numerically sorted by the values.
542 return
544 Returns the hash from the inner most block, macro, or file.
545 Similar to the RETURN directive.
546 [% myhash.return %]
548 [% RETURN myhash %]
549 size
551 [% myhash.size %] Returns the number of key/value pairs in the hash.
552 sort
554 [% myhash.sort.join(", ") Returns a list of keys alphabetically sorted by the values.
555 values
557 [% myhash.values.join(', ') %] Returns an arrayref of the values of the hash.
558
560 TT3 has a concept of Text, List, and Hash virtual objects which provide
561 direct access to the scalar, list, and hash virtual methods. In the
562 TT3 engine this will allow for more concise generated code. Because
563 Alloy does not generated perl code to be executed later, Alloy provides
564 for these virtual objects but does so as more of a namespace (using the
565 methods does not provide a speed optimization in your template - just
566 may help clarify things).
567 [% a = "foo"; a.length %] => 3
569 [% a = "foo"; Text.length(a) %] => 3
571 [% a = Text.new("foo"); a.length %] => 3
573 [% a = [1 .. 30]; a.size %] => 30
576 [% a = [1 .. 30]; List.size(a) %] => 30
578 [% a = List.new(1 .. 30); a.size %] => 30
580 [% a = {a => 1, b => 2}; a.size %] => 2
583 [% a = {a => 1, b => 2}; Hash.size(a) %] => 2
585 [% a = Hash.new({a => 1, b => 2}); a.size %] => 2
587 [% a = Hash.new(a => 1, b => 2); a.size %] => 2
589 [% a = Hash.new(a = 1, b = 2); a.size %] => 2
591 [% a = Hash.new('a', 1, 'b', 2); a.size %] => 2
593 One limitation is that if you pass a key named "Text", "List", or
595 "Hash" in your variable stash - the corresponding virtual object will
596 be hidden.
597 Additionally, you can use all of the Virtual object methods with the
599 pipe operator.
600 [% {a => 1, b => 2}
602 | Hash.keys
603 | List.join(", ") %] => a, b
604 Again, there aren't any speed optimizations to using the virtual
606 objects in Alloy, but it can help clarify the intent in some cases.
607 Note: these aren't really objects. All of the "virtual objects" are
609 references to the $SCALAR_OPS, $LIST_OPS, and $HASH_OPS hashes found in
610 the $VOBJS hash of Template::Alloy.
611
613 Paul Seamons <paul@seamons.com>
614
616 This module may be distributed under the same terms as Perl itself.
617perl v5.32.1 2021-03-23 Template::Alloy::VMethod(3)