There are many templating modules on CPAN. They're all far, far more powerful than Text::Printf. 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.

There are two ways to use this module: an immediate (printf-like) way, and a delayed (prepared) way.

For the immediate way, you simply call "tprintf" or "tsprintf" with a boilerplate string and the values to be inserted/formatted. See the following section for information on how to format the boilerplate string. This is somewhat easier than using plain printf or sprintf, since the name of the value to be inserted is at the same place as its format.

For the prepared way, you create a template object that contains the boilerplate text. Again, 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 flow control, no executable content, no filesystem access. Never had it, never will.

When you create a template object, or when you use one of the printf-like functions, you 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.

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

A printf format may be preceeded by a "-" sign to indicated that the string or number is to be left-justified within the field width. The default is right-justification. (This is how all printfs work) I personally have a hard time remembering that. So instead of a minus sign, you can use a less-than sign ("<") to indicate left- justification, or a greater-than sign (">") to indicate right-justification.

If Text::Printf 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::Printf is very strict about spaces and other characters; this is so that a non-placeholder does not get expanded by mistake.

The boilerplate parameter specifies the template pattern that is to be printed; presumably it has placeholders to be filled in later. If you do not specify it here in the constructor, you must specify it via the "text" method before you call "fill".

The options parameter specifies options to control how the object behaves. 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.

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.

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 your program, and you don't want to pass variables around. It is also useful if different parts of your program fill different parts of the template.

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.

Like Perl's printf, tprintf 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).

If the first argument is a filehandle, or any sort of object that supports a print method, output is sent there instead of to the default filehandle.

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 kept losing track of which value went into which position.

Text::Printf 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::Printf have a base class of Text::Printf::X. You can trap errors with an eval block:

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

and then check for errors as follows:

if (Text::Printf::X->caught()) {...

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

if (Text::Printf::X::KeyNotFound->caught()) {...

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

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.

This module is copyrighted only to ensure proper attribution of authorship and to ensure that it remains available to all. This module is free, open-source software. This module may be freely used for any purpose, commercial, public, or private, provided that proper credit is given, and that no more-restrictive license is applied to derivative (not dependent) works.

Substantial efforts have been made to ensure that this software meets high quality standards; however, no guarantee can be made that there are no undiscovered bugs, and no warranty is made as to suitability to any given use, including merchantability. Should this module cause your house to burn down, your dog to collapse, your heart-lung machine to fail, your spouse to desert you, or George Bush to be re-elected, I can offer only my sincere sympathy and apologies, and promise to endeavor to improve the software.