Teng Manual

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

Teng is case sensitive in all ways except for exactly specified exceptions.

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

	Tip
	If you need to generate ‘<?teng’ tag, use ‘${"<?teng"}’. In SGML- or XML-based document use ‘&lt;?teng’ according to W3C’s recommendations.

<!-- comment -->

/* comment */

The first version is used outside teng commands, the second inside.

Comment will not be in output file.

If you want to make a SGML or XML comment, that will occure in output file, use <!--- comment ---> (with three dashes).

Teng supports dynamic types, ie. every object can be used as if it has type of another one. Non-variable objects (fragments and dictionaries) cannot be converted from and to because there is no logical way how to do this.

If you try to convert an object from one type to another and this conversion is illogical (eg. converting string containing non-numeric characters to integer), an error is raised and a special type that can be converted to string "undefined" is returned.

The following definitions can be used to create objects:

"string"

Evalutes as string.

Strings can contain following escape characters:

123

Evalutes as integer.

123.45

Evalutes as real (number with floating decimal point).

Integers and reals are called numerics. Every numeric is signed, ie. it can have negative value. However, there is no way how to define a numeric with negative value, because ‘-’ before number creates an expression and therefore is not a definition.

Strings and numerics are called variables.

fragment

dictionary

Fragment and dictionary types cannot be declared inside Teng scripts. Objects of these types are posted by calling application only.

Fragment and dictionary types are called non-variable objects.

In logical operations, numeric 0, empty string and string "0" are false; other values are true.

Checks whether object with identifier ‘identifier’ exists and has a value.

Returns 0 if object does not exist; is string or fragment and is empty; is numeric and is zero. Otehrwise returns 1.

	Important
	This operator is available since version 1.0.13 of Teng library.

Checks whether object with identifier ‘identifier’ exists.

Returns one of following values:

	Warning
	Teng library version ≤ 1.0.12 also raises an error if such object does not exist; this is no more since version 1.0.13

<?teng expr expression ?>

${expression}

