Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Template::Manual::VMetUser(Contributed Perl DocumTemplate::Manual::VMethods(3)

       Template::Manual::VMethods - Virtual Methods

Scalar Virtual Methods
       Splits the value	into a list of chunks of a certain size.

	   [% ccard_no = "1234567824683579";


	   1234	5678 2468 3579

       If the size is specified	as a negative number then the text will	be
       chunked from right-to-left.  This gives the correct grouping for
       numbers,	for example.

	   [% number = 1234567;



       Returns the text	with any leading and trailing whitespace removed and
       any internal sequences of whitespace converted to a single space

	   [% text = "	The bird\n  is the word" %]
	   [% text.collapse %]	     # The bird	is the word

       Returns true if the value is defined.

	   [% user = get_user(uid) IF uid.defined %]

       Returns the text	with any double	quote characters escaped with a
       backslash prefix.  Any newline characters in the	text will be replaced
       with "\n".

	   [% quote = 'He said "Oh really?"' %]
	   [% quote.dquote %]	     # He said \"Oh really?\"

       Return the value	as a hash reference containing a single	entry with the
       key "value" indicating the original scalar value.  As with the "list"
       virtual method, this is generally used to help massage data into
       different formats.

       Returns the text	with the first letter converted	to lower case.

	   [% word = 'BIRD' %]
	   [% word.lcfirst %]	     # bIRD

       Returns the length of the string	representation of the item:

	   [% IF password.length < 8 %]
	      Password too short, dumbass!
	   [% END %]

       Returns true if the string is empty:

	   [% IF details.empty %]
	      No details specified
	   [% END %]

       Return the value	as a single element list.  This	can be useful if you
       have a variable which may contain a single item or a list and you want
       to treat	them equally.  The "list" method can be	called against a list
       reference and will simply return	the original reference,	effectively a

	   [% thing.list.size %]     # thing can be a scalar or	a list

       Returns the text	in lower case.

	   [% word = 'BIRD' %]
	   [% word.lower %]	     # bird

   match(pattern, global)
       Performs	a regular expression match on the string using the pattern
       passed as an argument.  If the pattern matches the string then the
       method returns a	reference to a list of any strings captured within
       parenthesis in the pattern.

	   [% name = 'Larry Wall' %]
	   [% matches =	name.match('(\w+) (\w+)') %]
	   [% matches.1	%], [% matches.0 %]    # Wall, Larry

       If the pattern does not match then the method returns false, rather
       than returning an empty list which Perl and the Template	Toolkit	both
       consider	to be a	true value.  This allows you to	write expression like

	   [% "We're not worthy!" IF name.match('Larry Wall') %]

	   [% IF (matches = name.match('(\w+) (\w+)')) %]
	      pattern matches: [% matches.join(', ') %]
	   [% ELSE %]
	      pattern does not match
	   [% END %]

       Any regex modifiers, like "/s", should be added in the regex using the
       "(?s)" syntax.  For example, to modify the regex	to disregard
       whitespace (the "/x" switch), use:

	   [% re = '(?x)
		      [	]
	     matches = name.match(re);

       To perform a global search to match the pattern as many times as	it
       appears in the source string, provide a true value for the "global"
       argument	following the pattern.

	   [% text = 'bandanna';
	      text.match('an+',	1).join(', )	  # an,	ann

       Repeat the string a specified number of times.

	   [% name = 'foo' %]
	   [% name.repeat(3) %]		       # foofoofoo

   replace(search, replace)
       Outputs the string with all instances of	the first argument (specified
       as a Perl regular expression) with the second.

	   [% name = 'foo, bar & baz' %]
	   [% name.replace('\W+', '_') %]	 # foo_bar_baz

       You can use $1, $2, etc., to reference captured parts (in parentheses)
       in the regular expression.  Just	be careful to single quote the
       replacement string.  If you use double quotes then TT will try and
       interpolate the variables before	passing	the string to the "replace"

	   [% name = 'FooBarBaz' %]
	   [% name.replace('([A-Z])', '	$1') %]	 # Foo Bar Baz

       Outputs the string with all instances of	the pattern (specified as a
       Perl regular expression)	removed.

	   [% name = 'foo, bar & baz' %]
	   [% name.remove('\W+') %]    # foobarbaz

       Performs	a similar function to match but	simply returns true if the
       string matches the regular expression pattern passed as an argument.

	   [% name = 'foo bar baz' %]
	   [%'bar') ? 'bar' : 'no bar' %]	   # bar

       This virtual method is now deprecated in	favour of match.  Move along
       now, there's nothing more to see	here.

       Always returns 1	for scalar values.  This method	is provided for
       consistency with	the hash and list size methods.

       Calls Perl's "split()" function to split	a string into a	list of

	   [% FOREACH dir IN mypath.split(':') %]
	      [% dir %]
	   [% END %]

   substr(offset, length, replacement)
       Returns a substring starting at "offset", for "length" characters.

	   [% str 'foo bar baz wiz waz woz') %]
	   [% str.substr(4, 3) %]    # bar

       If "length" is not specified then it returns everything from the
       "offset"	to the end of the string.

	   [% str.substr(12) %]	     # wiz waz woz

       If both "length"	and "replacement" are specified, then the method
       replaces	everything from	"offset" for "length" characters with
       $replacement.  The substring removed from the string is then returned.

	   [% str.substr(0, 11,	'FOO') %]   # foo bar baz
	   [% str %]			    # FOO wiz waz woz

       Returns the text	with any single	quote characters escaped with a
       backslash prefix.

	   [% tim = "Tim O'Reilly" %]
	   [% tim.squote %]	     # Tim O\'Reilly

       Returns the text	with any leading and trailing whitespace removed.

	   [% text = '	hello  world  '	%]
	   [% text.trim	%]	     # hello  world

       Returns the text	with the first letter converted	to upper case.

	   [% word = 'bird' %]
	   [% word.ucfirst %]	     # Bird

       Returns the text	in upper case.

	   [% word = 'bird' %]
	   [% word.upper %]	     # BIRD

Hash Virtual Methods
       Returns a list of keys in the hash.  They are not returned in any
       particular order, but the order is the same as for the corresponding
       values method.

	   [% FOREACH key IN hash.keys %]
	      *	[% key %]
	   [% END %]

       If you want the keys in sorted order, use the list "sort" method.

	   [% FOREACH key IN hash.keys.sort %]
	      *	[% key %]
	   [% END %]

       Having got the keys in sorted order, you	can then use variable
       interpolation to	fetch the value.  This is shown	in the following
       example by the use of $key to fetch the item from "hash"	whose key is
       stored in the "key" variable.

	   [% FOREACH key IN hash.keys.sort %]
	      *	[% key %] = [% hash.$key %]
	   [% END %]

       Alternately, you	can use	the "pairs" method to get a list of key/value
       pairs in	sorted order.

       Returns a list of the values in the hash.  As with the "keys" method,
       they are	not returned in	any particular order, although it is the same
       order that the keys are returned	in.

	   [% hash.values.join(', ') %]

       Returns a list of both the keys and the values expanded into a single

	   [% hash = {
		 a = 10
		 b = 20

	      hash.items.join(', ')    # a, 10,	b, 20

       This method currently returns the same thing as the "items" method.

       However,	please note that this method will change in the	next major
       version of the Template Toolkit (v3) to return the same thing as	the
       "pairs" method.	This will be done in an	effort to make these virtual
       method more consistent with each	other and how Perl works.

       In anticipation of this,	we recommend that you stop using "hash.each"
       and instead use "hash.items".

       This method returns a list of key/value pairs.  They are	returned in
       sorted order according to the keys.

	   [% FOREACH pair IN product.pairs %]
	      *	[% pair.key %] is [% pair.value	%]
	   [% END %]

       Returns the contents of the hash	in list	form.  An argument can be
       passed to indicate the desired items required in	the list: "keys" to
       return a	list of	the keys (same as "hash.keys"),	"values" to return a
       list of the values (same	as "hash.values"), "each" to return as list of
       key and values (same as "hash.each"), or	"pairs"	to return a list of
       key/value pairs (same as	"hash.pairs").

	   [% keys   = hash.list('keys') %]
	   [% values = hash.list('values') %]
	   [% items  = hash.list('each') %]
	   [% pairs  = hash.list('pairs') %]

       When called without an argument it currently returns the	same thing as
       the "pairs" method.  However, please note that this method will change
       in the next major version of the	Template Toolkit (v3) to return	a
       reference to a list containing the single hash reference	(as per	the
       scalar list method).

       In anticipation of this,	we recommend that you stop using "hash.list"
       and instead use "hash.pairs".

   sort, nsort
       Return a	list of	the keys, sorted alphabetically	("sort") or
       numerically ("nsort") according to the corresponding values in the

	   [% FOREACH n	IN phones.sort %]
	      [% phones.$n %] is [% n %],
	   [% END %]

       The "import" method can be called on a hash array to import the
       contents	of another hash	array.

	   [% hash1 = {
		foo = 'Foo'
		bar = 'Bar'
	      hash2 = {
		  wiz =	'Wiz'
		  woz =	'Woz'

	   [% hash1.import(hash2) %]
	   [% hash1.wiz	%]	       # Wiz

       You can also call the "import()"	method by itself to import a hash
       array into the current namespace	hash.

	   [% user = { id => 'lwall', name => 'Larry Wall' } %]
	   [% import(user) %]
	   [% id %]: [%	name %]	       # lwall:	Larry Wall

   defined, exists
       Returns a true or false value if	an item	in the hash denoted by the key
       passed as an argument is	defined	or exists, respectively.

	   [% hash.defined('somekey') ?	'yes' :	'no' %]
	   [% hash.exists('somekey') ? 'yes' : 'no' %]

       When called without any argument, "hash.defined"	returns	true if	the
       hash itself is defined (e.g. the	same effect as "scalar.defined").

       Delete one or more items	from the hash.

	   [% hash.delete('foo', 'bar')	%]

       Returns the number of key/value pairs in	the hash.

       Returns true if the hash	is empty:

	   [% IF config.empty %]
	      No configuration available
	   [% END %]

       Returns an item from the	hash using a key passed	as an argument.

	   [% hash.item('foo') %]  # same as

List Virtual Methods
   first, last
       Returns the first/last item in the list.	 The item is not removed from
       the list.

	   [% results.first %] to [% results.last %]

       If either is given a numeric argument "n", they return the first	or
       last "n"	elements:

	   The first 5 results are [% results.first(5).join(", ") %].

   size, max
       Returns the size	of a list (number of elements) and the maximum index
       number (size - 1), respectively.

	   [% results.size %] search results matched your query

       Returns true if the list	is empty:

	   [% IF results.empty %]
	      No results found
	   [% END %]

       Returns a true or false value if	the item in the	list denoted by	the
       argument	is defined.

	   [% list.defined(3) ?	'yes' :	'no' %]

       When called without any argument, "list.defined"	returns	true if	the
       list itself is defined (e.g. the	same effect as "scalar.defined").

       Returns the items of the	list in	reverse	order.

	   [% FOREACH s	IN scores.reverse %]
	   [% END %]

       Joins the items in the list into	a single string, using Perl's "join()"

	   [% items.join(', ') %]

       Returns a list of the items in the list that match a regular expression

	   [% FOREACH directory.files.grep('\.txt$') %]
	   [% END %]

   sort, nsort
       Returns the items in alpha ("sort") or numerical	("nsort") order.

	   [% library =	books.sort %]

       An argument can be provided to specify a	search key.  Where an item in
       the list	is a hash reference, the search	key will be used to retrieve a
       value from the hash which will then be used as the comparison value.
       Where an	item is	an object which	implements a method of that name, the
       method will be called to	return a comparison value.

	   [% library =	books.sort('author') %]

       In the example, the "books" list	can contains hash references with an
       "author"	key or objects with an "author"	method.

       You can also specify multiple sort keys.

	   [% library =	books.sort('author', 'title') %]

       In this case the	books will be sorted primarily by author.  If two or
       more books have authors with the	same name then they will be sorted by

   unshift(item), push(item)
       The "push()" method adds	an item	or items to the	end of list.

	   [% mylist.push(foo) %]
	   [% mylist.push(foo, bar) %]

       The "unshift()" method adds an item or items to the start of a list.

	   [% mylist.unshift(foo) %]
	   [% mylist.push(foo, bar)    %]

   shift, pop
       Removes the first/last item from	the list and returns it.

	   [% first = mylist.shift %]
	   [% last  = mylist.pop   %]

       Returns a list of the unique elements in	a list,	in the same order as
       in the list itself.

	   [% mylist = [ 1, 2, 3, 2, 3,	4, 1, 4, 3, 4, 5 ] %]
	   [% numbers =	mylist.unique %]

       While this can be explicitly sorted, it is not required that the	list
       be sorted before	the unique elements are	pulled out (unlike the Unix
       command line utility).

	   [% numbers =	mylist.unique.sort %]

       Appends the contents of one or more other lists to the end of the
       current list.

	   [% one   = [	1 2 3 ];
	      two   = [	4 5 6 ];
	      three = [	7 8 9 ];
	      one.import(two, three);
	      one.join(', );	 # 1, 2, 3, 4, 5, 6, 7,	8, 9

       Returns a list composed of zero or more other lists:

	   [% list_one = [ 1 2 3 ];
	      list_two = [ 4 5 6 ];
	      list_three = [ 7 8 9 ];
	      list_four	= list_one.merge(list_two, list_three);

       The original lists are not modified.

   slice(from, to)
       Returns a slice of items	in the list between the	bounds passed as
       arguments.  If the second argument, "to", isn't specified, then it
       defaults	to the last item in the	list.  The original list is not

	   [% first_three = list.slice(0,2) %]
	   [% last_three  = list.slice(-3, -1) %]

   splice(offset, length, list)
       Behaves just like Perl's	"splice()" function allowing you to
       selectively remove and/or replace elements in a list.  It removes
       "length"	items from the list, starting at "offset" and replaces them
       with the	items in "list".

	   [% play_game	= [ 'play', 'scrabble' ];
	      ping_pong	= [ 'ping', 'pong' ];
	      redundant	= play_game.splice(1, 1, ping_pong);
	      redundant.join;	  # scrabble
	      play_game.join;	  # play ping pong

       The method returns a list of the	items removed by the splice.  You can
       use the "CALL" directive	to ignore the output if	you're not planning to
       do anything with	it.

	   [% CALL play_game.splice(1, 1, ping_pong) %]

       As well as providing a reference	to a list of replacement values, you
       can pass	in a list of items.

	   [% CALL list.splice(-1, 0, 'foo', 'bar') %]

       Be careful about	passing	just one item in as a replacement value.  If
       it is a reference to a list then	the contents of	the list will be used.
       If it's not a list, then	it will	be treated as a	single value.  You can
       use square brackets around a single item	if you need to be explicit:

	   [% #	push a single item, an_item
	      CALL list.splice(-1, 0, an_item);

	      #	push the items from another_list
	      CALL list.splice(-1, 0, another_list);

	      #	push a reference to another_list
	      CALL list.splice(-1, 0, [	another_list ]);

       Returns a reference to a	hash array comprised of	the elements in	the
       list.  The even-numbered	elements (0, 2,	4, etc)	become the keys	and
       the odd-numbered	elements (1, 3,	5, etc)	the values.

	   [% list = ['pi', 3.14, 'e', 2.718] %]
	   [% hash = list.hash %]
	   [% hash.pi %]	       # 3.14
	   [% hash.e  %]	       # 2.718

       If a numerical argument is provided then	the hash returned will have
       keys generated for each item starting at	the number specified.

	   [% list = ['beer', 'peanuts'] %]
	   [% hash = list.hash(1) %]
	   [% hash.1  %]	       # beer
	   [% hash.2  %]	       # peanuts

Automagic Promotion of Scalar to List for Virtual Methods
       In addition to the scalar virtual methods listed	in the previous
       section,	you can	also call any list virtual method against a scalar.
       The item	will be	automagically promoted to a single element list	and
       the appropriate list virtual method will	be called.

       One particular benefit of this comes when calling subroutines or	object
       methods that return a list of items, rather than	the preferred
       reference to a list of items.  In this case, the	Template Toolkit
       automatically folds the items returned into a list.

       The upshot is that you can continue to use existing Perl	modules	or
       code that returns lists of items, without having	to refactor it just to
       keep the	Template Toolkit happy (by returning references	to list).
       "Class::DBI" module is just one example of a particularly useful	module
       which returns values this way.

       If only a single	item is	returned from a	subroutine then	the Template
       Toolkit assumes it meant	to return a single item	(rather	than a list of
       1 item) and leaves it well alone, returning the single value as it is.
       If you're executing a database query, for example, you might get	1 item
       returned, or perhaps many items which are then folded into a list.

       The "FOREACH" directive will happily accept either a list or a single
       item which it will treat	as a list. So it's safe	to write directives
       like this, where	we assume that the "something" variable	is bound to a
       subroutine which	may return one or more items:

	   [% FOREACH item IN something	%]
	   [% END %]

       The automagic promotion of scalars to single item lists means that you
       can also	use list virtual methods safely, even if you only get one item
       returned.  For example:

	   [% something.first	%]
	   [% something.join	%]
	   [% something.reverse.join(',	') %]

       Note that this is very much a last-ditch	behaviour.  If the single item
       return is an object with	a "first" method, for example, then that will
       be called, as expected, in preference to	the list virtual method.

Defining Custom	Virtual	Methods
       You can define your own virtual methods for scalars, lists and hash
       arrays.	The Template::Stash package variables $SCALAR_OPS, $LIST_OPS
       and $HASH_OPS are references to hash arrays that	define these virtual
       methods.	 "HASH_OPS" and	"LIST_OPS" methods are subroutines that	accept
       a hash/list reference as	the first item.	"SCALAR_OPS" are subroutines
       that accept a scalar value as the first item. Any other arguments
       specified when the method is called will	be passed to the subroutine.

	   # load Template::Stash to make method tables	visible
	   use Template::Stash;

	   # define list method	to return new list of odd numbers only
	   $Template::Stash::LIST_OPS->{ odd } = sub {
	       my $list	= shift;
	       return [	grep { $_ % 2 }	@$list ];

       Example template:

	   [% primes = [ 2, 3, 5, 7, 9 ] %]
	   [% primes.odd.join(', ') %]	       # 3, 5, 7, 9

       TODO: document the define_vmethod() method which	makes this even	easier

perl v5.24.1			  2015-03-08	 Template::Manual::VMethods(3)

NAME | Scalar Virtual Methods | Hash Virtual Methods | List Virtual Methods | Automagic Promotion of Scalar to List for Virtual Methods | Defining Custom Virtual Methods

Want to link to this manual page? Use this URL:

home | help