evoque

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.