/ 
Template-Alloy-1.022
River stage two • 13 direct dependents • 15 total dependents
/ Template::Alloy::VMethod

NAME

Template::Alloy::VMethod - VMethod role.

DESCRIPTION

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

ROLE METHODS

define_vmethod

Defines a vmethod. See Template::Alloy for more details.

vmethod_*

Methods by these names implement virtual methods that are more complex than oneliners. These methods are not exposed via the role.

filter_*

Methods by these names implement filters that are more complex than one liners. These methods are not exposed via the role.

VIRTUAL METHOD LIST

The following is the list of builtin virtual methods and filters that can be called on each type of data.

In Template::Alloy, the "|" operator can be used to call virtual methods just the same way that the "." operator can. The main difference between the two is that on access to hashrefs or objects, the "|" means to always call the virtual method or filter rather than looking in the hashref for a key by that name, or trying to call that method on the object. This is similar to how TT3 will function.

Virtual methods are also made available via Virtual Objects which are discussed in a later section.

SCALAR VIRTUAL METHODS AND FILTERS

The following is the list of builtin virtual methods and filters that can be called on scalar data types. In Alloy and TT3, filters and virtual methods are more closely related than in TT2. In general anywhere a virtual method can be used a filter can be used also - and likewise all scalar virtual methods can be used as filters.

In addition to the filters listed below, Alloy will automatically load Template::Filters and use them if Template::Toolkit is installed.

In addition to the scalar virtual methods, any scalar will be automatically converted to a single item list if a list virtual method is called on it.

Scalar virtual methods are also available through the "Text" virtual object (except for true filters such as eval and redirect).

All scalar virtual methods are available as top level functions as well. This is not true of TT2. In Template::Alloy the following are equivalent:

[% "abc".length %]
[% length("abc") %]

You may set VMETHOD_FUNCTIONS to 0 to disable this behavior.

'0'
[% item = 'foo' %][% item.0 %] Returns foo.

Allows for scalars to mask as arrays (scalars already will, but this allows for more direct access).

Not available in TT.

abs
[% -1.abs %] Returns the absolute value
atan2
[% pi = 4 * 1.atan2(1) %]

Returns the arctangent. The item itself represents Y, the passed argument represents X.

Not available in TT - available in HTML::Template::Expr.

chunk
[% item.chunk(60).join("\n") %] Split string up into a list of chunks of text 60 chars wide.
collapse
[% item.collapse %] Strip leading and trailing whitespace and collapse all other space to one space.
cos
[% item.cos %] Returns the cosine of the item.

Not available in TT - available in HTML::Template::Expr.

defined
[% item.defined %] Always true - because the undef sub translates all undefs to ''.
eval
[% item.eval %]

Process the string as though it was a template. This will start the parsing engine and will use the same configuration as the current process. Alloy is several times faster at doing this than TT is and is considered acceptable.

This is a filter and is not available via the Text virtual object.

Template::Alloy has attempted to make the compile process painless and fast. By default an MD5 sum of evaled is taken and used to cache the AST. This behavior can be disabled using the CACHE_STR_REFS configuration item.

Template::Alloy also allows for named parameters to be passed to the eval filter.

[% '[% 1 + 2 %]'.eval %]

[% '${ 1 + 2 }'.eval(interpolate => 1) %]

[% "#get( 1 + 2)"|eval(syntax => 'velocity') %]

[% '<TMPL_VAR EXPR="1 + 2">'.eval(syntax => 'hte') %]

[% '<TMPL_VAR EXPR="1 + 2">'.eval(syntax => 'hte') %]
evaltt
Same as the eval filter.
exp
[% 1.exp %] Something like 2.71828182845905

Returns "e" to the power of the item.

file
Same as the redirect filter.
fmt
[% item.fmt('%d') %]
[% item.fmt('%6s') %]
[% item.fmt('%*s', 6) %]

Similar to format. Returns a string formatted with the passed pattern. Default pattern is %s. Opposite from of the sprintf vmethod.

format
[% item.format('%d') %]
[% item.format('%6s') %]
[% item.format('%*s', 6) %]

Print the string out in the specified format. It is similar to the "fmt" virtual method, except that the item is split on newline and each line is processed separately.

hash
[% item.hash %] Returns a one item hash with a key of "value" and a value of the item.
hex
[% "FF".hex %]

