`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 (defaults to stdin)
  --output-file PATH, -o PATH
      Path to output file (defaults 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 named template with the following contents:

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

and a YAML file called values.yaml with the following contents:

greeting: Hello
recipient: World

To show the values needed to render the template:

$ uw template render --input-file template --values-needed
[2023-12-18T19:16:08]     INFO Value(s) needed to render this template are:
[2023-12-18T19:16:08]     INFO   greeting
[2023-12-18T19:16:08]     INFO   recipient

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

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

$ uw template render --input-file template --values-file values.yaml --output-file rendered

The content of 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
[2023-12-18T19:38:15]     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
Cannot deduce format of 'values.txt' from unknown extension 'txt'

In this case, the format can be explicitly specified:

$ 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
[2023-12-18T23:25:01]    DEBUG Command: uw template render --input-file template --values-file values.yaml --verbose
[2023-12-18T23:25:01]    DEBUG Internal arguments:
[2023-12-18T23:25:01]    DEBUG ---------------------------------------------------------------------
[2023-12-18T23:25:01]    DEBUG           values: values.yaml
[2023-12-18T23:25:01]    DEBUG    values_format: yaml
[2023-12-18T23:25:01]    DEBUG       input_file: template
[2023-12-18T23:25:01]    DEBUG      output_file: None
[2023-12-18T23:25:01]    DEBUG        overrides: {}
[2023-12-18T23:25:01]    DEBUG    values_needed: False
[2023-12-18T23:25:01]    DEBUG          dry_run: False
[2023-12-18T23:25:01]    DEBUG ---------------------------------------------------------------------
[2023-12-18T23:25:01]    DEBUG Read initial values from values.yaml
Hello, World!

If additional information is needed, --debug can be used which will return the stack trace from any unhandled exception as well.

Note that uw logs to stderr and writes non-log output to stdout, so the streams can be redirected separately:

$ uw template render --input-file template --values-file values.yaml --verbose >rendered 2>rendered.log

The content of rendered:

Hello, World!

The content of rendered.log:

[2023-12-18T23:27:04]    DEBUG Command: uw template render --input-file template --values-file values.yaml --verbose
[2023-12-18T23:27:04]    DEBUG Internal arguments:
[2023-12-18T23:27:04]    DEBUG ---------------------------------------------------------------------
[2023-12-18T23:27:04]    DEBUG           values: values.yaml
[2023-12-18T23:27:04]    DEBUG    values_format: yaml
[2023-12-18T23:27:04]    DEBUG       input_file: template
[2023-12-18T23:27:04]    DEBUG      output_file: None
[2023-12-18T23:27:04]    DEBUG        overrides: {}
[2023-12-18T23:27:04]    DEBUG    values_needed: False
[2023-12-18T23:27:04]    DEBUG          dry_run: False
[2023-12-18T23:27:04]    DEBUG ---------------------------------------------------------------------
[2023-12-18T23:27:04]    DEBUG Read initial values from values.yaml

NB: This set of examples is based on a values.yaml file with recipient: World removed.

It is an error to render a template without providing all needed values.
```
$ uw template render --input-file template --values-file values.yaml
[2024-03-02T16:42:48]    ERROR Required value(s) not provided:
[2024-03-02T16:42:48]    ERROR   recipient
[2024-03-02T16:42:48]    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 values.yaml recipient=Reader
Hello, Reader!
```
The optional --env switch allows environment variables to be used to supply values:
```
$ export recipient=You
$ uw template render --input-file template --values-file values.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 values.yaml recipient=Reader greeting="Good day" --env
Good day, Sunshine!
```
Note that recipient=Sunshine is shell syntax for exporting environment variable recipient 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
```
{% import "macros" as m -%}
{{ m.double(11) }}
```
and file macros (in the same directory as template)
```
{% macro double(n) -%}
{{ n * 2 }}
{%- endmacro %}
```
the template is rendered as
```
$ uw template render --input-file template
22
```
The invocation uw template render --input-file template --search-path $PWD would behave identically. Alternatively, --search-path could 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 /path/to/macros:
```
$ cat template | uw template render --search-path /path/to
22
```

Non-YAML-formatted files may also be used as value sources. For example, template

{{ values.greeting }}, {{ values.recipient }}!

can be rendered with values.nml

&values
  greeting = "Hello"
  recipient = "World"
/

like so:

$ uw template render --input-file template --values-file values.nml
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 (defaults to stdin)
  --output-file PATH, -o PATH
      Path to output file (defaults 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 the following contents:

@[greeting], @[recipient]!

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

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

$ uw template translate --input-file atparse.txt --output-file jinja2.txt

The content of 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
[2024-02-06T21:53:43]     INFO {{ greeting }}, {{ recipient }}!
```

template

render

Examples

translate

Examples

`template`

`render`

`translate`