Config::TT2 - Reading configuration files with the Template-Toolkit parser.
Define configuration files in the powerful, flexible and extensible Template-Toolkit syntax.
use Config::TT2; my $ctt2 = Config::TT2->new; my $cfg_stash = $ctt2->process($file);
Config::TT2 extends the Template-Toolkit aka TT2 in a very special way:
Config::TT2
Template-Toolkit
TT2
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
The new() constructor method instantiates a new Config::TT2 object. This method croaks on error.
new()
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.
Template
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
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.
process()
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:
Template::Stash
$item = $stash->{hash}{moo}[0];
or via the Template::Stash->get method like:
Template::Stash->get
$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.
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.
template
component
See the section "Special Variables" in Template::Manual::Variables.
The process method purges these toplevel variables unconditionally after processing but before returning the stash.
process
See also the special meaning of the global toplevel variable.
global
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
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.
Template::Manual::Intro, Template::Manual::Syntax, Template::Manual::Config, Template::Manual::Variables, Template::Manual::VMethods
Karl Gaissmaier, <gaissmai at cpan.org>
<gaissmai at cpan.org>
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.
bug-config-tt at rt.cpan.org
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/
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.
To install Config::TT2, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::TT2
CPAN shell
perl -MCPAN -e shell install Config::TT2
For more information on module installation, please visit the detailed CPAN module installation guide.