1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
ns: test
preamble: |
The `test` namespace contains some simple functions to help validate
assumptions and can cause template generation to fail in specific cases.
funcs:
- name: test.Assert
alias: assert
released: v2.7.0
description: |
Asserts that the given expression or value is `true`. If it is not, causes
template generation to fail immediately with an optional message.
pipeline: true
arguments:
- name: message
required: false
description: The optional message to provide in the case of failure
- name: value
required: true
description: The value to test
examples:
- |
$ gomplate -i '{{ assert (eq "foo" "bar") }}'
template: <arg>:1:3: executing "<arg>" at <assert (eq "foo" "ba...>: error calling assert: assertion failed
$ gomplate -i '{{ assert "something horrible happened" false }}'
template: <arg>:1:3: executing "<arg>" at <assert "something ho...>: error calling assert: assertion failed: something horrible happened
- name: test.Fail
alias: fail
released: v2.7.0
description: |
Cause template generation to fail immediately, with an optional message.
pipeline: true
arguments:
- name: message
required: false
description: The optional message to provide
examples:
- |
$ gomplate -i '{{ fail }}'
template: <arg>:1:3: executing "<arg>" at <fail>: error calling fail: template generation failed
$ gomplate -i '{{ test.Fail "something is wrong!" }}'
template: <arg>:1:7: executing "<arg>" at <test.Fail>: error calling Fail: template generation failed: something is wrong!
- name: test.IsKind
alias: isKind
released: v3.8.0
description: |
Report whether the argument is of the given Kind. Can be used to render
different templates depending on the kind of data.
See [the Go `reflect` source code](https://github.com/golang/go/blob/36fcde1676a0d3863cb5f295eed6938cd782fcbb/src/reflect/type.go#L595..L622)
for the complete list, but these are some common values:
- `string`
- `bool`
- `int`, `int64`, `uint64`
- `float64`
- `slice`
- `map`
- `invalid` (a catch-all, usually just `nil` values)
In addition, the special kind `number` is accepted by this function, to
represent _any_ numeric kind (whether `float32`, `uint8`, or whatever).
This is useful when the specific numeric type is unknown.
See also [`test.Kind`](#testkind).
pipeline: true
arguments:
- name: kind
required: true
description: the kind to compare with (see description for possible values)
- name: value
required: true
description: the value to check
examples:
- |
$ gomplate -i '{{ $data := "hello world" }}
{{- if isKind "string" $data }}{{ $data }} is a string{{ end }}'
hello world is a string
- |
$ gomplate -i '{{ $object := dict "key1" true "key2" "foobar" }}
{{- if test.IsKind "map" $object }}
Got a map:
{{ range $key, $value := $object -}}
- "{{ $key }}": {{ $value }}
{{ end }}
{{ else if test.IsKind "number" $object }}
Got a number: {{ $object }}
{{ end }}'
Got a map:
- "key1": true
- "key2": foobar
- name: test.Kind
alias: kind
released: v3.8.0
description: |
Report the _kind_ of the given argument. This differs from the _type_ of
the argument in specificity; for example, while a slice of strings may
have a type of `[]string`, the _kind_ of that slice will simply be `slice`.
If you need to know the precise type of a value, use `printf "%T" $value`.
See also [`test.IsKind`](#testiskind).
pipeline: true
arguments:
- name: value
required: true
description: the value to check
examples:
- |
$ gomplate -i '{{ kind "hello world" }}'
string
- |
$ gomplate -i '{{ dict "key1" true "key2" "foobar" | test.Kind }}'
map
- name: test.Required
alias: required
released: v3.0.0
description: |
Passes through the given value, if it's non-empty, and non-`nil`. Otherwise,
exits and prints a given error message so the user can adjust as necessary.
This is particularly useful for cases where templates require user-provided
data (such as datasources or environment variables), and rendering can not
continue correctly.
This was inspired by [Helm's `required` function](https://github.com/kubernetes/helm/blob/master/docs/charts_tips_and_tricks.md#know-your-template-functions),
but has slightly different behaviour. Notably, gomplate will always fail in
cases where a referenced _key_ is missing, and this function will have no
effect.
pipeline: true
arguments:
- name: message
required: false
description: The optional message to provide when the required value is not provided
- name: value
required: true
description: The required value
examples:
- |
$ FOO=foobar gomplate -i '{{ getenv "FOO" | required "Missing FOO environment variable!" }}'
foobar
$ FOO= gomplate -i '{{ getenv "FOO" | required "Missing FOO environment variable!" }}'
error: Missing FOO environment variable!
- |
$ cat <<EOF> config.yaml
defined: a value
empty: ""
EOF
$ gomplate -d config=config.yaml -i '{{ (ds "config").defined | required "The `config` datasource must have a value defined for `defined`" }}'
a value
$ gomplate -d config=config.yaml -i '{{ (ds "config").empty | required "The `config` datasource must have a value defined for `empty`" }}'
template: <arg>:1:25: executing "<arg>" at <required "The `confi...>: error calling required: The `config` datasource must have a value defined for `empty`
$ gomplate -d config=config.yaml -i '{{ (ds "config").bogus | required "The `config` datasource must have a value defined for `bogus`" }}'
template: <arg>:1:7: executing "<arg>" at <"config">: map has no entry for key "bogus"
- name: test.Ternary
alias: ternary
released: v3.1.0
description: |
Returns one of two values depending on whether the third is true. Note that the third value does not have to be a boolean - it is converted first by the [`conv.ToBool`](../conv/#convtobool) function (values like `true`, `1`, `"true"`, `"Yes"`, etc... are considered true).
This is effectively a short-form of the following template:
```
{{ if conv.ToBool $condition }}{{ $truevalue }}{{ else }}{{ $falsevalue }}{{ end }}
```
Keep in mind that using an explicit `if`/`else` block is often easier to understand than ternary expressions!
pipeline: true
arguments:
- name: truevalue
required: true
description: the value to return if `condition` is true
- name: falsevalue
required: true
description: the value to return if `condition` is false
- name: condition
required: true
description: the value to evaluate for truthiness
examples:
- |
$ gomplate -i '{{ ternary "FOO" "BAR" false }}'
BAR
$ gomplate -i '{{ ternary "FOO" "BAR" "yes" }}'
FOO
|
