local-lib5/lib/perl5/i486-linux-gnu-thread-multi/Template/Config.pm

   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
  19 package Template::Config;
  20
  21 use strict;
  22 use warnings;
  23 use base 'Template::Base';
  24 use 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::XS';
  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
  60 sub 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
  78 sub 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
  97 sub 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
 115 sub 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
 134 sub 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
 153 sub 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
 172 sub 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
 189 sub 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
 207 sub 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
 225 sub 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
 244 sub 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
 263 sub 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
 285 package Template::TieString;
 286
 287 sub TIEHANDLE {
 288     my ($class, $textref) = @_;
 289     bless $textref, $class;
 290 }
 291 sub PRINT {
 292     my $self = shift;
 293     $$self .= join('', @_);
 294 }
 295
 296
 297
 298 1;
 299
 300 __END__
 301
 302 =head1 NAME
 303
 304 Template::Config - Factory module for instantiating other TT2 modules
 305
 306 =head1 SYNOPSIS
 307
 308     use Template::Config;
 309
 310 =head1 DESCRIPTION
 311
 312 This module implements various methods for loading and instantiating
 313 other modules that comprise the Template Toolkit.  It provides a consistent
 314 way to create toolkit components and allows custom modules to be used in
 315 place of the regular ones.
 316
 317 Package variables such as C<$STASH>, C<$SERVICE>, C<$CONTEXT>, etc., contain
 318 the default module/package name for each component (L<Template::Stash>,
 319 L<Template::Service> and L<Template::Context>, respectively) and are used by
 320 the various factory methods (L<stash()>, L<service()> and L<context()>) to
 321 load the appropriate module. Changing these package variables will cause
 322 subsequent calls to the relevant factory method to load and instantiate an
 323 object from the new class.
 324
 325 =head1 PUBLIC METHODS
 326
 327 =head2 load($module)
 328
 329 Load a module using Perl's L<require()>. Any occurences of 'C<::>' in the module
 330 name are be converted to 'C</>', and 'C<.pm>' is appended. Returns 1 on success or
 331 undef on error.  Use C<$class-E<gt>error()> to examine the error string.
 332
 333 =head2 preload()
 334
 335 This method preloads all the other C<Template::*> modules that are likely to
 336 be used. It is called automatically by the L<Template> module when running
 337 under mod_perl (C<$ENV{MOD_PERL}> is set).
 338
 339 =head2 parser(\%config)
 340
 341 Instantiate a new parser object of the class whose name is denoted by
 342 the package variable C<$PARSER> (default: L<Template::Parser>).  Returns
 343 a reference to a newly instantiated parser object or undef on error.
 344
 345 =head2 provider(\%config)
 346
 347 Instantiate a new template provider object (default: L<Template::Provider>).
 348 Returns an object reference or undef on error, as above.
 349
 350 =head2 plugins(\%config)
 351
 352 Instantiate a new plugins provider object (default: L<Template::Plugins>).
 353 Returns an object reference or undef on error, as above.
 354
 355 =head2 filters(\%config)
 356
 357 Instantiate a new filter provider object (default: L<Template::Filters>).
 358 Returns an object reference or undef on error, as above.
 359
 360 =head2 stash(\%vars)
 361
 362 Instantiate a new stash object (L<Template::Stash> or L<Template::Stash::XS>
 363 depending on the default set at installation time) using the contents of the
 364 optional hash array passed by parameter as initial variable definitions.
 365 Returns an object reference or undef on error, as above.
 366
 367 =head2 context(\%config)
 368
 369 Instantiate a new template context object (default: L<Template::Context>).
 370 Returns an object reference or undef on error, as above.
 371
 372 =head2 service(\%config)
 373
 374 Instantiate a new template service object (default: L<Template::Service>).
 375 Returns an object reference or undef on error, as above.
 376
 377 =head2 iterator(\%config)
 378
 379 Instantiate a new template iterator object (default: L<Template::Iterator>).
 380 Returns an object reference or undef on error, as above.
 381
 382 =head2 constants(\%config)
 383
 384 Instantiate a new namespace handler for compile time constant folding
 385 (default: L<Template::Namespace::Constants>). Returns an object reference or
 386 undef on error, as above.
 387
 388 =head2 instdir($dir)
 389
 390 Returns the root directory of the Template Toolkit installation under
 391 which optional components are installed.  Any relative directory specified
 392 as 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
 402 Returns C<undef> and sets C<$Template::Config::ERROR> appropriately if the
 403 optional components of the Template Toolkit have not been installed.
 404
 405 =head1 AUTHOR
 406
 407 Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
 408
 409 =head1 COPYRIGHT
 410
 411 Copyright (C) 1996-2007 Andy Wardley.  All Rights Reserved.
 412
 413 This module is free software; you can redistribute it and/or
 414 modify it under the same terms as Perl itself.
 415
 416 =head1 SEE ALSO
 417
 418 L<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: