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 = Template->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.

