The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-QuickTemplate-0.05
++
/ Text::QuickTemplate

NAME

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

VERSION

This documentation describes v0.05 of Text::QuickTemplate, September 8, 2005.

SYNOPSIS

 # Create and fill a template:
 $template = Text::QuickTemplate->new($string, \%options);

 # Set default values:
 $template->default(\%values);

 # Set some override values:
 $template->pre_fill(\%values);

 # Fill it in, rendering the result string:
 $result = $template->fill(\%values);

 # printf-like usage
 QTprintf ($format, \%values);

 # sprintf-like usage
 $result = QTsprintf ($filehandle, $format, \%values);

 # fprintf-like usage (print to a filehandle)
 QTfprintf ($filehandle, $format, \%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, they're 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.

First, you create a template object that contains the boilerplate text. See the next section for information on how to format it properly.

Then, 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.

TEMPLATE FORMAT

When you create a template object, or when you use one of the printf-like functions, you must supply a template, which is a string that contains placeholders that will be filled in later (by the "fill" method). All other text in the template will remain undisturbed, as-is, unchanged.

Examples:

 'This is a template.'
 'Here's a placeholder: {{fill_me_in}}'
 'Can occur multiple times: {{name}} {{phone}} {{name}}'
 'Optionally, can use printf formats: {{name:20s}} {{salary:%.2f}}'
 'Fancier formats: {{salary:%.2f:,$}}'

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 }}, because that's easy to remember, 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.

Each keyword may optionally be followed (still within the delimiters) by a colon (:) and a printf format. If a format is specified, it will be used to format the entry when expanded. The format may omit the leading % symbol, or it may include it.

If a printf format is supplied, it may optionally be followed by another colon and zero or more special "extended formatting" characters. Currently, two such characters are recognized: , (comma) and $ (dollar sign). Each of these is only useful if the placeholder is being replaced by a number. If a comma character is used, commas will be inserted every three positions to the left of the decimal point. If a dollar-sign character is used, a dollar sign will be placed immediately to the left of the first digit of the number.

COMMON MISTAKE

If Text::QuickTemplate does not expand a placeholder, check to make sure that you did not include any spaces around the placeholder name, and did not use any non-"word" (regex \W) characters in the name. Text::QuickTemplate is very strict about spaces and other characters; this is so that a non-placeholder does not get expanded by mistake.

 Right: {{lemon}}
 Right: {{pi:%.9f}}
 Wrong: {{ lemon }}
 Wrong: {{lemon pie}}
 Wrong: {{pi: %.9f}}

Text::QuickTemplate will silently leave incorrectly-formatted placeholders alone. This is in case you are generating code; you don't want something like

 sub foo {{bar => 1}};

to be mangled or to generate errors.

METHODS

new

Constructor.

 $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

Render the formatted string.

 $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 the special constant $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

Set values without rendering.

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

default

Set default values without rendering.

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

Like "pre_fill", specifies key=>value pairs to be used by "fill", but where "pre_fill"'s values have a higher priority than those specified by "fill", "default"'s are lower. This can be used at the time the object is created to give default values that only get used if the call to "fill" (or "pre_fill") don't override them.

clear_values

Clear default and pre-filled values.

 $template->clear_values();

Removes any "pre_fill"ed or "default" hash references in the object.

FUNCTIONS

QTprintf

Render and print.

 QTprintf $format, \%values

Like Perl's printf, QTprintf takes a format string and a list of values. Unlike Perl's printf, the placeholders and values have names. Like Perl's printf, the result string is sent to the default filehandle (usually STDOUT).

This is equivalent to:

 my $template = Text::QuickTemplate->new ($format);
 print $template->fill (\%values);

QTprintf returns the same value as printf.

The original inspiration for this module came as the author was scanning through a long and complex list of arguments to a printf template, and lost track of which value when into which position.

QTsprintf

Render to string.

 $string = QTsprintf $format, \%values;

Same as "QTprintf", except that it returns the formatted string instead of sending it to the default filehandle.

