/ 
Text-QuickTemplate-0.01
/ Text::QuickTemplate

NAME

Text::QuickTemplate - A simple, lightweight text fill-in class.

VERSION

This documentation describes v0.01 of Text::QuickTemplate, July 22, 2005.

SYNOPSIS

$template = Text::QuickTemplate->new($string, \%options);

$result = $template->fill(\%values);

OPTIONS

delimiters => [ '{{', '}}' ];          # may be strings
delimiters => [ qr/\{\{/, qr/\{\{/ ];  # and/or regexps

DESCRIPTION

There are many templating modules on CPAN. They're all far, far more powerful than Text::QuickTemplate. When you need that power, that's wonderful. But when you don't, they're overkill.

This module provides a very simple, lightweight, quick and easy templating mechanism for when you don't need those other, powerful but cumbersome, modules.

You create a template object that contains the boilerplate text. Substitution placeholders within the text are indicated by keywords, set off from the surrounding text by a pair of delimiters. (By default the delimters are {{ and }}, since double curly braces are rare in programming languages [and natural languages]).

Keywords between the delimiters must be comprised entirely of "word" characters (that is, alphabetics, numerics, and the underscore), and there must be no spaces or other characters between the keyword and its delimiters. This strictness is considered a feature.

When it is necessary to render the final text (with placeholders filled in), you use the fill method, passing it one or more references of hashes of values to be substituted into the original boilerplate text. The special value $DONTSET indicates that the keyword (and its delimiters) are to remain in the boilerplate text, unsubstituted.

That's it. No control flow, no executable content, no filesystem access. Never had it, never will.

METHODS

new
$template_object = Text::QuickTemplate->new($boilerplate, \%options);

Creates a new Text::QuickTemplate object. The boilerplate text string parameter is mandatory; the hashref of options is optional.

Currently, the only option permitted is delimiters, which is a reference to an array of two strings (or compiled regular expresions): a starting delimiter and an ending delimiter.

fill
$result_string = $template->fill($hashref);
$result_string = $template->fill($hashref, $hashref, ...);

Replaces all of the placeholders within the template with values from the hashref(s) supplied.

For each placeholder, the hashrefs are examined in turn for a matching key. As soon as one is found, the template moves on to the next placeholder. Another way of looking at this behavior is "The first hashref that fulfills a given placeholder -- wins."

If the resulting value is $DONTSET, the placeholder is left intact in the template.

If no value for a placeholder is found among any of the hash references passed, an exception is thrown.

pre_fill
$template->pre_fill($hashref, ...);

Specifies one or more sets of key=>value pairs to be used by the fill method in addition to (and higher priority than) the ones passed to fill.

This can be useful if some template values are set when the template is created, but the template is filled elsewhere in the program, and you don't want to pass variables around.

clear_values
$template->clear_values();

Removes any pre_filled hash references in the object.

EXAMPLES

$book_t = Text::QuickTemplate->new('<i>{{title}}</i>, by {{author}}');

$bibl_1 = $book_t->fill({author => "Stephen Hawking",
                         title  => "A Brief History of Time"});
# yields: "<i>A Brief History of Time</i>, by Stephen Hawking"

$bibl_2 = $book_t->fill({author => "Dr. Seuss",
                         title  => "Green Eggs and Ham"});
# yields: "<i>Green Eggs and Ham</i>, by Dr. Seuss"

$bibl_3 = $book_t->fill({author => 'Isaac Asimov'});
# Dies with "could not resolve the following symbols: title"

$bibl_3 = $book_t->fill({author => 'Isaac Asimov',
                         title  => $DONTSET });
# yields: "<i>{{title}}</i>, by Isaac Asimov"

EXPORTS

This module exports the symbol $DONTSET into the caller's namespace.

DIAGNOSTICS

"Could not resolve the following symbols:"

The listed symbols were found in the template's boilerplate string, but no matching key was found among any of the hash references passed to pre_fill or fill.

==head1 AUTHOR / COPYRIGHT

Eric J. Roode, roode@cpan.org

Copyright (c) 2005 by Eric J. Roode. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.