135 lines
6.2 KiB
Markdown
135 lines
6.2 KiB
Markdown
---
|
|
title: "Templates"
|
|
permalink: /docs/templates
|
|
---
|
|
Templates are a special kind of [alternate](/docs/alternates) file. The template
|
|
content and host specific data are combined as input to a template processor
|
|
which produces a new file as its output.
|
|
|
|
This can be very useful if you need to vary a small part of a file, but it
|
|
doesn't support any kind of include directive.
|
|
|
|
## Template suffixes
|
|
|
|
To create a template, append an alternate suffix to the file name.
|
|
The suffix has the format:
|
|
|
|
##template.<template processor>
|
|
|
|
<sub><sup>
|
|
"template" can also be shortened to "t".
|
|
</sup></sub>
|
|
|
|
The supported template processors are:
|
|
|
|
| Processor | Suffixes | Dependencies |
|
|
| - | - | - |
|
|
| default | `##template`, `##template.default` | `awk` must be installed. (This should be installed on all *nix systems) |
|
|
| esh | `##template.esh` | `esh` must be installed. |
|
|
| j2cli | `##template.j2`, `##template.j2cli` | `j2cli` must be installed. |
|
|
| envtpl | `##template.j2`, `##template.envtpl` | `envtpl` must be installed. |
|
|
|
|
The processor can be omitted for "default".
|
|
Also, `j2` will be processed by either j2cli or envtpl, whichever is found.
|
|
|
|
## Exposed data
|
|
|
|
When template processors run, they will be provided the following set of data.
|
|
|
|
|
|
| Default (built-in) | Jinja or ESH | Description | Source |
|
|
| - | - | - | - |
|
|
| `yadm.arch` | `YADM_ARCH` | Architecture | <code>uname ‑m</code> |
|
|
| `yadm.class` | `YADM_CLASS` | Last defined class | <code>yadm config local.class</code> |
|
|
| `yadm.classes` | `YADM_CLASSES` | All classes | <code>yadm config ‑‑get‑all local.class</code> |
|
|
| `yadm.distro` | `YADM_DISTRO` | Distribution | <code>lsb_release ‑si</code><br/>or <code>/etc/os-release</code> |
|
|
| `yadm.distro_family` | `YADM_DISTRO_FAMILY` | Distribution Family | `ID_LIKE` from<code>/etc/os‑release</code> |
|
|
| `yadm.hostname` | `YADM_HOSTNAME` | Hostname | <code>uname ‑n</code> (without domain) |
|
|
| `yadm.os` | `YADM_OS` | Operating system | <code>uname ‑s</code> <sup>*</sup> |
|
|
| `yadm.source` | `YADM_SOURCE` | Template filename | (fully qualified path) |
|
|
| `yadm.user` | `YADM_USER` | Current user | <code>id ‑u ‑n</code> |
|
|
| `env.VAR` | | Env variables | Any VAR in the environment while yadm templates are processed |
|
|
|
|
<sub><sup>*
|
|
The OS for "Windows Subsystem for Linux" is reported as "WSL", even though uname identifies as "Linux".
|
|
<br/>
|
|
*
|
|
If `lsb_release` is not available, "distro" will be the ID specified in `/etc/os-release`.
|
|
</sup></sub>
|
|
|
|
## Supported template processors
|
|
|
|
default
|
|
: This built-in processor requires no additional software (assuming your distro
|
|
contains `awk`). This processor has a syntax _similar_ to the Jinja processors
|
|
below, however it only supports a small set of directives. Those directives are
|
|
detailed in the section below.
|
|
|
|
esh
|
|
: [esh][esh] is a template processor written in POSIX compliant shell. It allows
|
|
executing shell commands within templates. This can be used to reference
|
|
your own configurations within templates.
|
|
|
|
j2cli
|
|
: [j2cli][j2cli] (or `j2`) is a Python-based Jinja2 template processor. This
|
|
fully supports all directives of the [Jinja2 library][jinja]. When your template is
|
|
processed, the YADM_* values are provided to j2cli as environment variables.
|
|
|
|
envtpl
|
|
: [envtpl][envtpl] is another Python-based Jinja2 template processor. Online
|
|
comments suggest this software might not be maintained anymore.
|
|
|
|
## Built-in directives
|
|
yadm's "default" (built-in) template processor supports the following directives.
|
|
|
|
{% raw %}
|
|
variables
|
|
: Variables should be surrounded by `{{ }}`. It is fine for there to be
|
|
whitespace between the variable name and the double braces. The `{{` and
|
|
`}}` must be on the same line. For example:
|
|
|
|
```jinja
|
|
# WARNING: Do not edit this file.
|
|
# It was generated by processing {{ yadm.source }}
|
|
```
|
|
|
|
if-else-endif
|
|
: Entire blocks of content can be included or excluded based on the value of a
|
|
variable. Only equality can be tested. These blocks must start with
|
|
`{% if yadm.variable == "value" %}` and end with `{% endif %}`. An alternative
|
|
block can also be specified using the directive `{% else %}`. These directives
|
|
must appear on lines by themselves. They may not appear on the same line. The
|
|
"if" directive only supports testing a single variable, and there is no "elif"
|
|
directive as there is in Jinja.
|
|
<br><br>
|
|
If multiple classes are defined, `yadm.class=="someclass"` will be true if *any*
|
|
of the defined classes are "someclass".
|
|
<br><br>
|
|
Here is an example.
|
|
|
|
```jinja
|
|
{% if yadm.os == "Darwin" %}
|
|
This block is included for MacOS
|
|
{% else %}
|
|
This block is included for any other OS
|
|
{% endif %}
|
|
```
|
|
|
|
include
|
|
: Content can be included from external files using the
|
|
`{% include "filename" %}` syntax. The filename may include variables and
|
|
should be either a path relative to the current template or an absolute
|
|
path. The included file may itself also use variables, but if-else-endif or
|
|
include directives are not supported. An example:
|
|
|
|
```jinja
|
|
{% include "extra/config.{{ yadm.os }}" %}
|
|
```
|
|
|
|
{% endraw %}
|
|
|
|
[envtpl]: https://github.com/andreasjansson/envtpl
|
|
[esh]: https://github.com/jirutka/esh
|
|
[j2cli]: https://github.com/kolypto/j2cli
|
|
[jinja]: https://jinja.palletsprojects.com
|