More open source projects:

• CAPTCHA API
• CFG Parser
• DBG Log
• Fast-RPC
• FastRPC-netcat
• JAK
• KJS Compress
• Seznam FS

Teng (template engine) manual

1. Introduction

1.1 Description

Teng (template engine) is general purpose template tool. Primary C++ library but also available as Python module and PHP extension. It composes result (web page, mail message or any text file) by combining input template with data supplied by application and optional configuration and localization(language) dictionary.

1.2 Characterictics

• Separation of application code and design templates
• Multiple templates
• Dictionaries - language dependent or not
• Caching of templates and dictionaries - automatic update on change
• Possible data integrity control
• API for C++, Python and PHP
• much more :-)

2. Syntax

Tags are enclosed by <?teng and ?> marks.

2.1 Comment

<!--- comment --->

Comment will not be in output file.

2.2 Include

<?teng include file=" template.teng " ?>

Include other template file.

2.3 Whitespace formating

begin of block: <?teng format space=" value " ?> end of block: <?teng endformat ?>

Set type of formating whitespace in output file. Value of space is one of:

nowhite

removes all whitespaces

onespace

collapse all whitespace characters into one space

striplines

removes all whitespaces at the begin and end of row except line break

joinlines

removes newline character and all whitespaces at begin of next row

nowhitelines

removes all empty rows

noformat

end parent space formating

2.4 Fragment

begin of block: <?teng frag identifier ?> end of block: <?teng endfrag ?>

Basic data block for reference by application

Default variables:

_count

number of iterations of fragment.

_number

actual count of iteration. It begins with 0 and exists only in fragment.

_this

actual fragment context

2.5 Condicional block

begin: <?teng if expression ?>
next: <?teng elseif expression ?>
next: <?teng else ?>
end: <?teng endif ?>

Expression is envaluated as false if is equal to empty string, string "0" or number 0. Type of data is ignored.

2.6 Definition of variable

<?teng set variable = expression ?>

Variable is available only in current fragment. Redefinition of variable submited by application will raise error.

2.7 Variable

<?teng expr $variable ?>
short: ${variable}
shorter: $variable

Include variable (data from application or defined by set tag). Must begin with letter or _. Can be followed by number. Must start with $ character in expression.

Naming convetion

2.8 Dictionary item

<?teng expr #item ?>
short: #{item}
shorter: #item

Include item from language dictionary into output.

2.9 Expression

<?teng expr expression ?>
short: ${expression}

General expression. Can by combination of data literals, variables, dictionary items, functions, operators and parentheses. Parentheses sets priority.

2.10 Literals

string

"Lorem ipsum dolor sit amet"

Escaped characters

\"

quote "

\\

backslash \

\n

new line

\r

carriage return

\t

tabelator

\<char>

<char>

integer

123

real number (float)

123.45

2.11 Operators

Bit operator can be used only on integer numbers.

2.12 Ternary operator

expession ? expression_true : expression_false

Returns expression_value if expression is true .

2.13 Case operator

case( expession , key1 , key2 : expression1 , key3 : expression2 ...)

Returns corresponding expession to value of key.

2.14 Exist operator

exist( identifier )

Checks if object exists. Returns:

2.15 Functions

Special "debug" function - <?teng debug ?> "bytecode" - <?teng bytecode ?>

2.16 Index of chapter

3. C++ API

Teng library provides access to the core of Teng for C++ programmers.

3.1 Requirements

To use Teng library, you need working C++ compiler. The authors of this library made special effort to make it standard compliant. It compiles under GCC v. 3.2.

Any GCC from v. 2.95 is strongly encouraged but any standard compliant C++ compiler.

3.2 Installation

Follow these steps to create and install Python Teng module(s) on your system.

1. Unpack Teng source into a build directory, e.g. ` /usr/local/src/teng '.
2. Enter build directory:

   $ cd `<source_tree>'

