=head1 NAME

libtmpl - Templating system C library

=head1 SYNOPSIS

B<#include "template.h">

context_p
B<template_init>(void)

int
B<template_set_delimiters>(context_p ctx,
   char *opentag, char *closetag)

int
B<template_register_simple>(context_p ctx, char *name,
   void (*function)(context_p, char **, int, char**))

int
B<template_register_pair>(context_p ctx,
   char named_context, char *open_name, char *close_name,
   void (*function)(context_p, int, char**))

int
B<template_alias_simple>(context_p ctx, char *old_name,
   char *new_name)

int
B<template_alias_pair>(context_p ctx,
   char *old_open_name, char *old_close_name,
   char *new_open_name, char *new_close_name)

void
B<template_remove_simple>(context_p ctx, char *name)

void
B<template_remove_pair>(context_p ctx, char *open_name)

int
B<template_set_value>(context_p ctx, char *name,
   char *value)

void
B<template_set_debug>(context_p ctx, int debug)

void
B<template_set_strip>(context_p ctx, int strip)

int
B<template_set_dir>(context_p ctx, char *directory)

void
B<template_destroy>(context_p ctx)

context_p
B<template_loop_iteration>(context_p ctx,
   char *loop_name)

context_p
B<template_fetch_loop_iteration>(context_p ctx,
   char *loop_name, int iteration)

int
B<template_parse_file>(context_p ctx,
   char *template_filename, char **output)

int
B<template_parse_string>(context_p ctx, char *template,
   char **output)

extern int B<template_errno>

char *
B<template_strerror>(void)

=head1 DESCRIPTION

=head2 Design goals

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

=head2 Feature set

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

=head2 Usage

For starters, make sure you #include "template.h" and link against libtmpl.a.

Each function is described below:

=over 3

=item B<template_init>

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

template_init() can fail with TMPL_EMALLOC.

=item B<template_set_delimiters>

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

template_set_delimiters() can fail with TMPL_ENULLARG.

=item B<template_set_value>

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

template_set_value() can fail with TMPL_ENULLARG.

=item B<template_set_debug>

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

=item B<template_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.

=item B<template_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).

template_set_dir() can fail with TMPL_ENULLARG.

=item B<template_loop_iteration>

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

template_loop_iteration() can fail with TMPL_ENULLARG or TMPL_EMALLOC.

=item B<template_fetch_loop_iteration>

This function retrieves and returns the context for iteration number
iteration from the loop named loop_name.

template_fetch_loop_iteration() can fail with TMPL_ENULLARG or TMPL_ENOCTX.

=item B<template_parse_file>

This function opens template_filename, and parses the contents of
that file as a template, placing the output into *output.  It allocates
all the memory for you, but it is up to the programmer to free *output!

template_parse_file() can fail with TMPL_ENULLARG, TMPL_ENOTFOUND,
TMPL_EFOPEN, TMPL_EMALLOC or TMPL_EPARSE.

=item B<template_parse_string>

This function parses template directly, in the same way that
template_parse_file does.

template_parse_string() can fail with TMPL_ENULLARG, TMPL_EMALLOC or
TMPL_EPARSE.

=item B<template_register_simple>

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

template_register_simple() can fail with TMPL_ENULLARG, TMPL_EMALLOC.

=item B<template_register_pair>

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

template_register_pair() can fail with TMPL_ENULLARG, TMPL_EMALLOC.

=item B<template_alias_simple>

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

template_alias_simple() can fail with TMPL_ENULLARG, TMPL_EMALLOC.

=item B<template_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.

template_alias_pair() can fail with TMPL_ENULLARG, TMPL_EMALLOC.

=item B<template_remove_simple>

This function removes the simple tag name.

template_remove_simple() can fail with TMPL_ENULLARG.

=item B<template_remove_pair>

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

template_remove_pair() can fail with TMPL_ENULLARG.

=item B<template_destroy>

This function blows away all of the memory allocated within the given context.
You should really *only* call this on the context returned by template_init,
and only at the end of your code.

=item B<template_errno>

This is a global variable containing the error number of the last error -
see the RETURN VALUES section below.

=item B<template_strerror>

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

=back

=head1 RETURN VALUES

All of the above functions which return int values will return 0 if they fail,
or 1 otherwise.  The ones which return context_p pointers will return NULL if
they fail, or a valid pointer otherwise.

A function which fails will also set a global error number, which you can
read or use template_strerror() to describe.

=head1 BUGS

Hopefully none.

=head1 AUTHOR

J. David Lowe, dlowe@saturn5.com

=head1 SEE ALSO

Text::Tmpl(1), template_syntax(1), template_extend(1)

=cut