Profile of /usr/lib/perl5/vendor_perl/5.10.1/i386-linux-thread-multi/Template/Context.pm

File	/usr/lib/perl5/vendor_perl/5.10.1/i386-linux-thread-multi/Template/Context.pm
Statements Executed	24742
Statement Execution Time	196ms

Subroutines — ordered by exclusive time
Calls	P	F	Exclusive Time	Inclusive Time	Subroutine
1685	7	5	87.3ms	167ms	Template::Context::::filterTemplate::Context::filter
1724	3	3	49.1ms	70.0ms	Template::Context::::delocaliseTemplate::Context::delocalise
1724	3	3	46.8ms	190ms	Template::Context::::localiseTemplate::Context::localise
14	4	2	8.20ms	16.8s	Template::Context::::processTemplate::Context::process
18	2	2	1.38ms	619ms	Template::Context::::templateTemplate::Context::template
4	1	1	965µs	47.1ms	Template::Context::::_initTemplate::Context::_init
14	1	1	303µs	303µs	Template::Context::::visitTemplate::Context::visit
4	4	3	120µs	170ms	Template::Context::::includeTemplate::Context::include
14	1	1	118µs	118µs	Template::Context::::leaveTemplate::Context::leave
4	1	1	115µs	115µs	Template::Context::::resetTemplate::Context::reset
1	1	1	100µs	108µs	Template::Context::::BEGIN@27Template::Context::BEGIN@27
1	1	1	97µs	176µs	Template::Context::::BEGIN@29Template::Context::BEGIN@29
1	1	1	88µs	99µs	Template::Context::::BEGIN@23Template::Context::BEGIN@23
14	9	9	84µs	84µs	Template::Context::::stashTemplate::Context::stash
14	1	2	45µs	45µs	Template::Context::::CORE:substTemplate::Context::CORE:subst (opcode)
1	1	1	36µs	42µs	Template::Context::::BEGIN@30Template::Context::BEGIN@30
1	1	1	35µs	205µs	Template::Context::::BEGIN@33Template::Context::BEGIN@33
1	1	1	33µs	139µs	Template::Context::::BEGIN@31Template::Context::BEGIN@31
1	1	1	33µs	38µs	Template::Context::::BEGIN@28Template::Context::BEGIN@28
1	1	1	31µs	83µs	Template::Context::::BEGIN@24Template::Context::BEGIN@24
1	1	1	30µs	204µs	Template::Context::::BEGIN@25Template::Context::BEGIN@25
1	1	1	29µs	203µs	Template::Context::::BEGIN@34Template::Context::BEGIN@34
1	1	1	28µs	219µs	Template::Context::::BEGIN@35Template::Context::BEGIN@35
0	0	0	0s	0s	Template::Context::::AUTOLOADTemplate::Context::AUTOLOAD
0	0	0	0s	0s	Template::Context::::DESTROYTemplate::Context::DESTROY
0	0	0	0s	0s	Template::Context::::_dumpTemplate::Context::_dump
0	0	0	0s	0s	Template::Context::::catchTemplate::Context::catch
0	0	0	0s	0s	Template::Context::::debuggingTemplate::Context::debugging
0	0	0	0s	0s	Template::Context::::define_blockTemplate::Context::define_block
0	0	0	0s	0s	Template::Context::::define_filterTemplate::Context::define_filter
0	0	0	0s	0s	Template::Context::::define_viewTemplate::Context::define_view
0	0	0	0s	0s	Template::Context::::define_viewsTemplate::Context::define_views
0	0	0	0s	0s	Template::Context::::define_vmethodTemplate::Context::define_vmethod
0	0	0	0s	0s	Template::Context::::insertTemplate::Context::insert
0	0	0	0s	0s	Template::Context::::pluginTemplate::Context::plugin
0	0	0	0s	0s	Template::Context::::throwTemplate::Context::throw
0	0	0	0s	0s	Template::Context::::viewTemplate::Context::view

Call graph for these subroutines as a Graphviz dot language file.

