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 occurrences 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 occurrences of 'C<::>' in the 330module name are be converted to 'C</>', and 'C<.pm>' is appended. Returns 1 on 331success or undef on error. Use C<$class-E<gt>error()> to examine the error 332string. 333 334=head2 preload() 335 336This method preloads all the other C<Template::*> modules that are likely to 337be used. It is called automatically by the L<Template> module when running 338under mod_perl (C<$ENV{MOD_PERL}> is set). 339 340=head2 parser(\%config) 341 342Instantiate a new parser object of the class whose name is denoted by 343the package variable C<$PARSER> (default: L<Template::Parser>). Returns 344a reference to a newly instantiated parser object or undef on error. 345 346=head2 provider(\%config) 347 348Instantiate a new template provider object (default: L<Template::Provider>). 349Returns an object reference or undef on error, as above. 350 351=head2 plugins(\%config) 352 353Instantiate a new plugins provider object (default: L<Template::Plugins>). 354Returns an object reference or undef on error, as above. 355 356=head2 filters(\%config) 357 358Instantiate a new filter provider object (default: L<Template::Filters>). 359Returns an object reference or undef on error, as above. 360 361=head2 stash(\%vars) 362 363Instantiate a new stash object (L<Template::Stash> or L<Template::Stash::XS> 364depending on the default set at installation time) using the contents of the 365optional hash array passed by parameter as initial variable definitions. 366Returns an object reference or undef on error, as above. 367 368=head2 context(\%config) 369 370Instantiate a new template context object (default: L<Template::Context>). 371Returns an object reference or undef on error, as above. 372 373=head2 service(\%config) 374 375Instantiate a new template service object (default: L<Template::Service>). 376Returns an object reference or undef on error, as above. 377 378=head2 iterator(\%config) 379 380Instantiate a new template iterator object (default: L<Template::Iterator>). 381Returns an object reference or undef on error, as above. 382 383=head2 constants(\%config) 384 385Instantiate a new namespace handler for compile time constant folding 386(default: L<Template::Namespace::Constants>). Returns an object reference or 387undef on error, as above. 388 389=head2 instdir($dir) 390 391Returns the root directory of the Template Toolkit installation under 392which optional components are installed. Any relative directory specified 393as an argument will be appended to the returned directory. 394 395 # e.g. returns '/usr/local/tt2' 396 my $ttroot = Template::Config->instdir() 397 || die "$Template::Config::ERROR\n"; 398 399 # e.g. returns '/usr/local/tt2/templates' 400 my $template = Template::Config->instdir('templates') 401 || die "$Template::Config::ERROR\n"; 402 403Returns C<undef> and sets C<$Template::Config::ERROR> appropriately if the 404optional components of the Template Toolkit have not been installed. 405 406=head1 AUTHOR 407 408Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/> 409 410=head1 COPYRIGHT 411 412Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved. 413 414This module is free software; you can redistribute it and/or 415modify it under the same terms as Perl itself. 416 417=head1 SEE ALSO 418 419L<Template> 420 421=cut 422 423# Local Variables: 424# mode: perl 425# perl-indent-level: 4 426# indent-tabs-mode: nil 427# End: 428# 429# vim: expandtab shiftwidth=4: 430