Text version 0.01
=================

FORWARD
    This module is template facility who's focus is on generating code such
    as c, java or sql. While generating perl code is also possible, there is
    a potential conflict between the control-symbol and the perl comment
    symbol.

    Perl is excelent at manipulating text, and it begs the question why one
    would need such a tool. The answer is that good code design should be
    such that applications should not have to be modified so as to make
    configuration changes. Thus external configuration files/data is used.
    However, if these files are read in as perl-code, then simple errors
    could crash the whole application (or provide subtle security risks).
    Further, it is often desired to invert the control flow and text-data
    (namely, make the embedded strings primary, and control-flow secondary).
    This is the ASP model, and for 90% HTML, 10% code, this works great.

    This module supports many control facilities which directly translate
    into perl-control facilities (e.g. inverting the ASP-style code back
    into perl-style behind the scenes). The inversion process is cached in a
    simple user object.

    The module was initially inspired by Text::FastTemplate by Robert Lehr,
    who's module didn't completely fullfill my needs.

FEATURES
     * fast, simple, robust
     * code-generating-centric feature-set
     * substitutions stand-out from template
     * macro-code embedded in text
     * OOP
     * external and internal includes (for clearifying complex control-flow)
     * scoped variable-substitutions
     * line-based processing (like cpp)
     * usable error messages

SYNOPSIS
  Sample code

     use Text::Macro;
 
     my $parser = new Text::Macro path => "templates", file => "sql.template";
  
     # print macro substitutions
     $parser->print( { var1 => 'val1', var2 => 'val2' } );
 
     use IO::File;
     my $fh = new IO::File ">out.file";
 
     # direct the output to the given file
     $parse->pipe( 
        { 
          table_name => $table_name,
          f_primary_key => 1,
          primary_key => 'id',
          col_fields => 
            [
               {
                  col_name => 'colName1',
                  col_type => 'colType1'
               },
               {
                  col_name => 'colName2',
                  col_type => 'colType2'
               }
            ]
        }, $fh );

  Sample macro

     #sub pk_block
      #if ##primary_key##
       primary key ##primary_key##,
      #elsif ##f_define_id##
       primary key id,
      #endif
     #endsub
     #comment --------------

     #include licence_agreement.template

     create table ##table_name## (

     #callsub pk_block

     #comment Produce the appropriate fields
     #for ##col_fields##; sep=",\n"
       ##col_name## ##col_type##; ' \
       IDX = ##col_fields_IDX## of ##col_fields_SIZE##\
     #endfor

     );

DESCRIPTION METHODS
  new( path => 'path-to-files', file => 'particular template-name' )

    This creates a new optimized parser.. This actually generates perl code
    to run the data so invocations should be speedy.

    This throws an exception if the file can't be found.

  $obj->print( { subs vals } )

    This runs the macro, substituting the values specified in the input hash
    parameter. Note that it must be a hash-ref or an exception will be
    thrown. It's possible that the rendered code could throw an exception,
    but this would be considered a bug in the parser.

  $obj->pipe( { subs vals }, $file_handle )

    This is identical to print($) but redirects the output to the
    file-handle. It is assumed that IO::File is used.

DESCRIPTION MACRO format
    Text is passed unmodified except for '#' pre-processor directives. The
    easiest format is the "##var_name##" directive which searches for a
    context hash-value with the appropriate hash-key name. In the outer
    scope, the context is the passed hash-ref keys/values. Within a
    for-loop, the context changes as described below.

    Lines in the macro-file that begin with a '#directive' are flow-control
    statements. Valid statements are ( #if ##cond_var## | #else | #elsif
    ##cond_var## | #endif | #for ##list_var## | #endfor | #include file_name
    | #comment | #sub sub_name | #endsub | #callsub sub_name | #pre |
    #endpre | #switch ##var_name## | #case "value1", "value2".. | #default |
    #endswitch). Some of the flow-control directives take a variable and
    process on it. Non-recognized statements are passed as-is.

    The if/elsif/else/endif statements simply insert the contents of the
    hash-value into a perl "if ( $context->{$var_name} ) {" block, so
    potentially complex statements can be achieved. In general, however, the
    logic-computation should be pre-computed and simply provide a boolean
    flag.

    For "for"/"endfor" directives, the variable should be an array of hashes
    (technically an array-ref of hash-refs). It will iterate over the array
    and update an index of the name "varname_IDX" (which can be used as a
    regular insertion variable). Other custom variables are "varname_SIZE"
    (which contains the max IDX value). The context of the insertion
    variables will change to be the contents of the sub-hash. This is
    important since variables of the previous scope are not available. Any
    fields desired at this point should be duplicated in the setup process.

    The include directive simply replaces that line with the contents of the
    file_name (exception if not found). This is a recursive process.

    The 'comment' directive simply ignores that line

    The 'xxsub' routines are a sort of local include. They are good for
    extracting complex pieces out into separate blocks of
    code/template-data. At the moment, no parameters may be passed. The
    format is to declare a block with #sub {sub-name} / #endsub block, then
    invoke it with #callsub {sub-name} just like an include statement.

    The 'pre' block passes values exactly as is (with no hash-substution).
    The only thing that it can't pass is #endpre. This could be good to pass
    perl-comments.

    The 'switch' / 'case' / 'default' blocks are merely for convinience and
    deviate from the c-language style. In function they are readibility
    structures which get expanded out to: if ( ##cond_var## eq "case_value"
    ) { } elsif ( .. ) { } else { } Because of this, c-style
    break-statements and fall-throughs don't exist. Further, in c, the
    comparison is between integers. Here it is between strings (which _can_
    work for numbers, so long as there's no stringification ambiguity. Here
    is an example: #switch ##data_type## #case "boolean" Do somethign with
    boolean #case "int", "integer" Do something with type integer #default
    If neither of the above special cases, then do this #endswitch

    If a line ends with "\\\n" (meaning back-slash followed by a carrage
    return), then the carrage return is stripped. This is useful for
    hash-commands that would otherwise require carriage returns to be
    displayed. For example: pre-text \ #for ##var## data ##val##\ #endfor
    post-text

TODO
    Allow sub-contexts the access parent-contexts as defaults. Currently
    considered too much overhead.

    Provide better error handling (getting there)

    For performance enhancement, extract the hash-values into local
    variables when more than one instance is used. Since this slows down the
    parsing stage, this might be considered an input parameter flag to new.

SEE ALSO
AUTHOR
     maraist@udel.edu

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

  None

COPYRIGHT AND LICENCE

Artistic lisence

Copyright (C) 2002 Michael Maraist maraist@udel.edu