collection functions

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.

coll.Dict

Alias: dict

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 function, as used in Helm templates.

For creating more complex maps, see data.JSON or data.YAML.

For creating arrays, see coll.Slice.

Usage

coll.Dict in...

Arguments

name description
in... (required) 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!

coll.Slice

Alias: slice

Creates a slice (like an array or list). Useful when needing to range over a bunch of variables.

Usage

coll.Slice in...

Arguments

name description
in... (required) the elements of the slice

Examples

$ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
Hello, Bart
Hello, Lisa
Hello, Maggie

coll.Has

Alias: has

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.

Usage

coll.Has in item

Arguments

name description
in (required) The object or list to search
item (required) 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

coll.JSONPath

Alias: jsonpath

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

Usage

coll.JSONPath expression in
in | coll.JSONPath expression

Arguments

name description
expression (required) The JSONPath expression
in (required) 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]

coll.Keys

Alias: keys

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.

Usage

coll.Keys in...
in... | coll.Keys

Arguments

name description
in... (required) 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]

coll.Values

Alias: values

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.

Usage

coll.Values in...
in... | coll.Values

Arguments

name description
in... (required) 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]

coll.Append

Alias: append

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.

Usage

coll.Append value list...
list... | coll.Append value

Arguments

name description
value (required) the value to add
list... (required) the slice or array to append to

Examples

$ gomplate -i '{{ slice 1 1 2 3 | append 5 }}'
[1 1 2 3 5]

coll.Prepend

Alias: prepend

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.

Usage

coll.Prepend value list...
list... | coll.Prepend value

Arguments

name description
value (required) the value to add
list... (required) the slice or array to prepend to

Examples

$ gomplate -i '{{ slice 4 3 2 1 | prepend 5 }}'
[5 4 3 2 1]

coll.Uniq

Alias: uniq

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.

See also coll.Append.

Usage

coll.Uniq list
list | coll.Uniq

Arguments

name description
list (required) the input list

Examples

$ gomplate -i '{{ slice 4 3 2 1 | prepend 5 }}'
[5 4 3 2 1]

coll.Reverse

Alias: reverse

Reverse a list.

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

Usage

coll.Reverse list
list | coll.Reverse

Arguments

name description
list (required) the list to reverse

Examples

$ gomplate -i '{{ slice 4 3 2 1 | reverse }}'
[1 2 3 4]

coll.Sort

Alias: sort

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.

Usage

coll.Sort [key] list
list | coll.Sort [key]

Arguments

name description
key (optional) the key to sort by, for lists of maps or structs
list (required) 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

coll.Merge

Alias: merge

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.

Usage

coll.Merge dst srcs...
srcs... | coll.Merge dst

Arguments

name description
dst (required) the map to merge into
srcs... (required) 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]