version 0.5, nearly CPAN ready

Build.PL

@@ -7,6 +7,7 @@ my $builder = Module::Build->new(
     license           => 'perl',
     dist_author       => q{Karl Gaissmaier <gaissmai@cpan.org>},
     dist_version_from => 'lib/Config/TT.pm',
+    create_readme     => 1,
     build_requires    => { 'Test::More' => 0, },
     requires          => {
         'Template'  => '2.21',

Changes

@@ -1,5 +1,5 @@
 Revision history for Config-TT
 
-0.01    Date/time
-        First version, released on an unsuspecting world.
+0.50    Mon, 09 Jul 2012 22:08:38 +0200
+        Prepare the CPAN upload after internal hacking
 

MANIFEST.SKIP

@@ -29,6 +29,8 @@
 \#$
 \b\.#
 \.bak$
+^temp/
+^test/
 
 # Avoid Devel::Cover files.
 \bcover_db\b

META.yml

@@ -1,5 +1,5 @@
 ---
-abstract: 'Config files'
+abstract: 'Reading configuration files with the Template-Toolkit parser.'
 author:
   - 'Karl Gaissmaier <gaissmai@cpan.org>'
 build_requires:
@@ -12,12 +12,10 @@ meta-spec:
   url: http://module-build.sourceforge.net/META-spec-v1.4.html
   version: 1.4
 name: Config-TT
-provides:
-  Config::TT:
-    file: lib/Config/TT.pm
-    version: 0.01
 requires:
-  Template: 2.24
+  Carp: 0
+  Template: 2.21
+  Try::Tiny: 0
 resources:
   license: http://dev.perl.org/licenses/
-version: 0.01
+version: 0.50

MYMETA.yml

@@ -1,5 +1,5 @@
 ---
-abstract: 'Config files'
+abstract: 'Reading configuration files with the Template-Toolkit parser.'
 author:
   - 'Karl Gaissmaier <gaissmai@cpan.org>'
 build_requires:
@@ -13,14 +13,10 @@ meta-spec:
   url: http://module-build.sourceforge.net/META-spec-v1.4.html
   version: 1.4
 name: Config-TT
-provides:
-  Config::TT:
-    file: lib/Config/TT.pm
-    version: 0.01
 requires:
   Carp: 0
   Template: 2.21
   Try::Tiny: 0
 resources:
   license: http://dev.perl.org/licenses/
-version: 0.01
+version: 0.50

README

@@ -1,55 +1,199 @@
-Config-TT
+NAME
+    Config::TT - Reading configuration files with the Template-Toolkit
+    parser.
 
-The README is used to introduce the module and provide instructions on
-how to install the module, any machine dependencies it may have (for
-example C compilers and installed libraries) and any other information
-that should be provided before the module is installed.
+ABSTRACT
+    Define configuration files in the powerful, flexible and extensible
+    Template-Toolkit syntax.
 
-A README file is required for CPAN modules since CPAN extracts the README
-file from a module distribution so that people browsing the archive
-can use it to get an idea of the module's uses. It is usually a good idea
-to provide version information here so that people can decide whether
-fixes for the module are worth downloading.
+SYNOPSIS
+        use Config::TT;
 
+        my $ctt   = Config::TT->new;
+        my $stash = $ctt->process($file);
 
-INSTALLATION
+DESCRIPTION
+    "Config::TT" extends the "Template-Toolkit" aka "TT" in a very special
+    way:
 
-To install this module, run the following commands:
+    It returns the VARIABLES STASH instead of the template text!
 
-	perl Build.PL
-	./Build
-	./Build test
-	./Build install
+    The TT syntax is very powerful, flexible and extensible. One of the key
+    features of TT is the ability to bind template variables to any kind of
+    Perl data: scalars, lists, hash arrays, sub-routines and objects.
 
-SUPPORT AND DOCUMENTATION
+    e.g. this Template-Toolkit config
 
-After installing, you can find documentation for this module with the
-perldoc command.
+      [%                        # tt2 directive start-tag
+        scalar = 'string'       # strings in single or double quotes
 
-    perldoc Config::TT
+        array = [ 10 20 30 ]    # commas are optional
+        rev   = array.reverse   # powerful virtual methods
+        item  = array.0         # interpolate previous value
 
-You can also look for information at:
+        hash = { foo = 'bar'    # hashes to any depth
+                 moo = array    # points to above arrayref
+               }
+      %]
 
-    RT, CPAN's request tracker (report bugs here)
-        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Config-TT
+    is returned as a perl datastructure:
 
-    AnnoCPAN, Annotated CPAN documentation
-        http://annocpan.org/dist/Config-TT
+       '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
 
-    CPAN Ratings
-        http://cpanratings.perl.org/d/Config-TT
+    See the Template::Manuals for the whole story.
 
-    Search CPAN
-        http://search.cpan.org/dist/Config-TT/
+METHODS
+  new(%config)
+    The "new()" constructor method instantiates a new "Config::TT" object.
+    This method croaks on error.
 
+    Configuration items may be passed as a list of items or a hash array:
 
-LICENSE AND COPYRIGHT
+        my $ctt = 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 = $ctt->process( '.myapp.cfg', { foo => $ENV{MYAPP_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) = $ctt->process( $config );
+
+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.
+
+    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::TT instance MUST be
+    avoided. The Template CONTEXT and STASH have states belonging to the
+    processed config text. Create new instances for different "process"
+    calls.
+
+       $stash1 = Config::TT->new->process($file1);
+       $stash2 = Config::TT->new->process($file2);
+
+    The following Template options are not supported with Config::TT:
 
-Copyright (C) 2012 Karl Gaissmaier
+          PRE_PROCESS
+          PROCESS
+          POST_PROCESS
+          WRAPPER
+          AUTO_RESET
+          DEFAULT
+          OUTPUT
+          OUTPUT_PATH
+          ERROR
+          ERRORS
+
+EXTENSIBILITY
+  context()
+    This is a setter/getter method to access/change the underlying
+    Template::Context object of the Config::TT instance. Through the context
+    you can also access the stash and do weird things.
+
+       $ctt = Config::TT->new;
+       $stash = $ctt->context->stash;
+
+       $stash->define_vmethod($type, $name, $code);
+
+    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-TT>. 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::TT
+
+    You can also look for information at:
+
+    *   RT: CPAN's request tracker (report bugs here)
+
+        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Config-TT>
+
+    *   AnnoCPAN: Annotated CPAN documentation
+
+        <http://annocpan.org/dist/Config-TT>
+
+    *   CPAN Ratings
+
+        <http://cpanratings.perl.org/d/Config-TT>
+
+    *   Search CPAN
+
+        <http://search.cpan.org/dist/Config-TT/>
+
+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.
+    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.
+    See http://dev.perl.org/licenses/ for more information.