Template::Alloy::VMethUser)Contributed Perl DocumenTemplate::Alloy::VMethod(3)NAMETemplate::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 featureset 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).
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 nonthing.
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 hexidecimal, 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+", " ") %] Globally replace all space with
[% 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 %]
search
[% 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 interal 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.
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 interesing 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)
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 <perl at seamons dot com>
LICENSE
This module may be distributed under the same terms as Perl itself.
perl v5.14.1 2011-01-26 Template::Alloy::VMethod(3)
