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.
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.
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.
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'
}
)
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.
Returns the current value of the variable.
my $var = $vars->var( user => 'Slartibartfast' ); print $var->value; # Slartibartfast
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