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, and all optionally containing additional evoque-specific markup.

Entire template syntax at a glance

Alternative delimeters

The delimeter pairs "{" and "}" or "{%" and "%}" are liberally interchangeable.

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:

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

Directives

Directives have the form $directive{expr}. Syntactically they are same as an expression with a 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 "\" followed by only white space until end-of-line is put out as is but without the trailing white space, i.e. "\ \n"` produces "\\n" but "\\n" produces "".

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 trailing whitespace after a directive.

In addition, all leading or trailing whitespace within expressions and directives, 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 with domain.set_on_globals() or with template.set_on_locals() may be called as an expression, e.g. ${my_callable(params)}. Evoque provides the following built-in callables.

inspect(output=False)

Pretty prints to the file stream domain.log, or if output=True to output, an overview of the evaluation namespace, namely the context's globals and the locals and the template's expressions needing evaluation.

evoque(name, **kw)

This is perfectly equivalent to the directive form of $evoque{name, **kw}. The difference is that in the callable variation:

• the name parameter must be quoted, meaning that if it is not then it is a variable that is to be evaluated at runtime;
• 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 parameter of templates.