tema
 

Tema

Tema is a macro processor and a template engine. Features:

  • Database access.

Changes (full changelog)

(Mikhail Kryshen)
2009-11-11: Add TODO list. tip

Add TODO list.

(Mikhail Kryshen)
2009-11-11: Added tag release_0_3_1 for changeset 1664e621f636 tema-0.3

Added tag release_0_3_1 for changeset 1664e621f636

(Mikhail Kryshen)
2009-11-11: Release 0.3.1 tema-0.3 release_0_3_1

Release 0.3.1

(Mikhail Kryshen)
2009-11-10: Corrections in the manual. tema-0.3

Corrections in the manual.

Branches

(Mikhail Kryshen)
tema-0.3: Added tag release_0_3_1 for changeset 1664e621f636 2009-11-11

Added tag release_0_3_1 for changeset 1664e621f636

(Mikhail Kryshen)
default: Add TODO list. tip 2009-11-11

Add TODO list.

Tags

(Mikhail Kryshen)
release_0_3_1: Release 0.3.1 tema-0.3 2009-11-11

Release 0.3.1

(Mikhail Kryshen)
release_0_3: Tema 0.3 (imported from CVS). 2008-02-19

Tema 0.3 (imported from CVS).

(Mikhail Kryshen)
release_0_1jk: Tema 0.1jk - Javakonkurs edition (imported from CVS). 2006-12-14

Tema 0.1jk - Javakonkurs edition (imported from CVS).

(Mikhail Kryshen)
release_0_1: Tema 0.1 (imported from CVS). 2006-05-16

Tema 0.1 (imported from CVS).

Readme

Tema

Tema is a macro processor and a template engine. Features:

  • Database access.
  • Extensibility: implement new functions as Java classes.
  • 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 of the absolute values 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:

  • --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.