Evalutes ‘expression’ and prints evaluted value.

	Tip
	If you need to generate ‘${’, use ‘${"${"}’.

Object is a named data entity. It can be either variable or fragment or dictionary. Each object’s identifier must be unique in its dictionary.

Object’s identifier can contain numbers, letters and underscores. It cannot begin with number. It must be at least one character long. Maximal length of it is unlimited.

Object’s identifier can also contain dots. Dots in identifiers have special meaning:

	Note
	If fragment is used for specifying context, it’s first dictionary (‘iteration’) is used.

Dictionary is a set of objects and their identifiers. Dictionary can contain another dictionary only as an automatic object.

Each context is a dictionary, each fragment is an array of dictionaries.

For more information on specifying dictionaries, see API documentation and preface ‘dictionary’.

<?teng expr $variable?>

${variable}

$variable

Prints value of variable with identifier ‘variable’. If this identifier is either undefined or belongs to non-variable object, an error is raised.

<?teng expr #variable?>

#{variable}

#variable

Prints value of variable from external dictionary with identifier ‘variable’. If this identifier is not defined in any dictionary, an error is raised.

<?teng expr @expression?>

${@expression}

Prints value of variable from external dictionary with identifier equal to evaluated ‘expression’. If this identifier is not defined in any dictionary, an error is raised.

For more information on identifiers see section ‘Object’.

	Tip
	If you need to generate ‘$’ or ‘#’, use ‘${"$"}’ or ‘${"#"}’.

<?teng if expression ?>

Begins ‘if’ conditional block and its first part.

This part is skipped if ‘expression’ is empty string, string "0", or numeric 0.

<?teng elseif expression ?>

Begins another part of ‘if’ condition block.

This part can be omitted and can occure multiple times in one conditional block.

This part is skipped if ‘expression’ is empty string, string "0", or numeric 0.

<?teng else ?>

Begins last part of ‘if’ conditional block.

This part can be omitted.

This part is executed if no other part was.

<?teng endif ?>

Terminates ‘if’ conditional block.

expression ? if_true : if_false

Returns ‘if_false’ if ‘expression’ is empty string, string "0", or numeric 0; otherwise returns ‘if_true’.

case(expression, key1, key2: value12, key3: value3, …, *: value_other)

Returns ‘value12’ if ‘expression’ has value ‘key1’ or ‘key2’, ‘vaule3’ if ‘expression’ has value ‘key3’, or ‘value_other’ if nothing before matches.

Case operator can have any number of keys and values. It can also contain at most one wildcard key (‘*’).

Key can be variable definition only. If the key is numeric, it can have one plus or minus sign before its definition to define negative or possitive number.

If a key is matched, a value after first following colon is returned and searching is terminated.

Any key can occure multiple times, however only the first match will be evaluted. Also if wildcard key is placed before some more keys, these keys are never evaluted.

‘expression’ and values after colons are never used as keys.

<?teng set variable=expression ?>

Defines a variable with value equal to evaluated ‘expression’.

If such variable already exists, reset its value to evaluated ‘expression’.

If an object with identifier equal to ‘variable’ was submitted by the calling application, its value remains and an error is raised.

If defined inside fragment block, this variable is available only in current fragment block’s iteration.

<?teng format space="value" ?>

Begins whitespace formating block.

Child whitespace formating block overrides its parent whitespace formating block.

Outside any whitespace formating block is no whitespace formating at all like in whitespace formating block with ‘space’ equal to ‘noformat’.

Parameter ‘space’ sets its type. Possible values are one of the following:

<?teng endformat ?>

Terminates whitespace formating block.

<?teng frag identifier ?>

Begins fragment block.

Each fragment is an array of dictionaries.

The fragment block is executed once for each dictionary (this is called ‘iteration’).

There are some automatic objects defined for each fragment:

<?teng endfragment ?>

Terminates fragment block.

For more information on identifiers see section ‘Object’.

<?teng include file="filename" ?>

Includes other template file.

The included file will be compiled and cached as it is used directly.

Maximal include (‘nesting’) depth is limited due to possible problems with infinite recursion (default limit is 10, can be changed by dictionary command ‘%maxincludedepth’).

To debug Teng engine and templates, there are two commands beside error logging facility (as documented in function ‘Teng::Teng_t::generatePage’):

<?teng debug?>

If configuration flag ‘debug’ is enabled, prints debugging information; otherwise ignored.

<?teng bytecode?>

If configuration flag ‘bytecode’ is enabled, prints disassembled bytecode; otherwise ignored.

	Note
	This command is useful only when debugging Teng compiler and processor. Do not expect to get anything useful if debugging templates unless you know how Teng processor works.

Dictionaries are powerful way how to specify static data for your templates that are independent on calling application. Therefore dictionaries are very easy way to alter generated pages’ content and your news team may be absolutely lames in programming (there will need only a text editor and next section).

Moreover dictionaries brings the possibility to use one template and one application for multiple languages. Simply make your application capable of dynamically selecting language code and than to create new language mutation, just create new dictionary. No recompilation, no server restart.

On top of that, dictionaries gained the possibility to control Teng configuration. Once more no recompilation, no server restart. And it can even configure things, that can be otherwise configured only by modifying source and recompilation of Teng library and APIs, or can’t be configure otherwise at all.

If there are both language dependent and language independent dictionaries specified, language dependent dictionary fields overrides language independent dictionary fields.

With Teng dictionaries, it’s easy and fast to create dynamic content, multilingual pages, and debug your templates.

Each dictionary line begins with either identifier or a command, separeted by space from other content. Identifier must be unqualified.

Commands begin with ‘%’ sign and are used to modify Teng configuration. Commands can be only in configuration (language independent) dictionary; commands in language dependent dictionary are ignored.

Identifiers begin with a letter or underscore. Everything after first space is taken as value of variable specified by the identifier.

house The United States House of Representatives
months |January|February|March|April|May|June|July|August|September|October|November|December|
%enable debug

%disable flag

Disables configuration flag ‘flag’. This command overrides configuration specified by calling application.

For list of available flags, see ‘%enable’.

%enable flag

Enables configuration flag ‘flag’. This command overrides configuration specified by calling application.

Following flags are defined:

%expand state

Enables or disables variable expansions inside dictionary, ie. replacing ‘#{identifier}’ by item from dictionary with identifier ‘identifier’.

‘state’ can be either ‘on’ or ‘off’.

Expansions are disabled by default.

%maxincludedepth limit

Modifies maximal include (‘nesting’) depth to ‘limit’.

This command is very useful when including many templates.

Formats ‘timestamp’ according to locale settings.

The following characters escaped by ‘%’ in ‘string’ are replaced:

Any other character escaped by ‘%’ among the ones above is print as unescaped.

	Warning
	Sun Solaris seems to start ‘%u’ from Sunday althrough ISO 9899:1999 (current ISO C standard) clearly specifies that is should be Monday.

‘setup’ can specify month and weekday names in this format:

|January|February|…|December|Jan|Feb|…|Dec|Sunday|Monday|…|Saturday|Sun|Mon|…|Sat|

If this argument is not set or the name was not found (there are not enough fields), default as specified by locale is used.

Because ‘timestamp’ is integer, its value can be negative (therefore it can provide dates before UNIX epoch); however on some platforms (at least Microsoft Windows and some old Unices) built-in formating functions do not support this.

${date("%a %b %d %T %Y", now())}

Wed Jun 28 19:06:52 2006

Escapes ‘string’ according to current content type.

This function‘s inverse function is ‘unescape’ function.

${escape("<?teng")}

<?teng

Returns ‘number’ with chopped decimal values.

If you want to round numeric, see round.

${int("12" ++ "3.6") + 4}
${round("12" ++ "3.6", 0) + 4}
${int(round("12" ++ "3.6", 0)) + 4}

127
128.0
128

Returns 1 if ‘value’ is numeric; otherwise returns 0.

${isnumber("12")}
${isnumber(12)}

0
1

Returns length of ‘string’ in characters.

${len("12")}
${len(12)}

2
2

Inserts ‘<br />’ after each occurence of line feed character (UNIX and POSIX line break) in ‘string’.

Because DOS and Microsoft Windows uses carriage return and line feed character pair for line breaking, this function is also DOS and Microsoft Windows compatible. This is also the reason why ‘<br />’ is inserted after line feed character rather than before.

	Warning
	Because operating systems from Apple Computers through MacOS 9 and Commodores uses carriage return character for line breaking, this function won’t work as expected on these platforms. Use function ‘replace’ to replace carriage return characters by line feed characters.

${nl2br("a\nb")}

a
<br />b

Returns current time stamp with precission of microsecond.

For example see example of function ‘date’.

Formats numeric using ‘decimal’ as decimal and ‘thousand’ as thousand separator. Numeric is rounded to precision of ‘precision’.

${numformat("12345.67", 1, ".", ",")}
${numformat(12345.67, 0) == int(12345.67)}

12,345.7
0

Returns random integer from interval <0, ‘number’).

