Template syntax

definition: An evoque template is either
(a) a textual file or
(b) a string in memory or
(c) a begin/end delineated block in a textual file or a string,
each optionally containing additional evoque-specific markup.

Entire template syntax at a glance

Explanations

Expressions

Expressions have the form ${expr !format} where the “!format”
is optional, and defaults to “!s”, i.e. default string rendering. The possible
values for format are whatever is allowed by the
python’s
string formating operations.
The expr itself may be any valid python expression, that will be evaluated
within the passed context (that may optionally be restricted). For example, the
trivial template:

<p>${amount} ${amount!.2f}</p>

will produce the following output when rendered with
amount=1.0/3:

<p>0.333333333333 0.33</p>

Directives

Directives have the form $directive{expr}.
Syntactically they are same as an expression but have an additional
qualifying keyword
inserted between the $ and the opening {.
See dedicated discussion on directives in general and for each
directive in the directives section.

Literals: “$”, “{“, “}”, “!”, “\”

A literal “$” must always be escaped.
A single “$” always signals the beginning of a substitution or a directive,
e.g $expr has no specific meaning for Evoque and will
give a SyntaxError
(the “$” used to delineate any expanded svn keywords are exempted from this).
Should always use either $$expr or ${expr} instead,
depending on what is desired.

A literal “\” at end of a line slurps the newline character but
a literal “\” followed by white space (only) until the first newline
character is put out as is but without the white space, i.e.
"\   \n"
outputs
"\\n".

All other literals within the text are never escaped.

Within an expression it is sometimes necessary to use literal braces
e.g. to specify a dict value in place, such as key={"a":1},
or a literal piece of CSS such as "tag.class{display:inline}".
The alternative “{%” and “%}” expression delimeters are provided
to comfortably allow for this.

Whitespace

A “\” at end-of-line consumes the following newline, providing a basic
whitespace control. In addition to this, the
slurpy_directives=True on domain or on
each collection will
consume all (non-newline) leading and trailing whitespace
on the same line plus — only on the left side — the initial newline.

In addition, all leading or trailing whitespace
within expressions, i.e. between the curly braces,
even if multi-line, is always ignored.

Comments

Single or multi line comments are delineated with
#[ and ]#,
respectively. For the convenience of easily commenting out
a template section (even if that section itself already
contains comments) comments may be nested. This however
necessitates a minimum syntax to be respected, namely that
comment openings and closing are balanced.

Built-in callables

Any callable set on the evaluation context, either with
domain.set_on_globals() or by setting it on a
locals dict that is then passed as a parameter to
template.evoque(locals),
may be called as an expression, e.g.
${my_callable(params)}.
Evoque provides the following built-in callables.

inspect(output=True)

Pretty prints an overview of the evaluation namespace,
namely the context’s globals/locals and the template’s
expressions needing evaluation.
When output is set to False, the output is written
to domain.log.info() instead of rendered as
part of the template output.

The output of inspect() is of course escaped as per the
quoting setting of the template. However, templates should normally also
wrap this call into an appropriate markup container
e.g. wrap in a <div class="code"> element
if calling from an HTML context.

evoque(name, **kw)

This is perfectly equivalent to the directive form of
$evoque{name, **kw}.
The difference is that in the callable variation
it is possible to intercept the output and
process it further via any other callable —
but note that it is recommended that such
processing be specified via the filters
template parameter.