path: root/docs-src/content/functions/coll.yml

ns: coll
title: collection functions
preamble: |
  These functions help manipulate and query collections of data, like lists (slices, or arrays) and maps (dictionaries).

  #### Implementation Note
  For the functions that return an array, a Go `[]interface{}` is returned, regardless of whether or not the
  input was a different type.
funcs:
  - name: coll.Dict
    alias: dict
    description: |
      Dict is a convenience function that creates a map with string keys.
      Provide arguments as key/value pairs. If an odd number of arguments
      is provided, the last is used as the key, and an empty string is
      set as the value.

      All keys are converted to strings.

      This function is equivalent to [Sprig's `dict`](http://masterminds.github.io/sprig/dicts.html#dict)
      function, as used in [Helm templates](https://docs.helm.sh/chart_template_guide#template-functions-and-pipelines).

      For creating more complex maps, see [`data.JSON`](../data/#data-json) or [`data.YAML`](../data/#data-yaml).

      For creating arrays, see [`coll.Slice`](#coll-slice).
    arguments:
      - name: in...
        required: true
        description: The key/value pairs
    examples:
      - |
        $ gomplate -i '{{ coll.Dict "name" "Frank" "age" 42 | data.ToYAML }}'
        age: 42
        name: Frank
        $ gomplate -i '{{ dict 1 2 3 | toJSON }}'
        {"1":2,"3":""}
      - |
        $ cat <<EOF| gomplate
        {{ define "T1" }}Hello {{ .thing }}!{{ end -}}
        {{ template "T1" (dict "thing" "world")}}
        {{ template "T1" (dict "thing" "everybody")}}
        EOF
        Hello world!
        Hello everybody!
  - name: coll.Slice
    alias: slice
    description: |
      Creates a slice (like an array or list). Useful when needing to `range` over a bunch of variables.
    pipeline: false
    arguments:
      - name: in...
        required: true
        description: the elements of the slice
    examples:
      - |
        $ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
        Hello, Bart
        Hello, Lisa
        Hello, Maggie
  - name: coll.Has
    alias: has
    description: |
      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.
    pipeline: false
    arguments:
      - name: in
        required: true
        description: The object or list to search
      - name: item
        required: true
        description: The item to search for
    examples:
      - |
        $ gomplate -i '{{ $l := slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar'
        there is a bar
      - |
        $ export DATA='{"foo": "bar"}'
        $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}}
        {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}'
        bar
      - |
        $ export DATA='{"baz": "qux"}'
        $ gomplate -i '{{ $o := data.JSON (getenv "DATA") -}}
        {{ if (has $o "foo") }}{{ $o.foo }}{{ else }}THERE IS NO FOO{{ end }}'
        THERE IS NO FOO
  - name: coll.JSONPath
    alias: jsonpath
    description: |
      Extracts portions of an input object or list using a [JSONPath][] expression.

      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.

      JSONPath expressions can be validated at https://jsonpath.com

      [JSONPath]: https://goessner.net/articles/JsonPath
    pipeline: true
    arguments:
      - name: expression
        required: true
        description: The JSONPath expression
      - name: in
        required: true
        description: The object or list to query
    examples:
      - |
        $ gomplate -i '{{ .books | jsonpath `$..works[?( @.edition_count > 400 )].title` }}' -c books=https://openlibrary.org/subjects/fantasy.json
        [Alice's Adventures in Wonderland Gulliver's Travels]
  - name: coll.Keys
    alias: keys
    description: |
      Return a list of keys in one or more maps.

      The keys will be ordered first by map position (if multiple maps are given),
      then alphabetically.

      See also [`coll.Values`](#coll-values).
    pipeline: true
    arguments:
      - name: in...
        required: true
        description: the maps
    examples:
      - |
        $ gomplate -i '{{ coll.Keys (dict "foo" 1 "bar" 2) }}'
        [bar foo]
        $ gomplate -i '{{ $map1 := dict "foo" 1 "bar" 2 -}}{{ $map2 := dict "baz" 3 "qux" 4 -}}{{ coll.Keys $map1 $map2 }}'
        [bar foo baz qux]
  - name: coll.Values
    alias: values
    description: |
      Return a list of values in one or more maps.

      The values will be ordered first by map position (if multiple maps are given),
      then alphabetically by key.

      See also [`coll.Keys`](#coll-keys).
    pipeline: true
    arguments:
      - name: in...
        required: true
        description: the maps
    examples:
      - |
        $ gomplate -i '{{ coll.Values (dict "foo" 1 "bar" 2) }}'
        [2 1]
        $ gomplate -i '{{ $map1 := dict "foo" 1 "bar" 2 -}}{{ $map2 := dict "baz" 3 "qux" 4 -}}{{ coll.Values $map1 $map2 }}'
        [2 1 3 4]
  - name: coll.Append
    alias: append
    description: |
      Append a value to the end of a list.

      _Note that this function does not change the given list; it always produces a new one._

      See also [`coll.Prepend`](#coll-prepend).
    pipeline: true
    arguments:
      - name: value
        required: true
        description: the value to add
      - name: list...
        required: true
        description: the slice or array to append to
    examples:
      - |
        $ gomplate -i '{{ slice 1 1 2 3 | append 5 }}'
        [1 1 2 3 5]
  - name: coll.Prepend
    alias: prepend
    description: |
      Prepend a value to the beginning of a list.

      _Note that this function does not change the given list; it always produces a new one._

      See also [`coll.Append`](#coll-append).
    pipeline: true
    arguments:
      - name: value
        required: true
        description: the value to add
      - name: list...
        required: true
        description: the slice or array to prepend to
    examples:
      - |
        $ gomplate -i '{{ slice 4 3 2 1 | prepend 5 }}'
        [5 4 3 2 1]
  - name: coll.Uniq
    alias: uniq
    description: |
      Remove any duplicate values from the list, without changing order.

      _Note that this function does not change the given list; it always produces a new one._
    pipeline: true
    arguments:
      - name: list
        required: true
        description: the input list
    examples:
      - |
        $ gomplate -i '{{ slice 1 2 3 2 3 4 1 5 | uniq }}'
        [1 2 3 4 5]
  - name: coll.Flatten
    alias: flatten
    description: |
      Flatten a nested list. Defaults to completely flattening all nested lists,
      but can be limited with `depth`.

      _Note that this function does not change the given list; it always produces a new one._
    pipeline: true
    arguments:
      - name: depth
        required: false
        description: maximum depth of nested lists to flatten. Omit or set to `-1` for infinite depth.
      - name: list
        required: true
        description: the input list
    examples:
      - |
        $ gomplate -i '{{ "[[1,2],[],[[3,4],[[[5],6],7]]]" | jsonArray | flatten }}'
        [1 2 3 4 5 6 7]
      - |
        $ gomplate -i '{{ coll.Flatten 2 ("[[1,2],[],[[3,4],[[[5],6],7]]]" | jsonArray) }}'
        [1 2 3 4 [[5] 6] 7]
  - name: coll.Reverse
    alias: reverse
    description: |
      Reverse a list.

      _Note that this function does not change the given list; it always produces a new one._
    pipeline: true
    arguments:
      - name: list
        required: true
        description: the list to reverse
    examples:
      - |
        $ gomplate -i '{{ slice 4 3 2 1 | reverse }}'
        [1 2 3 4]
  - name: coll.Sort
    alias: sort
    description: |
      Sort a given list. Uses the natural sort order if possible. For inputs
      that are not sortable (either because the elements are of different types,
      or of an un-sortable type), the input will simply be returned, unmodified.

      Maps and structs can be sorted by a named key.

      _Note that this function does not modify the input._
    pipeline: true
    arguments:
      - name: key
        required: false
        description: the key to sort by, for lists of maps or structs
      - name: list
        required: true
        description: the slice or array to sort
    examples:
      - |
        $ gomplate -i '{{ slice "foo" "bar" "baz" | coll.Sort }}'
        [bar baz foo]
      - |
        $ gomplate -i '{{ sort (slice 3 4 1 2 5) }}'
        [1 2 3 4 5]
      - |
        $ cat <<EOF > in.json
        [{"a": "foo", "b": 1}, {"a": "bar", "b": 8}, {"a": "baz", "b": 3}]
        EOF
        $ gomplate -d in.json -i '{{ range (include "in" | jsonArray | coll.Sort "b") }}{{ print .a "\n" }}{{ end }}'
        foo
        baz
        bar
  - name: coll.Merge
    alias: merge
    description: |
      Merge maps together by overriding src with dst.

      In other words, the src map can be configured the "default" map, whereas the dst
      map can be configured the "overrides".

      Many source maps can be provided. Precedence is in left-to-right order.

      _Note that this function does not modify the input._
    pipeline: true
    arguments:
      - name: dst
        required: true
        description: the map to merge _into_
      - name: srcs...
        required: true
        description: the map (or maps) to merge _from_
    examples:
      - |
        $ gomplate -i '{{ $default := dict "foo" 1 "bar" 2}}
        {{ $config := dict "foo" 8 }}
        {{ merge $config $default }}'
        map[bar:2 foo:8]
      - |
        $ gomplate -i '{{ $dst := dict "foo" 1 "bar" 2 }}
        {{ $src1 := dict "foo" 8 "baz" 4 }}
        {{ $src2 := dict "foo" 3 "bar" 5 }}
        {{ coll.Merge $dst $src1 $src2 }}'
        map[foo:1 bar:5 baz:4]
  - name: coll.Pick
    description: |
      Given a map, returns a new map with any entries that have the given keys.

      All keys are converted to strings.

      This is the inverse of [`coll.Omit`](#coll-omit).

      _Note that this function does not modify the input._
    pipeline: true
    arguments:
      - name: keys...
        required: true
        description: the keys to match
      - name: map
        required: true
        description: the map to pick from
    examples:
      - |
        $ gomplate -i '{{ $data := dict "foo" 1 "bar" 2 "baz" 3 }}
        {{ coll.Pick "foo" "baz" $data }}'
        map[baz:3 foo:1]
  - name: coll.Omit
    description: |
      Given a map, returns a new map without any entries that have the given keys.

      All keys are converted to strings.

      This is the inverse of [`coll.Pic`](#coll-pick).

      _Note that this function does not modify the input._
    pipeline: true
    arguments:
      - name: keys...
        required: true
        description: the keys to match
      - name: map
        required: true
        description: the map to omit from
    examples:
      - |
        $ gomplate -i '{{ $data := dict "foo" 1 "bar" 2 "baz" 3 }}
        {{ coll.Omit "foo" "baz" $data }}'
        map[bar:2]