Returns string with numbers escaped by ‘%’ replaced by number^th parameter.

Each escaped number can be used more than once. There can also be some numbers ommited.

If there are not enough parameters, an error is raised and all escaped numbers without corresponding parameters are left.

	Warning
	If there are too many parameters, all escaped numbers are replaced and no error is raised, so if ‘reorder’ function does not what you expect, check whether all parameters are used.

${reorder("%2;%3;%1", 1, 2, 3)}
${reorder("%2;%1", 1)}
${reorder("%3;%1;%3", 1, 2, 3)}

2;3;1
%2;1
3;1;3

Runtime: reorder(): invalid or missing index in format '%2'. @ 2:22
Runtime: Function 'reorder()' call failed @ 2:22

Returns ‘text’ with all occurences of ‘out’ replaced with ‘in’.

	Important
	This function is available since version 1.0.13 of Teng library.

${replace("aoutboutcdeoutfg", "out", "in")}

ainbincdeinfg

Returns ‘number’ rounded to precision of ‘precision’.

If you want to floor the number, see function ‘int’.

For example see example of function ‘int’.

Takes ‘number’ as seconds and returns ‘H:MM:SS’ formated string.

	Note
	This function was originally called ‘sec_to_time’. Althrough this name of this function still exists, it is deprecated and you should not use it.

${sectotime(123)}
${sectotime(123456789)}

0:02:03
34293:33:09

Returns substring of string ‘text’ beginning after ‘from’^th and ending with ‘to’^th character.

If ‘from’ or ‘to’ are negative, they choose -‘from’^th, resp. -‘to’^th character from the end of the ‘text’.

If the character specified by ‘to’ is before or the same character as specified by ‘from’, returns an empty string.

Appends ‘suffix’ at the end of the substring.

If ‘from’ does not choose first character, prepends ‘prefix’ at the beginning of the substring.

If you want to cut substring at whole worlds, see function ‘wordsubstr’.

	Warning
	Compared to C++’s and PHP’s ‘substr’ functions, this function does not take length of substring as its third argument and has this argument required.

${substr("abcdef", -5, 5, "gh", "ij")}
${substr(123456, 0, -1, "gh", "ij")}
${substr("abcdef", 1, 0, "gh", "ij")}

