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 featureset of Tem‐
11 plate::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 com‐
22 plex than oneliners. These methods are not exposed via the role.
23 "filter_*"
25 Methods by these names implement filters that are more complex than
26 one liners. These methods are not exposed via the role.
27
29 The following is the list of builtin virtual methods and filters that
30 can be called on each type of data.
31 In Template::Alloy, the "⎪" operator can be used to call virtual meth‐
33 ods just the same way that the "." operator can. The main difference
34 between the two is that on access to hashrefs or objects, the "⎪" means
35 to always call the virtual method or filter rather than looking in the
36 hashref for a key by that name, or trying to call that method on the
37 object. This is similar to how TT3 will function.
38 Virtual methods are also made available via Virtual Objects which are
40 discussed in a later section.
41 SCALAR VIRTUAL METHODS AND FILTERS
43 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 vir‐
46 tual methods are more closely related than in TT2. In general anywhere
47 a virtual method can be used a filter can be used also - and likewise
48 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 automati‐
54 cally converted to a single item list if a list virtual method is
55 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
84 passed 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
106 start the parsing engine and will use the same configuration as
107 the current process. Alloy is several times faster at doing
108 this than TT is and is considered acceptable.
109 This is a filter and is not available via the Text virtual
111 object.
112 Template::Alloy has attempted to make the compile process pain‐
114 less and fast. By default an MD5 sum of evaled is taken and
115 used to cache the AST. This behavior can be disabled using the
116 CACHE_STR_REFS configuration item.
117 Template::Alloy also allows for named parameters to be passed
119 to the eval filter.
120 [% '[% 1 + 2 %]'.eval %]
122 [% '${ 1 + 2 }'.eval(interpolate => 1) %]
124 [% "#get( 1 + 2)"⎪eval(syntax => 'velocity') %]
126 [% '<TMPL_VAR EXPR="1 + 2">'.eval(syntax => 'hte') %]
128 [% '<TMPL_VAR EXPR="1 + 2">'.eval(syntax => 'hte') %]
130 evaltt
132 Same as the eval filter.
133 exp
135 [% 1.exp %] Something like 2.71828182845905
136 Returns "e" to the power of the item.
138 file
140 Same as the redirect filter.
141 fmt
143 [% item.fmt('%d') %]
144 [% item.fmt('%6s') %]
145 [% item.fmt('%*s', 6) %]
146 Similar to format. Returns a string formatted with the passed
148 pattern. Default pattern is %s. Opposite from of the sprintf
149 vmethod.
150 format
152 [% item.format('%d') %]
153 [% item.format('%6s') %]
154 [% item.format('%*s', 6) %]
155 Print the string out in the specified format. It is similar to
157 the "fmt" virtual method, except that the item is split on new‐
158 line and each line is processed separately.
159 hash
161 [% item.hash %] Returns a one item hash with a key of "value" and a value of the item.
162 hex
164 [% "FF".hex %]
165 Returns the decimal value of the passed hex numbers. Note that
167 you may also just use [% 0xFF %].
168 Not available in TT - available in HTML::Template::Expr.
170 html
172 [% item.html %] Performs a very basic html encoding (swaps out &, <, > and " for the html entities)
173 indent
175 [% item.indent(3) %] Indent that number of spaces.
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 lc Same as the lower vmethod. Returns the lower cased version of
183 the item.
184 lcfirst
186 [% item.lcfirst %] Capitalize the leading letter.
187 length
189 [% item.length %] Return the length of the string.
190 list
192 [% item.list %] Returns a list with a single value of the item.
193 log
195 [% 8.exp.log %] Equal to 8.
196 Returns the natural log base "e" of the item.
198 Not available in TT - available in HTML::Template::Expr.
200 lower
202 [% item.lower %] Return a lower-casified string.
203 match
205 [% item.match("(\w+) (\w+)") %] Return a list of items matching the pattern.
206 [% item.match("(\w+) (\w+)", 1) %] Same as before - but match globally.
208 In Template::Alloy and TT3 you can use regular expressions
210 notation as well.
211 [% item.match( /(\w+) (\w+)/ ) %] Same as before.
213 [% item.match( m{(\w+) (\w+)} ) %] Same as before.
215 null
217 [% item.null %] Do nothing.
218 oct
220 [% "377".oct %]
221 Returns the decimal value of the octal string. On recent ver‐
223 sions of perl you may also pass numbers starting with 0x which
224 will be interpreted as hexidecimal, and starting with 0b which
225 will be interpreted as binary.
226 Not available in TT - available in HTML::Template::Expr.
228 rand
230 [% item = 10; item.rand %] Returns a number greater or equal to 0 but less than 10.
231 [% 1.rand %]
232 Note: This filter is not available as of TT2.15.
234 remove
236 [% item.remove("\s+") %] Same as replace - but is global and replaces with nothing.
237 redirect
239 [% item.redirect("output_file.html") %]
240 Writes the contents out to the specified file. The filename
242 must be relative to the OUTPUT_PATH configuration variable and
243 the OUTPUT_PATH variable must be set.
244 This is a filter and is not available via the Text virtual
246 object.
247 repeat
249 [% item.repeat(3) %] Repeat the item 3 times
250 [% item.repeat(3, ' ⎪ ') %] Repeat the item 3 times separated with ' ⎪ '
252 replace
254 [% item.replace("\s+", " ") %] Globally replace all space with
255 [% item.replace("foo", "bar", 0) %] Replace only the first instance of foo with bar.
257 [% item.replace("(\w+)", "($1)") %] Surround all words with parenthesis.
259 In Template::Alloy and TT3 you may also use normal regular
261 expression notation.
262 [% item.replace(/(\w+)/, "($1)") %] Same as before.
264 search
266 [% item.search("(\w+)") %] Tests if the given pattern is in the string.
267 In Template::Alloy and TT3 you may also use normal regular
269 expression notation.
270 [% item.search(/(\w+)/, "($1)") %] Same as before.
272 sin
274 [% item.sin %] Returns the sine of the item.
275 size
277 [% item.size %] Always returns 1.
278 split
280 [% item.split %] Returns an arrayref from the item split on " "
281 [% item.split("\s+") %] Returns an arrayref from the item split on /\s+/
283 [% item.split("\s+", 3) %] Returns an arrayref from the item split on /\s+/ splitting until 3 elements are found.
285 In Template::Alloy and TT3 you may also use normal regular
287 expression notation.
288 [% item.split( /\s+/, 3 ) %] Same as before.
290 sprintf
292 [% item = "%d %d" %]
293 [% item.sprintf(7, 8) %]
294 Uses the pattern stored in self, and passes it to sprintf with
296 the passed arguments. Opposite from the fmt vmethod.
297 sqrt
299 [% item.sqrt %]
300 Returns the square root of the number.
302 srand
304 Calls the perl srand function to set the interal random seed.
305 This will affect future calls to the rand vmethod.
306 stderr
308 [% item.stderr %] Print the item to the current STDERR handle.
309 substr
311 [% item.substr(i) %] Returns a substring of item starting at i and going to the end of the string.
312 [% item.substr(i, n) %] Returns a substring of item starting at i and going n characters.
314 trim
316 [% item.trim %] Strips leading and trailing whitespace.
317 uc Same as the upper command. Returns upper cased string.
319 ucfirst
321 [% item.ucfirst %] Lower-case the leading letter.
322 upper
324 [% item.upper %] Return a upper cased string.
325 uri
327 [% item.uri %] Perform a very basic URI encoding.
328 url
330 [% item.url %] Perform a URI encoding - but some characters such
331 as : and / are left intact.
332 LIST VIRTUAL METHODS
334 The following methods can be called on an arrayref type data struc‐
336 tures (scalar types will automatically promote to a single element
337 list and call these methods if needed):
338 Additionally, list virtual methods can be accessed via the List
340 Virtual Object.
341 fmt
343 [% mylist.fmt('%s', ', ') %]
344 [% mylist.fmt('%6s', ', ') %]
345 [% mylist.fmt('%*s', ', ', 6) %]
346 Passed a pattern and an string to join on. Returns a string of
348 the values of the list formatted with the passed pattern and
349 joined with the passed string. Default pattern is %s and the
350 default join string is a space.
351 first
353 [% mylist.first(3) %] Returns a list of the first 3 items in the list.
354 grep
356 [% mylist.grep("^\w+\.\w+$") %] Returns a list of all items matching the pattern.
357 hash
359 [% mylist.hash %] Returns a hashref with the array indexes as keys and the values as values.
360 join
362 [% mylist.join %] Joins on space.
363 [% mylist.join(", ") Joins on the passed argument.
364 last
366 [% mylist.last(3) %] Returns a list of the last 3 items in the list.
367 list
369 [% mylist.list %] Returns a reference to the list.
370 max
372 [% mylist.max %] Returns the last item in the array.
373 merge
375 [% mylist.merge(list2) %] Returns a new list with all defined items from list2 added.
376 nsort
378 [% mylist.nsort %] Returns the numerically sorted items of the list. If the items are
379 hashrefs, a key containing the field to sort on can be passed.
380 pop
382 [% mylist.pop %] Removes and returns the last element from the arrayref (the stash is modified).
383 push
385 [% mylist.push(23) %] Adds an element to the end of the arrayref (the stash is modified).
386 pick
388 [% mylist.pick %] Returns a random item from the list.
389 [% ['a' .. 'z'].pick %]
390 An additional numeric argument is how many items to return.
392 [% ['a' .. 'z'].pick(8).join('') %]
394 Note: This filter is not available as of TT2.15.
396 reverse
398 [% mylist.reverse %] Returns the list in reverse order.
399 shift
401 [% mylist.shift %] Removes and returns the first element of the arrayref (the stash is modified).
402 size
404 [% mylist.size %] Returns the number of elements in the array.
405 slice
407 [% mylist.slice(i, n) %] Returns a list from the arrayref beginning at index i and continuing for n items.
408 sort
410 [% mylist.sort %] Returns the alphabetically sorted items of the list. If the items are
411 hashrefs, a key containing the field to sort on can be passed.
412 splice
414 [% mylist.splice(i, n) %] Removes items from array beginning at i and continuing for n items.
415 [% mylist.splice(i, n, list2) %] Same as before, but replaces removed items with the items
417 from list2.
418 unique
420 [% mylist.unique %] Return a list of the unique items in the array.
421 unshift
423 [% mylist.unshift(23) %] Adds an item to the beginning of the arrayref.
424 HASH VIRTUAL METHODS
426 The following methods can be called on hash type data structures:
428 Additionally, list virtual methods can be accessed via the Hash
430 Virtual Object.
431 fmt
433 [% myhash.fmt('%s => %s', "\n") %]
434 [% myhash.fmt('%4s => %5s', "\n") %]
435 [% myhash.fmt('%*s => %*s', "\n", 4, 5) %]
436 Passed a pattern and an string to join on. Returns a string of
438 the key/value pairs of the hash formatted with the passed pat‐
439 tern and joined with the passed string. Default pattern is
440 "%s\t%s" and the default join string is a newline.
441 defined
443 [% myhash.defined('a') %] Checks if a is defined in the hash.
444 delete
446 [% myhash.delete('a') %] Deletes the item from the hash.
447 Unlink Perl the value is not returned. Multiple values may be
449 passed and represent the keys to be deleted.
450 each
452 [% myhash.each.join(", ") %] Turns the contents of the hash into a list - subject
453 to change as TT is changing the operations of each and list.
454 exists
456 [% myhash.exists('a') %] Checks if a is in the hash.
457 hash
459 [% myhash.hash %] Returns a reference to the hash.
460 import
462 [% myhash.import(hash2) %] Overlays the keys of hash2 over the keys of myhash.
463 item
465 [% myhash.item(key) %] Returns the hashes value for that key.
466 items
468 [% myhash.items %] Returns a list of the key and values (flattened hash)
469 keys
471 [% myhash.keys.join(', ') %] Returns an arrayref of the keys of the hash.
472 list
474 [% myhash.list %] Returns an arrayref with the hash as a single value (subject to change).
475 pairs
477 [% myhash.pairs %] Returns an arrayref of hashrefs where each hash contains {key => $key, value => $value}
478 for each value of the hash.
479 nsort
481 [% myhash.nsort.join(", ") %] Returns a numerically sorted list of the keys.
482 size
484 [% myhash.size %] Returns the number of key/value pairs in the hash.
485 sort
487 [% myhash.sort.join(", ") Returns an alphabetically sorted list.
488 values
490 [% myhash.values.join(', ') %] Returns an arrayref of the values of the hash.
491
493 TT3 has a concept of Text, List, and Hash virtual objects which provide
494 direct access to the scalar, list, and hash virtual methods. In the
495 TT3 engine this will allow for more concise generated code. Because
496 Alloy does not generated perl code to be executed later, Alloy provides
497 for these virtual objects but does so as more of a namespace (using the
498 methods does not provide a speed optimization in your template - just
499 may help clarify things).
500 [% a = "foo"; a.length %] => 3
502 [% a = "foo"; Text.length(a) %] => 3
504 [% a = Text.new("foo"); a.length %] => 3
506 [% a = [1 .. 30]; a.size %] => 30
508 [% a = [1 .. 30]; List.size(a) %] => 30
510 [% a = List.new(1 .. 30); a.size %] => 30
512 [% a = {a => 1, b => 2}; a.size %] => 2
514 [% a = {a => 1, b => 2}; Hash.size(a) %] => 2
516 [% a = Hash.new({a => 1, b => 2}); a.size %] => 2
518 [% a = Hash.new(a => 1, b => 2); a.size %] => 2
520 [% a = Hash.new(a = 1, b = 2); a.size %] => 2
522 [% a = Hash.new('a', 1, 'b', 2); a.size %] => 2
524 One limitation is that if you pass a key named "Text", "List", or
526 "Hash" in your variable stash - the corresponding virtual object will
527 be hidden.
528 Additionally, you can use all of the Virtual object methods with the
530 pipe operator.
531 [% {a => 1, b => 2}
533 ⎪ Hash.keys
534 ⎪ List.join(", ") %] => a, b
535 Again, there aren't any speed optimizations to using the virtual
537 objects in Alloy, but it can help clarify the intent in some cases.
538 Note: these aren't really objects. All of the "virtual objects" are
540 references to the $SCALAR_OPS, $LIST_OPS, and $HASH_OPS hashes found in
541 the $VOBJS hash of Template::Alloy.
542
544 Paul Seamons <perl at seamons dot com>
545
547 This module may be distributed under the same terms as Perl itself.
548perl v5.8.8 2007-07-24 Template::Alloy::VMethod(3)