New collections (coll) namespace, plus new functions

Signed-off-by: Dave Henderson <dhenderson@gmail.com>

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 }}