NAME

Template::Stash - variable storage for Template Toolkit

SYNOPSIS

    use Template::Stash;

    my $stash = Template::Stash->new(\%params);

    # set variable value
    $stash->set($variable, $value, $context);

    # get variable values
    ($value, $error) = $stash->get($variable, \@params, $context);

    # methods for localising variables
    $stash = $stash->clone(\%new_params);
    $stash = $stash->declone($namespace);

DESCRIPTION

The Template::Stash module defines an object class which is used to store variable values for the runtime use of the template processor. Variable values are stored internally in a hash reference (which itself is blessed to create the object) and are accessible via the get() and set() methods.

The stash allows user code to be bound to variables which is then called automatically when the variable value is accesed via get(). By simply storing a code reference in the stash, the get() method will recognise it and call when the variable is requested. The user code should then return the intended variable value and optionally also a status code to report any error conditions. The Template Toolkit implements a basic exception handling mechanism to permit flexible handling and recovery from such errors.

The object has clone() and declone() methods which are used by the template processor to make temporary copies of the stash for localising changes made to variables. The use of the 'magical' variable, 'IMPORT' allows users to manipulate the contents of namespaces.

PUBLIC METHODS

new(\%params)

The new() constructor method creates and returns a reference to a new Template::Stash object. A hash reference may be passed to provide variables and values which should be used to initialise the stash.

    $stash->new({ 'bgcolor' => '#ffffff', 'img' => '/images' });

set($variable, $value, $context)

The set() method sets the variable name in the first parameter to the value specified in the second. The calling context passes a reference to itself as the third parameter.

The magical variable 'IMPORT' can be specified whose corresponding value should be a hash reference. The contents of the hash array are copied (i.e. imported) into the current namespace.

    # foo.bar = baz, foo.wiz = waz
    $stash->set('foo', { 'bar' => 'baz', 'wiz' => 'waz' });

    # import 'foo' into main namespace: foo = baz, wiz = waz
    $stash->set('IMPORT', $stash->get('foo'));

get($variable, \@params, $context)

The get() method returns the value of the variable named by the first parameter or undef if the variable is not defined. If the variable is bound to code then any additional parameters referenced by the second parameter are passed as arguments as the code is called.

clone(\%params)

The clone() method creates and returns a new Stash object which represents a local context of the parent stash. Variables can be freely updated in the cloned stash and when declone() is called, the original stash is returned with all it's members intact and in the same state as they were before clone() was called.

For convenience, a hash of parameters may be passed into clone() which is used to update any simple variable (i.e. those that don't contain any namespace elements like 'foo' and 'bar' but not 'foo.bar') variables while cloning the stash. For adding and updating complex variables, the set() method should be used after calling clone(). This will correctly resolve and/or create any necessary namespace hashes.

A cloned stash maintains a reference to the stash that it was copied from in its '.PARENT' member.

declone($namespace)

The declone() method returns the '.PARENT' reference and can be used to restore the state of a stash as described above. A namespace parameter may be provided to specify a namespace into which the clone's EXPORT variable should be imported. The namespace may be 'IMPORT' to indicate that the contents of the clone's EXPORT hash should be imported into the parent's (caller's) namespace.

AUTHOR

Andy Wardley <cre.canon.co.uk>

REVISION

$Revision: 1.9 $

COPYRIGHT

Copyright (C) 1996-1999 Andy Wardley. All Rights Reserved. Copyright (C) 1998-1999 Canon Research Centre Europe Ltd.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Template, Template::Context,

cpanm Template

perl -MCPAN -e shell
install Template