Template::Stash(3pm)

1Template::Stash(3)    User Contributed Perl Documentation   Template::Stash(3)
2
3
4

NAME

6       Template::Stash - Magical storage for template variables
7

SYNOPSIS

9           use Template::Stash;
10
11           my $stash = Template::Stash->new(\%vars);
12
13           # get variable values
14           $value = $stash->get($variable);
15           $value = $stash->get(\@compound);
16
17           # set variable value
18           $stash->set($variable, $value);
19           $stash->set(\@compound, $value);
20
21           # default variable value
22           $stash->set($variable, $value, 1);
23           $stash->set(\@compound, $value, 1);
24
25           # set variable values en masse
26           $stash->update(\%new_vars)
27
28           # methods for (de-)localising variables
29           $stash = $stash->clone(\%new_vars);
30           $stash = $stash->declone();
31

DESCRIPTION

33       The Template::Stash module defines an object class which is used to
34       store variable values for the runtime use of the template processor.
35       Variable values are stored internally in a hash reference (which itself
36       is blessed to create the object) and are accessible via the get() and
37       set() methods.
38
39       Variables may reference hash arrays, lists, subroutines and objects as
40       well as simple values.  The stash automatically performs the right
41       magic when dealing with variables, calling code or object methods,
42       indexing into lists, hashes, etc.
43
44       The stash has clone() and declone() methods which are used by the tem‐
45       plate processor to make temporary copies of the stash for localising
46       changes made to variables.
47

PUBLIC METHODS

49       new(\%params)
50
51       The new() constructor method creates and returns a reference to a new
52       Template::Stash object.
53
54           my $stash = Template::Stash->new();
55
56       A hash reference may be passed to provide variables and values which
57       should be used to initialise the stash.
58
59           my $stash = Template::Stash->new({ var1 => 'value1',
60                                              var2 => 'value2' });
61
62       get($variable)
63
64       The get() method retrieves the variable named by the first parameter.
65
66           $value = $stash->get('var1');
67
68       Dotted compound variables can be retrieved by specifying the variable
69       elements by reference to a list.  Each node in the variable occupies
70       two entries in the list.  The first gives the name of the variable ele‐
71       ment, the second is a reference to a list of arguments for that ele‐
72       ment, or 0 if none.
73
74           [% foo.bar(10).baz(20) %]
75
76           $stash->get([ 'foo', 0, 'bar', [ 10 ], 'baz', [ 20 ] ]);
77
78       set($variable, $value, $default)
79
80       The set() method sets the variable name in the first parameter to the
81       value specified in the second.
82
83           $stash->set('var1', 'value1');
84
85       If the third parameter evaluates to a true value, the variable is set
86       only if it did not have a true value before.
87
88           $stash->set('var2', 'default_value', 1);
89
90       Dotted compound variables may be specified as per get() above.
91
92           [% foo.bar = 30 %]
93
94           $stash->set([ 'foo', 0, 'bar', 0 ], 30);
95
96       The magical variable 'IMPORT' can be specified whose corresponding
97       value should be a hash reference.  The contents of the hash array are
98       copied (i.e. imported) into the current namespace.
99
100           # foo.bar = baz, foo.wiz = waz
101           $stash->set('foo', { 'bar' => 'baz', 'wiz' => 'waz' });
102
103           # import 'foo' into main namespace: bar = baz, wiz = waz
104           $stash->set('IMPORT', $stash->get('foo'));
105
106       clone(\%params)
107
108       The clone() method creates and returns a new Template::Stash object
109       which represents a localised copy of the parent stash.  Variables can
110       be freely updated in the cloned stash and when declone() is called, the
111       original stash is returned with all its members intact and in the same
112       state as they were before clone() was called.
113
114       For convenience, a hash of parameters may be passed into clone() which
115       is used to update any simple variable (i.e. those that don't contain
116       any namespace elements like 'foo' and 'bar' but not 'foo.bar') vari‐
117       ables while cloning the stash.  For adding and updating complex vari‐
118       ables, the set() method should be used after calling clone().  This
119       will correctly resolve and/or create any necessary namespace hashes.
120
121       A cloned stash maintains a reference to the stash that it was copied
122       from in its '_PARENT' member.
123
124       declone()
125
126       The declone() method returns the '_PARENT' reference and can be used to
127       restore the state of a stash as described above.
128

AUTHOR

130       Andy Wardley <abw@wardley.org>
131
132       <http://wardley.org/⎪http://wardley.org/>
133

VERSION

135       2.9, distributed as part of the Template Toolkit version 2.18, released
136       on 09 February 2007.
137

COPYRIGHT

139         Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
140
141       This module is free software; you can redistribute it and/or modify it
142       under the same terms as Perl itself.
143