FastTemplate(3)

📦

version 1.09 · 2 versions

1.09 · fedora 43 (latest)
1.09 · fedora 44

FastTemplate(3) — okay bestie, sit down, hydrate, because this is the whole manual page for CGI::FastTemplate from the User Contributed Perl Documentation and we are getting into it. 💅

✨ NAME ✨

CGI::FastTemplate — a Perl extension for managing templates, and performing variable interpolation. 🎀

🦋 SYNOPSIS 🦋

use CGI::FastTemplate;

$tpl = new CGI::FastTemplate();
$tpl = new CGI::FastTemplate("/path/to/templates");

CGI::FastTemplate->set_root("/path/to/templates");    ## all instances will use this path
$tpl->set_root("/path/to/templates");                 ## this instance will use this path

$tpl->define( main    => "main.tpl",
              row     => "table_row.tpl",
              all     => "table_all.tpl",
              );

$tpl->assign(TITLE => "I am the title.");

my %defaults = (  FONT   => "<font size=+2 face=helvetica>",
                  EMAIL   => 'jmoore@sober.com',
                  );
$tpl->assign(\%defaults);

$tpl->parse(ROWS      => ".row");      ## the '.' appends to ROWS
$tpl->parse(CONTENT   => ["row", "all"]);
$tpl->parse(CONTENT   => "main");

$tpl->print();            ## defaults to last parsed
$tpl->print("CONTENT");   ## same as print() as "CONTENT" was last parsed

$ref = $tpl->fetch("CONTENT");

🌸 DESCRIPTION 🌸

💖 What is a template? 💖

A template is literally just a text file with variables in it. When a template gets parsed, those variables get interpolated into text. (The text can be a few bytes or a few hundred kilobytes — size is not the vibe check here.) Here's a simple template with one variable ('$NAME'):

Hello $NAME.  How are you?

💖 When are templates useful? 💖

Templates are so useful for CGI programming, because the second you start adding HTML to your perl code, you've cluttered the code and now you're the one stuck doing every single HTML modification. By putting all your HTML in separate template files, you can let a graphic or interface designer change the look of your application without having to bug you, or let them muck around in your perl code. Delegation, bestie. It's giving leadership.

💖 There are other templating modules on CPAN, what makes FastTemplate different? 💖

CGI::FastTemplate has the following attributes:

Speed — FastTemplate doesn't use eval, and it parses with a single regular expression. It just does simple variable interpolation (i.e. there is no logic that you can add to templates — you keep the logic in the code). That's why it's got 'Fast' in its name! 🔥
Efficiency — FastTemplate functions accept and return references whenever possible, which saves needless copying of arguments (hashes, scalars, etc).
Flexibility — The API is robust and flexible, and it allows you to build very complex HTML documents or HTML interfaces. It is 100% perl and works on Unix or NT. Also, it isn't restricted to building HTML documents — it could be used to build any ascii based document (e.g. postscript, XML, email).

The similar modules on CPAN are:

Module          HTML::Template  (S/SA/SAMTREGAR/HTML-Template-0.04.tar.gz)
Module          Taco::Template  (KWILLIAMS/Taco-0.04.tar.gz)
Module          Text::BasicTemplate (D/DC/DCARRAWAY/Text-BasicTemplate-0.9.8.tar.gz)
Module          Text::Template  (MJD/Text-Template-1.20.tar.gz)
Module          HTML::Mason     (J/JS/JSWARTZ/HTML-Mason-0.5.1.tar.gz)

💖 What are the steps to use FastTemplate? 💖

The main steps are:

define
assign
parse
print

These are outlined in detail in CORE METHODS below. 👑

👑 CORE METHODS 👑

🍓 define(HASH)

The method define() maps a template filename to a (usually shorter) name. e.g.

my $tpl = new FastTemplate();
$tpl->define(   main   => "main.tpl",
                footer   => "footer.tpl",
                );

This new name is the name that you will use to refer to the templates. Filenames should not appear in any place other than a define().

