NAME
    Templater - A template engine.

SYNOPSIS
      #!/usr/bin/perl
      use Text::Templater;
  
      my $tpl = new Text::Templater($tagname);
      #Default tagname is "tpl"
  
      $tpl->setSource($some_template_text);
  
      #Set the data source...
      $tpl->setData({
        name => ['bob', undef, 'daniel'],
        color => ['red', 'green', 'blue'],
        nested => 
          [
            {lang => ['fr'], numeric => ['un', 'deux', 'trois', 'quatre']},
            {lang => ['en'], numeric => ['one', 'two', 'three', 'four']}
          ]
        });
      #Or use existing objects.
      $tpl->setData($cgi);
      $tpl->setData($sth);
  
      #Get the result.
      $result = $tpl->parse() || die $tpl->getError();
   
      #if you get weird stuff,
      #check for $tpl->getWarnings();

ABSTRACT
    The objective of the Templater object is to separate data manipulation
    from it's representation while keeping out logic as much as possible
    from the representation side.

DESCRIPTION
    Templater receive the template and the data to be binded in the
    template. Then using the parse method, it return the result.

    One tag and 5 properties are used in a xmlish way to describe data in
    the template. Since the object use an xml tag, you can use it in your
    xml files while keeping them well-formedness and valid.

    <tpl id="x" name="key" index="0" nullout="no" list="CONST:1,2,3..." />

  Tag properties
    id="unique"
          You can specify the id of an element to make late references to it.
          This can be used for not breaking the well-formedness of a xml
          document. You could write <tpl id="myvalue" name="nom" />
          <othertag value="#myvalue" /> instead of
          <other-tag value="<tpl name="nom" />" />.
          A tag with the id specified will not print his result, only
          record it for late references. Note that the second alternalive 
          will work as well.

    name="name"
          You can bind a specific data value to a tag using it's hash key.
          A tag without a name does not make sense.
          In the synopsis; <tpl name="color" /> eqals red.
          If you have nested structures, you can use the notation a.b
          <tpl name="nested.lang" /> equals fr.

    index="num"
          Specify the index of the value to be binded.
          If not specified, the current iteration is taken.
          In the synopsis; <tpl name="color" index="1" /> eqals green.

    nullout="yes|no"
          If the binded value is undef or '', all the expression
          is discarded. no is taken by default. In the synopsis:
          <tpl name="name" nullout="yes">hi</tpl> equals nothing.

    list="CONST:1,2,3,..."
          Defines a specific constant "CONST" into the tag inner source.
          The value of CONST will alternativly be 1,2,3,1,2,etc
          The backslash is used as a dummy quote character.

  Tag forms
    The templater tag can be written as: <tpl /> or <tpl></tpl>. The first
    form will replace the tag with the corresponding binded data. The second
    form will loop each value of the binded data; the concatenation of each
    result is used as the sole result.

  Methods
    new Creates a new Templater object. You can specify the tag name to be
        used in templates. No verification of the validity of name is made.

    setSource
        If a scalar is passed, it is set to be the template. The source of
        the object is returned.

    setData
        If a value is passed, it is set to be the data to bind. CGI and STH
        objects can be passed. The data of the object is returned.

    parse
        Takes the template and parse the data inside using the templater
        tags. The parsed template is returned.

    getError
        Returns the error that was recorded during the last parsing. This
        method should return undef if parse return a value and the cause of
        the error if parse says undef.

    getWarnings
        Returns the list of the warnings that occurned in the last parsing.
        This is the first place to look if you think you have weird or
        unexpected results.

CREDITS
    Mathieu Gagnon

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