github.com/wuhuizuo/gomplate@v3.5.0+incompatible/docs/content/functions/test.md (about)

     1  ---
     2  title: test functions
     3  menu:
     4    main:
     5      parent: functions
     6  ---
     7  
     8  The `test` namespace contains some simple functions to help validate
     9  assumptions and can cause template generation to fail in specific cases.
    10  
    11  ## `test.Assert`
    12  
    13  **Alias:** `assert`
    14  
    15  Asserts that the given expression or value is `true`. If it is not, causes
    16  template generation to fail immediately with an optional message.
    17  
    18  ### Usage
    19  
    20  ```go
    21  test.Assert [message] value
    22  ```
    23  ```go
    24  value | test.Assert [message]
    25  ```
    26  
    27  ### Arguments
    28  
    29  | name | description |
    30  |------|-------------|
    31  | `message` | _(optional)_ The optional message to provide in the case of failure |
    32  | `value` | _(required)_ The value to test |
    33  
    34  ### Examples
    35  
    36  ```console
    37  $ gomplate -i '{{ assert (eq "foo" "bar") }}'
    38  template: <arg>:1:3: executing "<arg>" at <assert (eq "foo" "ba...>: error calling assert: assertion failed
    39  $ gomplate -i '{{ assert "something horrible happened" false }}'
    40  template: <arg>:1:3: executing "<arg>" at <assert "something ho...>: error calling assert: assertion failed: something horrible happened
    41  ```
    42  
    43  ## `test.Fail`
    44  
    45  **Alias:** `fail`
    46  
    47  Cause template generation to fail immediately, with an optional message.
    48  
    49  ### Usage
    50  
    51  ```go
    52  test.Fail [message]
    53  ```
    54  ```go
    55  message | test.Fail
    56  ```
    57  
    58  ### Arguments
    59  
    60  | name | description |
    61  |------|-------------|
    62  | `message` | _(optional)_ The optional message to provide |
    63  
    64  ### Examples
    65  
    66  ```console
    67  $ gomplate -i '{{ fail }}'
    68  template: <arg>:1:3: executing "<arg>" at <fail>: error calling fail: template generation failed
    69  $ gomplate -i '{{ test.Fail "something is wrong!" }}'
    70  template: <arg>:1:7: executing "<arg>" at <test.Fail>: error calling Fail: template generation failed: something is wrong!
    71  ```
    72  
    73  ## `test.Required`
    74  
    75  **Alias:** `required`
    76  
    77  Passes through the given value, if it's non-empty, and non-`nil`. Otherwise,
    78  exits and prints a given error message so the user can adjust as necessary.
    79  
    80  This is particularly useful for cases where templates require user-provided
    81  data (such as datasources or environment variables), and rendering can not
    82  continue correctly.
    83  
    84  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),
    85  but has slightly different behaviour. Notably, gomplate will always fail in
    86  cases where a referenced _key_ is missing, and this function will have no
    87  effect.
    88  
    89  ### Usage
    90  
    91  ```go
    92  test.Required [message] value
    93  ```
    94  ```go
    95  value | test.Required [message]
    96  ```
    97  
    98  ### Arguments
    99  
   100  | name | description |
   101  |------|-------------|
   102  | `message` | _(optional)_ The optional message to provide when the required value is not provided |
   103  | `value` | _(required)_ The required value |
   104  
   105  ### Examples
   106  
   107  ```console
   108  $ FOO=foobar gomplate -i '{{ getenv "FOO" | required "Missing FOO environment variable!" }}'
   109  foobar
   110  $ FOO= gomplate -i '{{ getenv "FOO" | required "Missing FOO environment variable!" }}'
   111  error: Missing FOO environment variable!
   112  ```
   113  ```console
   114  $ cat <<EOF> config.yaml
   115  defined: a value
   116  empty: ""
   117  EOF
   118  $ gomplate -d config=config.yaml -i '{{ (ds "config").defined | required "The `config` datasource must have a value defined for `defined`" }}'
   119  a value
   120  $ gomplate -d config=config.yaml -i '{{ (ds "config").empty | required "The `config` datasource must have a value defined for `empty`" }}'
   121  template: <arg>:1:25: executing "<arg>" at <required "The `confi...>: error calling required: The `config` datasource must have a value defined for `empty`
   122  $ gomplate -d config=config.yaml -i '{{ (ds "config").bogus | required "The `config` datasource must have a value defined for `bogus`" }}'
   123  template: <arg>:1:7: executing "<arg>" at <"config">: map has no entry for key "bogus"
   124  ```
   125  
   126  ## `test.Ternary`
   127  
   128  **Alias:** `ternary`
   129  
   130  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).
   131  
   132  This is effectively a short-form of the following template:
   133  
   134  ```
   135  {{ if conv.ToBool $condition }}{{ $truevalue }}{{ else }}{{ $falsevalue }}{{ end }}
   136  ```
   137  
   138  Keep in mind that using an explicit `if`/`else` block is often easier to understand than ternary expressions!
   139  
   140  ### Usage
   141  
   142  ```go
   143  test.Ternary truevalue falsevalue condition
   144  ```
   145  ```go
   146  condition | test.Ternary truevalue falsevalue
   147  ```
   148  
   149  ### Arguments
   150  
   151  | name | description |
   152  |------|-------------|
   153  | `truevalue` | _(required)_ the value to return if `condition` is true |
   154  | `falsevalue` | _(required)_ the value to return if `condition` is false |
   155  | `condition` | _(required)_ the value to evaluate for truthiness |
   156  
   157  ### Examples
   158  
   159  ```console
   160  $ gomplate -i '{{ ternary "FOO" "BAR" false }}'
   161  BAR
   162  $ gomplate -i '{{ ternary "FOO" "BAR" "yes" }}'
   163  FOO
   164  ```