diff options
Diffstat (limited to 'docs-src')
| -rw-r--r-- | docs-src/content/functions/coll.yml | 197 | ||||
| -rw-r--r-- | docs-src/content/functions/conv.yml | 50 | ||||
| -rw-r--r-- | docs-src/content/functions/func_doc.md.tmpl | 3 |
3 files changed, 203 insertions, 47 deletions
diff --git a/docs-src/content/functions/coll.yml b/docs-src/content/functions/coll.yml new file mode 100644 index 00000000..c4d61dce --- /dev/null +++ b/docs-src/content/functions/coll.yml @@ -0,0 +1,197 @@ +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.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._ + + See also [`coll.Append`](#coll-append). + pipeline: true + arguments: + - name: list + required: true + description: the input list + examples: + - | + $ gomplate -i '{{ slice 4 3 2 1 | prepend 5 }}' + [5 4 3 2 1] + - 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] diff --git a/docs-src/content/functions/conv.yml b/docs-src/content/functions/conv.yml index e12b510c..0a7c14d4 100644 --- a/docs-src/content/functions/conv.yml +++ b/docs-src/content/functions/conv.yml @@ -50,6 +50,7 @@ funcs: $ gomplate -i '{{ "" | default "foo" }} {{ "bar" | default "baz" }}' foo bar - name: conv.Dict + deprecated: Renamed to [`coll.Dict`](#coll-dict) alias: dict description: | Dict is a convenience function that creates a map with string keys. @@ -62,8 +63,7 @@ funcs: 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 or maps with non-`string` keys, see - [`data.JSON`](../data/#data-json) or [`data.YAML`](../data/#data-yaml). + For creating more complex maps, see [`data.JSON`](../data/#data-json) or [`data.YAML`](../data/#data-yaml). For creating arrays, see [`conv.Slice`](#conv-slice). arguments: @@ -86,6 +86,7 @@ funcs: Hello world! Hello everybody! - name: conv.Slice + deprecated: Renamed to [`coll.Slice`](#coll-slice) alias: slice description: | Creates a slice (like an array or list). Useful when needing to `range` over a bunch of variables. @@ -101,6 +102,7 @@ funcs: Hello, Lisa Hello, Maggie - name: conv.Has + deprecated: Renamed to [`coll.Has`](#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. @@ -404,47 +406,3 @@ funcs: - | $ gomplate -i '{{ conv.ToStrings nil 42 true 0xF (slice 1 2 3) }}' [nil 42 true 15 [1 2 3]] - - name: conv.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 [`conv.Values`](#conv-values). - arguments: - - name: in... - required: true - description: the maps - examples: - - | - $ gomplate -i '{{ $map := json `{"foo": 1, "bar": 2}` -}} - {{ conv.Keys $map }}' - [bar foo] - $ gomplate -i '{{ $map1 := json `{"foo": 1, "bar": 2}` -}} - {{ $map2 := json `{"baz": 3, "qux": 4}` -}} - {{ conv.Keys $map1 $map2 }}' - [bar foo baz qux] - - name: conv.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 [`conv.Keys`](#conv-keys). - arguments: - - name: in... - required: true - description: the maps - examples: - - | - $ gomplate -i '{{ $map := json `{"foo": 1, "bar": 2}` -}} - {{ conv.Values $map }}' - [2 1] - $ gomplate -i '{{ $map1 := json `{"foo": 1, "bar": 2}` -}} - {{ $map2 := json `{"baz": 3, "qux": 4}` -}} - {{ conv.Values $map1 $map2 }}' - [2 1 3 4] diff --git a/docs-src/content/functions/func_doc.md.tmpl b/docs-src/content/functions/func_doc.md.tmpl index 9fb27758..c70a6ade 100644 --- a/docs-src/content/functions/func_doc.md.tmpl +++ b/docs-src/content/functions/func_doc.md.tmpl @@ -9,7 +9,8 @@ menu: {{ $data.preamble -}} {{ range $_, $f := $data.funcs }} -## `{{ $f.name }}` +## `{{ $f.name }}`{{ if has $f "deprecated" }} _(deprecated)_ +**Deprecation Notice:** {{ $f.deprecated }}{{ end }} {{ if has $f "alias" }} **Alias:** `{{$f.alias}}` {{ end }} |