`template`

The uw mode for handling Jinja2 templates.

uw template --help

usage: uw template [-h] [--version] ACTION ...

Handle templates

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit

Positional arguments:
  ACTION
    render
      Render a template
    translate
      Translate atparse to Jinja2

`render`

uw template render --help

usage: uw template render [-h] [--version] [--input-file PATH]
                          [--output-file PATH] [--values-file PATH]
                          [--values-format {ini,nml,sh,yaml}] [--env]
                          [--search-path PATH[:PATH:...]] [--values-needed]
                          [--dry-run] [--quiet] [--verbose]
                          [KEY=VALUE ...]

Render a template

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit
  --input-file PATH, -i PATH
      Path to input file (default: read from stdin)
  --output-file PATH, -o PATH
      Path to output file (default: write to stdout)
  --values-file PATH
      Path to file providing override or interpolation values
  --values-format {ini,nml,sh,yaml}
      Values format
  --env
      Use environment variables
  --search-path PATH[:PATH:...]
      Colon-separated paths to search for extra templates
  --values-needed
      Print report of values needed to render template
  --dry-run
      Only log info, making no changes
  --quiet, -q
      Print no logging messages
  --verbose, -v
      Print all logging messages
  KEY=VALUE
      A key=value pair to override/supplement config

Examples

The examples in this section use a template file template with contents:

{{ greeting }}, {{ recipient }}!

and a YAML file called values.yaml with contents:

greeting: Hello
recipient: World

To show the values needed to render the template:

uw template render --input-file template --values-needed

[2025-01-02T03:04:05]     INFO Value(s) needed to render this template are:
[2025-01-02T03:04:05]     INFO   greeting
[2025-01-02T03:04:05]     INFO   recipient

To render the template to stdout:
```
uw template render --input-file template --values-file values.yaml
```
```
Hello, World!
```
Shell redirection may also be used to stream output to a file, another process, etc.

To render the template to a file via command-line argument:

rm -f rendered
uw template render --input-file template --values-file values.yaml --output-file rendered
cat rendered

Hello, World!

With the --dry-run flag specified, nothing is written to stdout (or to a file if --output-file is specified), but a report of what would have been written is logged to stderr:
```
uw template render --input-file template --values-file values.yaml --dry-run
```
```
[2025-01-02T03:04:05]     INFO Hello, World!
```

To read the template from stdin and render to stdout:

cat template | uw template render --values-file values.yaml

Hello, World!

If the values file has an unrecognized (or no) extension, uw will not know how to parse its contents:

uw template render --input-file template --values-file values.txt

Hello, World!

The format must be explicitly specified (here, values.txt is identical to values.yaml):

uw template render --input-file template --values-file values.txt --values-format yaml

Hello, World!

To request verbose log output:

uw template render --input-file template --values-file values.yaml --verbose

[2025-01-02T03:04:05]    DEBUG Command: uw template render --input-file template --values-file values.yaml --verbose
[2025-01-02T03:04:05]    DEBUG Internal arguments when rendering template:
[2025-01-02T03:04:05]    DEBUG ---------------------------------------------------------------------
[2025-01-02T03:04:05]    DEBUG       values_src: values.yaml
[2025-01-02T03:04:05]    DEBUG    values_format: yaml
[2025-01-02T03:04:05]    DEBUG       input_file: template
[2025-01-02T03:04:05]    DEBUG      output_file: None
[2025-01-02T03:04:05]    DEBUG        overrides: {}
[2025-01-02T03:04:05]    DEBUG              env: False
[2025-01-02T03:04:05]    DEBUG       searchpath: None
[2025-01-02T03:04:05]    DEBUG    values_needed: False
[2025-01-02T03:04:05]    DEBUG          dry_run: False
[2025-01-02T03:04:05]    DEBUG ---------------------------------------------------------------------
[2025-01-02T03:04:05]    DEBUG Read initial template values from values.yaml
Hello, World!

Note that uw logs to stderr. Use shell redirection as needed.

The following examples use the YAML file greeting.yaml with contents:

greeting: Hello

It is an error to render a template without providing all needed values.

uw template render --input-file template --values-file greeting.yaml

[2025-01-02T03:04:05]    ERROR Value(s) required to render template not provided:
[2025-01-02T03:04:05]    ERROR   recipient
[2025-01-02T03:04:05]    ERROR Template could not be rendered

Values may also be supplemented by key=value command-line arguments:

uw template render --input-file template --values-file greeting.yaml recipient=Reader

Hello, Reader!

The optional --env switch allows environment variables to be used to supply values:

recipient=You uw template render --input-file template --values-file greeting.yaml --env

Hello, You!

Values from key=value arguments override values from file, and environment variables override both:

recipient=Sunshine uw template render --input-file template --values-file greeting.yaml recipient=Reader greeting="Good day" --env

Good day, Sunshine!

Note that, in the previous two examples, the var=val syntax preceding the uw command is shell syntax for exporting environment variable var only for the duration of the command that follows. It should not be confused with the two key=value pairs later on the command line, which are arguments to uw.)

Jinja2 supports references to additional templates via, for example, import expressions, and uw provides support as follows:
1. By default, the directory containing the primary template file is used as the search path for additional templates.
2. The optional --search-path flag overrides the default search path with any number of explicitly specified, colon-separated paths.
For example, given file template-with-macros
```
{% import "macros" as m -%}
{{ m.double(11) }}
```
and file macros (in the same directory as template-with-macros)
```
{% macro double(n) -%}
{{ n * 2 }}
{%- endmacro %}
```
the template is rendered as
```
uw template render --input-file template-with-macros
```
```
22
```
The --search-path option can also be specified with a colon-separated set of directories to be searched for templates.

NB: Reading the primary template from stdin requires use of --search-path, as there is no implicit directory related to the input. For example, given the existence of directory macros-dir:
```
cat template-with-macros | uw template render --search-path macros-dir
```
```
22
```
Non-YAML-formatted files may also be used as value sources. For example, values.sh with contents
```
greeting="Hello"
recipient="World"
```
can be used to render template:
```
uw template render --input-file template --values-file values.sh
```
```
Hello, World!
```

`translate`

uw template translate --help

usage: uw template translate [-h] [--version] [--input-file PATH]
                             [--output-file PATH] [--dry-run] [--quiet]
                             [--verbose]

Translate atparse to Jinja2

Optional arguments:
  -h, --help
      Show help and exit
  --version
      Show version info and exit
  --input-file PATH, -i PATH
      Path to input file (default: read from stdin)
  --output-file PATH, -o PATH
      Path to output file (default: write to stdout)
  --dry-run
      Only log info, making no changes
  --quiet, -q
      Print no logging messages
  --verbose, -v
      Print all logging messages

Examples

The examples in this section use atparse-formatted template file atparse.txt with contents:

@[greeting], @[recipient]!

To convert an atparse-formatted template file to Jinja2 format:
```
uw template translate --input-file atparse.txt
```
```
{{ greeting }}, {{ recipient }}!
```
Shell redirection may also be used to stream output to a file, another process, etc.

To convert the template to a file via command-line argument:

rm -f jinja2.txt
uw template translate --input-file atparse.txt --output-file jinja2.txt
cat jinja2.txt

{{ greeting }}, {{ recipient }}!

With the --dry-run flag specified, nothing is written to stdout (or to a file if --output-file is specified), but a report of what would have been written is logged to stderr:
```
uw template translate --input-file atparse.txt --dry-run
```
```
[2025-01-02T03:04:05]     INFO {{ greeting }}, {{ recipient }}!
```

template

render

Examples

translate

Examples

`template`

`render`

`translate`