(Note: This is a required step! It may seem like an annoying extra step when you're dealing with a trivial example like the one above, but when you're dealing with dozens of templates, it is very handy to refer to templates with names that are indepandant of filenames.)

TIP: Since define() does not actually load the templates, it is faster and more legible to define all the templates with one call to define(). 💡

🍓 define_nofile(HASH) alias: define_raw(HASH)

Sometimes it is desireable to not have to create a separate template file for each template (though in the long run it is usually better to do so). The method define_nofile() allows you to do this. For example, if you were writing a news tool where you wanted to bold an item if it was "new" you could do something like the following:

my $tpl = new FastTemplate();

$tpl->define_nofile(    new   => '<b>$ITEM_NAME</b> <BR>',
                        old   => '$ITEM_NAME <BR>');

if ($new)
{
    $tpl->parse($ITEM   => "new");
}
else
{
    $tpl->parse($ITEM   => "old");
}

Of course, now you, the programmer, has to update how new items are displayed, whereas if it was in a template, you could offload that task to someone else. Trade-offs, babes.

🍓 define_nofile(HASH REF) alias: define_raw(HASH REF)

A more efficient way of passing your arguments than using a real hash. Just pass in a hash reference instead of a real hash. 🦋

🍓 assign(HASH)

The method assign() assigns values for variables. In order for a variable in a template to be interpolated it must be assigned. There are two forms which have some important differences. The simple form is to accept a hash and copy all the key/value pairs into a hash in FastTemplate. There is only one hash in FastTemplate, so assigning a value for the same key will overwrite that key.

e.g.

$tpl->assign(TITLE   => "king kong");
$tpl->assign(TITLE   => "godzilla");    ## overwrites "king kong"

🍓 assign(HASH REF)

A much more efficient way to pass in values is to pass in a hash reference. (This is particularly nice if you get back a hash or hash reference from a database query.) Passing a hash reference doesn't copy the data, but simply keeps the reference in an array. During parsing, if the value for a variable cannot be found in the main FastTemplate hash, it starts to look through the array of hash references for the value. As soon as it finds the value it stops. It is important to remember to remove hash references when they are no longer needed.

e.g.

my %foo = ("TITLE" => "king kong");
my %bar = ("TITLE" => "godzilla");

$tpl->assign(\%foo);   ## TITLE resolves to "king kong"
$tpl->clear_href(1);   ## remove last hash ref assignment (\%foo)
$tpl->assign(\%bar);   ## TITLE resolves to "godzilla"

$tpl->clear_href();    ## remove all hash ref assignments

$tpl->assign(\%foo);   ## TITLE resolves to "king kong"
$tpl->assign(\%bar);   ## TITLE _still_ resolves to "king kong"

🍓 parse(HASH)

The parse function is the main function in FastTemplate. It accepts a hash, where the keys are the TARGET and the values are the SOURCE templates. There are three forms the hash can be in:

$tpl->parse(MAIN => "main");                ## regular

$tpl->parse(MAIN => ["table", "main"]);     ## compound

$tpl->parse(MAIN => ".row");                ## append

In the regular version, the template named "main" is loaded if it hasn't been already, all the variables are interpolated, and the result is then stored in FastTemplate as the value MAIN. If the variable '$MAIN' shows up in a later template, it will be interpolated to be the value of the parsed "main" template. This allows you to easily nest templates, which brings us to the compound style. 🧚

The compound style is designed to make it easier to nest templates. The following are equivalent:

$tpl->parse(MAIN => "table");
$tpl->parse(MAIN => "main");

## is the same as:

$tpl->parse(MAIN => ["table", "main"]);     ## this form saves function calls
                                            ## (and makes your code cleaner)

It is important to note that when you are using the compound form, each template after the first must contain the variable that you are parsing the results into. In the above example, 'main' must contain the variable '$MAIN', as that is where the parsed results of 'table' is stored. If 'main' does not contain the variable '$MAIN' then the parsed results of 'table' will be lost. 💀