ghbcdeij
12345ij
ghij

Replaces escape characters from ‘string’ with their values according to current content type.

This function is an inverse function of ‘escape’ function.

${unescape("<?teng")}

<?teng

Escapes ‘string’ according to RFC 1738, so it can be used in URL.

${urlescape("<?teng")}

%3C%3Fteng

Returns substring of string ‘text’ beginning after ‘from’^th and ending with ‘to’^th character. Leading and tailing whitespaces are removed. Incomplete words are completed.

	Note
	This function was originally called ‘substr_word’. Althrough this name of this function still exists, it is deprecated and you should not use it.

Basic whitespaces (space, tab, carriage return, and line feed characters) are recognized as word delimiters. A word must have at least one non-whitespace character.

If ‘from’ or ‘to’ are negative, they choose -‘from’^th, resp. -‘to’^th character from the end of the ‘text’.

If the character specified by ‘to’ is before or the same character as specified by ‘from’, returns an empty string.

Appends ‘suffix’ at the end of the substring.

If ‘from’ does not choose first character, prepends ‘prefix’ at the beginning of the substring.

This function is quite similar to function ‘substr’.

${wordsubstr("abc def", 0, 5)}
"${wordsubstr("   abc   def   ", 1, -1)}"

abc def
"abc   def"

To use Teng C++ API, you need woking POSIX-compatible C++ compiler compliant to ISO 14882:1998 (ISO C++) with STL. Moreover you need to build the Teng library.

The following compilers are known to work correctly:

	Note
	This library might work in Microsoft Windows under Cygwin or Mingw32, althrough this was never tested.

To build Teng library you need woking POSIX-compatible C++ compiler compliant to ISO 14882:1998 (ISO C++) with STL, Bourne-compatible shell and POSIX-compatible make.

Follow this procedure to build Teng library and prepare Teng C++ API on your system:

To compile programs using Teng C++ API, follow the following procedure:

class Teng::FileWriter_t: public Teng::Writer_t {
  public FileWriter_t(const std::string & filename);
  public FileWriter_t(FILE * file);
  public virtual ~FileWriter_t();
  public virtual int write(const std::string & str);
  public virtual int write(const char * str);
  public virtual int write(const std::string & str, std::pair<std::string::const_iterator, std::string::const_iterator> interval);
  public virtual int flush();
}

Creates new ‘Teng::FileWriter_t’ instance. It can use either a filename ‘filename’ or an opened file ‘file’.

If the file is invalid or cannot be opened, an error is written to log and ‘write’ and ‘flush’ methods will return non-zero error code.

	Warning
	The second version of this method does not check whether the opened file is opened for writing. However this will cause an error when calling the ’write‘ method.

Destroys ‘Teng::FileWriter_t’ instance. The output buffer is flushed and the file is closed if this instance was created by the first variant of constructor.

Writes to the output file.

If the third version is called, the part of the string that is bounded by the iterators pair is written to output file.

Returns zero if no error, otherwise returns non-zero error code.

When the constructor either failed to open the output file or got an invalid file handler, an error occures every time this function is called.

Flushes the output buffer.

Returns zero if no error, otherwise returns non-zero error code.

When the constructor either failed to open the output file or got an invalid file handler, an error occures every time this function is called.

class Teng::Fragment_t: public std::map<std::string, Teng::FragmentValue_t *> {
  public Fragment_t();
  public ~Fragment_t();
  public void addVariable(const std::string & name, const std::string & value);
  public void addVariable(const std::string & name, const long int value);
  public void addVariable(const std::string & name, const double value);
  public Teng::Fragment_t & addFragment(const std::string & name);
  public Teng::FragmentList_t & addFragmentList(const std::string & name);
}

Creates new empty fragment.

Destroys fragment and all of its entries.

Adds new variable ‘name’ with value ‘value’.

Creates new fragment in ‘Teng::FragmentList_t’ ‘name’. If this ‘Teng::FragmentList_t’ does not exist, it is created. If a value with name ‘name’ already exists, it’s changed to ‘Teng::FragmentList_t’.

Creates new empty ‘Teng::FragmentList_t’ name and returns reference to it. If ‘Teng::FragmentList_t’ ‘name’ already exists, it’s returned the existing one instead of creating a new one. If a value with name ‘name’ already exists, it’s changed to ‘Teng::FragmentList_t’.

