NAME

Top Close Open

Template::TT3::Variable - base class for template variable objects

DESCRIPTION

Top Close Open

The Template::TT3::Variable module defines a base class for objects used to represent variables in TT3. A variable is a very small, lightweight object that encapsulates the name of a variable and its value, along with some other housekeeping metadata.

Variables are typed. For example, variables that have hash references as values are represented by Template::TT3::Variable::Hash variable objects, those that are list references are represented by Template::TT3::Variable::List objects, and so on.

The Template::TT3::Variables factory module can be used to create variable objects.

use Template::TT3::Variables;

my $vars = Template::TT3::Variables->new;

my $hash = $vars->var( 
    user => { 
        name  => 'Ford Prefect',
        email => 'ford@heart-of-gold.com',
    }
);

These objects collectively implement the runtime functionality of variables in TT3. The get() method can be called to fetch the current value of the variable.

my $user = $hash->get;
print $user->{ name };      # Ford Prefect

The set() method can be used to set a new variable value. However, it is a non-destructive action that doesn't modify the variable object or the original data. Instead it returns a new variable reference containing the new value. It is effectively syntactic sugar for creating a new variable with the same name as an existing one.

my $old = $vars->var( user => 'Arthur Dent' );
my $new = $old->set('Ford Prefect');

print $old->value;          # Arthur Dent
print $new->value;          # Ford Prefect

The dot() method can be called to perform dot operations on the hash. This includes accessing hash items and calling virtual methods.

my $name = $hash->dot('name');
my $keys = $hash->dot('keys');

The dot() method returns a new Template::TT3::Variable object to represent the result. Thus, a fragment of template code like this:

[% user.name.length %]

Can be implemented in Perl like this:

$vars->var('user')->dot('name')->dot('length')->get;

Note that we must call the get() value right at the end to return the final variable value. Rather surprisingly, this gives slightly better performance than the current TT2 implementation for accessing variables, despite the fact that there's rather a lot of wrapping and delegating going on.

METHODS

Top Close Open

new()

Top Close Open

This defines a default constructor method for creating variable objects. It exists for the sake of completeness but most if not all of the internal TT code uses the constructor() method to return a constructor function that can then be called independently.

graft($context)

Top Close Open

Clones a variable and grafts it onto a new context. This is used when a child context (e.g. in a with or just block) accesses a variable defined in a parent context (i.e. the outer block). We can't re-use the cached variable (shame) because it's bound to the outer context. If we did re-use it then any subsequent updates to that variable (e.g. set() ) in the inner context would affect the vars cache in the outer context. That would be bad.

So instead we clone the variable and update the CONTEXT slot to point to the new inner context.

constructor()

Top Close Open

This method returns a constructor function for variable instances.

# fetch a constructor function for hash variables
my $HashVar = Template::TT3::Variable::Hash->constructor;

# call it to create a variable instance
my $hashvar = $HashVar->( 
    user => { 
        name => 'Ford Prefect' 
    } 
)

configuration(\%config)

Top Close Open

This method stub is provided for subclasses to examine or modify the configuration parameters that are bound inside the closure returned by the constructor() method. In the base class this method simply returns unmodified the hash reference passed to it as an argument by the constructor() method.

get()

Top Close Open

Returns the current value of the variable.

my $var = $vars->var( user => 'Slartibartfast' );

print $var->value;          # Slartibartfast

set($value)

Top Close Open

Used to set a new variable value. Note that this is a non-destructive action that returns a new variable reference containing the new value.

# create a variable called 'user' than contains a hash reference
my $old = $vars->use_var( user => { ... } );

# $old is now a Template::TT3::Variable::Hash object

# create a new value for the variable
my $new = $old->set('Ford Prefect');

# $new is now a Template::TT3::Variable::Text object, $old is unchanged

http://tt3.template-toolkit.org/docs/Template/TT3/Variable.pm last modified 2009-12-23 13:02:39