J. David Lowe

NAME

Text::Tmpl - Templating system perl library

SYNOPSIS

use Text::Tmpl;

$context = new Text::Tmpl;

$return = $context->set_delimiters($opentag, $closetag);

$return = $context->register_simple($name, $coderef);

$return = $context->register_pair($isnamed, $open_name, $close_name, $coderef);

$return = $context->alias_simple($old_name, $new_name);

$return = $context->alias_pair($old_open_name, $old_close_name, $new_open_name, $new_close_name);

$context->remove_simple($name);

$context->remove_pair($open_name);

$context->set_debug($to_debug_or_not_to_debug);

$context->set_strip($to_strip_or_not_to_strip);

$return = $context->set_dir($directory);

$return = $context->set_value($name, $value);

$return = $context->set_values($hashref);

$subcontext = $context->loop_iteration($loop_name);

$subcontext = $context->fetch_loop_iteration($loop_name, $iteration_number);

$output = $context->parse_file($template_filename);

$output = $context->parse_string($template);

$errno = Text::Tmpl::errno();

$errstr = Text::Tmpl::strerror();

DESCRIPTION

Design goals

simplicity, reusability, speed, complete separation of logic from formatting.

Feature set

variables, loops, conditionals, extensibility of tags, includes, arbitrary delimiters.

Usage

For starters, make sure you 'use Text::Tmpl'.

Each function is described below:

new

This function initializes the library. It allocates and returns the "global" context structure, and also configures all of the default tag behavior.

set_delimiters

This function lets you change the delimiters marking the beginning and end of a tag (by default, these are "<!--#" and "-->"), for the specified context.

set_value

This function stores the name=value pair in the current context.

set_values

This function dumps the name=value pairs from a hash reference into the current context.

set_debug

This function turns debugging output on or off. Note that debugging output hasn't been written yet - this is just a placeholder.

set_strip

This function enables or disables the newline stripping feature. If enabled, the parser removes a single newline (if present) from after any tag.

set_dir

This function sets the directory where templates will be sought, both by parse_file and by the include tag. Search order is always current directory then this searched directory.

This directory must contain all the necessary punctuation so that appending a filename to it produces a valid path (On unix systems, you have to include the trailing slash on the directory name).

loop_iteration

This function adds an iteration to the loop named loop_name, and returns a unique context for that loop iteration.

fetch_loop_iteration

This function retrieves and returns the context for $iteration_number from the loop named $loop_name.

parse_file

This function opens $template_filename, and parses the contents of that file as a template, returning the output.

parse_string

This function parses template directly, in the same way that Text::Tmpl::parse_file does.

register_simple

This function registers a new simple tag named $name, which when encountered will cause the parser to call $coderef. See template_extend(1) for the gory details.

register_pair

This function registers a new tag pair $open_name/$close_name, which when encountered will cause the parser to call $coderef. See template_extend for the gory details.

alias_simple

This function copies the definition of a simple tag, previously registered as $old_name, to also be called by $new_name.

alias_pair

This function copies the definition of a tag pair, previously registered as $old_open_name/$old_close_name, to also be called by $new_open_name/$new_close_name.

remove_simple

This function removes the simple tag $name.

remove_pair

This function removes the tag pair whose open tag is $open_name.

errno

This function returns the error number of the last error - see the RETURN VALUES section below.

strerror

This function returns a string describing the last error - see the RETURN VALUES section below.

RETURN VALUES

All of the above functions which return numeric values will return 0 if they fail, or 1 otherwise. The ones which return contexts will return undef if they fail, or a valid pointer otherwise.

A function which fails will also set a global error number, which you can read using the errno() or strerror() package functions.

BUGS

Hopefully none.

AUTHOR

J. David Lowe, dlowe@saturn5.com

SEE ALSO

libtmpl(1), template_syntax(1), template_extend(1)