class Teng::FragmentList_t: public std::vector<Teng::Fragment_t *> {
  public FragmentList_t();
  public ~FragmentList_t();
  public Teng::Fragment_t & addFragment();
}

Creates new empty fragment list.

Destroys fragment list and all of its fragments.

Adds new empty ‘Teng::Fragment_t’ and returns reference to it.

class Teng::FragmentValue_t {
  public FragmentValue_t();
  public FragmentValue_t(const std::string & value);
  public FragmentValue_t(long int value);
  public FragmentValue_t(double value);
  public ~FragmentValue_t();
  public Teng::Fragment_t & addFragment();
  public std::string value;
  public Teng::FragmentList_t * nestedFragments;
}

Creates new fragment value; either empty or with given ‘value’. It is converted to ‘std::string’ if not ‘std::string’.

Destroys fragment value. If ‘nestedFragments’ is non-zero, destroys it.

Adds new ‘Teng::Fragment_t’ to ‘nestedFragments’. If ‘nestedFragments’ is zero, it is created and value type of this ‘Teng::FragmentValue_t’ instance is changed.

If ‘nestedFragments’ is zero, value of this ‘Teng::FragmentValue_t’ instance; non-sense otherwise.

If non-zero, pointer to ‘Teng::FragmentList_t’.

class Teng::StringWriter_t: public Teng::Writer_t {
  public StringWriter_t(std::string & str);
  public virtual int write(const std::string & str);
  public virtual int write(const char * str);
  public virtual int write(const std::string & str, std::pair<std::string::const_iterator, std::string::const_iterator> interval);
  public virtual inline int flush();
}

Creates new ‘Teng::StringWriter_t’ instance. The output will be written to string ‘str’.

Writes to the output string.

If the third version is called, the part of the string that is bounded by the iterators pair is written to output string.

Returns zero.

Does nothing and returns zero.

class Teng::Teng_t {
  public Teng_t(const std::string & root, int logMode= 0, bool validate= false);
  public ~Teng_t();
  public int generatePage(const std::string & templateFilename, const std::string & skin, const std::string & dataDefinition, const std::string & dictionary, const std::string & language, const std::string & configuration, const std::string & contentType, const std::string & encoding, const TengFragment_t & date, const TengWriter_t & writer, const Teng::Error_t & err);
  public int generatePage(const std::string & templateString, const std::string & dataDefinition, const std::string & dictionary, const std::string & language, const std::string & param, const std::string & contentType, const std::string & encoding, const TengFragment_t & date, const Teng::Writer_t & writer, const Teng::Error_t & err);
  public int dictionaryLookup(const std::string & dictionary, const std::string & language, const std::string & key, std::string & value);
  static voidlistSupportedContentTypes(std::vector<std::pair<std::string, std::string> > & supported);
}

Creates new Teng engine with its own template and directory cache.

Launches page generation. First all dictionaries are read and parsed, then all templates are read, parsed and comipled, and finally the generated bytecode is executed.

If there is aleready a bytecode for the template, it is only checked whether the bytecode is fresh enough (ie. bytecode generation time is greater than template last modification time). This is performed only when executing template from external file.

Returns the highest level of encountered errors or zero if no errors.

Search dictionary ‘dict’ of language ‘language’ for an entry with key ‘key’. The same progress as for ‘dictionary’ and ‘language’ pair in ‘Teng_t::Teng_t::generatePage’ are applied.

Returns zero if the entry was found, non-zero number otherwise.

If returned zero, ‘value’ will contain value of the entry.

Returns a list of supported content types in format ‘std::pair(content_type, comment)’.

class Teng::Writer_t {
  public inline Writer_t();
  public inline virtual ~Writer_t();
  public virtual int write(const std::string & str);
  public virtual int write(const char * str);
  public virtual int write(const std::string & str, std::pair<std::string::const_iterator, std::string::const_iterator> interval);
  public virtual int flush();
  public const const Teng::Error_t & getErrors();
  protected Teng::Error_t err;
}

This class is virtual; for practical use either derive this class or use ‘Teng::FileWriter_t’ or ‘Teng::StringWriter_t’.

Creates new ‘Teng::Writer_t’ instance. The derived class should open the output if this is necessary.

	Note
	This method should not raise an exception; it should add an error to its error log instead and return non-zero error code when calling ‘write’ or ‘flush’ methods.

Destroys ‘Teng::Writer_t’ instance. The derived class should call ‘flush’ method and close the output if this is necessary.

Pure virtual methods for writing to output.

