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