10.3.1.1 Actions

Here is the list of actions. Arguments and pipelines are evaluations of data, defined in detail in the sections that follow.

{{ }}

Empty action is discarded. It may be useful to trim the preceding or following whitespace, as in

{{- -}}

{{/* a comment */}}

Comments are discarded. They may span multiple lines of text. Comments do not nest and must start immediately after the opening delimiter (with optional dash and whitespace in between). A comment may be followed by any action described below.

Comments may be used to control trailing and leading whitespace as well:

{{- a comment trimming the surrounding whitespace -}}

{{ pipeline }}

The pipeline is evaluated, and the default textual representation of its value is copied to the output.

{{if pipeline }} T1 {{end}}

If the value of the pipeline is empty, no output is generated; otherwise, T1 is executed. The empty values are null, false, numeric 0, empty string (‘""’), array (‘[]’), or object (‘{}’). Dot is unaffected.

{{if pipeline }} T1 {{else}} T0 {{end}}

If the value of the pipeline is empty, T0 is executed; otherwise, T1 is executed. Dot is unaffected.

{{if pipeline }} T1 {{else if pipeline }} T2 {{else}} T0 {{end}}

A shortcut to simplify writing the if-else chains. Equivalent to (newlines added for readability):

{{if pipeline }}
  T1
{{else -}}
 {{if pipeline }}
   T2
 {{else}}
   T0
 {{end}}
{{end}}

{{range pipeline }} T1 {{end}}

The value of pipeline must be an object or array. If it is of length zero, nothing is output. Otherwise, dot is set to the successive elements of the array or object and T1 is executed. For objects, the elements will be visited in sorted key order.

{{range pipeline }} T1 {{else}} T0 {{end}}

Same as above, except that if the value of the pipeline is of length zero, T0 is executed with dot unaffected.

Within the {{range}} action, the following two keywords may appear:

{{break}}

The innermost ‘{{range pipeline}}’ loop is ended early, stopping the current iteration and bypassing all remaining iterations.

{{continue}}

The current iteration of the innermost ‘{{range pipeline}}’ loop is stopped, and the loop starts the next iteration.

{{define "name"}} text {{end}}

The text is collected and stored for the further use as template with the given name. It can be invoked using the ‘{{template}}’ action (see below).

{{template "name"}}

The template with the specified name (see the ‘{{define}}’ above) is executed with dot set to null.

{{template "name" value }}

The template with the specified name (see the ‘{{define}}’ above) is executed with dot set to value.

{{block "name" pipeline }} T1 {{end}}

A block is shorthand for defining a template and then executing it in place:

{{define "name"}} T1 {{end}}
{{template "name" pipeline}}

{{with pipeline }} T1 {{end}}

If the value of the pipeline is empty, no output is generated; otherwise, dot is set to the value of the pipeline and T1 is executed.

{{with pipeline }} T1 {{else}} T0 {{end}}

Same as above, but if the value of the pipeline is empty, T0 is executed with dot unchanged.