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: :1:3: executing "" at : error calling assert: assertion failed $ gomplate -i '{{ assert "something horrible happened" false }}' template: :1:3: executing "" at : 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: :1:3: executing "" at : error calling fail: template generation failed $ gomplate -i '{{ test.Fail "something is wrong!" }}' template: :1:7: executing "" at : 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 < 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: :1:25: executing "" at : 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: :1:7: executing "" 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