github.com/wynshop-open-source/gomplate@v3.5.0+incompatible/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      description: |
     9        Asserts that the given expression or value is `true`. If it is not, causes
    10        template generation to fail immediately with an optional message.
    11      pipeline: true
    12      arguments:
    13        - name: message
    14          required: false
    15          description: The optional message to provide in the case of failure
    16        - name: value
    17          required: true
    18          description: The value to test
    19      examples:
    20        - |
    21          $ gomplate -i '{{ assert (eq "foo" "bar") }}'
    22          template: <arg>:1:3: executing "<arg>" at <assert (eq "foo" "ba...>: error calling assert: assertion failed
    23          $ gomplate -i '{{ assert "something horrible happened" false }}'
    24          template: <arg>:1:3: executing "<arg>" at <assert "something ho...>: error calling assert: assertion failed: something horrible happened
    25    - name: test.Fail
    26      alias: fail
    27      description: |
    28        Cause template generation to fail immediately, with an optional message.
    29      pipeline: true
    30      arguments:
    31        - name: message
    32          required: false
    33          description: The optional message to provide
    34      examples:
    35        - |
    36          $ gomplate -i '{{ fail }}'
    37          template: <arg>:1:3: executing "<arg>" at <fail>: error calling fail: template generation failed
    38          $ gomplate -i '{{ test.Fail "something is wrong!" }}'
    39          template: <arg>:1:7: executing "<arg>" at <test.Fail>: error calling Fail: template generation failed: something is wrong!
    40    - name: test.Required
    41      alias: required
    42      description: |
    43        Passes through the given value, if it's non-empty, and non-`nil`. Otherwise,
    44        exits and prints a given error message so the user can adjust as necessary.
    45  
    46        This is particularly useful for cases where templates require user-provided
    47        data (such as datasources or environment variables), and rendering can not
    48        continue correctly.
    49  
    50        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),
    51        but has slightly different behaviour. Notably, gomplate will always fail in
    52        cases where a referenced _key_ is missing, and this function will have no
    53        effect.
    54      pipeline: true
    55      arguments:
    56        - name: message
    57          required: false
    58          description: The optional message to provide when the required value is not provided
    59        - name: value
    60          required: true
    61          description: The required value
    62      examples:
    63        - |
    64          $ FOO=foobar gomplate -i '{{ getenv "FOO" | required "Missing FOO environment variable!" }}'
    65          foobar
    66          $ FOO= gomplate -i '{{ getenv "FOO" | required "Missing FOO environment variable!" }}'
    67          error: Missing FOO environment variable!
    68        - |
    69          $ cat <<EOF> config.yaml
    70          defined: a value
    71          empty: ""
    72          EOF
    73          $ gomplate -d config=config.yaml -i '{{ (ds "config").defined | required "The `config` datasource must have a value defined for `defined`" }}'
    74          a value
    75          $ gomplate -d config=config.yaml -i '{{ (ds "config").empty | required "The `config` datasource must have a value defined for `empty`" }}'
    76          template: <arg>:1:25: executing "<arg>" at <required "The `confi...>: error calling required: The `config` datasource must have a value defined for `empty`
    77          $ gomplate -d config=config.yaml -i '{{ (ds "config").bogus | required "The `config` datasource must have a value defined for `bogus`" }}'
    78          template: <arg>:1:7: executing "<arg>" at <"config">: map has no entry for key "bogus"
    79    - name: test.Ternary
    80      alias: ternary
    81      description: |
    82        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).
    83  
    84        This is effectively a short-form of the following template:
    85  
    86        ```
    87        {{ if conv.ToBool $condition }}{{ $truevalue }}{{ else }}{{ $falsevalue }}{{ end }}
    88        ```
    89  
    90        Keep in mind that using an explicit `if`/`else` block is often easier to understand than ternary expressions!
    91      pipeline: true
    92      arguments:
    93        - name: truevalue
    94          required: true
    95          description: the value to return if `condition` is true
    96        - name: falsevalue
    97          required: true
    98          description: the value to return if `condition` is false
    99        - name: condition
   100          required: true
   101          description: the value to evaluate for truthiness
   102      examples:
   103        - |
   104          $ gomplate -i '{{ ternary "FOO" "BAR" false }}'
   105          BAR
   106          $ gomplate -i '{{ ternary "FOO" "BAR" "yes" }}'
   107          FOO