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