Returns the decimal value of the passed hex numbers. Note that you may also just use [% 0xFF %].

Not available in TT - available in HTML::Template::Expr.

html
[% item.html %] Performs a very basic html encoding (swaps out &, <, > and " with the corresponding html entities)
Previously it also encoded the ' but this behavior did not match TT2's behavior.  Use .xml to obtain that behavior.
indent
[% item.indent(3) %] Indent by that number of spaces if an integer is passed (default is 4).

[% item.indent("Foo: ") %] Add the string "Foo: " to the beginning of every line.
int
[% item.int %] Return the integer portion of the value (0 if none).
json
[% item.json    %] Returns a JSON encoded representation.
[% item.json(1) %] Returns a pretty JSON encoded representation.
lc

Same as the lower vmethod. Returns the lowercased version of the item.

lcfirst
[% item.lcfirst %] Lowercase the leading letter.
length
[% item.length %] Return the length of the string.
list
[% item.list %] Returns a list (arrayref) with a single value of the item.
log
[% 8.exp.log %] Equal to 8.

Returns the natural log base "e" of the item.

Not available in TT - available in HTML::Template::Expr.

lower
[% item.lower %] Return the string lowercased.
match
[% item.match("(\w+) (\w+)") %] Return a list of items matching the pattern.

[% item.match("(\w+) (\w+)", 1) %] Same as before - but match globally.

In Template::Alloy and TT3 you can use regular expressions notation as well.

[% item.match( /(\w+) (\w+)/ ) %] Same as before.

[% item.match( m{(\w+) (\w+)} ) %] Same as before.

Note that you can't use the 'g' regex modifier - you must pass the second argument to turn on global match.

none

Returns the item without modification. This was added as a compliment case when the AUTO_FILTER configuration is specified. Note that it must be called as a filter to bypass the application of the AUTO_FILTER.

[% item | none %] Returns the item without modification.
null
[% item.null %] Return nothing.

If the item contains a coderef it will still be executed, but the result would be ignored.

oct
[% "377".oct %]

Returns the decimal value of the octal string. On recent versions of perl you may also pass numbers starting with 0x which will be interpreted as hexadecimal, and starting with 0b which will be interpreted as binary.

Not available in TT - available in HTML::Template::Expr.

rand
[% item = 10; item.rand %] Returns a number greater or equal to 0 but less than 10.
[% 1.rand %]

Note: This filter is not available as of TT2.15.

remove
[% item.remove("\s+") %] Same as replace - but is global and replaces with nothing.
redirect
[% item.redirect("output_file.html") %]

Writes the contents out to the specified file. The filename must be relative to the OUTPUT_PATH configuration variable and the OUTPUT_PATH variable must be set.

This is a filter and is not available via the Text virtual object.

repeat
[% item.repeat(3) %] Repeat the item 3 times

[% item.repeat(3, ' | ') %] Repeat the item 3 times separated with ' | '
replace
[% item.replace("\s+", "&nbsp;") %] Globally replace all space with &nbsp;

[% item.replace("foo", "bar", 0) %] Replace only the first instance of foo with bar.

[% item.replace("(\w+)", "($1)") %] Surround all words with parenthesis.

In Template::Alloy and TT3 you may also use normal regular expression notation.

[% item.replace(/(\w+)/, "($1)") %] Same as before.

Note that you can't use the 'g' regex modifier - global match is on by default. You must pass the third argument of false to turn off global match.

return

Returns the item from the inner most block, macro, or file. Similar to the RETURN directive.

[% item.return %]
[% RETURN item %]
[% item.search("(\w+)") %] Tests if the given pattern is in the string.

In Template::Alloy and TT3 you may also use normal regular expression notation.

[% item.search(/(\w+)/) %] Same as before.
sin
[% item.sin %] Returns the sine of the item.
size
[% item.size %] Always returns 1.
split
[% item.split %] Returns an arrayref from the item split on " "

[% item.split("\s+") %] Returns an arrayref from the item split on /\s+/

[% item.split("\s+", 3) %] Returns an arrayref from the item split on /\s+/ splitting until 3 elements are found.

In Template::Alloy and TT3 you may also use normal regular expression notation.

[% item.split( /\s+/, 3 ) %] Same as before.
sprintf
[% item = "%d %d" %]
[% item.sprintf(7, 8) %]

Uses the pattern stored in self, and passes it to sprintf with the passed arguments. Opposite from the fmt vmethod.

sqrt
[% item.sqrt %]

Returns the square root of the number.

srand

Calls the perl srand function to set the internal random seed. This will affect future calls to the rand vmethod.

stderr
[% item.stderr %] Print the item to the current STDERR handle.
substr
[% item.substr(i) %] Returns a substring of item starting at i and going to the end of the string.

[% item.substr(i, n) %] Returns a substring of item starting at i and going n characters.
trim
[% item.trim %] Strips leading and trailing whitespace.
uc

Same as the upper command. Returns uppercased string.

ucfirst
[% item.ucfirst %] Uppercase the leading letter.
upper
[% item.upper %] Return the string uppercased.
uri
[% item.uri %] Perform a very basic URI encoding.
url
[% item.url %] Perform a URI encoding - but some characters such
               as : and / are left intact.
xml
[% item.xml %] Performs a very basic xml encoding (swaps out &, <, >, ' and " with the corresponding xml entities)

LIST VIRTUAL METHODS

The following methods can be called on an arrayref type data structures (scalar types will automatically promote to a single element list and call these methods if needed):

Additionally, list virtual methods can be accessed via the List Virtual Object.

fmt
[% mylist.fmt('%s', ', ') %]
[% mylist.fmt('%6s', ', ') %]
[% mylist.fmt('%*s', ', ', 6) %]

Passed a pattern and an string to join on. Returns a string of the values of the list formatted with the passed pattern and joined with the passed string. Default pattern is %s and the default join string is a space.

first
[% mylist.first(3) %]  Returns a list of the first 3 items in the list.
grep
[% mylist.grep("^\w+\.\w+$") %] Returns a list of all items matching the pattern.

In Template::Alloy and TT3 you may also use normal regular expression notation.

[% mylist.grep(/^\w+\.\w+$/) %] Same as before.

[% mylist.grep(->(a){ a.foo.bar }
hash
[% mylist.hash %] Returns a hashref with the array indexes as keys and the values as values.
join
[% mylist.join %] Joins on space.
[% mylist.join(", ") Joins on the passed argument.
json
[% mylist.json    %] Returns a JSON encoded representation.
[% mylist.json(1) %] Returns a pretty JSON encoded representation.
last
[% mylist.last(3) %]  Returns a list of the last 3 items in the list.
list
[% mylist.list %] Returns a reference to the list.
map (Not in TT2)
[% mylist.map(->{ this.upper }) %] Returns a list with the macro played on each item.
[% mylist.map(->(a){ a.upper }) %] Same thing

The RETURN directive or return list, item, and hash vmethods allow for returning more interesting items.

[% [1..3].map(->(a){ [1..a].return }) %]
max
[% mylist.max %] Returns the last item in the array.
merge
[% mylist.merge(list2) %] Returns a new list with all defined items from list2 added.
nsort
[% mylist.nsort %] Returns the numerically sorted items of the list.  If the items are
hashrefs, a key containing the field to sort on can be passed.
pop
[% mylist.pop %] Removes and returns the last element from the arrayref (the stash is modified).
push
[% mylist.push(23) %] Adds an element to the end of the arrayref (the stash is modified).
pick
[% mylist.pick %] Returns a random item from the list.
[% ['a' .. 'z'].pick %]

An additional numeric argument is how many items to return.

[% ['a' .. 'z'].pick(8).join('') %]

Note: This filter is not available as of TT2.15.

return

Returns the list from the inner most block, macro, or file. Similar to the RETURN directive.

[% mylist.return %]
[% RETURN mylist %]
reverse
[% mylist.reverse %] Returns the list in reverse order.
shift
[% mylist.shift %] Removes and returns the first element of the arrayref (the stash is modified).
size
[% mylist.size %] Returns the number of elements in the array.
slice
[% mylist.slice(i, n) %] Returns a list from the arrayref beginning at index i and continuing for n items.
sort
[% mylist.sort %] Returns the alphabetically sorted items of the list.  If the items are
hashrefs, a key containing the field to sort on can be passed.
splice
[% mylist.splice(i, n) %] Removes items from array beginning at i and continuing for n items.

[% mylist.splice(i, n, list2) %] Same as before, but replaces removed items with the items
from list2.
unique
[% mylist.unique %] Return a list of the unique items in the array.
unshift
[% mylist.unshift(23) %] Adds an item to the beginning of the arrayref.

HASH VIRTUAL METHODS

The following methods can be called on hash type data structures:

Additionally, list virtual methods can be accessed via the Hash Virtual Object.

fmt
[% myhash.fmt('%s => %s', "\n") %]
[% myhash.fmt('%4s => %5s', "\n") %]
[% myhash.fmt('%*s => %*s', "\n", 4, 5) %]

Passed a pattern and an string to join on. Returns a string of the key/value pairs of the hash formatted with the passed pattern and joined with the passed string. Default pattern is "%s\t%s" and the default join string is a newline.

defined
[% myhash.defined('a') %]  Checks if a is defined in the hash.
delete
[% myhash.delete('a') %]  Deletes the item from the hash.

Unlink Perl the value is not returned. Multiple values may be passed and represent the keys to be deleted.

each
[% myhash.each.join(", ") %]  Turns the contents of the hash into a list - subject
to change as TT is changing the operations of each and list.
exists
[% myhash.exists('a') %]  Checks if a is in the hash.
hash
[% myhash.hash %]  Returns a reference to the hash.
import
[% myhash.import(hash2) %]  Overlays the keys of hash2 over the keys of myhash.
item
[% myhash.item(key) %] Returns the hashes value for that key.
items
[% myhash.items %] Returns a list of the key and values (flattened hash)
json
[% myhash.json    %] Returns a JSON encoded representation.
[% myhash.json(1) %] Returns a pretty JSON encoded representation.
keys
[% myhash.keys.join(', ') %] Returns an arrayref of the keys of the hash.
list
[% myhash.list %] Returns an arrayref with the hash as a single value (subject to change).
pairs
[% myhash.pairs %] Returns an arrayref of hashrefs where each hash contains {key => $key, value => $value}
for each value of the hash.
nsort
[% myhash.nsort.join(", ") %] Returns a list of keys numerically sorted by the values.
return

Returns the hash from the inner most block, macro, or file. Similar to the RETURN directive.

[% myhash.return %]
[% RETURN myhash %]
size
[% myhash.size %] Returns the number of key/value pairs in the hash.
sort
[% myhash.sort.join(", ") Returns a list of keys alphabetically sorted by the values.
values
[% myhash.values.join(', ') %] Returns an arrayref of the values of the hash.

VIRTUAL OBJECTS

TT3 has a concept of Text, List, and Hash virtual objects which provide direct access to the scalar, list, and hash virtual methods. In the TT3 engine this will allow for more concise generated code. Because Alloy does not generated perl code to be executed later, Alloy provides for these virtual objects but does so as more of a namespace (using the methods does not provide a speed optimization in your template - just may help clarify things).

[% a = "foo"; a.length %] => 3

[% a = "foo"; Text.length(a) %] => 3

[% a = Text.new("foo"); a.length %] => 3


[% a = [1 .. 30]; a.size %] => 30

[% a = [1 .. 30]; List.size(a) %] => 30

[% a = List.new(1 .. 30); a.size %] => 30


[% a = {a => 1, b => 2}; a.size %] => 2

[% a = {a => 1, b => 2}; Hash.size(a) %] => 2

[% a = Hash.new({a => 1, b => 2}); a.size %] => 2

[% a = Hash.new(a => 1, b => 2); a.size %] => 2

[% a = Hash.new(a = 1, b = 2); a.size %] => 2

[% a = Hash.new('a', 1, 'b', 2); a.size %] => 2

One limitation is that if you pass a key named "Text", "List", or "Hash" in your variable stash - the corresponding virtual object will be hidden.

Additionally, you can use all of the Virtual object methods with the pipe operator.

[% {a => 1, b => 2}
   | Hash.keys
   | List.join(", ") %] => a, b

Again, there aren't any speed optimizations to using the virtual objects in Alloy, but it can help clarify the intent in some cases.

Note: these aren't really objects. All of the "virtual objects" are references to the $SCALAR_OPS, $LIST_OPS, and $HASH_OPS hashes found in the $VOBJS hash of Template::Alloy.

AUTHOR

Paul Seamons <paul@seamons.com>

LICENSE

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