3. Configure teng.

   Invoke just this:

   $ ./configure

   or if you want to change installation root (default is ` /usr/local '), invoke:

   $ ./configure --prefix=installation-root

   to configure Teng.

4. Compile teng library:

   $ make

5. Built library (` libteng.a ') can be found in the ` src/teng ' directory.

   `<source_tree>/src/teng/libteng.a'.

6. Install the Teng library and its header files. To do so you have probably to change your persona to the super user (root):

   su -

   And then just invoke:

   make install

3.3 Classes and Methods

In the following declarations and method descriptions the std:: namespace prefix has been intentionally omitted to improve readibility.

All classes in the Teng library have intentionally private copy constructors and assignment operators to prevent disastrious consequences of copying internal data. Use references or pointers to pass values!

Only public interface of classes is documented here.

Data Tree

Data tree is composed of three clases ( TengFragment_t , TengFragmentList_t , and TengFragmentValue_t ). They can be found in the header ` <tengstructs.h> '.

Class TengFragment_t

Class TengFragment_t provides data for one fragment iteration. It is simply map between names and values. Value can be string or TengFragmentList_t . In the first case the pair (name, value) represents variable and in the second it's just link to data for nested fragment.

Declaration of class TengFragment_t

class TengFragment_t : public map<string, TengFragmentValue_t*> {
public:
	// Default constructor
	TengFragment_t();
	// Destructor
	~TengFragment_t();
	// Adds new variables to this fragment's data
	void addVariable(const string &name, const string &value);
	// Adds new variables to this fragment's data
	void addVariable(const string &name, long int value);
	// Adds new variables to this fragment's data
	void addVariable(const string &name, double value);
	// Adds new subfragment data to this fragment data
	TengFragment_t& addFragment(const string &name);
	// Adds new subfragment list to this fragment data
	TengFragmentList_t& addFragmentList(const string &name);
}

Constructor: TengFragment_t TengFragment_t ()

TengFragment_t creates new empty subfragment data.

Parameters:

None

Return value:

None

Destructor: TengFragment_t ~TengFragment_t ()

~TengFragment_t destroys subfragment data. Deletes all entries.

Parameters:

None

Return value:

None

Method: TengFragment_t void addVariable (const string& name , const string & value )

@deftypemethodx TengFragment_t void addVariable (const string & name , long int & value ) @deftypemethodx TengFragment_t void addVariable (const string & name , double & value ) addVariable adds new variable (maps name to string value value ). If entry for given name doesn't exist, nothing is inserted.

Parameters:

name

name is name of variable.

value

value is value name of variable.

Return value:

None

Method: TengFragment_t TengFragment_t& addFragment (const string& name )

addFragment calls TengFragment_t::addFragmentList( name ) to obtain reference to nestedFragments and then appends it by new empty subfragment data and returns reference to this data.

Parameters:

name

name is name of subfragment data.

Return value:

Reference to newly created subfragment data. It can be used to add some variables and subfragment data.

Method: TengFragment_t TengFragmentList_t& addFragmentList (conststring & name )

addFragmentList creates new TengFragmentValue_t of given name with new empty nestedFragments and returns reference to it. It's not considered as an error if TengFragmentValue_t already exists or even has non-zero nestedFragments .

Parameters:

name

name is name of subfragment data.

Return value:

Reference to newly created nestedList . It can be used to add subfragment data.

Class TengFragmentList_t

Class TengFragmentList_t encapsulates data for all iterations of one fragment. Its placeholder for list of fragments.

Declaration of class TengFragmentList_t

class TengFragmentList_t : public vector<TengFragment_t*> {
	public:
		// Default constructor
		TengFragmentList_t();
		// Descturctor
		~TengFragmentList_t();
		// Appends new (empty) fragment data at the end of this list
		TengFragment_t& addFragment();
}

Constructor: TengFragmentList_t TengFragmentList_t ()

TengFragmentList_t creates new empty subfragment data list.

Parameters:

None

Return value:

None

Destructor: TengFragmentList_t ~TengFragmentList_t ()

~TengFragmentList_t destroys subfragment data list. Deletes all subfragment data.

Parameters:

None

Return value:

None

Method: TengFragmentList_t TengFragment_t& addFragment ()

addFragment adds new empty subfragment data and returns reference to it.

Parameters:

None

Return value:

Reference to newly created fragment data.

Class TengFragmentValue_t

Class TengFragmentValue_t represents one entry in fragment's data table (class TengFragment_t ).

If value of member variable nestedFragments is non-zero, this instance is considered to link to the list of data for nested fragments. Otherwise this instance is considered to be fragment variable with value stored in member variable value .

Declaration of class TengFragmentValue_t

class TengFragmentValue_t {
	public:
		// Default constructor
		TengFragmentValue_t();
		// Destructor
		~TengFragmentValue_t();
		// Constructs variable
		TengFragmentValue_t(const string &value);
		// Constructs variable
		TengFragmentValue_t(long int value);
		// Constructs variable
		TengFragmentValue_t(double value);
		// Adds subfragment data to nestedFragments
		// Changes type to subfragment data!
		TengFragment_t& addFragment();
		// Value of variable (valid only when nestedFragments
		// is non-zero
		string value;
		// List of subfragment data
		TengFragmentList_t *nestedFragments;
}

Constructor: TengFragmentValue_t TengFragmentValue_t ()

TengFragmentValue_t creates new empty fragment value.

Parameters:

None

Return value:

None

Constructor: TengFragmentValue_t TengFragmentValue_t (const string& value )

Constructor: TengFragmentValue_t TengFragmentValue_t (long int value )

Constructor: TengFragmentValue_t TengFragmentValue_t (double value )

TengFragmentValue_t creates new variable with given value (converted to string ig needed).

Parameters:

value

Value of variable.

Return value:

None

Destructor: TengFragmentValue_t ~TengFragmentValue_t ()

~TengFragmentValue_t destructs fragment value. If nestedFragments is non-zero pointer, it's deleted.

Parameters:

None

Return value:

None

Method: TengFragmentValue_t TengFragment_t addFragment ()

addFragment optionaly creates new nestedFragments TengFragmentList_t (if not already exists), appends new empty subfragment data and returns reference to it.

Parameters:

None

Return value:

Reference to newly created fragment data.

Member: TengFragmentValue_t string value

Holds value of variable unless nestedFragments is non-zero.

Member: TengFragmentValue_t TengFragmentList_t *nestedFragments

If non-zero, it holds list of subfragment data.

Class Teng_t

The Teng_t class is the main Teng engine. It can be found in the header ` <teng.h> '.

Declaration of class TengFragmentValue_t

class Teng_t {
	public:
	
	// constructor
	Teng_t(const string &root, int logMode = 0,
	bool validate = false);
	// Destructor
	~Teng_t();
	
	// Generate page from template
	int generatePage(const string &templateFilename,
	const string &skin,
	const string &dataDefinition,
	const string &dictionary, const string &language,
	const string &configuration, const string &contentType,
	const string &encoding, const TengFragment_t &data,
	TengWriter_t &writer, TengError_t &err);
	
	// Generate page from template
	int generatePage(const string &templateString,
	const string &dataDefinition,
	const string &dictionary, const string &language,
	const string &param, const string &contentType,
	const string &encoding, const TengFragment_t &data,
	TengWriter_t &writer, TengError_t &err);
	
	// Direct dictionary lookup
	int dictionaryLookup(const string &dict, const string &lang,
	const string &key, string &value);
	
	// List content types supported by this engine
	static void listSupportedContentTypes(vector<pair<string, string> >
	&supported);
}

Constructor: Teng_t Teng_t (const string & root , int logMode =0, bool validate =false)

Teng_t creates new Teng engine with its own template and dictionary cache.

Parameters:

root

Root for relative paths (ones not starting wich / ).

logMode

Mode of logging errors. It's 0 or itwise-or'd zero or more of the following:

Teng_t::LM_LOG_TO_OUTPUT

If this bit is set, the error log will be appended at the end of generated page.

Teng_t::LM_ERROR_FRAGMENT

If this bit is set, the special fragment ` ._error ' will be accesible from the template.

validate

When true, the template and program supplied data will be validated agaist data definition.

Method: Teng_t int generatePage (const string& templateFilename , const string & skin , const string & dataDefinition , const string & dictionary , const string & language , const string & configuration , const string & contentType , const string & encoding , const TengFragment_t & data , TengWriter_t & writer , TengError_t & err )

@deftypemethodx Teng_t int generatePage (const string & templateString , const string & dataDefinition , const string & dictionary , const string & language , const string & configuration , const string & contentType , const string & encoding , const TengFragment_t & data , TengWriter_t & writer , TengError_t & err ) Main entry point to the engine. It reads and parses all dictionaries, reads and parses template, creates byte-code program for template and then executes it.

The first variant reads template from file templateFilename . If skin is non-empty string, it is prepended before first dot of basename of this file (e.g. ` .../filename.ext ' will become ` .../filename.<skin>.ext '). If basename doesn't contain any dot and skin is non-empty string, skin is appended as an extension at the end of basename (e.g. ` .../filename ' will become ` .../filename.<skin> ').

The second variant treats the templateString as template. It can be used to supply program generated template or template read from nother source than local file.

Language dictionary is read from file dictionary . If language is non-empty string, it is prepended before first dot of basename of this file (e.g. ` .../filename.ext ' will become ` .../filename.<language>.ext '). If basename doesn't contain any dot and language is non-empty string, language is appended as an extension at the end of basename (e.g. ` .../filename ' will become ` .../filename.<language> ').

Parameters:

1. templateFilename

   templateFilename is name (without skin) of file with template.

   skin

   skin is skin of template. Selects between variants of given template.

2. templateString

   templateString is template.

dataDefinition

dataDefinition is name of file with data definition. It is used only when validate supplid to Teng_t::Teng_t() was true.

dictionary

dictionary is name of file with language dictionary without language.

language

language is language of dictionary. Selects between language variants of given dictionary.

configFilename

configuration is name of file with configuration (language independent dictionary).

contentType

Content type is used for data escaping and commenting out.

encoding

encoding is used for string manipulating functions ( length , substr etc.).

data

data is data tree root.

writer

writer is output device. You can supply TengStringWriter_t for output to string or TengFileWriter_t for output to file (either open file stream or to file specified by filename). You can also inherit class from TengWriter_t for output to different destinatio.

err

err is error log with entry for every error encountered during template parsing and execution.

Return value:

Maximal severity of encountered error. Value of 0 means no error.

Method: Teng_t int dictionaryLookup (const string& dictionary , const string & language , const string & ket , string & value )

dictionaryLookup tries to find dictionary item in given dictionary.

Language dictionary is read from file dictionary . If language is non-empty string, it is prepended before first dot of basename of this file (e.g. ` .../filename.ext ' will become ` .../filename.<language>.ext '). If basename doesn't contain any dot and language is non-empty string, language is appended as an extension at the end of basename (e.g. ` .../filename ' will become ` .../filename.<language> ').

Parameters:

dictionary

dictionary is name of file with language dictionary without language.

language

language is language of dictionary. Selects between language variants of given dictionary.

key

key Name of dictionary item you are looking for.

value

This string is filled with value of found dictionary item unless result is non-zero.

Return value:

0 when item found !0 on error.

Method: Teng_t static void listSupportedContentTypes (vector<string,string> & supported )

listSupportedContentTypes returns list of content types supported by this engine. Each entry in the list is pair of content type name and comment on it.

Parameters:

supported

supported is filled with list of supported content types and comments on them.

Return value:

None

3.4 Examples

There is only one way to produce the reference example output (The Reference Example) using Teng Library.

#include <stdio.h>
// include teng header file
#include <teng.h>
// include writer
#include <tengwriter.h>
// include errorlog
#include <tengerror.h>

int main(int argc, char *argv[]) {
	static string characters[2] = { "A", "B" };
	
	// create Teng engine
	Teng_t teng("", Teng_t::LM_LOG_TO_OUTPUT | Teng_t::LM_ERROR_FRAGMENT);
	
	// root fragment data
	TengFragment_t rootFragment;
	
	// create list for rows
	TengFragmentList_t &rowList = rootFragment.addFragmentList("row");
	
	// create two rows
	for (int i = 0; i < 2; ++i) {
		// add varieble "rnum" ('A' or 'B')
		row.addVariable("rnum", characters[i]);
		// create two columns
		for (int j = 0; j < 2; ++j) {
			// create sub fragment data for column
			TengFragment_t &col = row.addFragment("col");
			// add variable "cnum" (1 or 2)
			rowcol.addVariable("cnum", j + 1);
		}
	}

	// output will go to the standard output
	TengFileWriter_t writer(stdout);
	
	// error log
	TengError_t err
	teng.generatePage("palette.html", // templateFilename
	string(), // skin (none)
	string(), // dataDefinition (none)
	string(), // dictionary (none)
	string(), // language (none)
	string(), // configuration (none)
	"text/html", // contentType
	"iso-8859-2", // encoding
	rootFragment, // data
	writer, // writer
	err); // err
	// OK
	return 0;
}

3.5 Index of chapter

4. Python Module

Python Teng module provides access to Teng functionality for Python programmers.

4.1 Requirements

To use Python Teng module, you need at least Python 1.5 with working distutils. Python 2.2 is strongly encouraged.

4.2 Installation

Follow these steps to create and install Python Teng module(s) on your system.

1. Unpack Teng source into a build directory, e.g. ` /usr/local/src/teng '.
2. Enter build directory:

   $ cd `<source_tree>'

3. Configure teng with Python module enabled. Configure looks for all Python binaries in` /usr/bin/ ' (exactly, any file matching ` /usr/bin/python?.? '). You may overide this behaviour by specifying other files as argument to --enable-python . Extension will be compiled for all found Python versions.

   Invoke just this:

   $ ./configure --enable-python

   or if you wish to explicitly specify Python binaries invoke this:

   $ ./configure --enable-python=/usr/local/bin/python2.2

   to configure Teng with Python module enabled.
4. Compile teng library:

   $ make

5. Built Python Teng modules can be found now in

   `<source_tree>/src/python/lib/python?.?/'.

   You may wish to install them to the installation directory. To do so you have probably to change your persona to the super user (root):

   su -

   And then just invoke:

   make install

6. If you want to create Debian package with Python Teng modules, simply enter` debian ' directory in the Teng source tree and invoke make :

   cd `<source_tree>/debian' make szn-py-teng

   Debian package can be found in ` <source_tree>/debian/tmp/ '.

   You can change package's version in file ` <source_tree>/debian/szn-py-teng.version '.

4.3 Data Tree

Data supplied to the engine can be Python data structures (dictionaries and lists/tuples) or Teng's native data structures encapsulated by Python object Fragment.

Python Data Tree

Python data tree is made up from dictionaries and lists/tuples.

Fragment data

Fragment data are mapped as dictionary. Key (name of entry in fragment data) must be string (keys of other types are silently ignored). String, unicode, integral and float values are treated as variables. Lists and tuple are treated as nested fragment data. Dictionaries are treated as special case of nested fragment data--just one iteration. Other types are treated as variables with result of call to str() as its value.

Nested fragment data.

Nested fragment data are mapped as lists or tuples (doesn't matter which you use). In the case you know that there will be just one iteration you can supply only this fragment data (dictionary) instead of list/tuple with single entry.

Native Teng Data Tree

Native data are mapped as type Fragment in Teng Python Module.

Fragment Supports only one method-- Fragment.addFragment() . It's used to add subfragment data into this fragment. Root fragment data are created with Teng's method Teng.createDataRoot() . Only root fragment data node can be supplied to Teng.generatePage() . Deletion of subfragment data doesn't invalidate other nodes. Deletion of root fragment data deletes internal data tree and invalidates all data subnodes pointing to this data tree. Such data subnodes cannot be used any more.

4.4 Types and Methods

Python module provides two data types, Teng and Fragment.

Teng

Teng is pure encapsulation of Teng engine. It provides access to original C++ API: method Teng.generatePage() and method Teng.dictionaryLookup() .

Fragment

Fragment is encapsulation of C++ structure TengFragment_t . It cannot be instantiated explicitly; to created object of this type you have to call method Teng.createDataRoot() to create new data tree root. Then you can add subnodes by invoking method Fragment.addFragment() on Fragment.

Constructor: teng.Teng teng.Teng (string root ="", string encoding ="iso-8859-2", string contentType ="", int logToOutput =0, int errorFragment =0, int validate =0)

teng.Teng() creates new Teng object encapsulating Teng engine.

Parameters:

root

Root for relative paths (ones not starting wich / ).

encoding

Default encoding supplied to Teng.generatePage if none specified. contentType is used for conversion from Unicode to 8-bit strings. Engine uses this value for string manipulating functions.

contentType

Default content type supplied to Teng.generatePage if none specified. Content type is used for data escaping and commenting out.

logToOutput

If logToOutput is non-zero, error log will appear at the end of generated page in commented block (according to content type.

errorFragment

If errorFragment is non-zero, error fragment is accesible from template.

validate

If validate is non-zero, data and templates will be validate to the data definition supplied to Teng.generatePage .

Return value:

Created object.

Module method: teng tuple teng.listSupportedContentTypes ()

Lists content types supported by this Teng engine. Result is tuple of two item tuples--content type and commentary on it.

Parameters:

None

Return value:

@verbatim ( (string, string), ...)

Method: teng.Teng dict Teng.generatePage (string templateFilename , string skin , string templateString , string dataDefinitionFilename , string dictionaryFilename , string language , string configFilename , string contentType , Object data , string outputFilename , FileObject outputFile , string encoding )

Main entry point to the engine. It reads and parses template and all dictionaries, creates byte-code program for template and then executes it.

All parameters are keywords. Some cannot be supplied together with other parameters, some cannot be supplied without other parameters.

Caution: It's different case when you supply None as value of keyword argument and when you don't supply any value to keyword argument!

Parameters:

templateFilename

templateFilename is name (without skin) of file with template. It cannot be supplied together with templateString .

skin

skin is skin of template. Selects between variants of given template. It cannot be supplied without supplying templateFilename .

templateString

templateString is string containing template. It cannot be supplied together with templateFilename .

dataDefinitionFilename

dataDefinitionFilename is name of file with data definition. It is used only when validate supplied to teng.Teng() was non-zero.

dictionaryFilename

dictionaryFilename is name of language dictionary without language.

language

language is language of dictionary. Selects between language variants of given dictionary. It cannot be supplied without supplying dictionaryFilename .

configFilename

configFilename is name of file with configuration (language independent dictionary).

contentType

Content type is used for data escaping and commenting out.

data

data is data tree. Either Python's native types or Fragment created by calling Teng.createDataRoot (other Fragment cannot be used).

outputFilename

outputFilename is name of file to which output will be written. Cannot be supplied together with outputFile .

outputFile

outputFile is file object to which output will written. Must be open for writing. Cannot be supplied together with outputFilename .

encoding

encoding is used for conversion from Unicode to 8-bit strings. Engine uses this value for string manipulating functions.

If neither templateFilename nor templateString is supplied, exception is raised to inform programmer that no source is specified.

If neither outputFilename nor outputFile is supplied, generated output can be found in result dictionary.

Return value:

Dictionary containing status code (0 == no error), output (filled only if no destination specified) and error log (tuple with entry for each line).

@verbatim

dict = { int status, # status code -- severity of # most severe error string output, # generated result tuple errorLog = ( # error log dict = { int level, # severity of error string filename, # file where error occured int line, # line in file string column, # column in line string message, # description } ) }

Method: teng.Teng string Teng.dictionaryLookup (string dictionaryFilename , string language , string key )

Search given key in dictionary. Parameters:

Parameters:

dictionaryFilename

dictionaryFilename is filename of dictionary without language.

language

language is language of dictionary. Selects between language variants of given dictionary.

key

key is name of searche dictionary item.

Return value:

Value of found item (string) or None if item for key not found.

Method: teng.Teng Fragment Teng.createDataRoot (Object data = None )

Creates native data root (type Fragment ) and populates it with data.

Parameters:

data

data is data tree which populates data root.

Return value:

Created root fragment (type Fragment ).

Method: Fragment Fragment Fragment.addFragment (string name , Fragment data )

Cretes new fragment, polulates it with data, adds to this fragment and finally returns it.

Parameters:

name

name is name of newly created fragment data.

data

data is data tree which populates newly created fragment data.

Return value:

Created root fragment (type Fragment ).

4.5 Examples

There are numerous ways to produce the reference example output (The Reference Example) using Teng Python Module. Two significantly different options exist.

The first approach uses native Python data structures to pass a data tree from a Python script to Teng.

#import Teng module
import teng

# initialize Teng engine with defaults
t = teng.Teng();

# build data tree from bottom up
data = {'row': []}
for i in range(ord('A'), ord('C')):
	row = { 'rnum': chr(i), 'col': [] };
		for j in range(0, 2):
			row['col'].append({ 'cnum': j});
	data['row'].append(row);

#generate page
print t.generatePage(templateFilename="palette.html", data=data,
contentType="text/html",
encoding="ISO-8859-2")['output']

# delete teng engine
del t

A different approach uses the Teng module API to build the data tree.

#import Teng module
import teng

# initialize Teng engine with defaults
t = teng.Teng();
data = t.createDataRoot()

for i in range(ord('A'), ord('C')):

# add nested row fragment
row = data.addFragment("row", { "rnum": chr(i) })
	for j in range(0, 2):
	
	#add nested column fragment
		row.addFragment("col", { "cnum": j })

#generate page
print t.generatePage(templateFilename="palette.html", data=data,
contentType="text/html",
encoding="ISO-8859-2")['output']

# delete data tree
del data

# delete teng engine
del t

4.6 Index of chapter

5. PHP Extension

PHP Teng extension provides access to Teng functionality for PHP4 programmers.

5.1 Requirements

Teng PHP extension can be built as a loadable PHP module or can be compiled into your PHP4 build. See the following subsection on instructions how to do it. The authors of the extension have used PHP 4.3.2 for their build though any version greater than 4.1. should suffice.

5.2 Installation

Follow these steps to install PHP4 with Teng extension on your system:

1. Unpack Teng source into a build directory, e.g. ` /usr/local/src/teng '. Build and install the teng library.
2. Obtain a source PHP distribution, and unpack it into a build directory, e.g.` /usr/local/src/php4 '.
3. Link the Teng extension into the PHP4 extension directory as

   $ ln -s /usr/local/src/teng/src/php /usr/local/src/php4/ext/teng

4. In the PHP source distribution root, run

   $ ./buildconf --force

5. Configure PHP to use the Teng extension. If you already have Teng library installed on your system, all you need to do

   $ ./configure --with-apxs --with-teng

   Depending on where you installed Teng, you might have to provide the installation path along with the option. Quite likely, you will also want to use other configure options to compile more extensions to your PHP build. Try ./configure --help to see what's on the menu.
6. From here, you probably know the drill

   $ make; make install

7. Try

   $ echo '<?php phpinfo() ?>' | /usr/local/bin/php

   And look for the Teng extension section in output.

5.3 Runtime Configuration

Teng's behavior is affected by the following ` php.ini ' entries:

A short explanation of the configuration directives follows.

Directive: string teng.template_root

Defines the default root path used to access Teng templates and dictionaries. This directive can be overriden by the first argument to teng_init .

Directive: string teng.default_dict

Sets the path to default language dictionary. Setting this directive is equivalent to passing a corresponding dict parameter in any call to teng_page_ family of functions.

Directive: string teng.default_lang

Sets the default language. Setting this directive is equivalent to passing a corresponding lang parameter in any call to teng_page_ family of functions.

Directive: string teng.default_config

Sets the path to default template configuration. Setting this directive is equivalent to passing a corresponding config parameter in any call to teng_page_ family of functions.

Directive: string teng.default_content_type

Sets the default content type. Setting this directive is equivalent to passing a corresponding content_type parameter in any call to teng_page_ family of functions. Content type effects escaping of data passed passed from the application, and formating of diagnostic output for parse and runtime errors. See the Teng section in phpinfo output, or the output of teng_list_content_types for suported content types.

Directive: string teng.default_encoding

Sets the default document encoding. Setting this directive is equivalent to passing a corresponding encoding parameter in any call to teng_page_ family of functions. Encodings are denoted in the iconv(1) uses.

Directive: boolean teng.validation

This boolean flag indicates whether Teng should perform template and application data validation. Validation provides a way to define the structure of data which can be passed from the application to the presentation layer (data definition). When validation is turned on, data definition file is supplied to a call to any teng_page_ function, failure to meet the data definition requirements on part of the template or of the application causes Teng to complain.

Directive: boolean teng.log_to_output

If this boolean flag is set, teng logs parsing and runtime errors into content-type dependant comments on the output page. If you send Teng output directly to the script output, teng.log_to_output is similar to log_errors but it does not clutter up the page.

Directive: boolean teng.error_fragment

If this boolean flag is set, diagnostic page-generation output is added to every data tree in the form of a special error fragment, ` ._error '. The fragment contains level , filename , line and message variables and the template can use it to visualize errors in a customized manner.

Directive: string teng.default_skin

Sets the default template skin. Setting this directive is equivalent to passing a corresponding skin parameter in any call to teng_page_ family of functions.

5.4 Resource Types

Two resource types exist in the Teng extension.

The first resource type provides access to the templating engine itself. A Teng resource is persistent. Once created, exists until the Teng extension remains in memory, allowing the cached templates and dictionary files to be reused by further requests. A repeated call to teng_init with the same template root results in reusing the previously created resource.

The second resource type represents a fragment. A fragment is a reference to a position in an internal data tree built using Teng extension. Fragment resources are fully reentrant (multiple data trees can exist simultanously within a single application) and non-persistent, that is, they are discarded, along with the data they refer to, at the end of every request.

5.5 Functions

PHP Teng extension provides the following functions:

Function: resource teng_init ([ string template_root ])

teng_init returns a new teng resource. A Teng resource provides the application with access to the templating engine.

template_root sets the implicit path used to access templates and dictionaries. If not provided, the teng.template_root configuration directive is used. If the directive is not set, the script's current working directory is used.

Teng resources are persistent which means there lifetime exceeds a duration of a single request. If a Teng instance with a given template_root was allocated before the return value points to a previously allocated instance. This allows the application to seamlessly cache templates and dictionaries across multiple HTTP requests.

Function: boolean teng_release (resource teng )

teng_release releases a teng resource teng previously created created with teng_init . This has no other effect but invalidation of the resource in current symbol table, the Teng instance the resource points continues to exist in PHP's memory.

Calling this function is not necessary but is recommended as a good practice. An application programmer uses this call to inform PHP that there is in further use for the Teng resource.

Function: resource teng_create_data_root ([ array data ])

teng_create_data_root allocates and initializes new internal data tree and returns it as a new fragment resource. Internal data trees are a fast and convenient way to pass application data to Teng.

data is an associative array with the content of data tree's root fragment. Nested lists of associative arrays can be included and function as one would expect, though there is usually little reason to use them: use teng_add_fragment to nest fragments instead. Any non-associative (integer key) elements in data are silently ignored. If data is not provided, the root fragment is created empty.

The fragment resource returned by teng_create_data_root can be used as an parent argument to teng_add_fragment and as the data argument to teng_page family of functions. The fragment resource should be cleared by teng_release_data when no longer needed, though PHP will do this automatically at the end of the request.

Function: resource teng_release_data (resource root )

teng_release_data removes the data tree root allocated by teng_create_data_root from memory and invalidates the corresponding fragment resource. Any nested fragment resource created by teng_add_fragment is also invalidated.

PHP automatically removes the data tree and invalidates corresponding fragment resources at the end of any HTTP request. However, it is a good pratice to call teng_release_data when the data tree is no longer needed.

Function: resource teng_add_fragment (resource parent , string name [, array  data ])

teng_add_fragment adds a nested fragment to a fragment refered to by resource parent and returns a new fragment resource for it.

name is the name of the nested fragment, data is an associative array with fragment content. Nested lists of associative arrays can be included and function as one would expect, though there is usually little reason to use them: use teng_add_fragment on the returned resource to nest fragments instead. Any non-associative (integer key) elements in data are silently ignored. If data is not provided, the fragment is created as empty.

The resource returned by teng_add_fragment can be used as the parent argument to teng_add_fragment . This implies it is sensible to keep the return value only when another level of nesting is added. The resource is automatically invalidated when teng_release_data is called on the data root resource.

Function: string teng_page_string (resource teng , string template_path [, array/resource data [, array options ] ])

teng_page_string invokes the Teng engine to generate a page from a template file and returns the result as a string.

teng is a Teng resource created by teng_init . template_path is a path to a Teng template file, either absolute or relative to the Teng template root.

data is either an associative array or a fragment resource. Both hold the entire data tree. In the first case, the associative array holds the root fragment content, with optional nested lists of associative arrays for multi-level data trees. In the second case, the fragment resource is created by teng_create_data_root and optionally populated by calls to teng_add_fragment .

options is an optional associative array holding a number of options modifying Teng's behavior in the process of page generation. Any number of options can be included. The folowing strings can be used as keys in options :

skin

Specifies a skin to use with the template. If specified, the skin works as modifier for the template name. If template is ` foo.html ' and the skin option is set to ` bar ', Teng will search for ` foo.bar.html ' in its template root.

dict

Specifies path of a language dictionary to use with the template. The path is absolute or relative to Teng's template root.

lang

Specifies a language variant of the dictionary. If specified, the skin works as a modifier for language dictionary path. If dict is ` foo.dict ' and the lang is set to ` cz ', Teng wil search for ` foo.cz.dict ' in its template root.

config

Specifies path of a configuration dictionary to use with the template. The path is absolute or relative to Teng's template root.

definition

Specifies path of a document definition to use with the template_path and data . If the document definition is set and teng.validation directive is ` On ', Teng validates the template and application data using the document definition provided and complains loudly if the document validation is violated.

content_type

Specifies the content type of the generated page. Content type determines the way data passed to the output page is quoted and format of diagnostic output for runtime errors log, if included in output. If not set, value of teng.content_type directive is used.

encoding

Specifies the character encoding of the generated page. Setting the correct character encoding ensures Teng functions such as len and substr , particularly if your document uses multi-byte character encoding. If not set, the value of teng.encoding is used.

Any runtime errors in page generation are logged to PHP error output.

Function: string teng_page_string_from_string (resource teng , string template_path [, array/resource data [, array options ] ])

teng_page_string_from_string invokes the Teng engine to generate a page from a template string and returns the result as a string.

For a description of teng , data , options arguments please see the documentation of teng_page_string .

Function: string teng_dict_lookup (resource teng , string key [,string dict [, string lang ] ])

teng_dict_lookup looks up a dynamic literal and returns the result.

teng is a Teng resource created by teng_init . key is the dynamic literal to be looked up. dict is the path to dictionary file. If not provided, value of teng.default_dict is used. lang is an optional language variant (a modifier to dict , see documentation of teng_page_string for details).

teng_dict_lookup returns FALSE if the dictionary lookup fails.

Function: array teng_list_content_types ()

teng_list_content_types lists content types supported by Teng. The return value is an associative array, with each element containing supported content type as the key and a brief description as the value.

5.6 Examples

There are numerous ways to produce the reference example output (The Reference Example) using Teng PHP Extension. Two significantly different options exist.

The first approach uses native PHP data structures to pass a data tree from a PHP script to Teng.

<?php
// initialize Teng engine with default data root
$teng = teng_init();

// build data tree from bottom up
$data = array();
for ( $i = 'A'; $i < 'C'; $i++ ) {
	$row = array( 'rnum' => $i );
	for ( $j = 0; $j < 2; $j++ )
		$row[ 'col' ][] = array( 'cnum' => $j );
	$data[ 'row' ][] = $row;
}

// generate page
echo( teng_page_string( $teng, "palette.html", $data,
array( "content_type" => "text/html",
"encoding" => "ISO-8859-2" ) ) );

// release teng engine (not necessary, but good practice)
teng_release( $teng );
?>

A different approach uses the Teng extension API to build the data tree.

<?php
// initialize Teng engine with default data root
$teng = teng_init();

// create new data tree
$data = teng_create_data_root();

// build data tree from top to bottom
for ( $i = 'A'; $i < 'C'; $i++ ) {

	// add nested row fragment
	$row = teng_add_fragment( $data, "row", array( "rnum" => $i ) );
		for ( $j = 0; $j < 2; $j++ )
		
		// add nested column fragment
		teng_add_fragment( $row, "col", array( "cnum" => $j ) );
}
// generate page
echo( teng_page_string( $teng, "palette.html", $data,
array( "content_type" => "text/html",
"encoding" => "ISO-8859-2" ) ) );

// release data tree (not necessary, but good practice)
teng_release_data( $data );

// release teng engine (not necessary, boot good practice)
teng_release( $teng );
?>

The first approach is a recommended option for simplistic data trees, with at most two nesting levels and little or no data outside the root fragment. The second approach is better suitable for more complex data trees, which would be difficult to build and navigate using PHP arrays. It should be also noted that, for larger data trees, Teng extension API is considerably more effective than native PHP data structures and consumes less memory.

5.7 Index of chapter

Table of Contents

1. Introduction

1.1 Description
1.2 Characterictics

2. Syntax

2.1 Comment
2.2 Include
2.3 Whitespace formating
2.4 Fragment
2.5 Condicional block
2.6 Definition of variable
2.7 Variable
2.8 Dictionary item
2.9 Expression
2.10 Literals
2.11 Operators
2.12 Ternary operator
2.13 Case operator
2.14 Exist operator
2.15 Functions
2.16 Index of chapter

3. C++ API

3.1 Requirements
3.2 Installation
3.3 Classes and Methods
3.4 Examples
3.5 Index of chapter

4. Python Module

4.1 Requirements
4.2 Installation
4.3 Data Tree
4.4 Types and Methods
4.5 Examples
4.6 Index of chapter

5. PHP Extension

5.1 Requirements
5.2 Installation
5.3 Runtime Configuration
5.4 Resource Types
5.5 Functions
5.6 Examples
5.7 Index of chapter

Short Table of Contents

1. Introduction
2. Syntax
3. C++ API
4. Python Module
5. PHP Extension

About this document

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== CurrentPosition
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on October, 19 2004 using texi2html