root/tlate/TemplateLanguage.txt

                         Template data model
                         -------------------

A template is always interpreted in the context of a data model,
provided by the part of Alue that is using the template.

A data model consists of a set of ATTRIBUTES.  An attribute has a name
(which follows the lexical syntax of an identifier, as specified
below) and a value.

There are several kinds of attribute values:

  – literal strings

  - a list of values

  - a structured value, which is simply a data (sub)model

  - a definition closure (described later)

An attribute value may also be specifically missing.

Typically, the part of Alue that uses the template defines a data
model schema, which describes the names and value kinds (including the
schemas of any submodels) of attributes.


                        Lexical considerations
                        ----------------------

The template language is modeful.  The two modes are LITERAL and
DIRECTIVE.  All template files start in the LITERAL mode.

In either mode, the dollar sign ($) may be used to switch modes.

In either mode, a hash sign (#) starts a comment that extends to the
end of the line.  The end-of-line is considered a part of the comment.

In LITERAL mode, most characters (including whitespace) stand for
themselves and are copied verbatim to the output.  The exceptions are
the curly brackets ({}), which are used for grouping, and the
mode-switching dollar sign.

In the DIRECTIVE mode, input is tokenized in the manner customary for
computer languages:

  - Whitespace is ignored, except so far as it is used to separate tokens.

  - Punctuation tokens are the ordinary parentheses (()), and the comma (,).

  – Names are nonempty sequences of the ASCII letters ('a' to 'z' in
    either case), ASCII decimal digits ('0' to '9'), the dash (-), the
    period (.) and the underscore (_).

  – The following names are reserved for use as syntactic keywords:
    def, else, for, if, in, include.  Other names are called
    identifiers.


                           Template syntax
                           ---------------

Curly brackets (in LITERAL mode) are used to delimit a TEMPLATE LIST.
A template list consists of literal text and directives.  When
occurring alone, a template list is processed as if the surrounding
curly brackets were missing, but in certain directives a template list
is saved (uninterpreted) for later use.

An ATTRIBUTE REFERENCE consists of an identifier by itself.  Since
identifiers are only recognized in DIRECTIVE mode, an attribute
reference is most commonly surrounded by dollar signs ($foo$).  If the
value of the attribute is a literal string, that string is outputted.

  For example, if there is an attribute called "foo" whose value is
  the literal string "cat", then $foo$ will output "cat".

A LIST ITERATION consists of an identifier followed by a template
list.  If the value of the attribute is a list (or a structured value,
which is treated as a one-element list), then the template list will
be interpreted once for each element of the value list.  The element
will be accessible inside the template list as the attribute named
"cursor", and if the element is a structured value, all its attributes
are also available inside the list.

  For example, if the attribute called "nephews" contains as its value
  a list of the literal strings "Huey", "Dewey", and "Louie", then
  $nephews${$cursor$! } will output "Huey! Dewey! Louie! ".  Note that
  there must be no whitespace in the "${" pair.

A CONDITIONAL consists of the keyword "if" followed by an identifier,
followed by a template list, and optionally followed by the keyword
"else" and another template list.  If the identifier names an
attribute that has a value, then the first template list is
interpreted.  if there is no attribute named by the identifier, the
the second template list (if any) is interpreted.

  For example, consider $if foo${yes}$else${no}$.  If there is an
  attribute called "foo", then "yes" is outputted; otherwise, "no" is
  outputted.

  Note that there must not be any spaces in the "${" and "}$" pairs.
  However, there may be whitespace between the dollar signs and the
  keywords (thus, "$ if" is allowed).

A DEFINITION consists of
    - the keyword "def", followed by
    - an identifier (the definee), followed by
    - an ordinary opening parenthesis "(", followed by
    - a comma-separated list of identifiers (the parameters), followed by
    - an ordinary closing parenthesis ")", followed by
    - a template list (the body).
The definition does not output anything.  However, the definee may
subsequently be used in an invocation, discussed below.  A definition
may be (and usually is) recursive.

An INVOCATION consists of
    - an identifier (the invokee), followed by
    - an ordinary opening parentesis "(", followed by
    - a comma-separated list of identifiers (the arguments), followed by
    - an ordinary closing parenthesis ")".
If there is no usable definee that matches the invokee, or the number
of parameters disagrees with the number of arguments, the invocation
outputs nothing.  Otherwise, the body of the corresponding definition
will be interpreted, with each parameter standing for the
corresponding argument.

  For example, consider the following template:
    $def twice(a)${$a$$a$} $twice(foo)$
  Now, if "foo" is an attribute having as its value the literal string
  "me", then this template outputs " meme".

  Note: as usual, the sequences "${" and "}$" may not contain any
  whitespace.  The one space before "meme" in the output results from
  the space separating the definition and the invocation (which is not
  mandatory by no means).