Template Syntax

ENYAML templates are simply YAML documents. Control structures are marked up using YAML tags.

Note

The fully qualified tags begin with tag:enyaml.org,2022:, and can be aliased using the %TAG directive in your YAML documents. This can usually be omitted, however, because the TemplateLoader class aliases this prefix to ! by default.

A Simple Example

The following is a simple example template that uses the !$ tag to evaluate an expression:

!$ 1 + 1

When rendered, this template outputs:

2

The Context

Templates are rendered with a Context. The Context is a mapping of variable names to values. This allows you to provide variables to the template for rendering, and allows templates to read and set variables during rendering.

Setting Context Variables

You can set Context variables by defining a YAML mapping with the !set tag. These mapping nodes will not appear in the rendered output of the template. If a set node appears within a sequence or mapping, that item will be removed. The variables will be updated as this node is processed, so generally, expressions accessing these variables after the set node in the source template will see the updated values. For example:

- !set
  foo: 1
- !$ foo
- !set
  foo: 2
- !$ foo

Will render as:

- 1
- 2

Context variables persist across documents in a given template file. For example:

---
!set
foo: 1

---
- !$ foo

Will render as:

- 1

Expressions

As seen above, you can access Context variables using expression nodes. Expression nodes are represented by the !$ tag, and are replaced by the value of the expression.

Format String Expressions

Format string nodes are represented by the !$f tag.

Loops

Loops are made by the !for tag.

Conditionals

Conditionals are made by the !if tag.