Tema – template macro processor
Introduction
Tema is a macro processor and template engine. It reads the input file
recursively expanding any macro found in the text.
Distinctive features:
- Extensible: implement new functions as Java classes.
- Database access.
- Processes and outputs data as early as possible (function could start
to output data before all it's arguments are read and parsed).
- Apache Ant integration.
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:
- ':' – process text recursively.
- '#' – parse text but do not replace any embedded macro.
- '\', '`' – do not parse text (ignore any '<%' sequences).
escape
is either '\' or '\\':
- \ – the following newline symbol will be removed;
- \\ – the following sequence of the whitespace characters will be removed.
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, code
Output: name
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
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 it has non-zero value.
Data: code
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:
--demo
— run demo console with a code example;
-h, --help
— print help message;
--input-encoding <arg>
— set the input encoding;
--log <arg>
— log all error messages to the specified file;
-o, --output <arg>
— set the output file;
--output-encoding <arg>
— set the output encoding;
-v, --version
— print the version information and exit.
Homepage
http://kryshen.pp.ru/tema/