If the third version is called, the derived class should write to output the part of the string ‘str’ that is bounded by the iterators pair ‘interval’.

Returns zero if no error, otherwise returns non-zero error code.

Pure virtual method for flushing the output buffer.

If there is no output buffer, the derived class should define flush as inline and with no effect.

Returns zero if no error, otherwise returns non-zero error code.

Returns writing error log.

This function is used when ‘write’ or ‘flush’ returns non-zero error code.

Protected error log; it is returned as constant by ‘getErrors’ method.

This is a simple Teng C++ API example:

#include <teng.h>

#include <stdio.h>
#include <string>

int main(int argc, char * argv[]) {
    static std::string characters[2] = { "A", "B" };

    // Define some template
    std::string templ = "<html>\n\
    <head>\n\
        <title>Example page</title>\n\
    </head>\n\
    <body>\n\
        <?teng frag row?><p>${rnum}\n\
            <?teng frag col?>${cnum} <?teng endfrag?>\n\
        </p><?teng endfrag?>\n\
    </body>\n\
</html>\n";

    // Create Teng engine
    Teng::Teng_t teng("", Teng::Teng_t::LM_LOG_TO_OUTPUT);

    // Root data fragment
    Teng::Fragment_t root;

    // Rows fragment list
    Teng::FragmentList_t &rowList = root.addFragmentList("row");

    // Create two rows
    for(int i = 0; i < 2; i++) {
        Teng::Fragment_t &row = rowList.addFragment();
        // Add variable ‘rnum’ (‘A’ or ‘B’)
        row.addVariable("rnum", characters[i]);
        // Create two columns
        for(int j = 1; j <= 2; j++) {
            Teng::Fragment_t &col = row.addFragment("col");
            // Add variable ‘cnum’ into ‘row’ (‘1’ or ‘2’)
            col.addVariable("cnum", (long int)j);
        }
    }

    // Output to standard output
    Teng::FileWriter_t writer(stdout);

    // Simple error log
    Teng::Error_t err;

    // Generate page
    return teng.generatePage(
        templ, // Template
        "", // Dictionary (none)
        "", // Language (none)
        "", // Configuration (none)
        "text/html", // Content type
        "utf-8", // Encoding
        root, // Root fragment
        writer, // Writer
        err // Error log
    );
}

<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <p>A
            1 2 3
        </p><p>B
            1 2 3
        </p>
    </body>
</html>

To use Teng Python API, you need Python version at least 1.5. Python version at least 2.2 is strongly encouraged. Moreover you need to build and install the Teng Python module.

To build Teng Python module, you need woking POSIX-compatible C++ compiler compliant to ISO 14882:1998 (ISO C++) with STL, Bourne-compatible shell, POSIX-compatible make, and at least one of supported versions of Python with Distutils modules (see Requirements).

Follow this procedure to build Teng Python module:

You can use either Python’s built-in objects or Teng native data object to specify data for Teng engine. However, you cannot mix them together.

When using Python’s built-in objects, the following rules is used:

When using Teng native data object, the data are mapped as instances of object ‘Fragment’ in Teng Python module. The usage of object ‘Fragment’ is very similar to usage of C++ API’s ‘Teng::Fragment_t’ class.

	Warning
	When using Teng native data object, there is a behaviour that violates Python conventions: deletion of root fragment deletes internal tree and invalidates all subnodes pointing to this tree and such subnodes cannot be used any more. However, deletion of non-root fragment doesn’t violate the convetions.

Creates new Teng engine. Call it using:

engine = teng.Teng(…)

This method is encapsulation of C++ API’s ‘Teng::Teng_t’ class constructor.

Creates ‘teng.Fragment’ instance for data root. Call it using:

engine.createDataRoot(…)

Creates new ‘teng.Fragment’, populates it with data ‘data’, appends it to ‘self’, and finally returns it. Call it using:

fragment.addFragment(…)

This method is encapsulation of C++ API’s ‘Teng::FragmentList_t::addFragment’ method.

Generate a page. Call it using:

engine.generatePage(…)

This method is encapsulation of C++ API’s ‘Teng::Teng_t::generatePage’ method.

Either ‘templateFilename’ or ‘templateString’ is required. If none is specified, an exception is raised.

Returned ‘dict’ object instance has the following values:

Search dictionary dictionaryFilename of language language for an entry with key key. Call it using:

engine.dictionaryLookup(…)

This method is encapsulation of C++ API’s ‘Teng::Teng_t::dictionaryLookup’ method.