This is equivalent to:

 $string = do { my $t = Text::QuickTemplate->new($format);
                $t->fill (\%values)  };
QTfprintf

Render and print to filehandle.

 QTfprintf $filehandle, $format, \%values;

Like "QTprintf", except that it sends the formatted string to the filehandle specified, instead of to the currently-selected filehandle.

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 symbol: title"

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

 # Example using format specification:
 $report_line = Text::QuickTemplate->new('{{Name:-20s}} {{Grade:10d}}');
 print $report_line->fill({Name => 'Susanna', Grade => 4});
 # prints "Susanna                       4"

 $line = QTsprintf '{{Name:-20s}} {{Grade:10d}}', {Name=>'Gwen', Grade=>6};
 # $line is now "Gwen                          6"

 QTfprintf *STDERR, '{{number:-5.2f}}', {number => 7.4};
 # prints "7.40 " to STDERR.

 # Example using extended formatting characters:
 $str = QTsprintf '{{widgets:%10d:,}} at {{price:%.2f:,$}} each',
                   {widgets => 1e6, price => 1234};
 # $str is now: " 1,000,000 at $1,234.00 each"

EXPORTS

This module exports the following symbols into the caller's namespace:

 $DONTSET
 QTprintf
 QTsprintf
 QTfprintf

REQUIREMENTS

This module is dependent upon the following other CPAN modules:

 Readonly
 Exception::Class

DIAGNOSTICS

Text::QuickTemplate uses Exception::Class objects for throwing exceptions. If you're not familiar with Exception::Class, don't worry; these exception objects work just like $@ does with die and croak, but they are easier to work with if you are trapping errors.

All exceptions thrown by Text::QuickTemplate have a base class of QuickTemplate::X. You can trap errors with an eval block:

 eval { $letter = $template->fill(@hashrefs); };

and then check for errors as follows:

 if (QuickTemplate::X->caught())  {...

You can look for more specific errors by looking at a more specific class:

 if (QuickTemplate::X::KeyNotFound->caught())  {...

Some exceptions provide further information, which may be useful for your exception handling:

 if (my $ex = QuickTemplate::X::OptionError->caught())
 {
     warn "Bad option: " . $ex->name();
     ...

If you choose not to (or cannot) handle a particular type of exception (for example, there's not much to be done about a parameter error), you should rethrow the error:

 if (my $ex = QuickTemplate::X->caught())
 {
     if ($ex->isa('QuickTemplate::X::SomethingUseful'))
     {
         ...
     }
     else
     {
         $ex->rethrow();
     }
 }

  • Parameter errors

    Class: QuickTemplate::X::ParameterError

    You called a Text::QuickTemplate method with one or more bad parameters. Since this is almost certainly a coding error, there is probably not much use in handling this sort of exception.

    As a string, this exception provides a human-readable message about what the problem was.

  • Option errors

    Class QuickTemplate::X::OptionError

    There's an error in one or more options passed to the constructor "new".

    This exception has one method, name(), which returns the name of the option that had a problem (for example, 'delimiters').

    As a string, this exception provides a human-readable message about what the problem was.

  • Unresolved symbols

    Class QuickTemplate::X::KeyNotFound

    One or more subsitution keywords in the template string were not found in any of the value hashes passed to "fill", "pre_fill", or "default". This exception is thrown by "fill".

    This exception has one method, symbols(), which returns a reference to an array containing the names of the keywords that were not found.

    As a string, this exception resolves to "Could not resolve the following symbols:" followed by a list of the unresolved symbols.

  • Internal errors

    Class QuickTemplate::X::InternalError

    Something happened that I thought couldn't possibly happen. I would appreciate it if you could send me an email message detailing the circumstances of the error.

AUTHOR / COPYRIGHT

Eric J. Roode, roode@cpan.org

To avoid my spam filter, please include "Perl", "module", or this module's name in the message's subject line, and/or GPG-sign your message.

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.