Mini Shell

#========================================================================
# Template Toolkit - parser
#========================================================================

This directory contains the YAPP grammar for the Template processor.  You
only need to worry about the files in this directory if you want to modify 
the template parser grammar.  If you're doing such a thing, then it is 
assumed that you have some idea of what you're doing.  


Files:

  Parser.yp          Yapp grammar file for the Template parser.
  Grammar.pm.skel    Skeleton file for ../lib/Template/Grammar.pm.
  yc                 Simple shell cript to compile grammar and build new 
                     ../lib/Template/Grammer.pm file from Grammar.pm.skel and 
                     the output rules and states generated from the grammar.
  Parser.output      Output file generated by the yapp parser.  This is 
                     for information and debugging purposes only and can 
                     otherwise be ignored.
  README             This file


If you don't know what you're doing and would like to, then I can 
recommend "Lex and Yacc" by John R. Levine, Tony Mason & Doug Brown
(O'Reilly, ISBN: 1-56592-000-7) which gives a good introduction 
to the principles of an LALR parser and how to define grammars in YACC.
YAPP is identical to YACC in all the important ways.  See also the 
Parse::Yapp documentation and the comments in Template::Parser for more
info.  For an in-depth study of parser and compiler theory, consult 
"Compiler Theory and Practice", a.k.a. "The Dragon Book", by Alfred
V. Aho, Ravi Sethi and Jeffrey D.Ullman (Addison-Wesley, ISBN:
0-201-10194-7)

The parser grammar is compiled by 'yapp', the front-end script to 
Francois Desarmenien's Parse::Yapp module(s).  You will need Parse::Yapp
version 0.32 or later, available from CPAN, to compile the grammar.

The grammar file that yapp produces (../Template/Grammar.pm) contains 
the rule and state tables for the grammar.  These are then loaded by 
Template::Parser and used to run the DFA which is implemented by the
parse_directive() method.  This has been derived from the standalone
parser created by Parse::Yapp.

Having modified the Parser.yp file to add your language changes, simply
run:

    ./yc

to compile the grammar and install it in ../lib/Template/Grammar.pm.
You can then make, make test, make install, or whatever you normally
do, and the new grammar should be used by the template processor.  To
revert to the original grammar, simply copy the original distribution
Parser.yp file back into this directory and repeat the above process.

To create a separate grammar, copy and modify the Parser.yp and 
Grammar.pm.skel files as you wish and then run yapp to compile them:

    yapp -v -s -o ../lib/Template/MyGrammar.pm   \
               -t MyGrammar.pm.skel MyParser.yp

You can then instantiate you own grammar and pass this to the 
Template constructor.

    my $template = Template->new({
	GRAMMAR  => Template::MyGrammar->new(),
    });

Changing the grammar is a simple process, in theory at least, if you're
familiar with YAPP/YACC.  In practice, it also requires some insight 
into the inner working of the template toolkit which should probably
be better documented somewhere.


Andy Wardley <abw@kfs.org>