The LibTPT Book (Preliminary Documentation)

LibTPT has been compiled and tested under the following platforms:

LibTPT is also rumored to build on:

Currently, LibTPT officially supports Microsoft Visual C++ 6.0, but is known to work with Visual C++.Net (7.0) as well. For optimal performance, it is highly recommended that you install the STLPort (http://www.stlport.org/).

After installing the STLPort, add the following line to %INCLUDE%\stlport\stl_user_config.h:

#define _STLP_DO_IMPORT_CSTD_FUNCTIONS 1

The %INCLUDE% variable is the path where the stlport directory was installed. This will make the STL import the standard C library functions into the "std" namespace, making Visual C++ act more like a standard C++ compiler.

Make sure you set %INCLUDE%\stlport as your first include path, or the wrong version of the header files will be included. Also, since MSVC 6 does not properly handle the standard library in the std namespace, avoid broad statements like

using namespace std;

Once your build environment is set up correctly, open w32/libtpt.dsw. The libtpt workspace includes all projects necessary to build libtpt and its tests. The default build configuration is intended for a generic x86 platform. Change these options if you so desire.

Both debug and release configurations are available for build. Each project should build with "debug" in its name when compiled as a debug project.

Batch build all the release versions, then run tests:

cd test/
test.bat

At the time of the writing of this document, LibTPT has only been tested with GCC 3.x. GCC 2.95.x is known to have problems compiling LibTPT.

The LibTPT configuration system requires Perl 5.005 or later. The configure.pl script requires that either the CXX environment variable is set to the path of your C++ compiler, or that you specify the path to you C++ compiler with the --cxx command line option.

./configure.pl --cxx /path/to/g++ [--help]
make
./test.sh
make install

By default, configure.pl will use /usr/local as the install directory. Use --prefix=/new/install/path to override this.

TPT reserves the following characters.

@ { } " ' \

To use one of these characters in text, use the backslash (\) escape character. For example, \\ in TPT will evaluate to a single \. Not escaping these reserved characters can lead to undesirable effects.

Variables are objects that hold values. In TPT, a variable may hold a value of type integer, string, array of values, or hash of values.

A variable in TPT is identified in plain-text as ${id} and in an expression as just id, where id is the name of the variable. The value of a variable is set using the @set TPT command.

@set(id, 123)

@set(id, "The red fox runs.")

A variable may also be cleared using the @unset TPT command.

@unset(id)

See Example 2.2 for an example of how variables may be used in a template.

Variables can also hold more complex values, such as arrays or hashes. Array variables look like,

${array[index]}

and hashes look like,

${array.member}

In arrays, the index can be either a number or an expression that evaluates to a number. Example 2.3 demonstrates how to set a variable to an array, then read the variable.

Note the use of spaces in this example. Backslashes are used to join lines. For more details about controlling whitespace and carriage returns, see the section called “Whitespace & Carriage Returns”.

Example 2.4 demonstrates how to use an array index in a creative fashion.

To determine the type of variable, use @isarray, @isscalar, and @ishash.

Comments are denoted by the @# (at-pound) symbols. TPT only supports to end-of-line comments. I.e. everything on the line following @# is a part of the comment.

Hello World!	@# This is the Hello World Comment.

In the above example, everything after Hello World! will be ignored by the TPT parser, including the whitespace. Comments affect whitespace depending on use. All whitespace immediately preceeding a comment is ignored. In the case of a full line comment,

@# This is a full line comment
	@# This is not

the entire line, including carriage returns, is ignored. In order to be classified as a full line comment, @# must be the very first characters on the line. Preceding the @# with whitespace will only cause the whitespace and comment to be ignored. This is useful if you need to insert a certain number of blank lines into a template.

@# Insert some blank lines
	@# blank line 1
	@# blank line 2
	@# blank line 3
	@# blank line 4
	@# blank line 5

Expressions in TPT can only be executed when placed inside a TPT wrapper like a function, macro, array [], loop, or conditional expression. TPT employs a full Recursive Descent parser, so complex infix expressions are supported. Use @eval to evaluate an expression in text.

Since the primary purpose of TPT is to format templates into text, controls are provided to remove whitespace and carriage returns. Using a backslash (\) at the end of a line will join lines. Any whitespace before @< will be ignored, and any whitespace after @> will also be ignored.

Macros are a powerful feature of TPT. User defined Macros in TPT are very similar to user defined functions or subroutines in other languages. A macro must be defined before it is used. A macro definition looks like:

@macro(mymacro, param1, param2, ...) {
	macro body
}

To access this macro once its defined would look like:

@mymacro(param1, param2, ...)

dumptpt.cxx

#include <libtpt/tpt.h>
#include <iostream>
#include <stdexcept>

// Dump the parsed template output straight to std::cout
void dumptemplate(const char* filename)
{
	try {
		// Instantiate a parser
		TPT::Parser p(filename);

		// Add an include path (only ./ searched by default)
		p.addincludepath("./include");

		// Parse the template directly to standard output
		if (p.run(std::cout))
		{
			// handle reporting of template errors
		}
	} catch(const std::exception& e) {
		std::cout << "EXCETPION: " << e.what() << std::endl;
	}
}

In C++, it is sometimes handy to specify that a library function call a user defined function for customizable behavior. In the standard library, the generic binary search and quick sort functions do this.

void *bsearch( const void *key, const void *base, size_t num, size_t width, int
	(*compare ) ( const void *elem1, const void *elem2 ) );
void qsort( void *base, size_t num, size_t width, int (*compare )(const void
	*elem1, const void *elem2 ) );

Each of these functions allows the user to specify a custom compare function for a user defined data type. LibTPT provides a similar method to allow the user to specify a C++ function that will be called from a TPT template.

Callbacks give the user the power to extend TPT beyond its core functionality. For instance, a project may require TPT to do some floating point math, which is not available in the core language. On the more extreme, a user may decide to extend TPT with CGI or Database functionality. Whatever the reason, callbacks let the user implement fast TPT functions within the C++ code.

Remember, while it is tempting to write callback modules that allow TPT to do anything a full blown language can do, TPT was designed to take advantage of the speed of C++ for variable management. Therefore, functionality like database access or CGI processing should remain in your C++ code for optimal performance.

A TPT callback must be declared in the form:

	bool mycallback(std::ostream& os, TPT::Object& params);

Note that the first parameter is a reference to an output stream. All communication between the callback and the LibTPT parser are handled with streams. So, to have the callback print a message would look like:

	os << "My Message";

The second parameter is of type TPT::Object, which represents a generic object in LibTPT. The object may hold a type of scalar, array, or hash. The params variable passed to the callback is guaranteed to hold an array, but that array may hold scalars, arrays, hashes, or any combination of those types, depending on how the callback was called from within the TPT template. The enumerated types of object available to a callback function are TPT::Object::type_scalar, TPT::Object::type_array, and TPT::Object::type_hash, with the corresponding access methods TPT::Object::scalar(), TPT::Object::array(), and TPT::Object::hash(). If a call to the incorrect access method is made, an exception will be thrown. The parser does its best to handle these exceptions without interrupting the template translation.

When accessing a member of Object::array() or Object::hash(), be sure to use the get() method to get the member's real address. Member of Object arrays and hashes are stored in a smart pointer to ensure proper memory management. Refer to the example below for how to properly access a member of an Object array.

As mentioned earlier, TPT does not have any built-in functionality for dealing with floating point numbers. Suppose you needed a function to sum a list of floating point numbers populated into variables from a database or user form. See Example 4.1 for an example of what the code might look like for a floating point summation function.

This callback is then registered with the TPT::Parser::addfunction() method.

	TPT::Parser p(buf);
	p.addfunction("fsum", &fsum);
		

The above example demonstrates how simple it is to loop through an array of scalar examples. As an exercise, modify fsum to be able to process sub-arrays of floats.

As with most programming interfaces, using TPT callbacks can open some serious security holes if you are not paying attention. It is recommended that you do not create callbacks that can execute arbitrary programs, and when processing user input, always bounds check the input. Bounds checking is already handled by the std::string class, so the best bet is to stick with std::string. Do not use sprintf for formatting strings. If you must format a string, and absolutely cannot use iostreams, use snprintf instead, and double check your format string for any errors.