The append style is a bit of a kludge, but it allows you to append the parsed results to the target variable. This is most useful when building tables that have an dynamic number of rows — such as data from a database query.

🍓 strict()

When strict() is on (it is on by default) all variables found during template parsing that are unresolved have a warning printed to STDERR. e.g.

[CGI::FastTemplate] Warning: no value found for variable: SOME_VARIABLE

Also, new as of version 1.04 the variables will be left in the output document. This was done for two reasons: to allow for parsing to be done in stages (i.e. multiple passes), and to make it easier to identify undefined variables since they appear in the parsed output. If you have been using an earlier version of FastTemplate and you want the old behavior of replacing unknown variables with an empty string, see: no_strict().

Note: version 1.07 adds support for two styles of variables, so that the following are equivalent: $VAR and ${VAR} However, when using strict(), variables with curly brackets that are not resolved are outputted as plain variables. e.g. if ${VAR} has no value assigned to it, it would appear in the output as $VAR. This is a slight inconsistency — ideally the unresolved variable would remain unchanged.

Note: STDERR output should be captured and logged by the webserver so you can just tail the error log to see the output. 🫶

e.g.

tail -f /etc/httpd/logs/error_log

🍓 no_strict()

Turns off warning messages about unresolved template variables. As of version 1.04 a call to no_strict() is required to replace unknown variables with an empty string. By default, all instances of FastTemplate behave as is strict() was called. Also, no_strict() must be set for each instance of CGI::FastTemplate. e.g.

CGI::FastTemplate::no_strict;        ## no

my $tpl = CGI::FastTemplate;
$tpl->no_strict;                     ## yes

🍓 print(SCALAR)

The method print() prints the contents of the named variable. If no variable is given, then it prints the last variable that was used in a call to parse which I find is a reasonable default.

e.g.

$tpl->parse(MAIN => "main");
$tpl->print();         ## prints value of MAIN
$tpl->print("MAIN");   ## same

This method is provided for convenience.

If you need to print other than STDOUT (e.g. socket, file handle) see fetch(). ✨

💖 OTHER METHODS 💖

`fetch(SCALAR)` — hand me the pointer bestie

Returns a scalar reference to parsed data. That's it, that's the whole vibe. It gives you back a ref, not the string itself, so you deref it with $$ when you wanna actually use it. ✨

$tpl->parse(CONTENT   => "main");
my $content = $tpl->fetch("CONTENT");

print $$content;        ## print to STDOUT
print FILE $$content;   ## print to filehandle or pipe

So you can yeet it to STDOUT, or push it into a filehandle, or a pipe. Iconic behaviour honestly. 🫶

`clear()` — the reset button

Note: all of the clear functions are for use under mod_perl (or anywhere where your scripts are persistant). They generally aren't needed if you are writing CGI scripts. 🫧

Clears the internal hash that stores data passed from calls to assign() and parse().

Often clear() is at the end of a mod_perl script, like the little goodbye kiss at the end of a routine:

$tpl->print();
$tpl->clear();

`clear(ARRAY)` — the selective one 💅

With no arguments, all assigned or parsed variables are cleared. But if you pass it an ARRAY of variable names, then only those variables get cleared. Targeted. Surgical. Main character energy fr fr.

e.g.

$tpl->assign(TITLE => "Welcome");
$tpl->clear("TITLE");                 ## title is now empty

Another way of achieving the same effect of clearing variables is to just assign an empty string. Same energy, different font:

e.g.

$tpl->assign(TITLE => '');           ## same as: $tpl->clear("TITLE");

`clear_parse()`

See: clear() 🦋

`clear_href(NUMBER)` — the loop cleaner-upper

Removes a given number of hash references from the list of hash refs that is built using:

$tpl->assign(HASH REF);

If called with no arguments, it removes all hash references from the array. This is often used for database queries where each row from the query is a hash or hash reference. So you push a row in, parse it, pop it back out, repeat. Chef's kiss. 😭

e.g.