Returns ‘None’ if specified key does not exist in specified dictionary.

There are numerous ways to produce the reference example outputusing Teng Python module. Two significantly different options exist.

The first approach uses Python built-in objects to pass a data tree from a Python script to Teng.

#!/usr/bin/python
import teng

# Initialize Teng engine using default values
engine = teng.Teng()

# Create some data
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)

# Define some template
template = '''<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <?teng frag row?><p>${rnum}
            <?teng frag col?>${cnum} <?teng endfrag?>
        </p><?teng endfrag?>
    </body>
</html>''';

# Generate page
print engine.generatePage(
    templateString = template,
    data = data,
    contentType = 'text/html',
    encoding = 'utf-8')['output']

# Delete Teng engine
del engine

<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <p>A
            0 1
        </p><p>B
            0 1
        </p>
    </body>
</html>

A different approach uses Teng native object to build the data tree:

#!/usr/bin/python
import teng

# Initialize Teng engine using default values
engine = teng.Teng()
data = engine.createDataRoot({})

for i in range(ord('A'), ord('C')):
    row = data.addFragment('row', {'rnum' : chr(i)})
    for j in range(0, 2):
        row.addFragment('col', {'cnum' : j})

# Define some template
template = '''<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <?teng frag row?><p>${rnum}
            <?teng frag col?>${cnum} <?teng endfrag?>
        </p><?teng endfrag?>
    </body>
</html>''';

# Generate page
print engine.generatePage(
    templateString = template,
    data = data,
    contentType = 'text/html',
    encoding = 'utf-8')['output']

# Delete Teng data and engine
del data
del engine

<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <p>A
            0 1
        </p><p>B
            0 1
        </p>
    </body>
</html>

To use Teng PHP extension, you need PHP4. Using at least version 4.1 is strongly encouraged. Moreover you need to build and install the Teng PHP extension.

To build Teng PHP extension, you need woking POSIX-compatible C++ compiler compliant to ISO 14882:1998 (ISO C++) with STL, Bourne-compatible shell, POSIX-compatible make, and headers of PHP4 (see ‘Requirements’).

Follow this procedure to build Teng PHP extension:

Teng PHP extension can be configured using the following directives:

Table 3. PHP API configuration directives

Directive	Default	Changeable	Description
teng.template_root	NULL	PHP_INI_ALL	Defines the default root path used to access Teng templates and dictionaries.
teng.default_dict	NULL	PHP_INI_ALL	Sets the path to default language dictionary.
teng.default_lang	NULL	PHP_INI_ALL	Sets the default language.
teng.default_config	NULL	PHP_INI_ALL	Sets the path to default template configuration.
teng.default_content_type	’text/html‘	PHP_INI_ALL	Sets the default content type. See the Teng section in ‘phpinfo’ output, or the output of ‘teng_list_content_types’ for suported content types.
teng.default_encoding	‘utf-8’	PHP_INI_ALL	Sets the default document encoding. Can be any encoding supported on your system.
teng.validation	’Off‘	PHP_INI_ALL	This boolean flag indicates whether Teng should perform template and application data validation. Important Data definition has been deprecated and is ignored.
teng.log_to_output	‘Off’	PHP_INI_ALL	If this boolean flag is set, teng logs parsing and runtime errors into content-type dependant comments on the output page.
teng.error_fragment	‘Off’	PHP_INI_ALL	If this boolean flag is set, a fragment called ‘._error’ is created containing all errors.
teng.default_skin	NULL	PHP_INI_ALL	Sets the default template skin. Important For HTML, XHTML, and XML, skinning is deprecated by CSS and XSLT.

There are two types provided by the Teng extension.

The first type is the engine itself. This type instances are persistant and reuseable, ie. when ‘teng_init’ is invoked and there already was created a Teng engine with the same ‘template_root’ argument, it is reused. Instances of this type are freed when the Teng PHP module in unloaded, therefore using the ‘dl’ function for loading the Teng PHP extension causes significant performace decrease.

The second type is a fragment. Every fragment function is fully reentrant, ie. there can be multiple data trees in your scripts. Each fragment instance is discarded at the end of your script’s execution along with all data it carries.

Returns a new Teng engine resource pointing to new Teng engine instance.

‘$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 engine instances are persistent and reuseable. If a Teng engine resource with given ‘$template_root’ was allocated before, this function returns a resource pointing to that instance. This allows the application to seamlessly cache templates and dictionaries across multiple HTTP requests and significantly increases performance.

