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
45       template processor to make temporary copies of the stash for localising
46       changes made to variables.
47

PUBLIC METHODS

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

AUTHOR

126       Andy Wardley <abw@wardley.org> <http://wardley.org/>
127

129       Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
130
131       This module is free software; you can redistribute it and/or modify it
132       under the same terms as Perl itself.
133

SEE ALSO

135       Template, Template::Context
136
137
138
139perl v5.10.1                      2009-05-20                Template::Stash(3)
Impressum