while($hash_row = $sth->fetchrow_hashref)
{
    $tpl->assign($hash_row);
    $tpl->parse(ROW => ".row");
    $tpl->clear_href(1);
}

`clear_define()` — nuke the definitions

Clears the internal hash that stores data passed to:

$tpl->define();

Note: the hash that holds the loaded templates is not touched with this method. See: clear_tpl. Don't come for the loaded templates with this one bestie, they're safe. 🙈

`clear_tpl()` `clear_tpl(NAME)` — free that memory 🧚

The first time a template is used, it is loaded and stored in a hash in memory. clear_tpl() removes all the templates being held in memory. clear_tpl(NAME) only removes the one with NAME.

This is generally not required for normal CGI programming, but if you have long running scripts (e.g. mod_perl) and have very large templates that are infrequently used, it gives you some control over how memory is being used. Very demure, very mindful memory management. ✨

`clear_all()` — the full reset 🌈

Cleans the module of any data, except for the ROOT directory. Equivalent to:

$tpl->clear_define();
$tpl->clear_href();
$tpl->clear_tpl();
$tpl->clear_parse();

Variables

A variable is defined as:

$[A-Z0-9][A-Z0-9_]+

This means that a variable must begin with a dollar sign $. The second character must be an uppercase letter or digit A-Z0-9. Remaining characters can include an underscore.

As of version 1.07 variables can also be delimited by curly brackets. Yes, we love an upgrade. 🎀

${[A-Z0-9][A-Z0-9_]+}

For example, the following are valid variables:

$FOO
$F123F
$TOP_OF_PAGE
${NEW_STYLE}

Variable Interpolation (Template Parsing)

When the a template is being scanned for variables, pattern matching is greedy. (For more info on "greediness" of regexps see perlre.) This is important, because if there are valid variable characters after your variable, FastTemplate will consider them to be part of the variable. 😭 She's committed. She takes everything she can.

As of version 1.07 you can use curly brackets as delimiters for your variable names. e.g. ${VARIABLE}

You do not need to use curly brackets if the character immediately after your variable name is not an uppercase letter, digit or underscore. ['A-Z0-9_']

If a variable cannot be resolved to a value then there are two possibilities:

If strict() has been called (it is on by default) then the variable remains and a warning is printed to STDERR.
If no_strict() has been called then the variables is converted to an empty string [''].

See strict() and no_strict() for more info.

Some examples will make this clearer.

Assume:

$FOO = "foo";
$BAR = "bar";
$ONE = "1";
$TWO = "2";
$UND = "_";

Variable — Interpolated/Parsed:

$FOO → foo
$FOO-$BAR → foo-bar
$ONE_$TWO → 2 — ## $ONE_ is undefined!
$ONE_$TWO → $ONE_2 — ## assume: strict()
$ONE$UND$TWO → 1_2 — ## kludge!
${ONE}_$TWO → 1_2 — ## much better
$$FOO → $foo
$25,000 → $25,000

FULL EXAMPLE — the whole glow-up 🌸

This example will build an HTML page that will consist of a table. The table will have 3 numbered rows. The first step is to decide what templates we need. In order to make it easy for the table to change to a different number of rows, we will have a template for the rows of the table, another for the table, and a third for the head/body part of the HTML page.

Below are the templates. (Pretend each one is in a separate file.)

<!-- NAME: main.tpl -->
<html>
<head><title>$TITLE</title>
</head>
<body>
$MAIN
</body>
</html>
<!-- END: main.tpl -->

<!-- NAME: table.tpl -->
<table>
$ROWS
</table>
<!-- END: table.tpl -->

<!-- NAME: row.tpl -->
<tr>
<td>$NUMBER</td>
<td>$BIG_NUMBER</td>
</tr>
<!-- END: row.tpl -->

Now we can start coding...

## START ##

use CGI::FastTemplate;
my $tpl = new CGI::FastTemplate("/path/to/template/files");

