Template Toolkit Version 3 Developer Documentation
http://www.template-toolkit.org/v3/

Template::Stash

Table of Contents

: $VMETHS$HASH_EQUALS$HASH_JOINT$LIST_JOINT$DEBUG$WARNINGS
: new()init()clone()declone()operate()get()set()pre_inc()post_inc()pre_dec()post_dec()
: vmeth_ref()vmeth_item()vmeth_list()vmeth_hash()vmeth_length()vmeth_size()vmeth_max()vmeth_first()vmeth_last()vmeth_join()vmeth_sort()vmeth_reverse()vmeth_repeat()
NOTES:

Synopsis


Description

The Stash has been totally re-written from the ground up for version 3. It implements a new internal dispatch mechanism which permits the lookahead required to implement several new postfix virtual methods such as LIST, ITEM, CODEREF and REF. This was inspired by Craig Barratt's recent work on implementing this feature in the v2 parser (Template::Stash::Context in v2.03).

By adding a few well-chosen virtual methods like these we can greatly extend the capability of the Stash operations permissible. LIST, HASH and ITEM act as explicit conversion filters to allow you to switch between types.

In addition, they also allow the calling context of a subroutine or object method to be explicitly stated.

REF returns a string indicating the reference type of an object, e.g. 'LIST, 'HASH', 'CODE'. Code references and object methods are not called. Object methods return 'CODE' as a reference type.

CODEREF returns a closure which can be used to subsequently evaluate a variable in a lazy fashion. This works for any data types, including object methods. Parameters specified with the node at the CODEREF point are correctly merged with those specified when the closure is called.

There is also full support for objects to provide their own virtual method implementations. If an object implements the TT_ITEM method, for example, then any calls to:

will be translated to calls of the form:

This holds for all the virtual methods. Simply define an object method with a 'TT_' prefix on the upper case virtual method name.

On the subject of case, this implementation has virtual methods in UPPER CASE by default. I'm inclined to make this the default for v3 in a move to make all Template Toolkit "builtin" commands, variables, etc., UPPER CASE, and all user data in lower case. However, it should be possible to set a parser option which does automatic case folding for directives and/or virtual methods so that will almost certainly be a user option.

One of the important differences between virtual methods from version 2 is that there is just one virtual method which applies to each and every data type. If a virtual method expects a list and receives an item, for example, then it automatically applies the LIST virtual method to first create a list representation of the item. This makes the use of virtual methods much more consistent and guarantees some correct result for any data type (for various definitions of "correct" which doesn't necessariy imply "useful").

Another new feature is support for inplace pre and post increment/decremement operations. Although the parser doesn't yet parse it at the time of writing, the Stash supports operations of the form [% a++ %] , [% a = b++ %] , [% c += d %] , etc.


Package Variables


Methods


Virtual Methods

The virtual methods have all been re-written such that any method can be applied to any data type with the correct promotion or demotion between scalars and lists being handled automatically. In other words, if you call item.FIRST, you get the item back because a single item is considered to be a one-element list. Some methods just Do The Right Thing for different types. For example, list.LENGTH returns the number of items in a list whereas item.LENGTH returns the length of the item string. Conversely, list.SIZE return the same as list.LENGTH but item.SIZE returns 1 because that virtual method treats a single item as a one-element list.

The JOIN and SORT virtual methods make particular use of the ability to work across different data types. Calling list.JOIN return a string of the form "a, b, c, d, ..." whereas hash.JOIN returns "a = b, c = d, ...". You can use the LIST, HASH and ITEM methods to explicitly convert between "types", e.g. list.HASH.JOIN converts 'list' to a hash and then performs a hash join on it, returning "a = b, c = d, ...". The JOIN method, in addition to its own parameters for specifying joining string, accepts arguments for sorting which are delegated to the SORT method. This means you can do things like:

to sort the hash items numerically by value (default: alphanumerically by key) and return a string of the form "a = b, c = d, ..."..

List of Virtual Methods:
Template Toolkit Version 3 Developer Documentation
http://www.template-toolkit.org/v3/