NAME
   Config::TT2 - Reading configuration files with the Template-Toolkit
   parser.

ABSTRACT
   Define configuration files in the powerful, flexible and extensible
   Template-Toolkit syntax.

SYNOPSIS
       use Config::TT2;

       my $ctt2      = Config::TT2->new;
       my $cfg_stash = $ctt2->process($file);

DESCRIPTION
   "Config::TT2" extends the "Template-Toolkit" aka "TT2" in a very special
   way:

   It returns the VARIABLES STASH instead of the template text!

   The TT2 syntax is very powerful, flexible and extensible. One of the key
   features of TT2 is the ability to bind template variables to any kind of
   Perl data: scalars, lists, hash arrays, sub-routines and objects.

   See Template::Manual::Variables for a reference.

   E.g. this Template-Toolkit config

     [%                        # tt2 directive start-tag
       scalar = 'string'       # strings in single or double quotes

       array = [ 10 20 30 ]    # commas are optional
       rev   = array.reverse   # powerful virtual methods
       item  = array.0         # interpolate previous value

       hash = { foo = 'bar'    # hashes to any depth
                moo = array    # points to above arrayref
              }
     %]                        # tt2 directive end-tag

   is returned as a perl datastructure:

      'scalar' => 'string'
      'array' => ARRAY(0x8ad2708)
         0  10
         1  20
         2  30
      'rev' => ARRAY(0x8afe740)
         0  30
         1  20
         2  10
      'item' => 10
      'hash' => HASH(0x8afe160)
         'foo' => 'bar'
         'moo' => ARRAY(0x8ad2708)
            -> REUSED_ADDRESS

METHODS
 new(%config)
   The "new()" constructor method instantiates a new "Config::TT2" object.
   This method croaks on error.

   Configuration items may be passed as a list of items or a hash array:

       my $ctt2 = Config::TT2->new(
           ABSOLUTE => 0,
           DEBUG    => 'all',
       );

   The supported configuration options are the same as for "Template",
   please see the Template::Manual::Config as a reference and the
   LIMITATIONS section below.

   The preset default options which differ from the Template default
   options are:

     STRICT     = 1   # undefined vars or values cause exceptions
     ABSOLUTE   = 1   # files with absolute filenames allowed
     RELATIVE   = 1   # files with relative filenames allowed
     CACHE_SIZE = 0   # don't cache compiled config files

 process($config, $variables)
   The "process()" method is called to process a config file or string. The
   first parameter indicates the input as one of: a filename; a reference
   to a text string containing the config text; or a file handle reference,
   from which the config can be read.

   A reference to a hash array may be passed as the second parameter,
   containing definitions of input variables.

       $stash = $ctt2->process( '.app.cfg', {foo => $ENV{APP_FOO}} );

   The returned datastructure is a "Template::Stash" object. You may access
   the key and values through normal perl dereferencing:

      $item = $stash->{hash}{moo}[0];

   or via the "Template::Stash->get" method like:

      $item = $stash->get('hash.moo.0');

   For debugging purposes you can even request the template output from the
   process method:

     ($stash, $output) = $ctt2->process( $config );

   The method croaks on error.

LIMITATIONS
   The Template-Toolkit processor uses the toplevel variables "template"
   und "component" for meta information during template file processing.
   You MUST NOT define or redefine these toplevel variables at object
   creation, processing or within the config files.

   See the section "Special Variables" in Template::Manual::Variables.

   The "process" method purges these toplevel variables unconditionally
   after processing but before returning the stash.

   See also the special meaning of the "global" toplevel variable.

   Successive calls to "process" with the same Config::TT2 instance MUST be
   avoided. The Template CONTEXT and STASH have states belonging to the
   processed config text. Create new instances for successive "process"
   calls.

      $stash1 = Config::TT2->new->process($file1);
      $stash2 = Config::TT2->new->process($file2);

   The following Template options are not supported with Config::TT2:

         PRE_PROCESS
         PROCESS
         POST_PROCESS
         WRAPPER
         AUTO_RESET
         DEFAULT
         OUTPUT
         OUTPUT_PATH
         ERROR
         ERRORS

EXTENSIONS AND VIRTUAL METHODS
   With the "context" method you can get/set the underlying
   Template::Context object.

 context()
   Getter/setter method for the underlying Template::Context object.

   With the context you can also access the stash and define new virtual
   methods BEFORE processing.

       $ctt2 = Config::TT2->new;
       $ctt2->context->stash->define_vmethod( $type, $name, $code_ref );
       $cfg_stash = $ctt2->process($cfg_file);

   See the manuals Template::Stash, Template::Context and
   Template::Manual::Internals.

SEE ALSO
   Template::Manual::Intro, Template::Manual::Syntax,
   Template::Manual::Config, Template::Manual::Variables,
   Template::Manual::VMethods

AUTHOR
   Karl Gaissmaier, "<gaissmai at cpan.org>"

BUGS
   Please report any bugs or feature requests to "bug-config-tt at
   rt.cpan.org", or through the web interface at
   <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Config-TT2>. I will be
   notified, and then you'll automatically be notified of progress on your
   bug as I make changes.

SUPPORT
   You can find documentation for this module with the perldoc command.

       perldoc Config::TT2

   You can also look for information at:

   *   RT: CPAN's request tracker (report bugs here)

       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Config-TT2>

   *   AnnoCPAN: Annotated CPAN documentation

       <http://annocpan.org/dist/Config-TT2>

   *   CPAN Ratings

       <http://cpanratings.perl.org/d/Config-TT2>

   *   Search CPAN

       <http://search.cpan.org/dist/Config-TT2/>

LICENSE AND COPYRIGHT
   Copyright 2012 Karl Gaissmaier.

   This program is free software; you can redistribute it and/or modify it
   under the terms of either: the GNU General Public License as published
   by the Free Software Foundation; or the Artistic License.

   See http://dev.perl.org/licenses/ for more information.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.