Debian Codegraph @

bench/perl/Template/Stash.pm

raw
1 #============================================================= -*-Perl-*-
2 #
3 # Template::Stash
4 #
5 # DESCRIPTION
6 # Definition of an object class which stores and manages access to
7 # variables for the Template Toolkit.
8 #
9 # AUTHOR
10 # Andy Wardley <[email protected]>
11 #
12 # COPYRIGHT
13 # Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
14 #
15 # This module is free software; you can redistribute it and/or
16 # modify it under the same terms as Perl itself.
17 #
18 #============================================================================
19
20 package Template::Stash;
21
22 use strict;
23 use warnings;
24 use Template::VMethods;
25 use Template::Exception;
26 use Scalar::Util qw( blessed reftype );
27
28 our $VERSION = 2.91;
29 our $DEBUG = 0 unless defined $DEBUG;
30 our $PRIVATE = qr/^[_.]/;
31 our $UNDEF_TYPE = 'var.undef';
32 our $UNDEF_INFO = 'undefined variable: %s';
33
34 # alias _dotop() to dotop() so that we have a consistent method name
35 # between the Perl and XS stash implementations
36 *dotop = \&_dotop;
37
38
39 #------------------------------------------------------------------------
40 # Virtual Methods
41 #
42 # If any of $ROOT_OPS, $SCALAR_OPS, $HASH_OPS or $LIST_OPS are already
43 # defined then we merge their contents with the default virtual methods
44 # define by Template::VMethods. Otherwise we can directly alias the
45 # corresponding Template::VMethod package vars.
46 #------------------------------------------------------------------------
47
48 our $ROOT_OPS = defined $ROOT_OPS
49 ? { %{$Template::VMethods::ROOT_VMETHODS}, %$ROOT_OPS }
50 : $Template::VMethods::ROOT_VMETHODS;
51
52 our $SCALAR_OPS = defined $SCALAR_OPS
53 ? { %{$Template::VMethods::TEXT_VMETHODS}, %$SCALAR_OPS }
54 : $Template::VMethods::TEXT_VMETHODS;
55
56 our $HASH_OPS = defined $HASH_OPS
57 ? { %{$Template::VMethods::HASH_VMETHODS}, %$HASH_OPS }
58 : $Template::VMethods::HASH_VMETHODS;
59
60 our $LIST_OPS = defined $LIST_OPS
61 ? { %{$Template::VMethods::LIST_VMETHODS}, %$LIST_OPS }
62 : $Template::VMethods::LIST_VMETHODS;
63
64
65 #------------------------------------------------------------------------
66 # define_vmethod($type, $name, \&sub)
67 #
68 # Defines a virtual method of type $type (SCALAR, HASH, or LIST), with
69 # name $name, that invokes &sub when called. It is expected that &sub
70 # be able to handle the type that it will be called upon.
71 #------------------------------------------------------------------------
72
73 sub define_vmethod {
74 my ($class, $type, $name, $sub) = @_;
75 my $op;
76 $type = lc $type;
77
78 if ($type =~ /^scalar|item$/) {
79 $op = $SCALAR_OPS;
80 }
81 elsif ($type eq 'hash') {
82 $op = $HASH_OPS;
83 }
84 elsif ($type =~ /^list|array$/) {
85 $op = $LIST_OPS;
86 }
87 else {
88 die "invalid vmethod type: $type\n";
89 }
90
91 $op->{ $name } = $sub;
92
93 return 1;
94 }
95
96
97 #========================================================================
98 # ----- CLASS METHODS -----
99 #========================================================================
100
101 #------------------------------------------------------------------------
102 # new(\%params)
103 #
104 # Constructor method which creates a new Template::Stash object.
105 # An optional hash reference may be passed containing variable
106 # definitions that will be used to initialise the stash.
107 #
108 # Returns a reference to a newly created Template::Stash.
109 #------------------------------------------------------------------------
110
111 sub new {
112 my $class = shift;
113 my $params = ref $_[0] eq 'HASH' ? shift(@_) : { @_ };
114
115 my $self = {
116 global => { },
117 %$params,
118 %$ROOT_OPS,
119 '_PARENT' => undef,
120 };
121
122 bless $self, $class;
123 }
124
125
126 #========================================================================
127 # ----- PUBLIC OBJECT METHODS -----
128 #========================================================================
129
130 #------------------------------------------------------------------------
131 # clone(\%params)
132 #
133 # Creates a copy of the current stash object to effect localisation
134 # of variables. The new stash is blessed into the same class as the
135 # parent (which may be a derived class) and has a '_PARENT' member added
136 # which contains a reference to the parent stash that created it
137 # ($self). This member is used in a successive declone() method call to
138 # return the reference to the parent.
139 #
140 # A parameter may be provided which should reference a hash of
141 # variable/values which should be defined in the new stash. The
142 # update() method is called to define these new variables in the cloned
143 # stash.
144 #
145 # Returns a reference to a cloned Template::Stash.
146 #------------------------------------------------------------------------
147
148 sub clone {
149 my ($self, $params) = @_;
150 $params ||= { };
151
152 # look out for magical 'import' argument which imports another hash
153 my $import = $params->{ import };
154 if (defined $import && ref $import eq 'HASH') {
155 delete $params->{ import };
156 }
157 else {
158 undef $import;
159 }
160
161 my $clone = bless {
162 %$self, # copy all parent members
163 %$params, # copy all new data
164 '_PARENT' => $self, # link to parent
165 }, ref $self;
166
167 # perform hash import if defined
168 &{ $HASH_OPS->{ import } }($clone, $import)
169 if defined $import;
170
171 return $clone;
172 }
173
174
175 #------------------------------------------------------------------------
176 # declone($export)
177 #
178 # Returns a reference to the PARENT stash. When called in the following
179 # manner:
180 # $stash = $stash->declone();
181 # the reference count on the current stash will drop to 0 and be "freed"
182 # and the caller will be left with a reference to the parent. This
183 # contains the state of the stash before it was cloned.
184 #------------------------------------------------------------------------
185
186 sub declone {
187 my $self = shift;
188 $self->{ _PARENT } || $self;
189 }
190
191
192 #------------------------------------------------------------------------
193 # get($ident)
194 #
195 # Returns the value for an variable stored in the stash. The variable
196 # may be specified as a simple string, e.g. 'foo', or as an array
197 # reference representing compound variables. In the latter case, each
198 # pair of successive elements in the list represent a node in the
199 # compound variable. The first is the variable name, the second a
200 # list reference of arguments or 0 if undefined. So, the compound
201 # variable [% foo.bar('foo').baz %] would be represented as the list
202 # [ 'foo', 0, 'bar', ['foo'], 'baz', 0 ]. Returns the value of the
203 # identifier or an empty string if undefined. Errors are thrown via
204 # die().
205 #------------------------------------------------------------------------
206
207 sub get {
208 my ($self, $ident, $args) = @_;
209 my ($root, $result);
210 $root = $self;
211
212 if (ref $ident eq 'ARRAY'
213 || ($ident =~ /\./)
214 && ($ident = [ map { s/\(.*$//; ($_, 0) } split(/\./, $ident) ])) {
215 my $size = $#$ident;
216
217 # if $ident is a list reference, then we evaluate each item in the
218 # identifier against the previous result, using the root stash
219 # ($self) as the first implicit 'result'...
220
221 foreach (my $i = 0; $i <= $size; $i += 2) {
222 $result = $self->_dotop($root, @$ident[$i, $i+1]);
223 last unless defined $result;
224 $root = $result;
225 }
226 }
227 else {
228 $result = $self->_dotop($root, $ident, $args);
229 }
230
231 return defined $result
232 ? $result
233 : $self->undefined($ident, $args);
234 }
235
236
237 #------------------------------------------------------------------------
238 # set($ident, $value, $default)
239 #
240 # Updates the value for a variable in the stash. The first parameter
241 # should be the variable name or array, as per get(). The second
242 # parameter should be the intended value for the variable. The third,
243 # optional parameter is a flag which may be set to indicate 'default'
244 # mode. When set true, the variable will only be updated if it is
245 # currently undefined or has a false value. The magical 'IMPORT'
246 # variable identifier may be used to indicate that $value is a hash
247 # reference whose values should be imported. Returns the value set,
248 # or an empty string if not set (e.g. default mode). In the case of
249 # IMPORT, returns the number of items imported from the hash.
250 #------------------------------------------------------------------------
251
252 sub set {
253 my ($self, $ident, $value, $default) = @_;
254 my ($root, $result, $error);
255
256 $root = $self;
257
258 ELEMENT: {
259 if (ref $ident eq 'ARRAY'
260 || ($ident =~ /\./)
261 && ($ident = [ map { s/\(.*$//; ($_, 0) }
262 split(/\./, $ident) ])) {
263
264 # a compound identifier may contain multiple elements (e.g.
265 # foo.bar.baz) and we must first resolve all but the last,
266 # using _dotop() with the $lvalue flag set which will create
267 # intermediate hashes if necessary...
268 my $size = $#$ident;
269 foreach (my $i = 0; $i < $size - 2; $i += 2) {
270 $result = $self->_dotop($root, @$ident[$i, $i+1], 1);
271 last ELEMENT unless defined $result;
272 $root = $result;
273 }
274
275 # then we call _assign() to assign the value to the last element
276 $result = $self->_assign($root, @$ident[$size-1, $size],
277 $value, $default);
278 }
279 else {
280 $result = $self->_assign($root, $ident, 0, $value, $default);
281 }
282 }
283
284 return defined $result ? $result : '';
285 }
286
287
288 #------------------------------------------------------------------------
289 # getref($ident)
290 #
291 # Returns a "reference" to a particular item. This is represented as a
292 # closure which will return the actual stash item when called.
293 # WARNING: still experimental!
294 #------------------------------------------------------------------------
295
296 sub getref {
297 my ($self, $ident, $args) = @_;
298 my ($root, $item, $result);
299 $root = $self;
300
301 if (ref $ident eq 'ARRAY') {
302 my $size = $#$ident;
303
304 foreach (my $i = 0; $i <= $size; $i += 2) {
305 ($item, $args) = @$ident[$i, $i + 1];
306 last if $i >= $size - 2; # don't evaluate last node
307 last unless defined
308 ($root = $self->_dotop($root, $item, $args));
309 }
310 }
311 else {
312 $item = $ident;
313 }
314
315 if (defined $root) {
316 return sub { my @args = (@{$args||[]}, @_);
317 $self->_dotop($root, $item, \@args);
318 }
319 }
320 else {
321 return sub { '' };
322 }
323 }
324
325
326
327
328 #------------------------------------------------------------------------
329 # update(\%params)
330 #
331 # Update multiple variables en masse. No magic is performed. Simple
332 # variable names only.
333 #------------------------------------------------------------------------
334
335 sub update {
336 my ($self, $params) = @_;
337
338 # look out for magical 'import' argument to import another hash
339 my $import = $params->{ import };
340 if (defined $import && ref $import eq 'HASH') {
341 @$self{ keys %$import } = values %$import;
342 delete $params->{ import };
343 }
344
345 @$self{ keys %$params } = values %$params;
346 }
347
348
349 #------------------------------------------------------------------------
350 # undefined($ident, $args)
351 #
352 # Method called when a get() returns an undefined value. Can be redefined
353 # in a subclass to implement alternate handling.
354 #------------------------------------------------------------------------
355
356 sub undefined {
357 my ($self, $ident, $args) = @_;
358
359 if ($self->{ _STRICT }) {
360 # Sorry, but we can't provide a sensible source file and line without
361 # re-designing the whole architecure of TT (see TT3)
362 die Template::Exception->new(
363 $UNDEF_TYPE,
364 sprintf(
365 $UNDEF_INFO,
366 $self->_reconstruct_ident($ident)
367 )
368 ) if $self->{ _STRICT };
369 }
370 else {
371 # There was a time when I thought this was a good idea. But it's not.
372 return '';
373 }
374 }
375
376 sub _reconstruct_ident {
377 my ($self, $ident) = @_;
378 my ($name, $args, @output);
379 my @input = ref $ident eq 'ARRAY' ? @$ident : ($ident);
380
381 while (@input) {
382 $name = shift @input;
383 $args = shift @input || 0;
384 $name .= '(' . join(', ', map { /^\d+$/ ? $_ : "'$_'" } @$args) . ')'
385 if $args && ref $args eq 'ARRAY';
386 push(@output, $name);
387 }
388
389 return join('.', @output);
390 }
391
392
393 #========================================================================
394 # ----- PRIVATE OBJECT METHODS -----
395 #========================================================================
396
397 #------------------------------------------------------------------------
398 # _dotop($root, $item, \@args, $lvalue)
399 #
400 # This is the core 'dot' operation method which evaluates elements of
401 # variables against their root. All variables have an implicit root
402 # which is the stash object itself (a hash). Thus, a non-compound
403 # variable 'foo' is actually '(stash.)foo', the compound 'foo.bar' is
404 # '(stash.)foo.bar'. The first parameter is a reference to the current
405 # root, initially the stash itself. The second parameter contains the
406 # name of the variable element, e.g. 'foo'. The third optional
407 # parameter is a reference to a list of any parenthesised arguments
408 # specified for the variable, which are passed to sub-routines, object
409 # methods, etc. The final parameter is an optional flag to indicate
410 # if this variable is being evaluated on the left side of an assignment
411 # (e.g. foo.bar.baz = 10). When set true, intermediated hashes will
412 # be created (e.g. bar) if necessary.
413 #
414 # Returns the result of evaluating the item against the root, having
415 # performed any variable "magic". The value returned can then be used
416 # as the root of the next _dotop() in a compound sequence. Returns
417 # undef if the variable is undefined.
418 #------------------------------------------------------------------------
419
420 sub _dotop {
421 my ($self, $root, $item, $args, $lvalue) = @_;
422 my $rootref = ref $root;
423 my $atroot = (blessed $root && $root->isa(ref $self));
424 my ($value, @result);
425
426 $args ||= [ ];
427 $lvalue ||= 0;
428
429 # print STDERR "_dotop(root=$root, item=$item, args=[@$args])\n"
430 # if $DEBUG;
431
432 # return undef without an error if either side of the dot is unviable
433 return undef unless defined($root) and defined($item);
434
435 # or if an attempt is made to access a private member, starting _ or .
436 return undef if $PRIVATE && $item =~ /$PRIVATE/;
437
438 if ($atroot || $rootref eq 'HASH') {
439 # if $root is a regular HASH or a Template::Stash kinda HASH (the
440 # *real* root of everything). We first lookup the named key
441 # in the hash, or create an empty hash in its place if undefined
442 # and the $lvalue flag is set. Otherwise, we check the HASH_OPS
443 # pseudo-methods table, calling the code if found, or return undef.
444
445 if (defined($value = $root->{ $item })) {
446 return $value unless ref $value eq 'CODE'; ## RETURN
447 @result = &$value(@$args); ## @result
448 }
449 elsif ($lvalue) {
450 # we create an intermediate hash if this is an lvalue
451 return $root->{ $item } = { }; ## RETURN
452 }
453 # ugly hack: only allow import vmeth to be called on root stash
454 elsif (($value = $HASH_OPS->{ $item })
455 && ! $atroot || $item eq 'import') {
456 @result = &$value($root, @$args); ## @result
457 }
458 elsif ( ref $item eq 'ARRAY' ) {
459 # hash slice
460 return [@$root{@$item}]; ## RETURN
461 }
462 }
463 elsif ($rootref eq 'ARRAY') {
464 # if root is an ARRAY then we check for a LIST_OPS pseudo-method
465 # or return the numerical index into the array, or undef
466 if ($value = $LIST_OPS->{ $item }) {
467 @result = &$value($root, @$args); ## @result
468 }
469 elsif ($item =~ /^-?\d+$/) {
470 $value = $root->[$item];
471 return $value unless ref $value eq 'CODE'; ## RETURN
472 @result = &$value(@$args); ## @result
473 }
474 elsif ( ref $item eq 'ARRAY' ) {
475 # array slice
476 return [@$root[@$item]]; ## RETURN
477 }
478 }
479
480 # NOTE: we do the can-can because UNIVSERAL::isa($something, 'UNIVERSAL')
481 # doesn't appear to work with CGI, returning true for the first call
482 # and false for all subsequent calls.
483
484 # UPDATE: that doesn't appear to be the case any more
485
486 elsif (blessed($root) && $root->can('can')) {
487
488 # if $root is a blessed reference (i.e. inherits from the
489 # UNIVERSAL object base class) then we call the item as a method.
490 # If that fails then we try to fallback on HASH behaviour if
491 # possible.
492 eval { @result = $root->$item(@$args); };
493
494 if ($@) {
495 # temporary hack - required to propogate errors thrown
496 # by views; if $@ is a ref (e.g. Template::Exception
497 # object then we assume it's a real error that needs
498 # real throwing
499
500 my $class = ref($root) || $root;
501 die $@ if ref($@) || ($@ !~ /Can't locate object method "\Q$item\E" via package "\Q$class\E"/);
502
503 # failed to call object method, so try some fallbacks
504 if (reftype $root eq 'HASH') {
505 if( defined($value = $root->{ $item })) {
506 return $value unless ref $value eq 'CODE'; ## RETURN
507 @result = &$value(@$args);
508 }
509 elsif ($value = $HASH_OPS->{ $item }) {
510 @result = &$value($root, @$args);
511 }
512 elsif ($value = $LIST_OPS->{ $item }) {
513 @result = &$value([$root], @$args);
514 }
515 }
516 elsif (reftype $root eq 'ARRAY') {
517 if( $value = $LIST_OPS->{ $item }) {
518 @result = &$value($root, @$args);
519 }
520 elsif( $item =~ /^-?\d+$/ ) {
521 $value = $root->[$item];
522 return $value unless ref $value eq 'CODE'; ## RETURN
523 @result = &$value(@$args); ## @result
524 }
525 elsif ( ref $item eq 'ARRAY' ) {
526 # array slice
527 return [@$root[@$item]]; ## RETURN
528 }
529 }
530 elsif ($value = $SCALAR_OPS->{ $item }) {
531 @result = &$value($root, @$args);
532 }
533 elsif ($value = $LIST_OPS->{ $item }) {
534 @result = &$value([$root], @$args);
535 }
536 elsif ($self->{ _DEBUG }) {
537 @result = (undef, $@);
538 }
539 }
540 }
541 elsif (($value = $SCALAR_OPS->{ $item }) && ! $lvalue) {
542 # at this point, it doesn't look like we've got a reference to
543 # anything we know about, so we try the SCALAR_OPS pseudo-methods
544 # table (but not for l-values)
545 @result = &$value($root, @$args); ## @result
546 }
547 elsif (($value = $LIST_OPS->{ $item }) && ! $lvalue) {
548 # last-ditch: can we promote a scalar to a one-element
549 # list and apply a LIST_OPS virtual method?
550 @result = &$value([$root], @$args);
551 }
552 elsif ($self->{ _DEBUG }) {
553 die "don't know how to access [ $root ].$item\n"; ## DIE
554 }
555 else {
556 @result = ();
557 }
558
559 # fold multiple return items into a list unless first item is undef
560 if (defined $result[0]) {
561 return ## RETURN
562 scalar @result > 1 ? [ @result ] : $result[0];
563 }
564 elsif (defined $result[1]) {
565 die $result[1]; ## DIE
566 }
567 elsif ($self->{ _DEBUG }) {
568 die "$item is undefined\n"; ## DIE
569 }
570
571 return undef;
572 }
573
574
575 #------------------------------------------------------------------------
576 # _assign($root, $item, \@args, $value, $default)
577 #
578 # Similar to _dotop() above, but assigns a value to the given variable
579 # instead of simply returning it. The first three parameters are the
580 # root item, the item and arguments, as per _dotop(), followed by the
581 # value to which the variable should be set and an optional $default
582 # flag. If set true, the variable will only be set if currently false
583 # (undefined/zero)
584 #------------------------------------------------------------------------
585
586 sub _assign {
587 my ($self, $root, $item, $args, $value, $default) = @_;
588 my $rootref = ref $root;
589 my $atroot = ($root eq $self);
590 my $result;
591 $args ||= [ ];
592 $default ||= 0;
593
594 # return undef without an error if either side of the dot is unviable
595 return undef unless $root and defined $item;
596
597 # or if an attempt is made to update a private member, starting _ or .
598 return undef if $PRIVATE && $item =~ /$PRIVATE/;
599
600 if ($rootref eq 'HASH' || $atroot) {
601 # if the root is a hash we set the named key
602 return ($root->{ $item } = $value) ## RETURN
603 unless $default && $root->{ $item };
604 }
605 elsif ($rootref eq 'ARRAY' && $item =~ /^-?\d+$/) {
606 # or set a list item by index number
607 return ($root->[$item] = $value) ## RETURN
608 unless $default && $root->{ $item };
609 }
610 elsif (blessed($root)) {
611 # try to call the item as a method of an object
612
613 return $root->$item(@$args, $value) ## RETURN
614 unless $default && $root->$item();
615
616 # 2 issues:
617 # - method call should be wrapped in eval { }
618 # - fallback on hash methods if object method not found
619 #
620 # eval { $result = $root->$item(@$args, $value); };
621 #
622 # if ($@) {
623 # die $@ if ref($@) || ($@ !~ /Can't locate object method/);
624 #
625 # # failed to call object method, so try some fallbacks
626 # if (UNIVERSAL::isa($root, 'HASH') && exists $root->{ $item }) {
627 # $result = ($root->{ $item } = $value)
628 # unless $default && $root->{ $item };
629 # }
630 # }
631 # return $result; ## RETURN
632 }
633 else {
634 die "don't know how to assign to [$root].[$item]\n"; ## DIE
635 }
636
637 return undef;
638 }
639
640
641 #------------------------------------------------------------------------
642 # _dump()
643 #
644 # Debug method which returns a string representing the internal state
645 # of the object. The method calls itself recursively to dump sub-hashes.
646 #------------------------------------------------------------------------
647
648 sub _dump {
649 my $self = shift;
650 return "[Template::Stash] " . $self->_dump_frame(2);
651 }
652
653 sub _dump_frame {
654 my ($self, $indent) = @_;
655 $indent ||= 1;
656 my $buffer = ' ';
657 my $pad = $buffer x $indent;
658 my $text = "{\n";
659 local $" = ', ';
660
661 my ($key, $value);
662
663 return $text . "...excessive recursion, terminating\n"
664 if $indent > 32;
665
666 foreach $key (keys %$self) {
667 $value = $self->{ $key };
668 $value = '<undef>' unless defined $value;
669 next if $key =~ /^\./;
670 if (ref($value) eq 'ARRAY') {
671 $value = '[ ' . join(', ', map { defined $_ ? $_ : '<undef>' }
672 @$value) . ' ]';
673 }
674 elsif (ref $value eq 'HASH') {
675 $value = _dump_frame($value, $indent + 1);
676 }
677
678 $text .= sprintf("$pad%-16s => $value\n", $key);
679 }
680 $text .= $buffer x ($indent - 1) . '}';
681 return $text;
682 }
683
684
685 1;
686
687 __END__
688
689 =head1 NAME
690
691 Template::Stash - Magical storage for template variables
692
693 =head1 SYNOPSIS
694
695 use Template::Stash;
696
697 my $stash = Template::Stash->new(\%vars);
698
699 # get variable values
700 $value = $stash->get($variable);
701 $value = $stash->get(\@compound);
702
703 # set variable value
704 $stash->set($variable, $value);
705 $stash->set(\@compound, $value);
706
707 # default variable value
708 $stash->set($variable, $value, 1);
709 $stash->set(\@compound, $value, 1);
710
711 # set variable values en masse
712 $stash->update(\%new_vars)
713
714 # methods for (de-)localising variables
715 $stash = $stash->clone(\%new_vars);
716 $stash = $stash->declone();
717
718 =head1 DESCRIPTION
719
720 The C<Template::Stash> module defines an object class which is used to store
721 variable values for the runtime use of the template processor. Variable
722 values are stored internally in a hash reference (which itself is blessed
723 to create the object) and are accessible via the L<get()> and L<set()> methods.
724
725 Variables may reference hash arrays, lists, subroutines and objects
726 as well as simple values. The stash automatically performs the right
727 magic when dealing with variables, calling code or object methods,
728 indexing into lists, hashes, etc.
729
730 The stash has L<clone()> and L<declone()> methods which are used by the
731 template processor to make temporary copies of the stash for
732 localising changes made to variables.
733
734 =head1 PUBLIC METHODS
735
736 =head2 new(\%params)
737
738 The C<new()> constructor method creates and returns a reference to a new
739 C<Template::Stash> object.
740
741 my $stash = Template::Stash->new();
742
743 A hash reference may be passed to provide variables and values which
744 should be used to initialise the stash.
745
746 my $stash = Template::Stash->new({ var1 => 'value1',
747 var2 => 'value2' });
748
749 =head2 get($variable)
750
751 The C<get()> method retrieves the variable named by the first parameter.
752
753 $value = $stash->get('var1');
754
755 Dotted compound variables can be retrieved by specifying the variable
756 elements by reference to a list. Each node in the variable occupies
757 two entries in the list. The first gives the name of the variable
758 element, the second is a reference to a list of arguments for that
759 element, or C<0> if none.
760
761 [% foo.bar(10).baz(20) %]
762
763 $stash->get([ 'foo', 0, 'bar', [ 10 ], 'baz', [ 20 ] ]);
764
765 =head2 set($variable, $value, $default)
766
767 The C<set()> method sets the variable name in the first parameter to the
768 value specified in the second.
769
770 $stash->set('var1', 'value1');
771
772 If the third parameter evaluates to a true value, the variable is
773 set only if it did not have a true value before.
774
775 $stash->set('var2', 'default_value', 1);
776
777 Dotted compound variables may be specified as per L<get()> above.
778
779 [% foo.bar = 30 %]
780
781 $stash->set([ 'foo', 0, 'bar', 0 ], 30);
782
783 The magical variable 'C<IMPORT>' can be specified whose corresponding
784 value should be a hash reference. The contents of the hash array are
785 copied (i.e. imported) into the current namespace.
786
787 # foo.bar = baz, foo.wiz = waz
788 $stash->set('foo', { 'bar' => 'baz', 'wiz' => 'waz' });
789
790 # import 'foo' into main namespace: bar = baz, wiz = waz
791 $stash->set('IMPORT', $stash->get('foo'));
792
793 =head2 clone(\%params)
794
795 The C<clone()> method creates and returns a new C<Template::Stash> object
796 which represents a localised copy of the parent stash. Variables can be freely
797 updated in the cloned stash and when L<declone()> is called, the original stash
798 is returned with all its members intact and in the same state as they were
799 before C<clone()> was called.
800
801 For convenience, a hash of parameters may be passed into C<clone()> which
802 is used to update any simple variable (i.e. those that don't contain any
803 namespace elements like C<foo> and C<bar> but not C<foo.bar>) variables while
804 cloning the stash. For adding and updating complex variables, the L<set()>
805 method should be used after calling C<clone().> This will correctly resolve
806 and/or create any necessary namespace hashes.
807
808 A cloned stash maintains a reference to the stash that it was copied
809 from in its C<_PARENT> member.
810
811 =head2 declone()
812
813 The C<declone()> method returns the C<_PARENT> reference and can be used to
814 restore the state of a stash as described above.
815
816 =head1 AUTHOR
817
818 Andy Wardley E<lt>[email protected]<gt> L<http://wardley.org/>
819
820 =head1 COPYRIGHT
821
822 Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
823
824 This module is free software; you can redistribute it and/or
825 modify it under the same terms as Perl itself.
826
827 =head1 SEE ALSO
828
829 L<Template>, L<Template::Context>
830
831 =cut
832
833 # Local Variables:
834 # mode: perl
835 # perl-indent-level: 4
836 # indent-tabs-mode: nil
837 # End:
838 #
839 # vim: expandtab shiftwidth=4: