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
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   update($variables)
104       This method can be used to set or update several variables in one go.
105
106           $stash->update({
107               foo => 10,
108               bar => 20,
109           });
110
111   getref($variable)
112       This undocumented feature returns a closure which can be called to get
113       the value of a variable.  It is used to implement variable references
114       which are evaluated lazily.
115
116           [% x = \foo.bar.baz %]          # x is a reference to foo.bar.baz
117           [% x %]                         # evalautes foo.bar.baz
118
119   clone(\%params)
120       The "clone()" method creates and returns a new "Template::Stash" object
121       which represents a localised copy of the parent stash. Variables can be
122       freely updated in the cloned stash and when declone() is called, the
123       original stash is returned with all its members intact and in the same
124       state as they were before "clone()" was called.
125
126       For convenience, a hash of parameters may be passed into "clone()"
127       which is used to update any simple variable (i.e. those that don't
128       contain any namespace elements like "foo" and "bar" but not "foo.bar")
129       variables while cloning the stash.  For adding and updating complex
130       variables, the set() method should be used after calling "clone()."
131       This will correctly resolve and/or create any necessary namespace
132       hashes.
133
134       A cloned stash maintains a reference to the stash that it was copied
135       from in its "_PARENT" member.
136
137   declone()
138       The "declone()" method returns the "_PARENT" reference and can be used
139       to restore the state of a stash as described above.
140
141   define_vmethod($type, $name, $code)
142       This method can be used to define new virtual methods.  The first
143       argument should be either "scalar" or "item" to define scalar virtual
144       method, "hash" to define hash virtual methods, or either "array" or
145       "list" for list virtual methods.  The second argument should be the
146       name of the new method.  The third argument should be a reference to a
147       subroutine implementing the method.  The data item on which the virtual
148       method is called is passed to the subroutine as the first argument.
149
150           $stash->define_vmethod(
151               item => ucfirst => sub {
152                   my $text = shift;
153                   return ucfirst $text
154               }
155           );
156

INTERNAL METHODS

158   dotop($root, $item, \@args, $lvalue)
159       This is the core "dot" operation method which evaluates elements of
160       variables against their root.
161
162   undefined($ident, $args)
163       This method is called when get() encounters an undefined value.  If the
164       STRICT option is in effect then it will throw an exception indicating
165       the use of an undefined value.  Otherwise it will silently return an
166       empty string.
167
168       The method can be redefined in a subclass to implement alternate
169       handling of undefined values.
170

AUTHOR

172       Andy Wardley <abw@wardley.org> <http://wardley.org/>
173

COPYRIGHT

175       Copyright (C) 1996-2013 Andy Wardley.  All Rights Reserved.
176
177       This module is free software; you can redistribute it and/or modify it
178       under the same terms as Perl itself.
179