1#============================================================= -*-Perl-*- 2# 3# Template::Context 4# 5# DESCRIPTION 6# Module defining a context in which a template document is processed. 7# This is the runtime processing interface through which templates 8# can access the functionality of the Template Toolkit. 9# 10# AUTHOR 11# Andy Wardley <abw@wardley.org> 12# 13# COPYRIGHT 14# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. 15# 16# This module is free software; you can redistribute it and/or 17# modify it under the same terms as Perl itself. 18# 19#============================================================================ 20 21package Template::Context; 22 23use strict; 24use warnings; 25use base 'Template::Base'; 26 27use Template::Base; 28use Template::Config; 29use Template::Constants; 30use Template::Exception; 31use Scalar::Util 'blessed'; 32 33use constant DOCUMENT => 'Template::Document'; 34use constant EXCEPTION => 'Template::Exception'; 35use constant BADGER_EXCEPTION => 'Badger::Exception'; 36 37our $VERSION = 2.98; 38our $DEBUG = 0 unless defined $DEBUG; 39our $DEBUG_FORMAT = "\n## \$file line \$line : [% \$text %] ##\n"; 40our $VIEW_CLASS = 'Template::View'; 41our $AUTOLOAD; 42 43#======================================================================== 44# ----- PUBLIC METHODS ----- 45#======================================================================== 46 47#------------------------------------------------------------------------ 48# template($name) 49# 50# General purpose method to fetch a template and return it in compiled 51# form. In the usual case, the $name parameter will be a simple string 52# containing the name of a template (e.g. 'header'). It may also be 53# a reference to Template::Document object (or sub-class) or a Perl 54# sub-routine. These are considered to be compiled templates and are 55# returned intact. Finally, it may be a reference to any other kind 56# of valid input source accepted by Template::Provider (e.g. scalar 57# ref, glob, IO handle, etc). 58# 59# Templates may be cached at one of 3 different levels. The internal 60# BLOCKS member is a local cache which holds references to all 61# template blocks used or imported via PROCESS since the context's 62# reset() method was last called. This is checked first and if the 63# template is not found, the method then walks down the BLOCKSTACK 64# list. This contains references to the block definition tables in 65# any enclosing Template::Documents that we're visiting (e.g. we've 66# been called via an INCLUDE and we want to access a BLOCK defined in 67# the template that INCLUDE'd us). If nothing is defined, then we 68# iterate through the LOAD_TEMPLATES providers list as a 'chain of 69# responsibility' (see Design Patterns) asking each object to fetch() 70# the template if it can. 71# 72# Returns the compiled template. On error, undef is returned and 73# the internal ERROR value (read via error()) is set to contain an 74# error message of the form "$name: $error". 75#------------------------------------------------------------------------ 76 77sub template { 78 my ($self, $name) = @_; 79 my ($prefix, $blocks, $defblocks, $provider, $template, $error); 80 my ($shortname, $blockname, $providers); 81 82 $self->debug("template($name)") if $self->{ DEBUG }; 83 84 # references to Template::Document (or sub-class) objects, or 85 # CODE references are assumed to be pre-compiled templates and are 86 # returned intact 87 return $name 88 if (blessed($name) && $name->isa(DOCUMENT)) 89 || ref($name) eq 'CODE'; 90 91 $shortname = $name; 92 93 unless (ref $name) { 94 95 $self->debug("looking for block [$name]") if $self->{ DEBUG }; 96 97 # we first look in the BLOCKS hash for a BLOCK that may have 98 # been imported from a template (via PROCESS) 99 return $template 100 if ($template = $self->{ BLOCKS }->{ $name }); 101 102 # then we iterate through the BLKSTACK list to see if any of the 103 # Template::Documents we're visiting define this BLOCK 104 foreach $blocks (@{ $self->{ BLKSTACK } }) { 105 return $template 106 if $blocks && ($template = $blocks->{ $name }); 107 } 108 109 # now it's time to ask the providers, so we look to see if any 110 # prefix is specified to indicate the desired provider set. 111 if ($^O eq 'MSWin32') { 112 # let C:/foo through 113 $prefix = $1 if $shortname =~ s/^(\w{2,})://o; 114 } 115 else { 116 $prefix = $1 if $shortname =~ s/^(\w+)://; 117 } 118 119 if (defined $prefix) { 120 $providers = $self->{ PREFIX_MAP }->{ $prefix } 121 || return $self->throw( Template::Constants::ERROR_FILE, 122 "no providers for template prefix '$prefix'"); 123 } 124 } 125 $providers = $self->{ PREFIX_MAP }->{ default } 126 || $self->{ LOAD_TEMPLATES } 127 unless $providers; 128 129 130 # Finally we try the regular template providers which will 131 # handle references to files, text, etc., as well as templates 132 # reference by name. If 133 134 $blockname = ''; 135 while ($shortname) { 136 $self->debug("asking providers for [$shortname] [$blockname]") 137 if $self->{ DEBUG }; 138 139 foreach my $provider (@$providers) { 140 ($template, $error) = $provider->fetch($shortname, $prefix); 141 if ($error) { 142 if ($error == Template::Constants::STATUS_ERROR) { 143 # $template contains exception object 144 if (blessed($template) && $template->isa(EXCEPTION) 145 && $template->type eq Template::Constants::ERROR_FILE) { 146 $self->throw($template); 147 } 148 else { 149 $self->throw( Template::Constants::ERROR_FILE, $template ); 150 } 151 } 152 # DECLINE is ok, carry on 153 } 154 elsif (length $blockname) { 155 return $template 156 if $template = $template->blocks->{ $blockname }; 157 } 158 else { 159 return $template; 160 } 161 } 162 163 last if ref $shortname || ! $self->{ EXPOSE_BLOCKS }; 164 $shortname =~ s{/([^/]+)$}{} || last; 165 $blockname = length $blockname ? "$1/$blockname" : $1; 166 } 167 168 $self->throw(Template::Constants::ERROR_FILE, "$name: not found"); 169} 170 171 172#------------------------------------------------------------------------ 173# plugin($name, \@args) 174# 175# Calls on each of the LOAD_PLUGINS providers in turn to fetch() (i.e. load 176# and instantiate) a plugin of the specified name. Additional parameters 177# passed are propagated to the new() constructor for the plugin. 178# Returns a reference to a new plugin object or other reference. On 179# error, undef is returned and the appropriate error message is set for 180# subsequent retrieval via error(). 181#------------------------------------------------------------------------ 182 183sub plugin { 184 my ($self, $name, $args) = @_; 185 my ($provider, $plugin, $error); 186 187 $self->debug("plugin($name, ", defined $args ? @$args : '[ ]', ')') 188 if $self->{ DEBUG }; 189 190 # request the named plugin from each of the LOAD_PLUGINS providers in turn 191 foreach my $provider (@{ $self->{ LOAD_PLUGINS } }) { 192 ($plugin, $error) = $provider->fetch($name, $args, $self); 193 return $plugin unless $error; 194 if ($error == Template::Constants::STATUS_ERROR) { 195 $self->throw($plugin) if ref $plugin; 196 $self->throw(Template::Constants::ERROR_PLUGIN, $plugin); 197 } 198 } 199 200 $self->throw(Template::Constants::ERROR_PLUGIN, "$name: plugin not found"); 201} 202 203 204#------------------------------------------------------------------------ 205# filter($name, \@args, $alias) 206# 207# Similar to plugin() above, but querying the LOAD_FILTERS providers to 208# return filter instances. An alias may be provided which is used to 209# save the returned filter in a local cache. 210#------------------------------------------------------------------------ 211 212sub filter { 213 my ($self, $name, $args, $alias) = @_; 214 my ($provider, $filter, $error); 215 216 $self->debug("filter($name, ", 217 defined $args ? @$args : '[ ]', 218 defined $alias ? $alias : '<no alias>', ')') 219 if $self->{ DEBUG }; 220 221 # use any cached version of the filter if no params provided 222 return $filter 223 if ! $args && ! ref $name 224 && ($filter = $self->{ FILTER_CACHE }->{ $name }); 225 226 # request the named filter from each of the FILTERS providers in turn 227 foreach my $provider (@{ $self->{ LOAD_FILTERS } }) { 228 ($filter, $error) = $provider->fetch($name, $args, $self); 229 last unless $error; 230 if ($error == Template::Constants::STATUS_ERROR) { 231 $self->throw($filter) if ref $filter; 232 $self->throw(Template::Constants::ERROR_FILTER, $filter); 233 } 234 # return $self->error($filter) 235 # if $error == &Template::Constants::STATUS_ERROR; 236 } 237 238 return $self->error("$name: filter not found") 239 unless $filter; 240 241 # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 242 # commented out by abw on 19 Nov 2001 to fix problem with xmlstyle 243 # plugin which may re-define a filter by calling define_filter() 244 # multiple times. With the automatic aliasing/caching below, any 245 # new filter definition isn't seen. Don't think this will cause 246 # any problems as filters explicitly supplied with aliases will 247 # still work as expected. 248 # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 249 # alias defaults to name if undefined 250 # $alias = $name 251 # unless defined($alias) or ref($name) or $args; 252 253 # cache FILTER if alias is valid 254 $self->{ FILTER_CACHE }->{ $alias } = $filter 255 if $alias; 256 257 return $filter; 258} 259 260 261#------------------------------------------------------------------------ 262# view(\%config) 263# 264# Create a new Template::View bound to this context. 265#------------------------------------------------------------------------ 266 267sub view { 268 my $self = shift; 269 require Template::View; 270 return $VIEW_CLASS->new($self, @_) 271 || $self->throw(&Template::Constants::ERROR_VIEW, 272 $VIEW_CLASS->error); 273} 274 275 276#------------------------------------------------------------------------ 277# process($template, \%params) [% PROCESS template var=val ... %] 278# process($template, \%params, $local) [% INCLUDE template var=val ... %] 279# 280# Processes the template named or referenced by the first parameter. 281# The optional second parameter may reference a hash array of variable 282# definitions. These are set before the template is processed by 283# calling update() on the stash. Note that, unless the third parameter 284# is true, the context is not localised and these, and any other 285# variables set in the template will retain their new values after this 286# method returns. The third parameter is in place so that this method 287# can handle INCLUDE calls: the stash will be localized. 288# 289# Returns the output of processing the template. Errors are thrown 290# as Template::Exception objects via die(). 291#------------------------------------------------------------------------ 292 293sub process { 294 my ($self, $template, $params, $localize) = @_; 295 my ($trim, $blocks) = @$self{ qw( TRIM BLOCKS ) }; 296 my (@compiled, $name, $compiled); 297 my ($stash, $component, $tblocks, $error, $tmpout); 298 my $output = ''; 299 300 $template = [ $template ] unless ref $template eq 'ARRAY'; 301 302 $self->debug("process([ ", join(', '), @$template, ' ], ', 303 defined $params ? $params : '<no params>', ', ', 304 $localize ? '<localized>' : '<unlocalized>', ')') 305 if $self->{ DEBUG }; 306 307 # fetch compiled template for each name specified 308 foreach $name (@$template) { 309 push(@compiled, $self->template($name)); 310 } 311 312 if ($localize) { 313 # localise the variable stash with any parameters passed 314 $stash = $self->{ STASH } = $self->{ STASH }->clone($params); 315 } else { 316 # update stash with any new parameters passed 317 $self->{ STASH }->update($params); 318 $stash = $self->{ STASH }; 319 } 320 321 eval { 322 # save current component 323 eval { $component = $stash->get('component') }; 324 325 foreach $name (@$template) { 326 $compiled = shift @compiled; 327 my $element = ref $compiled eq 'CODE' 328 ? { (name => (ref $name ? '' : $name), modtime => time()) } 329 : $compiled; 330 331 if (blessed($component) && $component->isa(DOCUMENT)) { 332 $element->{ caller } = $component->{ name }; 333 $element->{ callers } = $component->{ callers } || []; 334 push(@{$element->{ callers }}, $element->{ caller }); 335 } 336 337 $stash->set('component', $element); 338 339 unless ($localize) { 340 # merge any local blocks defined in the Template::Document 341 # into our local BLOCKS cache 342 @$blocks{ keys %$tblocks } = values %$tblocks 343 if (blessed($compiled) && $compiled->isa(DOCUMENT)) 344 && ($tblocks = $compiled->blocks); 345 } 346 347 if (ref $compiled eq 'CODE') { 348 $tmpout = &$compiled($self); 349 } 350 elsif (ref $compiled) { 351 $tmpout = $compiled->process($self); 352 } 353 else { 354 $self->throw('file', 355 "invalid template reference: $compiled"); 356 } 357 358 if ($trim) { 359 for ($tmpout) { 360 s/^\s+//; 361 s/\s+$//; 362 } 363 } 364 $output .= $tmpout; 365 366 # pop last item from callers. 367 # NOTE - this will not be called if template throws an 368 # error. The whole issue of caller and callers should be 369 # revisited to try and avoid putting this info directly into 370 # the component data structure. Perhaps use a local element 371 # instead? 372 373 pop(@{$element->{ callers }}) 374 if (blessed($component) && $component->isa(DOCUMENT)); 375 } 376 $stash->set('component', $component); 377 }; 378 $error = $@; 379 380 if ($localize) { 381 # ensure stash is delocalised before dying 382 $self->{ STASH } = $self->{ STASH }->declone(); 383 } 384 385 $self->throw(ref $error 386 ? $error : (Template::Constants::ERROR_FILE, $error)) 387 if $error; 388 389 return $output; 390} 391 392 393#------------------------------------------------------------------------ 394# include($template, \%params) [% INCLUDE template var = val, ... %] 395# 396# Similar to process() above but processing the template in a local 397# context. Any variables passed by reference to a hash as the second 398# parameter will be set before the template is processed and then 399# revert to their original values before the method returns. Similarly, 400# any changes made to non-global variables within the template will 401# persist only until the template is processed. 402# 403# Returns the output of processing the template. Errors are thrown 404# as Template::Exception objects via die(). 405#------------------------------------------------------------------------ 406 407sub include { 408 my ($self, $template, $params) = @_; 409 return $self->process($template, $params, 'localize me!'); 410} 411 412#------------------------------------------------------------------------ 413# insert($file) 414# 415# Insert the contents of a file without parsing. 416#------------------------------------------------------------------------ 417 418sub insert { 419 my ($self, $file) = @_; 420 my ($prefix, $providers, $text, $error); 421 my $output = ''; 422 423 my $files = ref $file eq 'ARRAY' ? $file : [ $file ]; 424 425 $self->debug("insert([ ", join(', '), @$files, " ])") 426 if $self->{ DEBUG }; 427 428 429 FILE: foreach $file (@$files) { 430 my $name = $file; 431 432 if ($^O eq 'MSWin32') { 433 # let C:/foo through 434 $prefix = $1 if $name =~ s/^(\w{2,})://o; 435 } 436 else { 437 $prefix = $1 if $name =~ s/^(\w+)://; 438 } 439 440 if (defined $prefix) { 441 $providers = $self->{ PREFIX_MAP }->{ $prefix } 442 || return $self->throw(Template::Constants::ERROR_FILE, 443 "no providers for file prefix '$prefix'"); 444 } 445 else { 446 $providers = $self->{ PREFIX_MAP }->{ default } 447 || $self->{ LOAD_TEMPLATES }; 448 } 449 450 foreach my $provider (@$providers) { 451 ($text, $error) = $provider->load($name, $prefix); 452 next FILE unless $error; 453 if ($error == Template::Constants::STATUS_ERROR) { 454 $self->throw($text) if ref $text; 455 $self->throw(Template::Constants::ERROR_FILE, $text); 456 } 457 } 458 $self->throw(Template::Constants::ERROR_FILE, "$file: not found"); 459 } 460 continue { 461 $output .= $text; 462 } 463 return $output; 464} 465 466 467#------------------------------------------------------------------------ 468# throw($type, $info, \$output) [% THROW errtype "Error info" %] 469# 470# Throws a Template::Exception object by calling die(). This method 471# may be passed a reference to an existing Template::Exception object; 472# a single value containing an error message which is used to 473# instantiate a Template::Exception of type 'undef'; or a pair of 474# values representing the exception type and info from which a 475# Template::Exception object is instantiated. e.g. 476# 477# $context->throw($exception); 478# $context->throw("I'm sorry Dave, I can't do that"); 479# $context->throw('denied', "I'm sorry Dave, I can't do that"); 480# 481# An optional third parameter can be supplied in the last case which 482# is a reference to the current output buffer containing the results 483# of processing the template up to the point at which the exception 484# was thrown. The RETURN and STOP directives, for example, use this 485# to propagate output back to the user, but it can safely be ignored 486# in most cases. 487# 488# This method rides on a one-way ticket to die() oblivion. It does not 489# return in any real sense of the word, but should get caught by a 490# surrounding eval { } block (e.g. a BLOCK or TRY) and handled 491# accordingly, or returned to the caller as an uncaught exception. 492#------------------------------------------------------------------------ 493 494sub throw { 495 my ($self, $error, $info, $output) = @_; 496 local $" = ', '; 497 498 # die! die! die! 499 if (blessed($error) && $error->isa(EXCEPTION)) { 500 die $error; 501 } 502 elsif (blessed($error) && $error->isa(BADGER_EXCEPTION)) { 503 # convert a Badger::Exception to a Template::Exception so that 504 # things continue to work during the transition to Badger 505 die EXCEPTION->new($error->type, $error->info); 506 } 507 elsif (defined $info) { 508 die (EXCEPTION->new($error, $info, $output)); 509 } 510 else { 511 $error ||= ''; 512 die (EXCEPTION->new('undef', $error, $output)); 513 } 514 515 # not reached 516} 517 518 519#------------------------------------------------------------------------ 520# catch($error, \$output) 521# 522# Called by various directives after catching an error thrown via die() 523# from within an eval { } block. The first parameter contains the error 524# which may be a sanitized reference to a Template::Exception object 525# (such as that raised by the throw() method above, a plugin object, 526# and so on) or an error message thrown via die from somewhere in user 527# code. The latter are coerced into 'undef' Template::Exception objects. 528# Like throw() above, a reference to a scalar may be passed as an 529# additional parameter to represent the current output buffer 530# localised within the eval block. As exceptions are thrown upwards 531# and outwards from nested blocks, the catch() method reconstructs the 532# correct output buffer from these fragments, storing it in the 533# exception object for passing further onwards and upwards. 534# 535# Returns a reference to a Template::Exception object.. 536#------------------------------------------------------------------------ 537 538sub catch { 539 my ($self, $error, $output) = @_; 540 541 if ( blessed($error) 542 && ( $error->isa(EXCEPTION) || $error->isa(BADGER_EXCEPTION) ) ) { 543 $error->text($output) if $output; 544 return $error; 545 } 546 else { 547 return EXCEPTION->new('undef', $error, $output); 548 } 549} 550 551 552#------------------------------------------------------------------------ 553# localise(\%params) 554# delocalise() 555# 556# The localise() method creates a local copy of the current stash, 557# allowing the existing state of variables to be saved and later 558# restored via delocalise(). 559# 560# A reference to a hash array may be passed containing local variable 561# definitions which should be added to the cloned namespace. These 562# values persist until delocalisation. 563#------------------------------------------------------------------------ 564 565sub localise { 566 my $self = shift; 567 $self->{ STASH } = $self->{ STASH }->clone(@_); 568} 569 570sub delocalise { 571 my $self = shift; 572 $self->{ STASH } = $self->{ STASH }->declone(); 573} 574 575 576#------------------------------------------------------------------------ 577# visit($document, $blocks) 578# 579# Each Template::Document calls the visit() method on the context 580# before processing itself. It passes a reference to the hash array 581# of named BLOCKs defined within the document, allowing them to be 582# added to the internal BLKSTACK list which is subsequently used by 583# template() to resolve templates. 584# from a provider. 585#------------------------------------------------------------------------ 586 587sub visit { 588 my ($self, $document, $blocks) = @_; 589 unshift(@{ $self->{ BLKSTACK } }, $blocks) 590} 591 592 593#------------------------------------------------------------------------ 594# leave() 595# 596# The leave() method is called when the document has finished 597# processing itself. This removes the entry from the BLKSTACK list 598# that was added visit() above. For persistence of BLOCK definitions, 599# the process() method (i.e. the PROCESS directive) does some extra 600# magic to copy BLOCKs into a shared hash. 601#------------------------------------------------------------------------ 602 603sub leave { 604 my $self = shift; 605 shift(@{ $self->{ BLKSTACK } }); 606} 607 608 609#------------------------------------------------------------------------ 610# define_block($name, $block) 611# 612# Adds a new BLOCK definition to the local BLOCKS cache. $block may 613# be specified as a reference to a sub-routine or Template::Document 614# object or as text which is compiled into a template. Returns a true 615# value (the $block reference or compiled block reference) if 616# successful or undef on failure. Call error() to retrieve the 617# relevant error message (i.e. compilation failure). 618#------------------------------------------------------------------------ 619 620sub define_block { 621 my ($self, $name, $block) = @_; 622 $block = $self->template(\$block) 623 || return undef 624 unless ref $block; 625 $self->{ BLOCKS }->{ $name } = $block; 626} 627 628 629#------------------------------------------------------------------------ 630# define_filter($name, $filter, $is_dynamic) 631# 632# Adds a new FILTER definition to the local FILTER_CACHE. 633#------------------------------------------------------------------------ 634 635sub define_filter { 636 my ($self, $name, $filter, $is_dynamic) = @_; 637 my ($result, $error); 638 $filter = [ $filter, 1 ] if $is_dynamic; 639 640 foreach my $provider (@{ $self->{ LOAD_FILTERS } }) { 641 ($result, $error) = $provider->store($name, $filter); 642 return 1 unless $error; 643 $self->throw(&Template::Constants::ERROR_FILTER, $result) 644 if $error == &Template::Constants::STATUS_ERROR; 645 } 646 $self->throw(&Template::Constants::ERROR_FILTER, 647 "FILTER providers declined to store filter $name"); 648} 649 650 651#------------------------------------------------------------------------ 652# define_vmethod($type, $name, \&sub) 653# 654# Passes $type, $name, and &sub on to stash->define_vmethod(). 655#------------------------------------------------------------------------ 656 657sub define_vmethod { 658 my $self = shift; 659 $self->stash->define_vmethod(@_); 660} 661 662 663#------------------------------------------------------------------------ 664# define_view($name, $params) 665# 666# Defines a new view. 667#------------------------------------------------------------------------ 668 669sub define_view { 670 my ($self, $name, $params) = @_; 671 my $base; 672 673 if (defined $params->{ base }) { 674 my $base = $self->{ STASH }->get($params->{ base }); 675 676 return $self->throw( 677 &Template::Constants::ERROR_VIEW, 678 "view base is not defined: $params->{ base }" 679 ) unless $base; 680 681 return $self->throw( 682 &Template::Constants::ERROR_VIEW, 683 "view base is not a $VIEW_CLASS object: $params->{ base } => $base" 684 ) unless blessed($base) && $base->isa($VIEW_CLASS); 685 686 $params->{ base } = $base; 687 } 688 my $view = $self->view($params); 689 $view->seal(); 690 $self->{ STASH }->set($name, $view); 691} 692 693 694#------------------------------------------------------------------------ 695# define_views($views) 696# 697# Defines multiple new views. 698#------------------------------------------------------------------------ 699 700sub define_views { 701 my ($self, $views) = @_; 702 703 # a list reference is better because the order is deterministic (and so 704 # allows an earlier VIEW to be the base for a later VIEW), but we'll 705 # accept a hash reference and assume that the user knows the order of 706 # processing is undefined 707 $views = [ %$views ] 708 if ref $views eq 'HASH'; 709 710 # make of copy so we don't destroy the original list reference 711 my @items = @$views; 712 my ($name, $view); 713 714 while (@items) { 715 $self->define_view(splice(@items, 0, 2)); 716 } 717} 718 719 720#------------------------------------------------------------------------ 721# reset() 722# 723# Reset the state of the internal BLOCKS hash to clear any BLOCK 724# definitions imported via the PROCESS directive. Any original 725# BLOCKS definitions passed to the constructor will be restored. 726#------------------------------------------------------------------------ 727 728sub reset { 729 my ($self, $blocks) = @_; 730 $self->{ BLKSTACK } = [ ]; 731 $self->{ BLOCKS } = { %{ $self->{ INIT_BLOCKS } } }; 732} 733 734 735#------------------------------------------------------------------------ 736# stash() 737# 738# Simple accessor methods to return the STASH values. This is likely 739# to be called quite often so we provide a direct method rather than 740# relying on the slower AUTOLOAD. 741#------------------------------------------------------------------------ 742 743sub stash { 744 return $_[0]->{ STASH }; 745} 746 747 748#------------------------------------------------------------------------ 749# debugging($command, @args, \%params) 750# 751# Method for controlling the debugging status of the context. The first 752# argument can be 'on' or 'off' to enable/disable debugging, 'format' 753# to define the format of the debug message, or 'msg' to generate a 754# debugging message reporting the file, line, message text, etc., 755# according to the current debug format. 756#------------------------------------------------------------------------ 757 758sub debugging { 759 my $self = shift; 760 my $hash = ref $_[-1] eq 'HASH' ? pop : { }; 761 my @args = @_; 762 763 if (@args) { 764 if ($args[0] =~ /^on|1$/i) { 765 $self->{ DEBUG_DIRS } = 1; 766 shift(@args); 767 } 768 elsif ($args[0] =~ /^off|0$/i) { 769 $self->{ DEBUG_DIRS } = 0; 770 shift(@args); 771 } 772 } 773 774 if (@args) { 775 if ($args[0] =~ /^msg$/i) { 776 return unless $self->{ DEBUG_DIRS }; 777 my $format = $self->{ DEBUG_FORMAT }; 778 $format = $DEBUG_FORMAT unless defined $format; 779 $format =~ s/\$(\w+)/$hash->{ $1 }/ge; 780 return $format; 781 } 782 elsif ($args[0] =~ /^format$/i) { 783 $self->{ DEBUG_FORMAT } = $args[1]; 784 } 785 # else ignore 786 } 787 788 return ''; 789} 790 791 792#------------------------------------------------------------------------ 793# AUTOLOAD 794# 795# Provides pseudo-methods for read-only access to various internal 796# members. For example, templates(), plugins(), filters(), 797# eval_perl(), load_perl(), etc. These aren't called very often, or 798# may never be called at all. 799#------------------------------------------------------------------------ 800 801sub AUTOLOAD { 802 my $self = shift; 803 my $method = $AUTOLOAD; 804 my $result; 805 806 $method =~ s/.*:://; 807 return if $method eq 'DESTROY'; 808 809 warn "no such context method/member: $method\n" 810 unless defined ($result = $self->{ uc $method }); 811 812 return $result; 813} 814 815 816#------------------------------------------------------------------------ 817# DESTROY 818# 819# Stash may contain references back to the Context via macro closures, 820# etc. This breaks the circular references. 821#------------------------------------------------------------------------ 822 823sub DESTROY { 824 my $self = shift; 825 undef $self->{ STASH }; 826} 827 828 829 830#======================================================================== 831# -- PRIVATE METHODS -- 832#======================================================================== 833 834#------------------------------------------------------------------------ 835# _init(\%config) 836# 837# Initialisation method called by Template::Base::new() 838#------------------------------------------------------------------------ 839 840sub _init { 841 my ($self, $config) = @_; 842 my ($name, $item, $method, $block, $blocks); 843 my @itemlut = ( 844 LOAD_TEMPLATES => 'provider', 845 LOAD_PLUGINS => 'plugins', 846 LOAD_FILTERS => 'filters' 847 ); 848 849 # LOAD_TEMPLATE, LOAD_PLUGINS, LOAD_FILTERS - lists of providers 850 while (($name, $method) = splice(@itemlut, 0, 2)) { 851 $item = $config->{ $name } 852 || Template::Config->$method($config) 853 || return $self->error($Template::Config::ERROR); 854 $self->{ $name } = ref $item eq 'ARRAY' ? $item : [ $item ]; 855 } 856 857 my $providers = $self->{ LOAD_TEMPLATES }; 858 my $prefix_map = $self->{ PREFIX_MAP } = $config->{ PREFIX_MAP } || { }; 859 while (my ($key, $val) = each %$prefix_map) { 860 $prefix_map->{ $key } = [ ref $val ? $val : 861 map { $providers->[$_] } split(/\D+/, $val) ] 862 unless ref $val eq 'ARRAY'; 863 } 864 865 # STASH 866 $self->{ STASH } = $config->{ STASH } || do { 867 my $predefs = $config->{ VARIABLES } 868 || $config->{ PRE_DEFINE } 869 || { }; 870 871 # hack to get stash to know about debug mode 872 $predefs->{ _DEBUG } = ( ($config->{ DEBUG } || 0) 873 & &Template::Constants::DEBUG_UNDEF ) ? 1 : 0 874 unless defined $predefs->{ _DEBUG }; 875 $predefs->{ _STRICT } = $config->{ STRICT }; 876 877 Template::Config->stash($predefs) 878 || return $self->error($Template::Config::ERROR); 879 }; 880 881 # compile any template BLOCKS specified as text 882 $blocks = $config->{ BLOCKS } || { }; 883 $self->{ INIT_BLOCKS } = $self->{ BLOCKS } = { 884 map { 885 $block = $blocks->{ $_ }; 886 $block = $self->template(\$block) 887 || return undef 888 unless ref $block; 889 ($_ => $block); 890 } 891 keys %$blocks 892 }; 893 894 # define any VIEWS 895 $self->define_views( $config->{ VIEWS } ) 896 if $config->{ VIEWS }; 897 898 # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 899 # RECURSION - flag indicating is recursion into templates is supported 900 # EVAL_PERL - flag indicating if PERL blocks should be processed 901 # TRIM - flag to remove leading and trailing whitespace from output 902 # BLKSTACK - list of hashes of BLOCKs defined in current template(s) 903 # CONFIG - original configuration hash 904 # EXPOSE_BLOCKS - make blocks visible as pseudo-files 905 # DEBUG_FORMAT - format for generating template runtime debugging messages 906 # DEBUG - format for generating template runtime debugging messages 907 908 $self->{ RECURSION } = $config->{ RECURSION } || 0; 909 $self->{ EVAL_PERL } = $config->{ EVAL_PERL } || 0; 910 $self->{ TRIM } = $config->{ TRIM } || 0; 911 $self->{ BLKSTACK } = [ ]; 912 $self->{ CONFIG } = $config; 913 $self->{ EXPOSE_BLOCKS } = defined $config->{ EXPOSE_BLOCKS } 914 ? $config->{ EXPOSE_BLOCKS } 915 : 0; 916 917 $self->{ DEBUG_FORMAT } = $config->{ DEBUG_FORMAT }; 918 $self->{ DEBUG_DIRS } = ($config->{ DEBUG } || 0) 919 & Template::Constants::DEBUG_DIRS; 920 $self->{ DEBUG } = defined $config->{ DEBUG } 921 ? $config->{ DEBUG } & ( Template::Constants::DEBUG_CONTEXT 922 | Template::Constants::DEBUG_FLAGS ) 923 : $DEBUG; 924 925 return $self; 926} 927 928 929#------------------------------------------------------------------------ 930# _dump() 931# 932# Debug method which returns a string representing the internal state 933# of the context object. 934#------------------------------------------------------------------------ 935 936sub _dump { 937 my $self = shift; 938 my $output = "[Template::Context] {\n"; 939 my $format = " %-16s => %s\n"; 940 my $key; 941 942 foreach $key (qw( RECURSION EVAL_PERL TRIM )) { 943 $output .= sprintf($format, $key, $self->{ $key }); 944 } 945 foreach my $pname (qw( LOAD_TEMPLATES LOAD_PLUGINS LOAD_FILTERS )) { 946 my $provtext = "[\n"; 947 foreach my $prov (@{ $self->{ $pname } }) { 948 $provtext .= $prov->_dump(); 949# $provtext .= ",\n"; 950 } 951 $provtext =~ s/\n/\n /g; 952 $provtext =~ s/\s+$//; 953 $provtext .= ",\n ]"; 954 $output .= sprintf($format, $pname, $provtext); 955 } 956 $output .= sprintf($format, STASH => $self->{ STASH }->_dump()); 957 $output .= '}'; 958 return $output; 959} 960 961 9621; 963 964__END__ 965 966=head1 NAME 967 968Template::Context - Runtime context in which templates are processed 969 970=head1 SYNOPSIS 971 972 use Template::Context; 973 974 # constructor 975 $context = Template::Context->new(\%config) 976 || die $Template::Context::ERROR; 977 978 # fetch (load and compile) a template 979 $template = $context->template($template_name); 980 981 # fetch (load and instantiate) a plugin object 982 $plugin = $context->plugin($name, \@args); 983 984 # fetch (return or create) a filter subroutine 985 $filter = $context->filter($name, \@args, $alias); 986 987 # process/include a template, errors are thrown via die() 988 $output = $context->process($template, \%vars); 989 $output = $context->include($template, \%vars); 990 991 # raise an exception via die() 992 $context->throw($error_type, $error_message, \$output_buffer); 993 994 # catch an exception, clean it up and fix output buffer 995 $exception = $context->catch($exception, \$output_buffer); 996 997 # save/restore the stash to effect variable localisation 998 $new_stash = $context->localise(\%vars); 999 $old_stash = $context->delocalise(); 1000 1001 # add new BLOCK or FILTER definitions 1002 $context->define_block($name, $block); 1003 $context->define_filter($name, \&filtersub, $is_dynamic); 1004 1005 # reset context, clearing any imported BLOCK definitions 1006 $context->reset(); 1007 1008 # methods for accessing internal items 1009 $stash = $context->stash(); 1010 $tflag = $context->trim(); 1011 $epflag = $context->eval_perl(); 1012 $providers = $context->templates(); 1013 $providers = $context->plugins(); 1014 $providers = $context->filters(); 1015 ... 1016 1017=head1 DESCRIPTION 1018 1019The C<Template::Context> module defines an object class for representing 1020a runtime context in which templates are processed. It provides an 1021interface to the fundamental operations of the Template Toolkit 1022processing engine through which compiled templates (i.e. Perl code 1023constructed from the template source) can process templates, load 1024plugins and filters, raise exceptions and so on. 1025 1026A default C<Template::Context> object is created by the L<Template> module. 1027Any C<Template::Context> options may be passed to the L<Template> 1028L<new()|Template#new()> constructor method and will be forwarded to the 1029C<Template::Context> constructor. 1030 1031 use Template; 1032 1033 my $template = Template->new({ 1034 TRIM => 1, 1035 EVAL_PERL => 1, 1036 BLOCKS => { 1037 header => 'This is the header', 1038 footer => 'This is the footer', 1039 }, 1040 }); 1041 1042Similarly, the C<Template::Context> constructor will forward all configuration 1043parameters onto other default objects (e.g. L<Template::Provider>, 1044L<Template::Plugins>, L<Template::Filters>, etc.) that it may need to 1045instantiate. 1046 1047 $context = Template::Context->new({ 1048 INCLUDE_PATH => '/home/abw/templates', # provider option 1049 TAG_STYLE => 'html', # parser option 1050 }); 1051 1052A C<Template::Context> object (or subclass) can be explicitly instantiated and 1053passed to the L<Template> L<new()|Template#new()> constructor method as the 1054C<CONTEXT> configuration item. 1055 1056 use Template; 1057 use Template::Context; 1058 1059 my $context = Template::Context->new({ TRIM => 1 }); 1060 my $template = Template->new({ CONTEXT => $context }); 1061 1062The L<Template> module uses the L<Template::Config> 1063L<context()|Template::Config#context()> factory method to create a default 1064context object when required. The C<$Template::Config::CONTEXT> package 1065variable may be set to specify an alternate context module. This will be 1066loaded automatically and its L<new()> constructor method called by the 1067L<context()|Template::Config#context()> factory method when a default context 1068object is required. 1069 1070 use Template; 1071 1072 $Template::Config::CONTEXT = 'MyOrg::Template::Context'; 1073 1074 my $template = Template->new({ 1075 EVAL_PERL => 1, 1076 EXTRA_MAGIC => 'red hot', # your extra config items 1077 ... 1078 }); 1079 1080=head1 METHODS 1081 1082=head2 new(\%params) 1083 1084The C<new()> constructor method is called to instantiate a 1085C<Template::Context> object. Configuration parameters may be specified as a 1086HASH reference or as a list of C<name =E<gt> value> pairs. 1087 1088 my $context = Template::Context->new({ 1089 INCLUDE_PATH => 'header', 1090 POST_PROCESS => 'footer', 1091 }); 1092 1093 my $context = Template::Context->new( EVAL_PERL => 1 ); 1094 1095The C<new()> method returns a C<Template::Context> object or C<undef> on 1096error. In the latter case, a relevant error message can be retrieved by the 1097L<error()|Template::Base#error()> class method or directly from the 1098C<$Template::Context::ERROR> package variable. 1099 1100 my $context = Template::Context->new(\%config) 1101 || die Template::Context->error(); 1102 1103 my $context = Template::Context->new(\%config) 1104 || die $Template::Context::ERROR; 1105 1106The following configuration items may be specified. Please see 1107L<Template::Manual::Config> for further details. 1108 1109=head3 VARIABLES 1110 1111The L<VARIABLES|Template::Manual::Config#VARIABLES> option can be used to 1112specify a hash array of template variables. 1113 1114 my $context = Template::Context->new({ 1115 VARIABLES => { 1116 title => 'A Demo Page', 1117 author => 'Joe Random Hacker', 1118 version => 3.14, 1119 }, 1120 }; 1121 1122=head3 BLOCKS 1123 1124The L<BLOCKS|Template::Manual::Config#BLOCKS> option can be used to pre-define 1125a default set of template blocks. 1126 1127 my $context = Template::Context->new({ 1128 BLOCKS => { 1129 header => 'The Header. [% title %]', 1130 footer => sub { return $some_output_text }, 1131 another => Template::Document->new({ ... }), 1132 }, 1133 }); 1134 1135=head3 VIEWS 1136 1137The L<VIEWS|Template::Manual::Config#VIEWS> option can be used to pre-define 1138one or more L<Template::View> objects. 1139 1140 my $context = Template::Context->new({ 1141 VIEWS => [ 1142 bottom => { prefix => 'bottom/' }, 1143 middle => { prefix => 'middle/', base => 'bottom' }, 1144 top => { prefix => 'top/', base => 'middle' }, 1145 ], 1146 }); 1147 1148=head3 TRIM 1149 1150The L<TRIM|Template::Manual::Config#TRIM> option can be set to have any 1151leading and trailing whitespace automatically removed from the output of all 1152template files and C<BLOCK>s. 1153 1154example: 1155 1156 [% BLOCK foo %] 1157 1158 Line 1 of foo 1159 1160 [% END %] 1161 1162 before 1163 [% INCLUDE foo %] 1164 after 1165 1166output: 1167 1168 before 1169 Line 1 of foo 1170 after 1171 1172=head3 EVAL_PERL 1173 1174The L<EVAL_PERL|Template::Manual::Config#EVAL_PERL> is used to indicate if 1175C<PERL> and/or C<RAWPERL> blocks should be evaluated. It is disabled by 1176default. 1177 1178=head3 RECURSION 1179 1180The L<RECURSION|Template::Manual::Config#RECURSION> can be set to 1181allow templates to recursively process themselves, either directly 1182(e.g. template C<foo> calls C<INCLUDE foo>) or indirectly (e.g. 1183C<foo> calls C<INCLUDE bar> which calls C<INCLUDE foo>). 1184 1185=head3 LOAD_TEMPLATES 1186 1187The L<LOAD_TEMPLATES|Template::Manual::Config#LOAD_TEMPLATES> option can be 1188used to provide a reference to a list of L<Template::Provider> objects or 1189sub-classes thereof which will take responsibility for loading and compiling 1190templates. 1191 1192 my $context = Template::Context->new({ 1193 LOAD_TEMPLATES => [ 1194 MyOrg::Template::Provider->new({ ... }), 1195 Template::Provider->new({ ... }), 1196 ], 1197 }); 1198 1199=head3 LOAD_PLUGINS 1200 1201The L<LOAD_PLUGINS|Template::Manual::Config#LOAD_PLUGINS> options can be used 1202to specify a list of provider objects responsible for loading and 1203instantiating template plugin objects. 1204 1205 my $context = Template::Context->new({ 1206 LOAD_PLUGINS => [ 1207 MyOrg::Template::Plugins->new({ ... }), 1208 Template::Plugins->new({ ... }), 1209 ], 1210 }); 1211 1212=head3 LOAD_FILTERS 1213 1214The L<LOAD_FILTERS|Template::Manual::Config#LOAD_FILTERS> option can be used 1215to specify a list of provider objects for returning and/or creating filter 1216subroutines. 1217 1218 my $context = Template::Context->new({ 1219 LOAD_FILTERS => [ 1220 MyTemplate::Filters->new(), 1221 Template::Filters->new(), 1222 ], 1223 }); 1224 1225=head3 STASH 1226 1227The L<STASH|Template::Manual::Config#STASH> option can be used to 1228specify a L<Template::Stash> object or sub-class which will take 1229responsibility for managing template variables. 1230 1231 my $stash = MyOrg::Template::Stash->new({ ... }); 1232 my $context = Template::Context->new({ 1233 STASH => $stash, 1234 }); 1235 1236=head3 DEBUG 1237 1238The L<DEBUG|Template::Manual::Config#DEBUG> option can be used to enable 1239various debugging features of the L<Template::Context> module. 1240 1241 use Template::Constants qw( :debug ); 1242 1243 my $template = Template->new({ 1244 DEBUG => DEBUG_CONTEXT | DEBUG_DIRS, 1245 }); 1246 1247=head2 template($name) 1248 1249Returns a compiled template by querying each of the L<LOAD_TEMPLATES> providers 1250(instances of L<Template::Provider>, or sub-class) in turn. 1251 1252 $template = $context->template('header'); 1253 1254On error, a L<Template::Exception> object of type 'C<file>' is thrown via 1255C<die()>. This can be caught by enclosing the call to C<template()> in an 1256C<eval> block and examining C<$@>. 1257 1258 eval { $template = $context->template('header') }; 1259 if ($@) { 1260 print "failed to fetch template: $@\n"; 1261 } 1262 1263=head2 plugin($name, \@args) 1264 1265Instantiates a plugin object by querying each of the L<LOAD_PLUGINS> 1266providers. The default L<LOAD_PLUGINS> provider is a L<Template::Plugins> 1267object which attempts to load plugin modules, according the various 1268configuration items such as L<PLUGIN_BASE|Template::Plugins#PLUGIN_BASE>, 1269L<LOAD_PERL|Template::Plugins#LOAD_PERL>, etc., and then instantiate an object 1270via L<new()|Template::Plugin#new()>. A reference to a list of constructor 1271arguments may be passed as the second parameter. These are forwarded to the 1272plugin constructor. 1273 1274Returns a reference to a plugin (which is generally an object, but 1275doesn't have to be). Errors are thrown as L<Template::Exception> objects 1276with the type set to 'C<plugin>'. 1277 1278 $plugin = $context->plugin('DBI', 'dbi:msql:mydbname'); 1279 1280=head2 filter($name, \@args, $alias) 1281 1282Instantiates a filter subroutine by querying the L<LOAD_FILTERS> providers. 1283The default L<LOAD_FILTERS> provider is a L<Template::Filters> object. 1284 1285Additional arguments may be passed by list reference along with an optional 1286alias under which the filter will be cached for subsequent use. The filter is 1287cached under its own C<$name> if C<$alias> is undefined. Subsequent calls to 1288C<filter($name)> will return the cached entry, if defined. Specifying arguments 1289bypasses the caching mechanism and always creates a new filter. Errors are 1290thrown as L<Template::Exception> objects with the type set to 'C<filter>'. 1291 1292 # static filter (no args) 1293 $filter = $context->filter('html'); 1294 1295 # dynamic filter (args) aliased to 'padright' 1296 $filter = $context->filter('format', '%60s', 'padright'); 1297 1298 # retrieve previous filter via 'padright' alias 1299 $filter = $context->filter('padright'); 1300 1301=head2 process($template, \%vars) 1302 1303Processes a template named or referenced by the first parameter and returns 1304the output generated. An optional reference to a hash array may be passed 1305as the second parameter, containing variable definitions which will be set 1306before the template is processed. The template is processed in the current 1307context, with no localisation of variables performed. Errors are thrown 1308as L<Template::Exception> objects via C<die()>. 1309 1310 $output = $context->process('header', { title => 'Hello World' }); 1311 1312=head2 include($template, \%vars) 1313 1314Similar to L<process()>, but using localised variables. Changes made to 1315any variables will only persist until the C<include()> method completes. 1316 1317 $output = $context->include('header', { title => 'Hello World' }); 1318 1319=head2 insert($template) 1320 1321This method returns the source content of a template file without performing 1322any evaluation. It is used to implement the C<INSERT> directive. 1323 1324=head2 throw($error_type, $error_message, \$output) 1325 1326Raises an exception in the form of a L<Template::Exception> object by calling 1327C<die()>. This method may be passed a reference to an existing 1328L<Template::Exception> object; a single value containing an error message 1329which is used to instantiate a L<Template::Exception> of type 'C<undef>'; or a 1330pair of values representing the exception C<type> and C<info> from which a 1331L<Template::Exception> object is instantiated. e.g. 1332 1333 $context->throw($exception); 1334 $context->throw("I'm sorry Dave, I can't do that"); 1335 $context->throw('denied', "I'm sorry Dave, I can't do that"); 1336 1337The optional third parameter may be a reference to the current output 1338buffer. This is then stored in the exception object when created, 1339allowing the catcher to examine and use the output up to the point at 1340which the exception was raised. 1341 1342 $output .= 'blah blah blah'; 1343 $output .= 'more rhubarb'; 1344 $context->throw('yack', 'Too much yacking', \$output); 1345 1346=head2 catch($exception, \$output) 1347 1348Catches an exception thrown, either as a reference to a L<Template::Exception> 1349object or some other value. In the latter case, the error string is promoted 1350to a L<Template::Exception> object of 'C<undef>' type. This method also 1351accepts a reference to the current output buffer which is passed to the 1352L<Template::Exception> constructor, or is appended to the output buffer stored 1353in an existing L<Template::Exception> object, if unique (i.e. not the same 1354reference). By this process, the correct state of the output buffer can be 1355reconstructed for simple or nested throws. 1356 1357=head2 define_block($name, $block) 1358 1359Adds a new block definition to the internal L<BLOCKS> cache. The first 1360argument should contain the name of the block and the second a reference 1361to a L<Template::Document> object or template sub-routine, or template text 1362which is automatically compiled into a template sub-routine. 1363 1364Returns a true value (the sub-routine or L<Template::Document> reference) on 1365success or undef on failure. The relevant error message can be retrieved by 1366calling the L<error()|Template::Base#error()> method. 1367 1368=head2 define_filter($name, \&filter, $is_dynamic) 1369 1370Adds a new filter definition by calling the 1371L<store()|Template::Filters#store()> method on each of the L<LOAD_FILTERS> 1372providers until accepted (in the usual case, this is accepted straight away by 1373the one and only L<Template::Filters> provider). The first argument should 1374contain the name of the filter and the second a reference to a filter 1375subroutine. The optional third argument can be set to any true value to 1376indicate that the subroutine is a dynamic filter factory. 1377 1378Returns a true value or throws a 'C<filter>' exception on error. 1379 1380=head2 define_vmethod($type, $name, $code) 1381 1382This method is a wrapper around the L<Template::Stash> 1383L<define_vmethod()|Template::Stash#define_vmethod()> method. It can be used 1384to define new virtual methods. 1385 1386 # define a new scalar (item) virtual method 1387 $context->define_vmethod( 1388 item => ucfirst => sub { 1389 my $text = shift; 1390 return ucfirst $text; 1391 } 1392 ) 1393 1394=head2 define_view($name, \%params) 1395 1396This method allows you to define a named L<view|Template::View>. 1397 1398 $context->define_view( 1399 my_view => { 1400 prefix => 'my_templates/' 1401 } 1402 ); 1403 1404The view is then accessible as a template variable. 1405 1406 [% my_view.print(some_data) %] 1407 1408=head2 define_views($views) 1409 1410This method allows you to define multiple named L<views|Template::View>. 1411A reference to a hash array or list reference should be passed as an argument. 1412 1413 $context->define_view({ # hash reference 1414 my_view_one => { 1415 prefix => 'my_templates_one/' 1416 }, 1417 my_view_two => { 1418 prefix => 'my_templates_two/' 1419 } 1420 }); 1421 1422If you're defining multiple views of which one or more are based on other 1423views in the same definition then you should pass them as a list reference. 1424This ensures that they get created in the right order (Perl does not preserve 1425the order of items defined in a hash reference so you can't guarantee that 1426your base class view will be defined before your subclass view). 1427 1428 $context->define_view([ # list referenence 1429 my_view_one => { 1430 prefix => 'my_templates_one/' 1431 }, 1432 my_view_two => { 1433 prefix => 'my_templates_two/' , 1434 base => 'my_view_one', 1435 } 1436 ]); 1437 1438The views are then accessible as template variables. 1439 1440 [% my_view_one.print(some_data) %] 1441 [% my_view_two.print(some_data) %] 1442 1443See also the L<VIEWS> option. 1444 1445=head2 stash() 1446 1447This method returns the L<Template::Stash> object used internally to manage 1448template variables. 1449 1450=head2 localise(\%vars) 1451 1452Clones the stash to create a context with localised variables. Returns a 1453reference to the newly cloned stash object which is also stored 1454internally. 1455 1456 $stash = $context->localise(); 1457 1458=head2 delocalise() 1459 1460Restore the stash to its state prior to localisation. 1461 1462 $stash = $context->delocalise(); 1463 1464=head2 visit(\%blocks) 1465 1466This method is called by L<Template::Document> objects immediately before 1467they process their content. It is called to register any local C<BLOCK> 1468definitions with the context object so that they may be subsequently 1469delivered on request. 1470 1471=head2 leave() 1472 1473Compliment to the L<visit()> method. Called by L<Template::Document> objects 1474immediately after they process their content. 1475 1476=head2 view() 1477 1478This method creates a L<Template::View> object bound to the context. 1479 1480=head2 reset() 1481 1482Clears the local L<BLOCKS> cache of any C<BLOCK> definitions. Any initial set of 1483L<BLOCKS> specified as a configuration item to the constructor will be reinstated. 1484 1485=head2 debugging($flag, @args) 1486 1487This method is used to control debugging output. It is used to implement 1488the L<DEBUG|Template::Manual::Directives#DEBUG> directive. 1489 1490The first argument can be C<on> or C<off> to enable or disable debugging 1491respectively. The numerical values C<0> and C<1> can also be used if you 1492prefer. 1493 1494 $context->debugging('on'); 1495 1496Alternately, the first argument can be C<format> to define a new debug message 1497format. The second argument should be the format string which can contain 1498any of the C<$file>, C<$line> or C<$text> symbols to indicate where the 1499relevant values should be inserted. 1500 1501 # note single quotes to prevent interpolated of variables 1502 $context->debugging( format => '## $file line $line: $text' ); 1503 1504The final use of this method is to generate debugging messages themselves. 1505The first argument should be C<msg>, followed by a reference to a hash array 1506of value to insert into the debugging format string. 1507 1508 $context->debugging( 1509 msg => { 1510 line => 20, 1511 file => 'example.tt', 1512 text => 'Trampoline! Trampoline!', 1513 } 1514 ); 1515 1516=head2 AUTOLOAD 1517 1518An C<AUTOLOAD> method provides access to context configuration items. 1519 1520 $stash = $context->stash(); 1521 $tflag = $context->trim(); 1522 $epflag = $context->eval_perl(); 1523 ... 1524 1525=head1 AUTHOR 1526 1527Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> 1528 1529=head1 COPYRIGHT 1530 1531Copyright (C) 1996-2012 Andy Wardley. All Rights Reserved. 1532 1533This module is free software; you can redistribute it and/or 1534modify it under the same terms as Perl itself. 1535 1536=head1 SEE ALSO 1537 1538L<Template>, L<Template::Document>, L<Template::Exception>, 1539L<Template::Filters>, L<Template::Plugins>, L<Template::Provider>, 1540L<Template::Service>, L<Template::Stash> 1541 1542=cut 1543 1544# Local Variables: 1545# mode: perl 1546# perl-indent-level: 4 1547# indent-tabs-mode: nil 1548# End: 1549# 1550# vim: expandtab shiftwidth=4: 1551