Mikhail Kryshen

Tema user manual

Introduction

Tema is a macro processor and template engine. It reads the input file recursively expanding any macro found in the text.

Distinctive features:

Tema macro has the following syntax:

<%function_list{:|#|\|`}[escape]text%>[escape]

function_list is the list of text-processing functions. Functions will be applied to text in reverse order.

text could contain space-separated list of arguments followed by arbitrary data. Number of arguments is determined by the last function in the function_list.

[arg1 arg2...] [data]

The text is separated from the list of functions by one of the following characters:

escape is either '\' or '\\':

You could use '[%' and '%]' character sequences to denote macro as an alternative to '<%' and '%>'.

Every function returns integer value. The general convention is to return non-zero for successful operation. The value of the macro substitution is the return value of the first function in the function list. The value of any Tema text is the sum value of all macro in the text, except the value of the text without any macro equals -1.

Internally, Tema function could be represented by any Java object. Instances of kryshen.tema.Function and kryshen.tema.Context are handled specially. For any other type of object, function output would be the value returned by the method toString().

Built-in functions

Notice: some functions are not yet described in this manual. For the complete list of built-in functions refer to the API documentation and source code.

tema
Output: Tema version
echo
Output: function data
!
Ignores the input text (':' separator works as '#'). Use for commenting (e.g. [%!\ comment %]).
Output: nothing
silent
Output: nothing
set
Defines new function as a static variable.
Arguments: definition name
Data: variable value
Output: function data
define
Defines new function. Use next_arg, data, and has_more_data functions to access function arguments.
Arguments: name
Data: code
Output: name
next_arg
Works in context of define function. Parses the next argument from the calling function input.
Output: next argument text
data
Works in context of define function. Outputs remaining text passed to the calling function.
Output: remaining text
has_more_data
Works in context of define function. Returns non-zero value if the calling function has more input data available.
export
Exports the definition to the global (outermost) context.
Arguments: definition name
Data: static variable value (optional)
Output: function data
unset
Unsets the definitions.
Arguments: def1, def2, ...
Output: nothing
invoke
Invokes function.
Arguments: function, arg1, arg2, ..., data
Output: function output
load
Instantiate specified class as a Tema function definition. URL arguments are optional.
Arguments: name, class, url1, url2, ...
Output: name
super
Evaluates the specified template code in the super-context (i.e. context of the calling function or context executing the database query).
Data: code
Output: output generated by the code
replace
Replaces all occurrences of s1 with s2 in data.
Arguments: s1, s2, data
xml_escape
Data: text
Output: text with escaped XML special characters
xml_cdata
Data: text
Output: XML CDATA section containing the text

Input / output

copy
Copies file src to dest.
Arguments: src, dest
Output: dest
write
Writes text to file.
Arguments: name
Data: text
Output: name
read
Reads file.
Arguments: name
Output: File contents.
include
Includes template.
Arguments: name
Output: Result of processing the template.
file
Arguments: base, name
Output: Path constructed from the base directory and file name.

Conditionals

optional
Data: text
Output: Function data if it's value is non-zero or empty text.
while
Repeatedly outputs it's evaluated data while parses with non-zero value.
Data: code
if
Outputs the input text if the condition parses with non-zero value.
Arguments: condition
Data: text

Database

db_connect
Establishes connection with the database. Load the appropriate database driver using the load function before using db_connect (e.g. <%load:driver sun.jdbc.odbc.JdbcOdbcDriver%>).
Arguments: connection name
Data: resource
db_prepare
Arguments: query name, connection name
Data: SQL statement
db_query
Executes query, evaluating the template for each result row.
Arguments: query, template, arg1, arg2, ...
db
Available in the template for the db_query function.
Data: column name
Output: value from the query result.
db_row
Available in the template for the db_query function.
Output: current row number in the result set.

Running Tema

Change to the dist subdirectory in the distribution package and issue the following command:

java -jar tema.jar [options] [files]

The following options are recognized: