..Gedafe Pearls
Mailing List
Page Maintainer:
David Schweikert

Last Update:


Text::CPPTemplate - CPP-Style Templates


 use Text::CPPTemplate;
 my $templ = new Text::CPPTemplate('/var/web/templates','.html');
 print $templ->template({
        PAGE => 'index',
        ELEMENT => 'header',
        TITLE => 'Test'


CPPTemplate is a templating system using a CPP-style (C Pre-Processor) syntax. CPPTemplate is quite fast so that it can be used in online Applications such as CGI scripts to separate program the code from the HTML. CPPTemplate is not HTML specific, so it can be used for other applications. For performance reasons, the files containing the templates are read only once and are cached for further use. This is especially handy when working with long running scripts which use the same template over and over again. Apache mod_perl is such an environment.

An application can use a large number of templates. They could for example represent different parts of output generated by the aplication. Each template can contain variables and CPP style if-then-else structures. When the template gets activated, all the variables will get substituted and the if-then-else structures will get processed.


When you activate a template, you do not specify a file-name, but only variables. Based on the contents of some special variables, CPPTemplate will try to load an apropriate template file from disk. It tries to do this using a number of different file-names. The first one to exist will be used. A directory where the templates reside and a suffix have to be specified with the new method. The following list shows which variables cause CPPTemplate to look for which files:

  • PAGE_ELEMENT (PAGE and ELEMENT are variables)
  • PAGE
  • default (as is, not a variable)

In addition, if THEME is specified, the template will be first searched in the subdirectory specified by that variable of the templates directory.

In the example given in SYNOPSIS, the following files will be opened in turn until one is found to exist (in the directory /var/web/templates): index_header.html, header.html, index.html and default.html.


Variables are marked ##var## in the templates. If no variable is found with that specified name, the ##var## text remains unchanged.


``MiniCPP'' directives permit the selection of parts of the template based on some condition. The language is very very basic, it seems to be good-enough for most applications. The following directives are supported:

// comment
The whole line is removed from the output
#ifdef VAR
If variable VAR is defined, the following text will be selected.
#if expr
If the expression expr evaluates to true (see EXPRESSIONS), the following text will be selected. You can use substitutions in the expression with the syntax '##VAR##'.
#elif expr
If the previous #if (or #elif) expression was false, evaluate this expr and if true select the following text.
If the previous #if (or #elif) expression was false, select the following text.
Ends an #ifdef or an #if.

Note that these elements can be nested.

The newlines will be removed unless two consecutive lines without MiniCPP directives are found. Spaces and tabs will be removed from the beginning and the end of each line. Use '\ ' (backslash space) to insert spaces at the beginning or the end of the line.


At the moment only the following expressions are supported (don't laugh :-))

A = B
If A is equal to B (the text), then the expression is true.
A ~ B
Match A against the regular expression (perl) B. True if it does match, false otherwise.


     <A href="##ADD_URL##">Add</A>
     <A href="##PREV_URL##">Prev</A>
     <A href="##NEXT_URL##">Next</A>


new($templates_dir, $suffix)
Create a new CPPTemplate object. $templates_dir is the directory where the templates are stored and $suffix is a text to append to the file-names.

Return a processed template. \%vars is a hashref containing the variables used for building the file-name, for the substitutions and the CPP-style directives.




Copyright (c) 2000 ETH Zurich, All rights reserved.


This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
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 GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.


David Schweikert <dws@ee.ethz.ch>, Tobi Oetiker <tobi@oetiker.ch>