Template Toolkit Version 3 Developer Documentation
http://www.template-toolkit.org/v3/

Template::Parser

Table of Contents

: $TAG_STYLE$DEFAULT_STYLE
: new()init()new_scope()current_scope()old_scope()push_scope()pop_scope()new_handler()current_handler()old_handler()push_handler()pop_handler()tags()interpolate()parse_template()parse_block()parse_statement()parse_expression()parse_assign()parse_embedded()parse_term()parse_variable()parse_node()parse_hash()parse_list()parse_args()parse_filename()parse_interpolate()location()parse_error()parse_warning()
: _tokenise()_tokenise_regex()
NOTES:

Synopsis


Description

The parser's role is to parse the input text of a template and generate a compiled form, which in the general case will be a a Perl code equivalent of the template. However, the code generation is performed by a separate Template::Compiler backend module and this can be subclassed and registered for use with a parser to generate different compiled forms such as a parse tree or some other intermediate code representation.

The template is first split into plain text and embedded directives according to the START_TAG and END_TAG definitions in effect. The INTERPOLATE flag also determines if the parser should attempt to resolve variable reference in plain text. At this stage, chomping is also performing according to the PRE_CHOMP and POST_CHOMP flags and also any directive markers, e.g. [% blah -%]

The parser maintains a stack of hash arrays which contain the current configuration details for the current lexical parser scope, e.g. START_TAG, END_TAG, INTERPOLATE, POST_CHOMP, etc. The new_scope() can be used to create a new local parser scope in which these options can be changed. It accepts a list or reference to hash array of configuration parameters which are used to modify the new scope configuration. Any values not explicitly set default to the values of the parent content. The old_scope() method can be used to restore the previous scope and hence, parser configuration. In summary, this allows different parser options to be locally scoped within template blocks,

e.g.

The parser also maintains a stack of HANDLERS, implemented as Template::Parser::Handler objects. The top item receives method calls from the parser as it identifies these different elements within the template, e.g. directive() and text(). The new_handler($handler) and old_handler() methods can be used to install and later remove parser handlers.

The handler is responsible for dispatching a directive to the correct facility parser registered to parse it. For example, the directive might be [% INCLUDE foo %] , and the handler identifies this as an INCLUDE directive for which is has a callback defined. It calls the facility parser passing a reference to the main parser object and passing the remaining directive text. This should return a compiled representation of the template which the handler appends to its current content model. The handler also receives notification of text blocks which are also added to the internal content list.

The facility parser registered to parse a particular directive can make calls back against the main parser to parse common elements of the Template Toolkit language. For example, the INCLUDE directive expects one or more names and then a list of arguments.


Package Variables


Methods


Private Methods

List of Private Methods

Template Toolkit Language Grammar

The Template::Parser module implements a hand-crafted recursive descent parser to parse the basic elements of the language. It supports only very basic knowledge of Perl's binary operators, simply collecting them up and spitting them out again as Perl code. Thus we retain the same precedence rules as Perl but without having to code any precedence rules ourselves.

The grammar looks something like this:

directive:  KEYWORD ...
	|   statement

statement:  assignment+
	|   expression

assignment: variable =>? expression

expression: ! expression
	|   ( expression )
        |   ( assignment )
	|   expression ? expression : expression	    
        |   term BINOP expression
	|   term

term:	    number
	|   literal
	|   quoted
	|   variable
	|   qw[ list ]		# or qw( ), qw< >, qw{ }, qw| |
	|   [ list ]
	|   { hash }

variable:   varnode ( . varnode )*

varnode:    node
	|   node ( args )

node:	    number
	|   ident
	|   $ident
	|   ${directive}

list:	    expression ,? list

hash:	    hashitem ,? hash

hashitem:   hashkey =>? expression

hashkey:    ident
	|   literal

args:	    arg ,? args

args:	    hashitem
	|   expression	

literal:    'literal string'

quoted:	    "quoted $var string with ${vars} interpolated"

ident:	    \w+

number:	    [-+]\d+(\.\d+)?

Template Toolkit Version 3 Developer Documentation
http://www.template-toolkit.org/v3/