Line	State ments	Time on line	Calls	Time in subs	Code
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
21					package Template::Context;
22
23	3	93µs	2	111µs	# spent 99µs (88+12) within Template::Context::BEGIN@23 which was called # once (88µs+12µs) by base::import at line 23 use strict; # spent 99µs making 1 call to Template::Context::BEGIN@23 # spent 12µs making 1 call to strict::import
24	3	85µs	2	135µs	# spent 83µs (31+52) within Template::Context::BEGIN@24 which was called # once (31µs+52µs) by base::import at line 24 use warnings; # spent 83µs making 1 call to Template::Context::BEGIN@24 # spent 52µs making 1 call to warnings::import
25	3	142µs	2	204µs	# spent 204µs (30+174) within Template::Context::BEGIN@25 which was called # once (30µs+174µs) by base::import at line 25 use base 'Template::Base'; # spent 204µs making 1 call to Template::Context::BEGIN@25 # spent 174µs making 1 call to base::import, recursion: max depth 2, time 174µs
26
27	3	94µs	2	115µs	# spent 108µs (100+7) within Template::Context::BEGIN@27 which was called # once (100µs+7µs) by base::import at line 27 use Template::Base; # spent 108µs making 1 call to Template::Context::BEGIN@27 # spent 7µs making 1 call to UNIVERSAL::import
28	3	140µs	2	44µs	# spent 38µs (33+6) within Template::Context::BEGIN@28 which was called # once (33µs+6µs) by base::import at line 28 use Template::Config; # spent 38µs making 1 call to Template::Context::BEGIN@28 # spent 6µs making 1 call to UNIVERSAL::import
29	3	208µs	2	256µs	# spent 176µs (97+80) within Template::Context::BEGIN@29 which was called # once (97µs+80µs) by base::import at line 29 use Template::Constants; # spent 176µs making 1 call to Template::Context::BEGIN@29 # spent 80µs making 1 call to Exporter::import
30	3	143µs	2	49µs	# spent 42µs (36+6) within Template::Context::BEGIN@30 which was called # once (36µs+6µs) by base::import at line 30 use Template::Exception; # spent 42µs making 1 call to Template::Context::BEGIN@30 # spent 6µs making 1 call to UNIVERSAL::import
31	3	184µs	2	245µs	# spent 139µs (33+106) within Template::Context::BEGIN@31 which was called # once (33µs+106µs) by base::import at line 31 use Scalar::Util 'blessed'; # spent 139µs making 1 call to Template::Context::BEGIN@31 # spent 106µs making 1 call to Exporter::import
32
33	3	96µs	2	374µs	# spent 205µs (35+170) within Template::Context::BEGIN@33 which was called # once (35µs+170µs) by base::import at line 33 use constant DOCUMENT => 'Template::Document'; # spent 205µs making 1 call to Template::Context::BEGIN@33 # spent 170µs making 1 call to constant::import
34	3	89µs	2	376µs	# spent 203µs (29+173) within Template::Context::BEGIN@34 which was called # once (29µs+173µs) by base::import at line 34 use constant EXCEPTION => 'Template::Exception'; # spent 203µs making 1 call to Template::Context::BEGIN@34 # spent 174µs making 1 call to constant::import
35	3	12.2ms	2	409µs	# spent 219µs (28+191) within Template::Context::BEGIN@35 which was called # once (28µs+191µs) by base::import at line 35 use constant BADGER_EXCEPTION => 'Badger::Exception'; # spent 219µs making 1 call to Template::Context::BEGIN@35 # spent 191µs making 1 call to constant::import
36
37	1	2µs			our $VERSION = 2.98;
38	1	2µs			our $DEBUG = 0 unless defined $DEBUG;
39	1	3µs			our $DEBUG_FORMAT = "\n## \$file line \$line : [% \$text %] ##\n";
40	1	2µs			our $VIEW_CLASS = 'Template::View';
41	1	1µs			our $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
77					# spent 619ms (1.38+617) within Template::Context::template which was called 18 times, avg 34.4ms/call: # 14 times (1.04ms+252ms) by Template::Context::process at line 309, avg 18.1ms/call # 4 times (338µs+366ms) by Template::Service::process at line 68 of Template/Service.pm, avg 91.5ms/call sub template {
78	18	44µs			my ($self, $name) = @_;
79	18	27µs			my ($prefix, $blocks, $defblocks, $provider, $template, $error);
80	18	20µs			my ($shortname, $blockname, $providers);
81
82	18	32µs			$self->debug("template($name)") if $self->{ DEBUG };
83
84					# references to Template::Document (or sub-class) objects objects, or
85					# CODE references are assumed to be pre-compiled templates and are
86					# returned intact
87	18	283µs	22	91µs	return $name # spent 81µs making 18 calls to Scalar::Util::blessed, avg 4µs/call # spent 10µs making 4 calls to UNIVERSAL::isa, avg 2µs/call
88					if (blessed($name) && $name->isa(DOCUMENT))
89					\|\| ref($name) eq 'CODE';
90
91	14	24µs			$shortname = $name;
92
93	14	37µs			unless (ref $name) {
94
95	14	22µs			$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	14	30µs			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	14	104µs			foreach $blocks (@{ $self->{ BLKSTACK } }) {
105	5	25µs			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	14	81µs			if ($^O eq 'MSWin32') {
112					# let C:/foo through
113					$prefix = $1 if $shortname =~ s/^(\w{2,})://o;
114					}
115					else {
116	14	158µs	14	45µs	$prefix = $1 if $shortname =~ s/^(\w+)://; # spent 45µs making 14 calls to Template::Context::CORE:subst, avg 3µs/call
117					}
118
119	14	19µs			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	14	56µs			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	14	21µs			$blockname = '';
135	14	22µs			while ($shortname) {
136					$self->debug("asking providers for [$shortname] [$blockname]")
137	14	23µs			if $self->{ DEBUG };
138
139	14	61µs			foreach my $provider (@$providers) {
140	14	182µs	14	617ms	($template, $error) = $provider->fetch($shortname, $prefix); # spent 617ms making 14 calls to Template::Provider::fetch, avg 44.1ms/call
141	14	143µs			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	14	134µs			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
183					sub 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
212					# spent 167ms (87.3+79.4) within Template::Context::filter which was called 1685 times, avg 99µs/call: # 1672 times (86.9ms+78.8ms) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/admin/voters.tt:105] at line 67 of Epoll/root/templates/admin/voters.tt, avg 99µs/call # 8 times (225µs+268µs) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/locale_select.tt:36] at line 10 of Epoll/root/templates/includes/locale_select.tt, avg 62µs/call # once (46µs+104µs) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/admin_menu.tt:31] at line 9 of Epoll/root/templates/includes/admin_menu.tt # once (44µs+44µs) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/footer.tt:15] at line 9 of Epoll/root/templates/includes/footer.tt # once (43µs+42µs) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/footer.tt:15] at line 7 of Epoll/root/templates/includes/footer.tt # once (15µs+42µs) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/header.tt:65] at line 42 of Epoll/root/templates/includes/header.tt # once (21µs+22µs) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/header.tt:65] at line 35 of Epoll/root/templates/includes/header.tt sub filter {
213	1685	7.30ms			my ($self, $name, $args, $alias) = @_;
214	1685	4.19ms			my ($provider, $filter, $error);
215
216					$self->debug("filter($name, ",
217					defined $args ? @$args : '[ ]',
218					defined $alias ? $alias : '<no alias>', ')')
219	1685	6.44ms			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	1685	8.04ms			&& ($filter = $self->{ FILTER_CACHE }->{ $name });
225
226					# request the named filter from each of the FILTERS providers in turn
227	1685	6.96ms			foreach my $provider (@{ $self->{ LOAD_FILTERS } }) {
228	1685	21.0ms	1685	79.4ms	($filter, $error) = $provider->fetch($name, $args, $self); # spent 79.4ms making 1685 calls to Template::Filters::fetch, avg 47µs/call
229	1685	5.08ms			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	1685	3.99ms			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	1685	3.02ms			$self->{ FILTER_CACHE }->{ $alias } = $filter
255					if $alias;
256
257	1685	18.6ms			return $filter;
258					}
259
260
261					#------------------------------------------------------------------------
262					# view(\%config)
263					#
264					# Create a new Template::View bound to this context.
265					#------------------------------------------------------------------------
266
267					sub 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
293					# spent 16.8s (8.20ms+16.8) within Template::Context::process which was called 14 times, avg 1.20s/call: # 5 times (1.57ms+196ms) by Template::Service::process at line 85 of Template/Service.pm, avg 39.5ms/call # 4 times (4.80ms+16.6s) by Template::Service::process at line 94 of Template/Service.pm, avg 4.15s/call # 4 times (1.40ms+-1.40ms) by Template::Context::include at line 409, avg 0s/call # once (426µs+32.7ms) by Template::Service::process at line 118 of Template/Service.pm sub process {
294	14	74µs			my ($self, $template, $params, $localize) = @_;
295	14	49µs			my ($trim, $blocks) = @$self{ qw( TRIM BLOCKS ) };
296	14	21µs			my (@compiled, $name, $compiled);
297	14	25µs			my ($stash, $component, $tblocks, $error, $tmpout);
298	14	77µs			my $output = '';
299
300	14	60µs			$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	14	26µs			if $self->{ DEBUG };
306
307					# fetch compiled template for each name specified
308	14	49µs			foreach $name (@$template) {
309	14	164µs	14	253ms	push(@compiled, $self->template($name)); # spent 253ms making 14 calls to Template::Context::template, avg 18.1ms/call
310					}
311
312	14	131µs	4	385µs	if ($localize) { # spent 385µs making 4 calls to Template::Stash::clone, avg 96µs/call
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	10	211µs	10	198µs	$self->{ STASH }->update($params); # spent 198µs making 10 calls to Template::Stash::update, avg 20µs/call
318	10	21µs			$stash = $self->{ STASH };
319					}
320
321	14	44µs			eval {
322					# save current component
323	28	572µs	18	514µs	eval { $component = $stash->get('component') }; # spent 470µs making 14 calls to Template::Stash::XS::get, avg 34µs/call # spent 45µs making 4 calls to Template::Stash::undefined, avg 11µs/call
324
325	14	106µs			foreach $name (@$template) {
326	14	26µs			$compiled = shift @compiled;
327	14	47µs			my $element = ref $compiled eq 'CODE'
328					? { (name => (ref $name ? '' : $name), modtime => time()) }
329					: $compiled;
330
331	14	424µs	18	91µs	if (blessed($component) && $component->isa(DOCUMENT)) { # spent 75µs making 14 calls to Scalar::Util::blessed, avg 5µs/call # spent 16µs making 4 calls to UNIVERSAL::isa, avg 4µs/call
332	4	20µs			$element->{ caller } = $component->{ name };
333	4	119µs			$element->{ callers } = $component->{ callers } \|\| [];
334	4	25µs			push(@{$element->{ callers }}, $element->{ caller });
335					}
336
337	14	319µs	14	161µs	$stash->set('component', $element); # spent 161µs making 14 calls to Template::Stash::XS::set, avg 11µs/call
338
339	14	489µs	30	126µs	unless ($localize) { # spent 59µs making 10 calls to Template::Document::blocks, avg 6µs/call # spent 34µs making 10 calls to UNIVERSAL::isa, avg 3µs/call # spent 33µs making 10 calls to Scalar::Util::blessed, avg 3µs/call
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	14	268µs	14	16.7s	if (ref $compiled eq 'CODE') { # spent 16.8s making 14 calls to Template::Document::process, avg 1.20s/call, recursion: max depth 2, time 79.9ms
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	14	17µs			if ($trim) {
359					for ($tmpout) {
360					s/^\s+//;
361					s/\s+$//;
362					}
363					}
364	14	2.41ms			$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	14	305µs	18	89µs	pop(@{$element->{ callers }}) # spent 77µs making 14 calls to Scalar::Util::blessed, avg 5µs/call # spent 12µs making 4 calls to UNIVERSAL::isa, avg 3µs/call
374					if (blessed($component) && $component->isa(DOCUMENT));
375					}
376	14	592µs	14	342µs	$stash->set('component', $component); # spent 342µs making 14 calls to Template::Stash::XS::set, avg 24µs/call
377					};
378	14	27µs			$error = $@;
379
380	14	44µs	4	28µs	if ($localize) { # spent 28µs making 4 calls to Template::Stash::declone, avg 7µs/call
381					# ensure stash is delocalised before dying
382					$self->{ STASH } = $self->{ STASH }->declone();
383					}
384
385	14	14µs			$self->throw(ref $error
386					? $error : (Template::Constants::ERROR_FILE, $error))
387					if $error;
388
389	14	2.29ms			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
407					# spent 170ms (120µs+170) within Template::Context::include which was called 4 times, avg 42.5ms/call: # once (15µs+121ms) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/admin/voters.tt:105] at line 4 of Epoll/root/templates/admin/voters.tt # once (16µs+45.1ms) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/header.tt:65] at line 25 of Epoll/root/templates/includes/header.tt # once (69µs+3.88ms) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/admin/voters.tt:105] at line 34 of Epoll/root/templates/admin/voters.tt # once (19µs+-19µs) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/locale_select_form.tt:13] at line 3 of Epoll/root/templates/includes/locale_select_form.tt sub include {
408	4	14µs			my ($self, $template, $params) = @_;
409	4	219µs	8	19µs	return $self->process($template, $params, 'localize me!'); # spent 19µs making 4 calls to Template::Stash::XS::DESTROY, avg 5µs/call # spent 195ms making 4 calls to Template::Context::process, avg 48.7ms/call, recursion: max depth 2, time 195ms
410					}
411
412					#------------------------------------------------------------------------
413					# insert($file)
414					#
415					# Insert the contents of a file without parsing.
416					#------------------------------------------------------------------------
417
418					sub 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
494					sub 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 errror
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
538					sub 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
565					# spent 190ms (46.8+143) within Template::Context::localise which was called 1724 times, avg 110µs/call: # 1693 times (46.0ms+141ms) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/loc.tt:6] at line 11 of Epoll/root/templates/includes/loc.tt, avg 111µs/call # 27 times (603µs+1.85ms) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/mail/includes/loc.tt:6] at line 11 of Epoll/root/mail/includes/loc.tt, avg 91µs/call # 4 times (180µs+250µs) by Template::Service::process at line 78 of Template/Service.pm, avg 107µs/call sub localise {
566	1724	4.32ms			my $self = shift;
567	1724	40.0ms	1724	143ms	$self->{ STASH } = $self->{ STASH }->clone(@_); # spent 143ms making 1724 calls to Template::Stash::clone, avg 83µs/call
568					}
569
570					# spent 70.0ms (49.1+20.8) within Template::Context::delocalise which was called 1724 times, avg 41µs/call: # 1693 times (48.5ms+20.6ms) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/loc.tt:6] at line 3 of Epoll/root/templates/includes/loc.tt, avg 41µs/call # 27 times (423µs+175µs) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/mail/includes/loc.tt:6] at line 3 of Epoll/root/mail/includes/loc.tt, avg 22µs/call # 4 times (239µs+31µs) by Template::Service::process at line 124 of Template/Service.pm, avg 68µs/call sub delocalise {
571	1724	5.34ms			my $self = shift;
572	1724	36.3ms	1724	20.8ms	$self->{ STASH } = $self->{ STASH }->declone(); # spent 20.8ms making 1724 calls to Template::Stash::declone, avg 12µs/call
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
587					# spent 303µs within Template::Context::visit which was called 14 times, avg 22µs/call: # 14 times (303µs+0s) by Template::Document::process at line 146 of Template/Document.pm, avg 22µs/call sub visit {
588	14	28µs			my ($self, $document, $blocks) = @_;
589	14	173µs			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
603					# spent 118µs within Template::Context::leave which was called 14 times, avg 8µs/call: # 14 times (118µs+0s) by Template::Document::process at line 155 of Template/Document.pm, avg 8µs/call sub leave {
604	14	25µs			my $self = shift;
605	14	125µs			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					# relevent error message (i.e. compilation failure).
618					#------------------------------------------------------------------------
619
620					sub 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
635					sub 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					sub define_view {
651					my ($self, $name, $params) = @_;
652					my $base;
653
654					if (defined $params->{ base }) {
655					my $base = $self->{ STASH }->get($params->{ base });
656
657					return $self->throw(
658					&Template::Constants::ERROR_VIEW,
659					"view base is not defined: $params->{ base }"
660					) unless $base;
661
662					return $self->throw(
663					&Template::Constants::ERROR_VIEW,
664					"view base is not a $VIEW_CLASS object: $params->{ base } => $base"
665					) unless blessed($base) && $base->isa($VIEW_CLASS);
666
667					$params->{ base } = $base;
668					}
669					my $view = $self->view($params);
670					$view->seal();
671					$self->{ STASH }->set($name, $view);
672					}
673
674					sub define_views {
675					my ($self, $views) = @_;
676
677					# a list reference is better because the order is deterministic (and so
678					# allows an earlier VIEW to be the base for a later VIEW), but we'll
679					# accept a hash reference and assume that the user knows the order of
680					# processing is undefined
681					$views = [ %$views ]
682					if ref $views eq 'HASH';
683
684					# make of copy so we don't destroy the original list reference
685					my @items = @$views;
686					my ($name, $view);
687
688					while (@items) {
689					$self->define_view(splice(@items, 0, 2));
690					}
691					}
692
693
694					#------------------------------------------------------------------------
695					# reset()
696					#
697					# Reset the state of the internal BLOCKS hash to clear any BLOCK
698					# definitions imported via the PROCESS directive. Any original
699					# BLOCKS definitions passed to the constructor will be restored.
700					#------------------------------------------------------------------------
701
702					# spent 115µs within Template::Context::reset which was called 4 times, avg 29µs/call: # 4 times (115µs+0s) by Template::Service::process at line 64 of Template/Service.pm, avg 29µs/call sub reset {
703	4	8µs			my ($self, $blocks) = @_;
704	4	75µs			$self->{ BLKSTACK } = [ ];
705	4	48µs			$self->{ BLOCKS } = { %{ $self->{ INIT_BLOCKS } } };
706					}
707
708
709					#------------------------------------------------------------------------
710					# stash()
711					#
712					# Simple accessor methods to return the STASH values. This is likely
713					# to be called quite often so we provide a direct method rather than
714					# relying on the slower AUTOLOAD.
715					#------------------------------------------------------------------------
716
717					# spent 84µs within Template::Context::stash which was called 14 times, avg 6µs/call: # 3 times (14µs+0s) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/mail/includes/loc.tt:17] at line 3 of (eval 0)[Template/Document.pm:78] at line 78 of Template/Document.pm, avg 5µs/call # 3 times (12µs+0s) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/mail/voting_passwd.tt:39] at line 3 of (eval 0)[Template/Document.pm:78] at line 78 of Template/Document.pm, avg 4µs/call # 2 times (12µs+0s) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/locale_select.tt:36] at line 3 of (eval 0)[Template/Document.pm:78] at line 78 of Template/Document.pm, avg 6µs/call # once (11µs+0s) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/footer.tt:15] at line 3 of (eval 0)[Template/Document.pm:78] at line 78 of Template/Document.pm # once (10µs+0s) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/locale_select_form.tt:13] at line 3 of (eval 0)[Template/Document.pm:78] at line 78 of Template/Document.pm # once (8µs+0s) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/admin_menu.tt:31] at line 3 of (eval 0)[Template/Document.pm:78] at line 78 of Template/Document.pm # once (8µs+0s) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/loc.tt:17] at line 3 of (eval 0)[Template/Document.pm:78] at line 78 of Template/Document.pm # once (7µs+0s) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/includes/header.tt:65] at line 3 of (eval 0)[Template/Document.pm:78] at line 78 of Template/Document.pm # once (4µs+0s) by Template::Document::__ANON__[/usr/lib/perl5/vendor_perl/5.10.1/Epoll/root/templates/admin/voters.tt:105] at line 3 of (eval 0)[Template/Document.pm:78] at line 78 of Template/Document.pm sub stash {
718	14	172µs			return $_[0]->{ STASH };
719					}
720
721
722					#------------------------------------------------------------------------
723					# define_vmethod($type, $name, \&sub)
724					#
725					# Passes $type, $name, and &sub on to stash->define_vmethod().
726					#------------------------------------------------------------------------
727					sub define_vmethod {
728					my $self = shift;
729					$self->stash->define_vmethod(@_);
730					}
731
732
733					#------------------------------------------------------------------------
734					# debugging($command, @args, \%params)
735					#
736					# Method for controlling the debugging status of the context. The first
737					# argument can be 'on' or 'off' to enable/disable debugging, 'format'
738					# to define the format of the debug message, or 'msg' to generate a
739					# debugging message reporting the file, line, message text, etc.,
740					# according to the current debug format.
741					#------------------------------------------------------------------------
742
743					sub debugging {
744					my $self = shift;
745					my $hash = ref $_[-1] eq 'HASH' ? pop : { };
746					my @args = @_;
747
748					# print "*** debug(@args)\n";
749					if (@args) {
750					if ($args[0] =~ /^on\|1$/i) {
751					$self->{ DEBUG_DIRS } = 1;
752					shift(@args);
753					}
754					elsif ($args[0] =~ /^off\|0$/i) {
755					$self->{ DEBUG_DIRS } = 0;
756					shift(@args);
757					}
758					}
759
760					if (@args) {
761					if ($args[0] =~ /^msg$/i) {
762					return unless $self->{ DEBUG_DIRS };
763					my $format = $self->{ DEBUG_FORMAT };
764					$format = $DEBUG_FORMAT unless defined $format;
765					$format =~ s/\$(\w+)/$hash->{ $1 }/ge;
766					return $format;
767					}
768					elsif ($args[0] =~ /^format$/i) {
769					$self->{ DEBUG_FORMAT } = $args[1];
770					}
771					# else ignore
772					}
773
774					return '';
775					}
776
777
778					#------------------------------------------------------------------------
779					# AUTOLOAD
780					#
781					# Provides pseudo-methods for read-only access to various internal
782					# members. For example, templates(), plugins(), filters(),
783					# eval_perl(), load_perl(), etc. These aren't called very often, or
784					# may never be called at all.
785					#------------------------------------------------------------------------
786
787					sub AUTOLOAD {
788					my $self = shift;
789					my $method = $AUTOLOAD;
790					my $result;
791
792					$method =~ s/.*:://;
793					return if $method eq 'DESTROY';
794
795					warn "no such context method/member: $method\n"
796					unless defined ($result = $self->{ uc $method });
797
798					return $result;
799					}
800
801
802					#------------------------------------------------------------------------
803					# DESTROY
804					#
805					# Stash may contain references back to the Context via macro closures,
806					# etc. This breaks the circular references.
807					#------------------------------------------------------------------------
808
809					sub DESTROY {
810					my $self = shift;
811					undef $self->{ STASH };
812					}
813
814
815
816					#========================================================================
817					# -- PRIVATE METHODS --
818					#========================================================================
819
820					#------------------------------------------------------------------------
821					# _init(\%config)
822					#
823					# Initialisation method called by Template::Base::new()
824					#------------------------------------------------------------------------
825
826					# spent 47.1ms (965µs+46.1) within Template::Context::_init which was called 4 times, avg 11.8ms/call: # 4 times (965µs+46.1ms) by Template::Base::new at line 65 of Template/Base.pm, avg 11.8ms/call sub _init {
827	4	10µs			my ($self, $config) = @_;
828	4	6µs			my ($name, $item, $method, $block, $blocks);
829	4	24µs			my @itemlut = (
830					LOAD_TEMPLATES => 'provider',
831					LOAD_PLUGINS => 'plugins',
832					LOAD_FILTERS => 'filters'
833					);
834
835					# LOAD_TEMPLATE, LOAD_PLUGINS, LOAD_FILTERS - lists of providers
836	4	24µs			while (($name, $method) = splice(@itemlut, 0, 2)) {
837	12	121µs	12	21.3ms	$item = $config->{ $name } # spent 14.2ms making 4 calls to Template::Config::filters, avg 3.55ms/call # spent 6.27ms making 4 calls to Template::Config::plugins, avg 1.57ms/call # spent 871µs making 4 calls to Template::Config::provider, avg 218µs/call
838					\|\| Template::Config->$method($config)
839					\|\| return $self->error($Template::Config::ERROR);
840	12	142µs			$self->{ $name } = ref $item eq 'ARRAY' ? $item : [ $item ];
841					}
842
843	4	59µs			my $providers = $self->{ LOAD_TEMPLATES };
844	4	16µs			my $prefix_map = $self->{ PREFIX_MAP } = $config->{ PREFIX_MAP } \|\| { };
845	4	23µs			while (my ($key, $val) = each %$prefix_map) {
846					$prefix_map->{ $key } = [ ref $val ? $val :
847					map { $providers->[$_] } split(/\D+/, $val) ]
848					unless ref $val eq 'ARRAY';
849					}
850
851					# STASH
852	4	23µs			$self->{ STASH } = $config->{ STASH } \|\| do {
853					my $predefs = $config->{ VARIABLES }
854					\|\| $config->{ PRE_DEFINE }
855	4	60µs			\|\| { };
856
857					# hack to get stash to know about debug mode
858					$predefs->{ _DEBUG } = ( ($config->{ DEBUG } \|\| 0)
859					& &Template::Constants::DEBUG_UNDEF ) ? 1 : 0
860	4	77µs	4	20µs	unless defined $predefs->{ _DEBUG }; # spent 20µs making 4 calls to Template::Constants::DEBUG_UNDEF, avg 5µs/call
861	4	9µs			$predefs->{ _STRICT } = $config->{ STRICT };
862
863	4	40µs	4	24.8ms	Template::Config->stash($predefs) # spent 24.8ms making 4 calls to Template::Config::stash, avg 6.19ms/call
864					\|\| return $self->error($Template::Config::ERROR);
865					};
866
867					# compile any template BLOCKS specified as text
868	4	13µs			$blocks = $config->{ BLOCKS } \|\| { };
869					$self->{ INIT_BLOCKS } = $self->{ BLOCKS } = {
870					map {
871	4	30µs			$block = $blocks->{ $_ };
872					$block = $self->template(\$block)
873					\|\| return undef
874					unless ref $block;
875					($_ => $block);
876					}
877					keys %$blocks
878					};
879
880					# define any VIEWS
881					$self->define_views( $config->{ VIEWS } )
882	4	8µs			if $config->{ VIEWS };
883
884					# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
885					# RECURSION - flag indicating is recursion into templates is supported
886					# EVAL_PERL - flag indicating if PERL blocks should be processed
887					# TRIM - flag to remove leading and trailing whitespace from output
888					# BLKSTACK - list of hashes of BLOCKs defined in current template(s)
889					# CONFIG - original configuration hash
890					# EXPOSE_BLOCKS - make blocks visible as pseudo-files
891					# DEBUG_FORMAT - format for generating template runtime debugging messages
892					# DEBUG - format for generating template runtime debugging messages
893
894	4	80µs			$self->{ RECURSION } = $config->{ RECURSION } \|\| 0;
895	4	11µs			$self->{ EVAL_PERL } = $config->{ EVAL_PERL } \|\| 0;
896	4	10µs			$self->{ TRIM } = $config->{ TRIM } \|\| 0;
897	4	11µs			$self->{ BLKSTACK } = [ ];
898	4	9µs			$self->{ CONFIG } = $config;
899					$self->{ EXPOSE_BLOCKS } = defined $config->{ EXPOSE_BLOCKS }
900					? $config->{ EXPOSE_BLOCKS }
901	4	11µs			: 0;
902
903	4	17µs			$self->{ DEBUG_FORMAT } = $config->{ DEBUG_FORMAT };
904	4	11µs			$self->{ DEBUG_DIRS } = ($config->{ DEBUG } \|\| 0)
905					& Template::Constants::DEBUG_DIRS;
906					$self->{ DEBUG } = defined $config->{ DEBUG }
907	4	10µs			? $config->{ DEBUG } & ( Template::Constants::DEBUG_CONTEXT
908					\| Template::Constants::DEBUG_FLAGS )
909					: $DEBUG;
910
911	4	46µs			return $self;
912					}
913
914
915					#------------------------------------------------------------------------
916					# _dump()
917					#
918					# Debug method which returns a string representing the internal state
919					# of the context object.
920					#------------------------------------------------------------------------
921
922					sub _dump {
923					my $self = shift;
924					my $output = "[Template::Context] {\n";
925					my $format = " %-16s => %s\n";
926					my $key;
927
928					foreach $key (qw( RECURSION EVAL_PERL TRIM )) {
929					$output .= sprintf($format, $key, $self->{ $key });
930					}
931					foreach my $pname (qw( LOAD_TEMPLATES LOAD_PLUGINS LOAD_FILTERS )) {
932					my $provtext = "[\n";
933					foreach my $prov (@{ $self->{ $pname } }) {
934					$provtext .= $prov->_dump();
935					# $provtext .= ",\n";
936					}
937					$provtext =~ s/\n/\n /g;
938					$provtext =~ s/\s+$//;
939					$provtext .= ",\n ]";
940					$output .= sprintf($format, $pname, $provtext);
941					}
942					$output .= sprintf($format, STASH => $self->{ STASH }->_dump());
943					$output .= '}';
944					return $output;
945					}
946
947
948	1	14µs			1;
949
950					__END__
951
952					=head1 NAME
953
954					Template::Context - Runtime context in which templates are processed
955
956					=head1 SYNOPSIS
957
958					use Template::Context;
959
960					# constructor
961					$context = Template::Context->new(\%config)
962					\|\| die $Template::Context::ERROR;
963
964					# fetch (load and compile) a template
965					$template = $context->template($template_name);
966
967					# fetch (load and instantiate) a plugin object
968					$plugin = $context->plugin($name, \@args);
969
970					# fetch (return or create) a filter subroutine
971					$filter = $context->filter($name, \@args, $alias);
972
973					# process/include a template, errors are thrown via die()
974					$output = $context->process($template, \%vars);
975					$output = $context->include($template, \%vars);
976
977					# raise an exception via die()
978					$context->throw($error_type, $error_message, \$output_buffer);
979
980					# catch an exception, clean it up and fix output buffer
981					$exception = $context->catch($exception, \$output_buffer);
982
983					# save/restore the stash to effect variable localisation
984					$new_stash = $context->localise(\%vars);
985					$old_stash = $context->delocalise();
986
987					# add new BLOCK or FILTER definitions
988					$context->define_block($name, $block);
989					$context->define_filter($name, \&filtersub, $is_dynamic);
990
991					# reset context, clearing any imported BLOCK definitions
992					$context->reset();
993
994					# methods for accessing internal items
995					$stash = $context->stash();
996					$tflag = $context->trim();
997					$epflag = $context->eval_perl();
998					$providers = $context->templates();
999					$providers = $context->plugins();
1000					$providers = $context->filters();
1001					...
1002
1003					=head1 DESCRIPTION
1004
1005					The C<Template::Context> module defines an object class for representing
1006					a runtime context in which templates are processed. It provides an
1007					interface to the fundamental operations of the Template Toolkit
1008					processing engine through which compiled templates (i.e. Perl code
1009					constructed from the template source) can process templates, load
1010					plugins and filters, raise exceptions and so on.
1011
1012					A default C<Template::Context> object is created by the L<Template> module.
1013					Any C<Template::Context> options may be passed to the L<Template>
1014					L<new()\|Template#new()> constructor method and will be forwarded to the
1015					C<Template::Context> constructor.
1016
1017					use Template;
1018
1019					my $template = Template->new({
1020					TRIM => 1,
1021					EVAL_PERL => 1,
1022					BLOCKS => {
1023					header => 'This is the header',
1024					footer => 'This is the footer',
1025					},
1026					});
1027
1028					Similarly, the C<Template::Context> constructor will forward all configuration
1029					parameters onto other default objects (e.g. L<Template::Provider>,
1030					L<Template::Plugins>, L<Template::Filters>, etc.) that it may need to
1031					instantiate.
1032
1033					$context = Template::Context->new({
1034					INCLUDE_PATH => '/home/abw/templates', # provider option
1035					TAG_STYLE => 'html', # parser option
1036					});
1037
1038					A C<Template::Context> object (or subclass) can be explicitly instantiated and
1039					passed to the L<Template> L<new()\|Template#new()> constructor method as the
1040					C<CONTEXT> configuration item.
1041
1042					use Template;
1043					use Template::Context;
1044
1045					my $context = Template::Context->new({ TRIM => 1 });
1046					my $template = Template->new({ CONTEXT => $context });
1047
1048					The L<Template> module uses the L<Template::Config>
1049					L<context()\|Template::Config#context()> factory method to create a default
1050					context object when required. The C<$Template::Config::CONTEXT> package
1051					variable may be set to specify an alternate context module. This will be
1052					loaded automatically and its L<new()> constructor method called by the
1053					L<context()\|Template::Config#context()> factory method when a default context
1054					object is required.
1055
1056					use Template;
1057
1058					$Template::Config::CONTEXT = 'MyOrg::Template::Context';
1059
1060					my $template = Template->new({
1061					EVAL_PERL => 1,
1062					EXTRA_MAGIC => 'red hot', # your extra config items
1063					...
1064					});
1065
1066					=head1 METHODS
1067
1068					=head2 new(\%params)
1069
1070					The C<new()> constructor method is called to instantiate a
1071					C<Template::Context> object. Configuration parameters may be specified as a
1072					HASH reference or as a list of C<name =E<gt> value> pairs.
1073
1074					my $context = Template::Context->new({
1075					INCLUDE_PATH => 'header',
1076					POST_PROCESS => 'footer',
1077					});
1078
1079					my $context = Template::Context->new( EVAL_PERL => 1 );
1080
1081					The C<new()> method returns a C<Template::Context> object or C<undef> on
1082					error. In the latter case, a relevant error message can be retrieved by the
1083					L<error()\|Template::Base#error()> class method or directly from the
1084					C<$Template::Context::ERROR> package variable.
1085
1086					my $context = Template::Context->new(\%config)
1087					\|\| die Template::Context->error();
1088
1089					my $context = Template::Context->new(\%config)
1090					\|\| die $Template::Context::ERROR;
1091
1092					The following configuration items may be specified. Please see
1093					L<Template::Manual::Config> for further details.
1094
1095					=head3 VARIABLES
1096
1097					The L<VARIABLES\|Template::Manual::Config#VARIABLES> option can be used to
1098					specify a hash array of template variables.
1099
1100					my $context = Template::Context->new({
1101					VARIABLES => {
1102					title => 'A Demo Page',
1103					author => 'Joe Random Hacker',
1104					version => 3.14,
1105					},
1106					};
1107
1108					=head3 BLOCKS
1109
1110					The L<BLOCKS\|Template::Manual::Config#BLOCKS> option can be used to pre-define
1111					a default set of template blocks.
1112
1113					my $context = Template::Context->new({
1114					BLOCKS => {
1115					header => 'The Header. [% title %]',
1116					footer => sub { return $some_output_text },
1117					another => Template::Document->new({ ... }),
1118					},
1119					});
1120
1121					=head3 VIEWS
1122
1123					The L<VIEWS\|Template::Manual::Config#VIEWS> option can be used to pre-define
1124					one or more L<Template::View> objects.
1125
1126					my $context = Template::Context->new({
1127					VIEWS => [
1128					bottom => { prefix => 'bottom/' },
1129					middle => { prefix => 'middle/', base => 'bottom' },
1130					top => { prefix => 'top/', base => 'middle' },
1131					],
1132					});
1133
1134					=head3 TRIM
1135
1136					The L<TRIM\|Template::Manual::Config#TRIM> option can be set to have any
1137					leading and trailing whitespace automatically removed from the output of all
1138					template files and C<BLOCK>s.
1139
1140					example:
1141
1142					[% BLOCK foo %]
1143
1144					Line 1 of foo
1145
1146					[% END %]
1147
1148					before
1149					[% INCLUDE foo %]
1150					after
1151
1152					output:
1153
1154					before
1155					Line 1 of foo
1156					after
1157
1158					=head3 EVAL_PERL
1159
1160					The L<EVAL_PERL\|Template::Manual::Config#EVAL_PERL> is used to indicate if
1161					C<PERL> and/or C<RAWPERL> blocks should be evaluated. It is disabled by
1162					default.
1163
1164					=head3 RECURSION
1165
1166					The L<RECURSION\|Template::Manual::Config#RECURSION> can be set to
1167					allow templates to recursively process themselves, either directly
1168					(e.g. template C<foo> calls C<INCLUDE foo>) or indirectly (e.g.
1169					C<foo> calls C<INCLUDE bar> which calls C<INCLUDE foo>).
1170
1171					=head3 LOAD_TEMPLATES
1172
1173					The L<LOAD_TEMPLATES\|Template::Manual::Config#LOAD_TEMPLATES> option can be
1174					used to provide a reference to a list of L<Template::Provider> objects or
1175					sub-classes thereof which will take responsibility for loading and compiling
1176					templates.
1177
1178					my $context = Template::Context->new({
1179					LOAD_TEMPLATES => [
1180					MyOrg::Template::Provider->new({ ... }),
1181					Template::Provider->new({ ... }),
1182					],
1183					});
1184
1185					=head3 LOAD_PLUGINS
1186
1187					The L<LOAD_PLUGINS\|Template::Manual::Config#LOAD_PLUGINS> options can be used
1188					to specify a list of provider objects responsible for loading and
1189					instantiating template plugin objects.
1190
1191					my $context = Template::Context->new({
1192					LOAD_PLUGINS => [
1193					MyOrg::Template::Plugins->new({ ... }),
1194					Template::Plugins->new({ ... }),
1195					],
1196					});
1197
1198					=head3 LOAD_FILTERS
1199
1200					The L<LOAD_FILTERS\|Template::Manual::Config#LOAD_FILTERS> option can be used
1201					to specify a list of provider objects for returning and/or creating filter
1202					subroutines.
1203
1204					my $context = Template::Context->new({
1205					LOAD_FILTERS => [
1206					MyTemplate::Filters->new(),
1207					Template::Filters->new(),
1208					],
1209					});
1210
1211					=head3 STASH
1212
1213					The L<STASH\|Template::Manual::Config#STASH> option can be used to
1214					specify a L<Template::Stash> object or sub-class which will take
1215					responsibility for managing template variables.
1216
1217					my $stash = MyOrg::Template::Stash->new({ ... });
1218					my $context = Template::Context->new({
1219					STASH => $stash,
1220					});
1221
1222					=head3 DEBUG
1223
1224					The L<DEBUG\|Template::Manual::Config#DEBUG> option can be used to enable
1225					various debugging features of the L<Template::Context> module.
1226
1227					use Template::Constants qw( :debug );
1228
1229					my $template = Template->new({
1230					DEBUG => DEBUG_CONTEXT \| DEBUG_DIRS,
1231					});
1232
1233					=head2 template($name)
1234
1235					Returns a compiled template by querying each of the L<LOAD_TEMPLATES> providers
1236					(instances of L<Template::Provider>, or sub-class) in turn.
1237
1238					$template = $context->template('header');
1239
1240					On error, a L<Template::Exception> object of type 'C<file>' is thrown via
1241					C<die()>. This can be caught by enclosing the call to C<template()> in an
1242					C<eval> block and examining C<$@>.
1243
1244					eval { $template = $context->template('header') };
1245					if ($@) {
1246					print "failed to fetch template: $@\n";
1247					}
1248
1249					=head2 plugin($name, \@args)
1250
1251					Instantiates a plugin object by querying each of the L<LOAD_PLUGINS>
1252					providers. The default L<LOAD_PLUGINS> provider is a L<Template::Plugins>
1253					object which attempts to load plugin modules, according the various
1254					configuration items such as L<PLUGIN_BASE\|Template::Plugins#PLUGIN_BASE>,
1255					L<LOAD_PERL\|Template::Plugins#LOAD_PERL>, etc., and then instantiate an object
1256					via L<new()\|Template::Plugin#new()>. A reference to a list of constructor
1257					arguments may be passed as the second parameter. These are forwarded to the
1258					plugin constructor.
1259
1260					Returns a reference to a plugin (which is generally an object, but
1261					doesn't have to be). Errors are thrown as L<Template::Exception> objects
1262					with the type set to 'C<plugin>'.
1263
1264					$plugin = $context->plugin('DBI', 'dbi:msql:mydbname');
1265
1266					=head2 filter($name, \@args, $alias)
1267
1268					Instantiates a filter subroutine by querying the L<LOAD_FILTERS> providers.
1269					The default L<LOAD_FILTERS> provider is a L<Template::Filters> object.
1270
1271					Additional arguments may be passed by list reference along with an optional
1272					alias under which the filter will be cached for subsequent use. The filter is
1273					cached under its own C<$name> if C<$alias> is undefined. Subsequent calls to
1274					C<filter($name)> will return the cached entry, if defined. Specifying arguments
1275					bypasses the caching mechanism and always creates a new filter. Errors are
1276					thrown as L<Template::Exception> objects with the type set to 'C<filter>'.
1277
1278					# static filter (no args)
1279					$filter = $context->filter('html');
1280
1281					# dynamic filter (args) aliased to 'padright'
1282					$filter = $context->filter('format', '%60s', 'padright');
1283
1284					# retrieve previous filter via 'padright' alias
1285					$filter = $context->filter('padright');
1286
1287					=head2 process($template, \%vars)
1288
1289					Processes a template named or referenced by the first parameter and returns
1290					the output generated. An optional reference to a hash array may be passed
1291					as the second parameter, containing variable definitions which will be set
1292					before the template is processed. The template is processed in the current
1293					context, with no localisation of variables performed. Errors are thrown
1294					as L<Template::Exception> objects via C<die()>.
1295
1296					$output = $context->process('header', { title => 'Hello World' });
1297
1298					=head2 include($template, \%vars)
1299
1300					Similar to L<process()>, but using localised variables. Changes made to
1301					any variables will only persist until the C<include()> method completes.
1302
1303					$output = $context->include('header', { title => 'Hello World' });
1304
1305					=head2 throw($error_type, $error_message, \$output)
1306
1307					Raises an exception in the form of a L<Template::Exception> object by calling
1308					C<die()>. This method may be passed a reference to an existing
1309					L<Template::Exception> object; a single value containing an error message
1310					which is used to instantiate a L<Template::Exception> of type 'C<undef>'; or a
1311					pair of values representing the exception C<type> and C<info> from which a
1312					L<Template::Exception> object is instantiated. e.g.
1313
1314					$context->throw($exception);
1315					$context->throw("I'm sorry Dave, I can't do that");
1316					$context->throw('denied', "I'm sorry Dave, I can't do that");
1317
1318					The optional third parameter may be a reference to the current output
1319					buffer. This is then stored in the exception object when created,
1320					allowing the catcher to examine and use the output up to the point at
1321					which the exception was raised.
1322
1323					$output .= 'blah blah blah';
1324					$output .= 'more rhubarb';
1325					$context->throw('yack', 'Too much yacking', \$output);
1326
1327					=head2 catch($exception, \$output)
1328
1329					Catches an exception thrown, either as a reference to a L<Template::Exception>
1330					object or some other value. In the latter case, the error string is promoted
1331					to a L<Template::Exception> object of 'C<undef>' type. This method also
1332					accepts a reference to the current output buffer which is passed to the
1333					L<Template::Exception> constructor, or is appended to the output buffer stored
1334					in an existing L<Template::Exception> object, if unique (i.e. not the same
1335					reference). By this process, the correct state of the output buffer can be
1336					reconstructed for simple or nested throws.
1337
1338					=head2 define_block($name, $block)
1339
1340					Adds a new block definition to the internal L<BLOCKS> cache. The first
1341					argument should contain the name of the block and the second a reference
1342					to a L<Template::Document> object or template sub-routine, or template text
1343					which is automatically compiled into a template sub-routine.
1344
1345					Returns a true value (the sub-routine or L<Template::Document> reference) on
1346					success or undef on failure. The relevant error message can be retrieved by
1347					calling the L<error()\|Template::Base#error()> method.
1348
1349					=head2 define_filter($name, \&filter, $is_dynamic)
1350
1351					Adds a new filter definition by calling the
1352					L<store()\|Template::Filters#store()> method on each of the L<LOAD_FILTERS>
1353					providers until accepted (in the usual case, this is accepted straight away by
1354					the one and only L<Template::Filters> provider). The first argument should
1355					contain the name of the filter and the second a reference to a filter
1356					subroutine. The optional third argument can be set to any true value to
1357					indicate that the subroutine is a dynamic filter factory.
1358
1359					Returns a true value or throws a 'C<filter>' exception on error.
1360
1361					=head2 define_view($name, \%params)
1362
1363					This method allows you to define a named L<view\|Template::View>.
1364
1365					$context->define_view(
1366					my_view => {
1367					prefix => 'my_templates/'
1368					}
1369					);
1370
1371					The view is then accessible as a template variable.
1372
1373					[% my_view.print(some_data) %]
1374
1375					=head2 define_views($views)
1376
1377					This method allows you to define multiple named L<views\|Template::View>.
1378					A reference to a hash array or list reference should be passed as an argument.
1379
1380					$context->define_view({ # hash reference
1381					my_view_one => {
1382					prefix => 'my_templates_one/'
1383					},
1384					my_view_two => {
1385					prefix => 'my_templates_two/'
1386					}
1387					});
1388
1389					If you're defining multiple views of which one or more are based on other
1390					views in the same definition then you should pass them as a list reference.
1391					This ensures that they get created in the right order (Perl does not preserve
1392					the order of items defined in a hash reference so you can't guarantee that
1393					your base class view will be defined before your subclass view).
1394
1395					$context->define_view([ # list referenence
1396					my_view_one => {
1397					prefix => 'my_templates_one/'
1398					},
1399					my_view_two => {
1400					prefix => 'my_templates_two/' ,
1401					base => 'my_view_one',
1402					}
1403					]);
1404
1405					The views are then accessible as template variables.
1406
1407					[% my_view_one.print(some_data) %]
1408					[% my_view_two.print(some_data) %]
1409
1410					See also the L<VIEWS> option.
1411
1412					=head2 localise(\%vars)
1413
1414					Clones the stash to create a context with localised variables. Returns a
1415					reference to the newly cloned stash object which is also stored
1416					internally.
1417
1418					$stash = $context->localise();
1419
1420					=head2 delocalise()
1421
1422					Restore the stash to its state prior to localisation.
1423
1424					$stash = $context->delocalise();
1425
1426					=head2 visit(\%blocks)
1427
1428					This method is called by L<Template::Document> objects immediately before
1429					they process their content. It is called to register any local C<BLOCK>
1430					definitions with the context object so that they may be subsequently
1431					delivered on request.
1432
1433					=head2 leave()
1434
1435					Compliment to the L<visit()> method. Called by L<Template::Document> objects
1436					immediately after they process their content.
1437
1438					=head2 reset()
1439
1440					Clears the local L<BLOCKS> cache of any C<BLOCK> definitions. Any initial set of
1441					L<BLOCKS> specified as a configuration item to the constructor will be reinstated.
1442
1443					=head2 AUTOLOAD
1444
1445					An C<AUTOLOAD> method provides access to context configuration items.
1446
1447					$stash = $context->stash();
1448					$tflag = $context->trim();
1449					$epflag = $context->eval_perl();
1450					...
1451
1452					=head1 AUTHOR
1453
1454					Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
1455
1456					=head1 COPYRIGHT
1457
1458					Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
1459
1460					This module is free software; you can redistribute it and/or
1461					modify it under the same terms as Perl itself.
1462
1463					=head1 SEE ALSO
1464
1465					L<Template>, L<Template::Document>, L<Template::Exception>,
1466					L<Template::Filters>, L<Template::Plugins>, L<Template::Provider>,
1467					L<Template::Service>, L<Template::Stash>
1468
1469					=cut
1470
1471					# Local Variables:
1472					# mode: perl
1473					# perl-indent-level: 4
1474					# indent-tabs-mode: nil
1475					# End:
1476					#
1477					# vim: expandtab shiftwidth=4:
					# spent 45µs within Template::Context::CORE:subst which was called 14 times, avg 3µs/call: # 14 times (45µs+0s) by Template::Context::template at line 116 of Template/Context.pm, avg 3µs/call sub Template::Context::CORE:subst; # xsub