libtmpl(3p)

NAME
libtmpl - Templating system C library

SYNOPSIS
#include "template.h"

context_p template_init(void)

int template_set_delimiters(context_p ctx,
   char *opentag, char *closetag)

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

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

int template_alias_simple(context_p ctx, char *old_name,
   char *new_name)

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

void template_remove_simple(context_p ctx, char *name)

void template_remove_pair(context_p ctx, char *open_name)

int template_set_value(context_p ctx, char *name,
   char *value)

void template_set_debug(context_p ctx, int debug)

void template_set_strip(context_p ctx, int strip)

int template_set_dir(context_p ctx, char *directory)

void template_destroy(context_p ctx)

context_p template_loop_iteration(context_p ctx,
   char *loop_name)

context_p template_fetch_loop_iteration(context_p ctx,
   char *loop_name, int iteration)

int template_parse_file(context_p ctx,
   char *template_filename, char **output)

int template_parse_string(context_p ctx, char *template,
   char **output)

extern int template_errno

char * template_strerror(void)

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 #include "template.h" and link against libtmpl.a.

Each function is described below:

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.

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.

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

    template_set_value() can fail with TMPL_ENULLARG.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

template_remove_simple
    This function removes the simple tag name.

    template_remove_simple() can fail with TMPL_ENULLARG.

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

    template_remove_pair() can fail with TMPL_ENULLARG.

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.

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

template_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 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.

BUGS
Hopefully none.

AUTHOR
J. David Lowe, dlowe@saturn5.com

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