$tpl->define(     main    => "main.tpl",
                  table   => "table.tpl",
                  row     => "row.tpl",
                  );

$tpl->assign(TITLE => "FastTemplate Test");

for $n (1..3)
{
      $tpl->assign(   NUMBER      => $n,
      BIG_NUMBER   => $n*10);
      $tpl->parse(ROWS   => ".row");
}

$tpl->parse(MAIN => ["table", "main"]);
$tpl->print();

## END ##

When run it returns:

<!-- NAME: main.tpl -->
<html>
<head><title>FastTemplate Test</title>
</head>
<body>
<!-- NAME: table.tpl -->
<table>
<!-- NAME: row.tpl -->
<tr>
<td>1</td>
<td>10</td>
</tr>
<!-- END: row.tpl -->
<!-- NAME: row.tpl -->
<tr>
<td>2</td>
<td>20</td>
</tr>
<!-- END: row.tpl -->
<!-- NAME: row.tpl -->
<tr>
<td>3</td>
<td>30</td>
</tr>
<!-- END: row.tpl -->

</table>
<!-- END: table.tpl -->

</body>
</html>
<!-- END: main.tpl -->

If you're thinking you could have done the same thing in a few lines of plain perl, well yes you probably could. But bestie, let's think bigger:

How would a graphic designer tweak the resulting HTML?
How would you have a designer editing the HTML while you're editing another part of the code?
How would you save the output to a file, or pipe it to another application (e.g. sendmail)?
How would you make your application multi-lingual?
How would you build an application that has options for high graphics, or text-only?

FastTemplate really starts to shine when you are building mid to large scale web applications, simply because it begins to separate the application's generic logic from the specific implementation. That's the ✨ separation of concerns ✨ moment. Periodt.

👑 COPYRIGHT 👑

Copyright (c) 1998-99 Jason Moore <jmoore@sober.com>.  All rights
reserved.

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

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
Artistic License for more details.

💜 AUTHOR 💜

Jason Moore <jmoore@sober.com>

🦋 SEE ALSO 🦋

mod_perl(1).

and that's a wrap on the whole page, bestie 🫶 this was perl v5.42.0, 2025-07-25, filed under FastTemplate(3) — go build something cute with it 💖✨

📦 where this page comes from

fedora 43: perl-CGI-FastTemplate 1.09-51.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

FastTemplate(3)

✨ NAME ✨

🦋 SYNOPSIS 🦋

🌸 DESCRIPTION 🌸

💖 What is a template? 💖

💖 When are templates useful? 💖

💖 There are other templating modules on CPAN, what makes FastTemplate different? 💖

💖 What are the steps to use FastTemplate? 💖

👑 CORE METHODS 👑

🍓 define(HASH)

🍓 define_nofile(HASH) alias: define_raw(HASH)

🍓 define_nofile(HASH REF) alias: define_raw(HASH REF)

🍓 assign(HASH)

🍓 assign(HASH REF)

🍓 parse(HASH)

🍓 strict()

🍓 no_strict()

🍓 print(SCALAR)

💖 OTHER METHODS 💖

fetch(SCALAR) — hand me the pointer bestie

clear() — the reset button

clear(ARRAY) — the selective one 💅

clear_parse()

clear_href(NUMBER) — the loop cleaner-upper

clear_define() — nuke the definitions

clear_tpl() clear_tpl(NAME) — free that memory 🧚

clear_all() — the full reset 🌈

Variables

Variable Interpolation (Template Parsing)

FULL EXAMPLE — the whole glow-up 🌸

👑 COPYRIGHT 👑

💜 AUTHOR 💜

🦋 SEE ALSO 🦋

`fetch(SCALAR)` — hand me the pointer bestie

`clear()` — the reset button

`clear(ARRAY)` — the selective one 💅

`clear_parse()`

`clear_href(NUMBER)` — the loop cleaner-upper

`clear_define()` — nuke the definitions

`clear_tpl()` `clear_tpl(NAME)` — free that memory 🧚

`clear_all()` — the full reset 🌈