Michael Heilmann's Arcadia Template Engine

This is the documentation for Michael Heilmann's Arcadia Template Engine. The Template Engine is a template engine primarily used to generate websites.

Invoking the Template Engine from the command line

The Template Engine can be invoked by the following command (assuming the executable Arcadia.TemplateEngine is in your path).

Arcadia.TemplateEngine source file target file environment file

where

source file is the path to the source file (relative to the working directory).

target file is the path to the target file (relative to the working directory).

environment file is the path to the environment file (relative to the working directory).

The source file is an UTF-8 encoded text file which is an input to this template engine invocation. The contents of this file are evaluated by the template engine and the evaluation result is written to the target file.

The target file is an UTF-8 encoded text file which is an output of this template engine invocation. If the file exists and is a regular file, its contents are overwritten. If the file exists and is not a regular file or the path to the file does not exist, then this template engine invocation fails.

The environment file is an Data Definition Language file which must consist of a single value of type Map. The values of the map element values of this map value must be of type String. These map values represent variables which can be used in the template directives (see Template Language of this template engine invocation. Note: Definitions in this environment file shadow definitions of default variables and default procedures.

The Template Language

A program of the Template Language consists of texts in which directives are embedded into. text is a sequence of UTF8 symbols excluding the ampersand symbol. An directive begins with an ampersand. The extend (in UTF8 symbols) of an directive is determined by the directive itself. text is written directly to the output. directives are not written to the output. Instead, they are evaluated and the evaluation result is written to the output. There are two major categories of directives, the ampersand directive and the expression directives.

Remark for this version: In future version of the Template Language, there will be directives (e.g., loop operators) working on text. Consequently, the statement that text is written directly to the output will be revised.

Remark for this version: There will be a new category of directovies in future versions of the Template Language called statement directives. They will allow for defining new variables and (bounded) loops over text and directives. Consequently, the statement that there are two major categories of directives will be revised.

Ampersand Directive

The ampersand directive is of the form @@ and is used output a single ampersand.

Expression Directive

Expression directives start with an ampersand @ followed by curly bracket { followed by a name. Optionally, the name is followed by an argument list which is opened by a left parenthesis ( and closed by a right parenthesis ). The parentheses enclosed zero or more literals separated by commas ,. Expressions without an argument list are variable load expression, expressions with an argument list are invocation expressions.

Variable load expression search first the environment defined by the environment file and then the default environment for definitions of the name. If it discovers are a variable definition, it will emit the value of the variable to the output. The processing stops with an error if a definition for a procedure was found or no definition was found at all.

Invocation expression search first the environment defined by the environment file and then the default environment for definitions of the name. If it discovers a procedure definition, it will invoke that procedure with the specified arguments and write the return value of the procedure to the output. The processing stops with an error if a definition for a variable procedure was found or no definition was found at all.

Remark for this version: Currently, it is not possible to specify procedures. Consequently, all procedures available are defined in the default environment. However, if a variable is defined in the environment file with a name used by a procedure in the default environment, then an invocation expression of that name will discover the variable and not the procedure causing the processing to stop with an error.

The following invocation expression directives are known:

Name	Description
include	Defined in the default environment. Expects a string as its single argument which denotes the path to a file relative to the working directory. The file contents are processed by and the result is written to the output. Recursive includes (direct or indirect) are an error.
dayOfMonth	Defined in the default environment. Expects zero arguments. Outputs the day of the month of "now", that is, an integer in the interval [1,31] without leading zeroes.
month	Defined in the default environment. Expects zero arguments. Outputs the month of the year of "now", that is, an integer in the interval [1,12] without leading zeroes.
monthName	Defined in the default environment. Expects zero arguments. Outputs the English name of the month of the year of "now" (e.g., "January" or "October" without the quotes).
year	Defined in the default environ,ent. Expects zero arguments. Outputs the year of "now" (e.g., 2025).