NAME

 Parse::Plain - simple template parsing engine

SYNOPSIS

 # in user's code
 use Parse::Plain;

 my $t = new Parse::Plain('filename.tmpl');

 $t->set_tag('mytag', 'value');          # %%mytag%% set to value
 $t->push_tag('mytag', '-pushed');       # %%mytag%% set to value-pushed
 $t->set_tag('mytag', 'value');          # %%mytag%% set to value
 $t->unshift_tag('mytag', 'unshifted-'); # %%mytag%% set to unshifted-value

 $t->push_block('myblock', 'some text to append to the block');
 $t->unshift_block('myblock', 'some text to prepend to the block');

 $t->parse('myblock', {'blocktag' => 'block value'});  # parse block
 $t->parse('myblock', {'blocktag' => 'another block value'});

 $t->parse;   # parse whole document
 $t->output;  # output parsed results to STDOUT

DESCRIPTION

Parse::Plain is a simple module for parsing text templates. It was designed to use on HTML, XHTML, XML and other markup languages but usually can also be used on arbitrary text files.

Basic constructions in the templates are tags and blocks. Both have names. Valid symbols for using in tag and block names are digits, latin letters, underscores, dashes, dots, semicolons, colons, commas, parentheses, asterisks, ampersands and caret symbols. An exclamation mark ('!') has special meaning and will be discussed later. All names are case sensitive.

Tag is a string in form %%tagname%%. There may be any number of tags with the same name in the template and any number of different tags.

Block is a construction that begins with line

{{ blockname

and ends with line

}}

Both block-start and block-end elements must be on separate lines. Symbols between block-start and block-end form block body. Blocks are especially useful for iterative elements like table rows etc. Blocks can be nested and tags are allowed within block body.

There also is a special form of tag names. Lets say you have a block named myblock. Then you can use in your template tags named %%!myblock%% and they will be substituted to current value of myblock.

You can also hide block from place in template where it is defined by prepending ! to it's name. Then you'll only be able to show this block using appropriate tag names (with '!'). See EXAMPLES section.

METHODS

new()

The constructor. The only parameter is a path to template file. Template file must exist and be readable. If file cannot be read several attempts will be made (see $loop_cnt_max and $sleep_sec variables at the BEGIN section).

set_tag()

Tags accessor. Requires parameters: tagname, value. Example:

$t->set_tag('mytag', 'value'); # set %%mytag%% to 'value'

Value may be another instance of Parse::Plain. In this case parse method will be called automatically on value object. Returns new value of tag.

get_tag()

Tags accessor. Requires one parameter: tagname. Returns current value of tag.

push_tag()

Append supplied value to current value of tag. Requires parameters: tag name and value. Value may be an instance of Parse::Plain. In this case parse method will be called automatically on value object. Returns new value of tag.

unshift_tag()

Prepend supplied value to current value of tag. Requires parameters: tag name and value. Value may be an instance of Parse::Plain. In this case parse method will be called automatically on value object. Returns new value of tag.

block()

Block accessor. Requires parameter: block name. Second parameter (value) is optional. If it is omitted current value of block is returned, otherwise it's set to a new value. Value may be an instance of Parse::Plain. In this case parse method will be called automatically on value object. Returns new value of the block or old value if the block wasn't changed.

push_block()

Append supplied value to block. Required parameters: block name, value. Value may be an instance of Parse::Plain. In this case parse method will be called automatically on value object. Returns new value of the block.

unshift_block()

Prepend supplied value to block. Required parameters: block name, value. Value may be an instance of Parse::Plain. In this case parse method will be called automatically on value object. Returns new value of the block.

set_text()

Set text to parameter. Text is a special member containing outermost block source if hasn't been parsed yet or whole parsed results if parse() method has already been called. WARNING: You should probably never use this function directly! Return new value of text.

set_text()

Returns current value of text. Text is a special member containing outermost block source if hasn't been parsed yet or whole parsed results if parse() method has already been called. WARNING: You should probably never use this function directly! See parse() function elsewhere is this document!

parse()

Parse chunk of text using defined tags and blocks. If called without parameters the template is parsed using tags and blocks defined so far. There are three optional parameters: blockname, hashref, useglobalhash. First specifies block name to be parsed. You must call parse() function on each block in your template at least onse or the block will be ignored. You must also call parse() function for each iteration of the block. See EXAMPLES section elsewhere in this document. You can also provide a referense to hash of tags used for parsing current block. For example:

$t->parse('blockname', {'tag1' => 'val1', 'tag2' => 'val2'});

If you don't specify this hash reference global hash (filled with set_tag() functions) wiil be used instead. You can also use both supplied hash and global hash for parsing your block by setting third parameter to true. Returns parsing results (either text or block).

output()

Print parsing results to STDOUT. If text hasn't been parsed yet calls parse() method before. Returns parsed text.

TIPS AND CAVEATS

• Names are case sensitive.

• Non-defined tags and blocks are moved off from the result

• Block start and end elements do not insert newline. Consider the template fragment:

         He
    {{ myblock
  ll
    }}
  o

  It will be parsed to

  Hello

  line.

• Block start and end elements may be padded with whitespaces or tabs for better readability.

• Always parse innermost block before outer blocks.

• Blocks may be reparsed with different values, tags also can be reset.

EXAMPLES

Using blocks

Template (template.tmpl): <table> <th>%%name%%</th>

 {{ block1
         <tr><td>%%tag1%%</td><td>%%tag2%%</td></tr>

 }}
 </table> 

Code: use Parse::Plain; $t = new Parse::Plain 'template.tmpl'; $t->set_tag('name', "My table"); $t->parse('block1', {'tag1' => '01', 'tag2' => '02'}); $t->parse('block1', {'tag1' => '03', 'tag2' => '04'}); $t->output;

Output: <table> <th>My table</th> <tr><td>01</td><td>02</td></tr> <tr><td>03</td><td>04</td></tr> </table>

Using hidden blocks

Template (template.tmpl): <table %%border%%>

 {{ myblock
         <tr><td %%!hidden%%>%%value%%</td></tr>

 }}
 </table>

 {{ !hidden
 class="%%class%%" align="%%align%%"
 }}

Code: use Parse::Plain; $t = new Parse::Plain 'template.tmpl'; $t->parse('hidden', {'class' => 'red', 'align' => 'right'}); $t->parse('myblock', {'value' => '01'}); $t->parse('myblock', {'value' => '02'}); # we didn't define %%border%% tag $t->output;

Output: <table > <tr><td class="red" align="right">01</td></tr> <tr><td class="red" align="right">02</td></tr> </table>

BUGS

If you define a hidden block (with '!') and a nested block inside it and use tag to show the hidden block (outer) behavior is undefined.

You have no way to change tag / block delimiters. See FAQ document provided with distribution for more details.

If you have found any other bugs or have any comments/wishes don't hesitate to contact me.

AUTHOR

 Andrew Alexandre Novikov.
 mailto: perl@an.kiev.ua
 www: http://www.an.kiev.ua/
 icq: 7593332

COPYRIGHTS

Copyright 2003 by Andrew A Novikov <http://www.an.kiev.ua/>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

cpanm Parse::Plain

perl -MCPAN -e shell
install Parse::Plain