Releases Teng engine resource ‘$teng’ that was previously created via ‘teng_init’.

This does not destroy the Teng engine instance this resource is pointing at.

Calling this function is not necessary but a good practice.

Allocates and initializes a 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. This array may include nests of associative arrays that will be translated into fragment nests; however use rather ‘teng_add_fragment’ function. Every element with non-associative (ie. integer) key is silently ignored. If ‘$data’ is not provided, the root fragment is created empty.

Removes the data tree pointed by ‘$root’ allocated by ‘teng_create_data_root’ from memory, clears all nested fragments, and invalides all corresponding fragment resources.

Calling this function is not necessary but a good practice.

Appends a nested fragment into fragment pointed by ‘$parent’ and returns a new fragment resource pointing on the enwly created fragment.

‘$name’ is a name for the newly created nested fragment. If there is no fragment nest with name ‘$name’ in the fragment pointed by ‘$parent’, an empty fragment nest with name ‘$name’ is created before.

‘$data’ is an associative array with the content of data tree’s root fragment. This array may include nests of associative arrays that will be translated into fragment nests; however use rather ‘teng_add_fragment’ function. Every element with non-associative (ie. integer) key is silently ignored. If ‘$data’ is not provided, the root fragment is created empty.

Invokes Teng engine pointed by ‘$teng’ to generate a page from template file ‘$template_path’ and returns the result as a string.

‘$data’ is either an associative array or a Teng root fragment resource created by ‘teng_create_data_root’. It holds the entire data tree. If this variable is an array, ‘teng_create_data_root’ is called before proceeding.

‘$options’ is an optional associative array holding options modifying Teng engine’s behavior in the process of page generation. Any number of options can be provided. Unknown and unexpected options are silently ignored.

The following options are recognized:

Errors during page generation are logged into PHP error output.

Invokes Teng engine pointed by ‘$teng’ to generate a page from template string ‘$template’ and returns the result as a string.

‘$data’ is either an associative array or a Teng root fragment resource created by ‘teng_create_data_root’. It holds the entire data tree. If this variable is an array, ’teng_create_data_root’ is called before proceeding.

‘$options’ is an optional associative array holding options modifying Teng engine’s behavior in the process of page generation. Any number of options can be provided. Unknown and unexpected options are silently ignored.

The following options are recognized:

Errors during page generation are logged into PHP error output.

Looks up the dictionary ’$dict’ for language ‘$lang’ for a literal with key ‘$key’ using Teng engine pointed by ‘$teng’ and returns its value; returns FALSE if not found.

If ‘$dict’ and/or ‘$lang’ is not supplied, it is used the value supplied in configuration.

Returns an array where every key represents supported content type and every value its brief description.

There are numerous ways to produce the reference example outputusing Teng PHP extension. Two significantly different options exist.

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

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

// Sample template
$template = "<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <?teng frag row?><p>\${rnum}
            <?teng frag col?>\${cnum} <?teng endfrag?>
        </p><?teng endfrag?>
    </body>
</html>";

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

// Generate page
echo teng_page_string_from_string(
    $teng,
    $template,
    $data,
    array(
        "content-type" => "text/html",
        "encoding" => "utf-8"
    )
);

// Release Teng engine
teng_release($teng);
?>

<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <p>A
            0 1
        </p><p>B
            0 1
        </p>
    </body>
</html>

A different approach uses Teng native types to build the data tree:

	Tip
	This approach is preferred.

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

// Sample template
$template = "<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <?teng frag row?><p>\${rnum}
            <?teng frag col?>\${cnum} <?teng endfrag?>
        </p><?teng endfrag?>
    </body>
</html>";

// Build data tree
$data = teng_create_data_root();
for($i = 'A'; $i < 'C'; $i++) {
    $row = teng_add_fragment($data, "row", array("rnum" => $i));
    for($j = 0; $j < 2; $j++)
        teng_add_fragment($row, "col", array("cnum" => $j));
}

// Generate page
echo teng_page_string_from_string(
    $teng,
    $template,
    $data,
    array(
        "content-type" => "text/html",
        "encoding" => "utf-8"
    )
);

// Release root fragment
teng_release_data($data);

// Release Teng engine
teng_release($teng);
?>

<html>
    <head>
        <title>Example page</title>
    </head>
    <body>
        <p>A
            0 1
        </p><p>B
            0 1
        </p>
    </body>
</html>