github.com/wynshop-open-source/gomplate@v3.5.0+incompatible/docs-src/content/functions/coll.yml (about)

     1  ns: coll
     2  title: collection functions
     3  preamble: |
     4    These functions help manipulate and query collections of data, like lists (slices, or arrays) and maps (dictionaries).
     5  
     6    #### Implementation Note
     7    For the functions that return an array, a Go `[]interface{}` is returned, regardless of whether or not the
     8    input was a different type.
     9  funcs:
    10    - name: coll.Dict
    11      alias: dict
    12      description: |
    13        Dict is a convenience function that creates a map with string keys.
    14        Provide arguments as key/value pairs. If an odd number of arguments
    15        is provided, the last is used as the key, and an empty string is
    16        set as the value.
    17  
    18        All keys are converted to strings.
    19  
    20        This function is equivalent to [Sprig's `dict`](http://masterminds.github.io/sprig/dicts.html#dict)
    21        function, as used in [Helm templates](https://docs.helm.sh/chart_template_guide#template-functions-and-pipelines).
    22  
    23        For creating more complex maps, see [`data.JSON`](../data/#data-json) or [`data.YAML`](../data/#data-yaml).
    24  
    25        For creating arrays, see [`coll.Slice`](#coll-slice).
    26      arguments:
    27        - name: in...
    28          required: true
    29          description: The key/value pairs
    30      examples:
    31        - |
    32          $ gomplate -i '{{ coll.Dict "name" "Frank" "age" 42 | data.ToYAML }}'
    33          age: 42
    34          name: Frank
    35          $ gomplate -i '{{ dict 1 2 3 | toJSON }}'
    36          {"1":2,"3":""}
    37        - |
    38          $ cat <<EOF| gomplate
    39          {{ define "T1" }}Hello {{ .thing }}!{{ end -}}
    40          {{ template "T1" (dict "thing" "world")}}
    41          {{ template "T1" (dict "thing" "everybody")}}
    42          EOF
    43          Hello world!
    44          Hello everybody!
    45    - name: coll.Slice
    46      alias: slice
    47      description: |
    48        Creates a slice (like an array or list). Useful when needing to `range` over a bunch of variables.
    49      pipeline: false
    50      arguments:
    51        - name: in...
    52          required: true
    53          description: the elements of the slice
    54      examples:
    55        - |
    56          $ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
    57          Hello, Bart
    58          Hello, Lisa
    59          Hello, Maggie
    60    - name: coll.Has
    61      alias: has
    62      description: |
    63        Reports whether a given object has a property with the given key, or whether a given array/slice contains the given value. Can be used with `if` to prevent the template from trying to access a non-existent property in an object.
    64      pipeline: false
    65      arguments:
    66        - name: in
    67          required: true
    68          description: The object or list to search
    69        - name: item
    70          required: true
    71          description: The item to search for
    72      examples:
    73        - |
    74          $ gomplate -i '{{ $l := slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar'
    75          there is a bar
    76        - |
    77          $ export DATA='{"foo": "bar"}'
    78          $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}}
    79          {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}'
    80          bar
    81        - |
    82          $ export DATA='{"baz": "qux"}'
    83          $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}}
    84          {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}'
    85          THERE IS NO FOO
    86    - name: coll.JSONPath
    87      alias: jsonpath
    88      description: |
    89        Extracts portions of an input object or list using a [JSONPath][] expression.
    90  
    91        Any object or list may be used as input. The output depends somewhat on the expression; if multiple items are matched, an array is returned.
    92  
    93        JSONPath expressions can be validated at https://jsonpath.com
    94  
    95        [JSONPath]: https://goessner.net/articles/JsonPath
    96      pipeline: true
    97      arguments:
    98        - name: expression
    99          required: true
   100          description: The JSONPath expression
   101        - name: in
   102          required: true
   103          description: The object or list to query
   104      examples:
   105        - |
   106          $ gomplate -i '{{ .books | jsonpath `$..works[?( @.edition_count > 400 )].title` }}' -c books=https://openlibrary.org/subjects/fantasy.json
   107          [Alice's Adventures in Wonderland Gulliver's Travels]
   108    - name: coll.Keys
   109      alias: keys
   110      description: |
   111        Return a list of keys in one or more maps.
   112  
   113        The keys will be ordered first by map position (if multiple maps are given),
   114        then alphabetically.
   115  
   116        See also [`coll.Values`](#coll-values).
   117      pipeline: true
   118      arguments:
   119        - name: in...
   120          required: true
   121          description: the maps
   122      examples:
   123        - |
   124          $ gomplate -i '{{ coll.Keys (dict "foo" 1 "bar" 2) }}'
   125          [bar foo]
   126          $ gomplate -i '{{ $map1 := dict "foo" 1 "bar" 2 -}}{{ $map2 := dict "baz" 3 "qux" 4 -}}{{ coll.Keys $map1 $map2 }}'
   127          [bar foo baz qux]
   128    - name: coll.Values
   129      alias: values
   130      description: |
   131        Return a list of values in one or more maps.
   132  
   133        The values will be ordered first by map position (if multiple maps are given),
   134        then alphabetically by key.
   135  
   136        See also [`coll.Keys`](#coll-keys).
   137      pipeline: true
   138      arguments:
   139        - name: in...
   140          required: true
   141          description: the maps
   142      examples:
   143        - |
   144          $ gomplate -i '{{ coll.Values (dict "foo" 1 "bar" 2) }}'
   145          [2 1]
   146          $ gomplate -i '{{ $map1 := dict "foo" 1 "bar" 2 -}}{{ $map2 := dict "baz" 3 "qux" 4 -}}{{ coll.Values $map1 $map2 }}'
   147          [2 1 3 4]
   148    - name: coll.Append
   149      alias: append
   150      description: |
   151        Append a value to the end of a list.
   152  
   153        _Note that this function does not change the given list; it always produces a new one._
   154  
   155        See also [`coll.Prepend`](#coll-prepend).
   156      pipeline: true
   157      arguments:
   158        - name: value
   159          required: true
   160          description: the value to add
   161        - name: list...
   162          required: true
   163          description: the slice or array to append to
   164      examples:
   165        - |
   166          $ gomplate -i '{{ slice 1 1 2 3 | append 5 }}'
   167          [1 1 2 3 5]
   168    - name: coll.Prepend
   169      alias: prepend
   170      description: |
   171        Prepend a value to the beginning of a list.
   172  
   173        _Note that this function does not change the given list; it always produces a new one._
   174  
   175        See also [`coll.Append`](#coll-append).
   176      pipeline: true
   177      arguments:
   178        - name: value
   179          required: true
   180          description: the value to add
   181        - name: list...
   182          required: true
   183          description: the slice or array to prepend to
   184      examples:
   185        - |
   186          $ gomplate -i '{{ slice 4 3 2 1 | prepend 5 }}'
   187          [5 4 3 2 1]
   188    - name: coll.Uniq
   189      alias: uniq
   190      description: |
   191        Remove any duplicate values from the list, without changing order.
   192  
   193        _Note that this function does not change the given list; it always produces a new one._
   194  
   195        See also [`coll.Append`](#coll-append).
   196      pipeline: true
   197      arguments:
   198        - name: list
   199          required: true
   200          description: the input list
   201      examples:
   202        - |
   203          $ gomplate -i '{{ slice 4 3 2 1 | prepend 5 }}'
   204          [5 4 3 2 1]
   205    - name: coll.Reverse
   206      alias: reverse
   207      description: |
   208        Reverse a list.
   209  
   210        _Note that this function does not change the given list; it always produces a new one._
   211      pipeline: true
   212      arguments:
   213        - name: list
   214          required: true
   215          description: the list to reverse
   216      examples:
   217        - |
   218          $ gomplate -i '{{ slice 4 3 2 1 | reverse }}'
   219          [1 2 3 4]
   220    - name: coll.Sort
   221      alias: sort
   222      description: |
   223        Sort a given list. Uses the natural sort order if possible. For inputs
   224        that are not sortable (either because the elements are of different types,
   225        or of an un-sortable type), the input will simply be returned, unmodified.
   226  
   227        Maps and structs can be sorted by a named key.
   228  
   229        _Note that this function does not modify the input._
   230      pipeline: true
   231      arguments:
   232        - name: key
   233          required: false
   234          description: the key to sort by, for lists of maps or structs
   235        - name: list
   236          required: true
   237          description: the slice or array to sort
   238      examples:
   239        - |
   240          $ gomplate -i '{{ slice "foo" "bar" "baz" | coll.Sort }}'
   241          [bar baz foo]
   242        - |
   243          $ gomplate -i '{{ sort (slice 3 4 1 2 5) }}'
   244          [1 2 3 4 5]
   245        - |
   246          $ cat <<EOF > in.json
   247          [{"a": "foo", "b": 1}, {"a": "bar", "b": 8}, {"a": "baz", "b": 3}]
   248          EOF
   249          $ gomplate -d in.json -i '{{ range (include "in" | jsonArray | coll.Sort "b") }}{{ print .a "\n" }}{{ end }}'
   250          foo
   251          baz
   252          bar
   253    - name: coll.Merge
   254      alias: merge
   255      description: |
   256        Merge maps together by overriding src with dst.
   257  
   258        In other words, the src map can be configured the "default" map, whereas the dst
   259        map can be configured the "overrides".
   260  
   261        Many source maps can be provided. Precedence is in left-to-right order.
   262  
   263        _Note that this function does not modify the input._
   264      pipeline: true
   265      arguments:
   266        - name: dst
   267          required: true
   268          description: the map to merge _into_
   269        - name: srcs...
   270          required: true
   271          description: the map (or maps) to merge _from_
   272      examples:
   273        - |
   274          $ gomplate -i '{{ $default := dict "foo" 1 "bar" 2}}
   275          {{ $config := dict "foo" 8 }}
   276          {{ merge $config $default }}'
   277          map[bar:2 foo:8]
   278        - |
   279          $ gomplate -i '{{ $dst := dict "foo" 1 "bar" 2 }}
   280          {{ $src1 := dict "foo" 8 "baz" 4 }}
   281          {{ $src2 := dict "foo" 3 "bar" 5 }}
   282          {{ coll.Merge $dst $src1 $src2 }}'
   283          map[foo:1 bar:5 baz:4]