1#============================================================= -*-perl-*-
2#
3# Template::Config
4#
5# DESCRIPTION
6#   Template Toolkit configuration module.
7#
8# AUTHOR
9#   Andy Wardley   <abw@wardley.org>
10#
11# COPYRIGHT
12#   Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
13#
14#   This module is free software; you can redistribute it and/or
15#   modify it under the same terms as Perl itself.
16#
17#========================================================================
18
19package Template::Config;
20
21use strict;
22use warnings;
23use base 'Template::Base';
24use vars qw( $VERSION $DEBUG $ERROR $INSTDIR
25             $PARSER $PROVIDER $PLUGINS $FILTERS $ITERATOR
26             $LATEX_PATH $PDFLATEX_PATH $DVIPS_PATH
27             $STASH $SERVICE $CONTEXT $CONSTANTS @PRELOAD );
28
29$VERSION   = 2.75;
30$DEBUG     = 0 unless defined $DEBUG;
31$ERROR     = '';
32$CONTEXT   = 'Template::Context';
33$FILTERS   = 'Template::Filters';
34$ITERATOR  = 'Template::Iterator';
35$PARSER    = 'Template::Parser';
36$PLUGINS   = 'Template::Plugins';
37$PROVIDER  = 'Template::Provider';
38$SERVICE   = 'Template::Service';
39$STASH     = 'Template::Stash';
40$CONSTANTS = 'Template::Namespace::Constants';
41
42@PRELOAD   = ( $CONTEXT, $FILTERS, $ITERATOR, $PARSER,
43               $PLUGINS, $PROVIDER, $SERVICE, $STASH );
44
45# the following is set at installation time by the Makefile.PL
46$INSTDIR  = '';
47
48
49#========================================================================
50#                       --- CLASS METHODS ---
51#========================================================================
52
53#------------------------------------------------------------------------
54# preload($module, $module, ...)
55#
56# Preloads all the standard TT modules that are likely to be used, along
57# with any other passed as arguments.
58#------------------------------------------------------------------------
59
60sub preload {
61    my $class = shift;
62
63    foreach my $module (@PRELOAD, @_) {
64        $class->load($module) || return;
65    };
66    return 1;
67}
68
69
70#------------------------------------------------------------------------
71# load($module)
72#
73# Load a module via require().  Any occurences of '::' in the module name
74# are be converted to '/' and '.pm' is appended.  Returns 1 on success
75# or undef on error.  Use $class->error() to examine the error string.
76#------------------------------------------------------------------------
77
78sub load {
79    my ($class, $module) = @_;
80    $module =~ s[::][/]g;
81    $module .= '.pm';
82    eval { require $module; };
83    return $@ ? $class->error("failed to load $module: $@") : 1;
84}
85
86
87#------------------------------------------------------------------------
88# parser(\%params)
89#
90# Instantiate a new parser object of the class whose name is denoted by
91# the package variable $PARSER (default: Template::Parser).  Returns
92# a reference to a newly instantiated parser object or undef on error.
93# The class error() method can be called without arguments to examine
94# the error message generated by this failure.
95#------------------------------------------------------------------------
96
97sub parser {
98    my $class  = shift;
99    my $params = defined($_[0]) && ref($_[0]) eq 'HASH'
100               ? shift : { @_ };
101
102    return undef unless $class->load($PARSER);
103    return $PARSER->new($params)
104        || $class->error("failed to create parser: ", $PARSER->error);
105}
106
107
108#------------------------------------------------------------------------
109# provider(\%params)
110#
111# Instantiate a new template provider object (default: Template::Provider).
112# Returns an object reference or undef on error, as above.
113#------------------------------------------------------------------------
114
115sub provider {
116    my $class  = shift;
117    my $params = defined($_[0]) && ref($_[0]) eq 'HASH'
118               ? shift : { @_ };
119
120    return undef unless $class->load($PROVIDER);
121    return $PROVIDER->new($params)
122        || $class->error("failed to create template provider: ",
123                         $PROVIDER->error);
124}
125
126
127#------------------------------------------------------------------------
128# plugins(\%params)
129#
130# Instantiate a new plugins provider object (default: Template::Plugins).
131# Returns an object reference or undef on error, as above.
132#------------------------------------------------------------------------
133
134sub plugins {
135    my $class  = shift;
136    my $params = defined($_[0]) && ref($_[0]) eq 'HASH'
137               ? shift : { @_ };
138
139    return undef unless $class->load($PLUGINS);
140    return $PLUGINS->new($params)
141        || $class->error("failed to create plugin provider: ",
142                         $PLUGINS->error);
143}
144
145
146#------------------------------------------------------------------------
147# filters(\%params)
148#
149# Instantiate a new filters provider object (default: Template::Filters).
150# Returns an object reference or undef on error, as above.
151#------------------------------------------------------------------------
152
153sub filters {
154    my $class  = shift;
155    my $params = defined($_[0]) && ref($_[0]) eq 'HASH'
156               ? shift : { @_ };
157
158    return undef unless $class->load($FILTERS);
159    return $FILTERS->new($params)
160        || $class->error("failed to create filter provider: ",
161                         $FILTERS->error);
162}
163
164
165#------------------------------------------------------------------------
166# iterator(\@list)
167#
168# Instantiate a new Template::Iterator object (default: Template::Iterator).
169# Returns an object reference or undef on error, as above.
170#------------------------------------------------------------------------
171
172sub iterator {
173    my $class = shift;
174    my $list  = shift;
175
176    return undef unless $class->load($ITERATOR);
177    return $ITERATOR->new($list, @_)
178        || $class->error("failed to create iterator: ", $ITERATOR->error);
179}
180
181
182#------------------------------------------------------------------------
183# stash(\%vars)
184#
185# Instantiate a new template variable stash object (default:
186# Template::Stash). Returns object or undef, as above.
187#------------------------------------------------------------------------
188
189sub stash {
190    my $class  = shift;
191    my $params = defined($_[0]) && ref($_[0]) eq 'HASH'
192               ? shift : { @_ };
193
194    return undef unless $class->load($STASH);
195    return $STASH->new($params)
196        || $class->error("failed to create stash: ", $STASH->error);
197}
198
199
200#------------------------------------------------------------------------
201# context(\%params)
202#
203# Instantiate a new template context object (default: Template::Context).
204# Returns object or undef, as above.
205#------------------------------------------------------------------------
206
207sub context {
208    my $class  = shift;
209    my $params = defined($_[0]) && ref($_[0]) eq 'HASH'
210               ? shift : { @_ };
211
212    return undef unless $class->load($CONTEXT);
213    return $CONTEXT->new($params)
214        || $class->error("failed to create context: ", $CONTEXT->error);
215}
216
217
218#------------------------------------------------------------------------
219# service(\%params)
220#
221# Instantiate a new template context object (default: Template::Service).
222# Returns object or undef, as above.
223#------------------------------------------------------------------------
224
225sub service {
226    my $class  = shift;
227    my $params = defined($_[0]) && ref($_[0]) eq 'HASH'
228               ? shift : { @_ };
229
230    return undef unless $class->load($SERVICE);
231    return $SERVICE->new($params)
232        || $class->error("failed to create context: ", $SERVICE->error);
233}
234
235
236#------------------------------------------------------------------------
237# constants(\%params)
238#
239# Instantiate a new namespace handler for compile time constant folding
240# (default: Template::Namespace::Constants).
241# Returns object or undef, as above.
242#------------------------------------------------------------------------
243
244sub constants {
245    my $class  = shift;
246    my $params = defined($_[0]) && ref($_[0]) eq 'HASH'
247               ? shift : { @_ };
248
249    return undef unless $class->load($CONSTANTS);
250    return $CONSTANTS->new($params)
251        || $class->error("failed to create constants namespace: ",
252                         $CONSTANTS->error);
253}
254
255
256#------------------------------------------------------------------------
257# instdir($dir)
258#
259# Returns the root installation directory appended with any local
260# component directory passed as an argument.
261#------------------------------------------------------------------------
262
263sub instdir {
264    my ($class, $dir) = @_;
265    my $inst = $INSTDIR
266        || return $class->error("no installation directory");
267    $inst =~ s[/$][]g;
268    $inst .= "/$dir" if $dir;
269    return $inst;
270}
271
272
273#========================================================================
274# This should probably be moved somewhere else in the long term, but for
275# now it ensures that Template::TieString is available even if the
276# Template::Directive module hasn't been loaded, as is the case when
277# using compiled templates and Template::Parser hasn't yet been loaded
278# on demand.
279#========================================================================
280
281#------------------------------------------------------------------------
282# simple package for tying $output variable to STDOUT, used by perl()
283#------------------------------------------------------------------------
284
285package Template::TieString;
286
287sub TIEHANDLE {
288    my ($class, $textref) = @_;
289    bless $textref, $class;
290}
291sub PRINT {
292    my $self = shift;
293    $$self .= join('', @_);
294}
295
296
297
2981;
299
300__END__
301
302=head1 NAME
303
304Template::Config - Factory module for instantiating other TT2 modules
305
306=head1 SYNOPSIS
307
308    use Template::Config;
309
310=head1 DESCRIPTION
311
312This module implements various methods for loading and instantiating
313other modules that comprise the Template Toolkit.  It provides a consistent
314way to create toolkit components and allows custom modules to be used in
315place of the regular ones.
316
317Package variables such as C<$STASH>, C<$SERVICE>, C<$CONTEXT>, etc., contain
318the default module/package name for each component (L<Template::Stash>,
319L<Template::Service> and L<Template::Context>, respectively) and are used by
320the various factory methods (L<stash()>, L<service()> and L<context()>) to
321load the appropriate module. Changing these package variables will cause
322subsequent calls to the relevant factory method to load and instantiate an
323object from the new class.
324
325=head1 PUBLIC METHODS
326
327=head2 load($module)
328
329Load a module using Perl's L<require()>. Any occurences of 'C<::>' in the module
330name are be converted to 'C</>', and 'C<.pm>' is appended. Returns 1 on success or
331undef on error.  Use C<$class-E<gt>error()> to examine the error string.
332
333=head2 preload()
334
335This method preloads all the other C<Template::*> modules that are likely to
336be used. It is called automatically by the L<Template> module when running
337under mod_perl (C<$ENV{MOD_PERL}> is set).
338
339=head2 parser(\%config)
340
341Instantiate a new parser object of the class whose name is denoted by
342the package variable C<$PARSER> (default: L<Template::Parser>).  Returns
343a reference to a newly instantiated parser object or undef on error.
344
345=head2 provider(\%config)
346
347Instantiate a new template provider object (default: L<Template::Provider>).
348Returns an object reference or undef on error, as above.
349
350=head2 plugins(\%config)
351
352Instantiate a new plugins provider object (default: L<Template::Plugins>).
353Returns an object reference or undef on error, as above.
354
355=head2 filters(\%config)
356
357Instantiate a new filter provider object (default: L<Template::Filters>).
358Returns an object reference or undef on error, as above.
359
360=head2 stash(\%vars)
361
362Instantiate a new stash object (L<Template::Stash> or L<Template::Stash::XS>
363depending on the default set at installation time) using the contents of the
364optional hash array passed by parameter as initial variable definitions.
365Returns an object reference or undef on error, as above.
366
367=head2 context(\%config)
368
369Instantiate a new template context object (default: L<Template::Context>).
370Returns an object reference or undef on error, as above.
371
372=head2 service(\%config)
373
374Instantiate a new template service object (default: L<Template::Service>).
375Returns an object reference or undef on error, as above.
376
377=head2 iterator(\%config)
378
379Instantiate a new template iterator object (default: L<Template::Iterator>).
380Returns an object reference or undef on error, as above.
381
382=head2 constants(\%config)
383
384Instantiate a new namespace handler for compile time constant folding
385(default: L<Template::Namespace::Constants>). Returns an object reference or
386undef on error, as above.
387
388=head2 instdir($dir)
389
390Returns the root directory of the Template Toolkit installation under
391which optional components are installed.  Any relative directory specified
392as an argument will be appended to the returned directory.
393
394    # e.g. returns '/usr/local/tt2'
395    my $ttroot = Template::Config->instdir()
396        || die "$Template::Config::ERROR\n";
397
398    # e.g. returns '/usr/local/tt2/templates'
399    my $template = Template::Config->instdir('templates')
400        || die "$Template::Config::ERROR\n";
401
402Returns C<undef> and sets C<$Template::Config::ERROR> appropriately if the
403optional components of the Template Toolkit have not been installed.
404
405=head1 AUTHOR
406
407Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
408
409=head1 COPYRIGHT
410
411Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
412
413This module is free software; you can redistribute it and/or
414modify it under the same terms as Perl itself.
415
416=head1 SEE ALSO
417
418L<Template>
419
420=cut
421
422# Local Variables:
423# mode: perl
424# perl-indent-level: 4
425# indent-tabs-mode: nil
426# End:
427#
428# vim: expandtab shiftwidth=4:
429