Add coll.GoSlice and deprecate slice alias

Signed-off-by: Dave Henderson <[email protected]>
hairyhenderson · Sep 25, 2022 · 5184fa4 · 5184fa4
1 parent ea83b8f
commit 5184fa4
Show file tree

Hide file tree

Showing 19 changed files with 382 additions and 78 deletions.
diff --git a/docs-src/content/functions/coll.yml b/docs-src/content/functions/coll.yml
@@ -43,6 +43,7 @@ funcs:
         Hello world!
         Hello everybody!
   - name: coll.Slice
+    deprecated: The `slice` alias is deprecated, use the full name `coll.Slice` instead.
     alias: slice
     description: |
       Creates a slice (like an array or list). Useful when needing to `range` over a bunch of variables.
@@ -53,10 +54,39 @@ funcs:
         description: the elements of the slice
     examples:
       - |
-        $ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
+        $ gomplate -i '{{ range coll.Slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
         Hello, Bart
         Hello, Lisa
         Hello, Maggie
+  - name: coll.GoSlice
+    description: |
+      This exposes the `slice` function from Go's [`text/template`](https://golang.org/pkg/text/template/#hdr-Functions)
+      package. Note that using `slice` will use the `coll.Slice` function instead,
+      which may not be desired.
+      For some background on this, see [this issue](https://github.com/hairyhenderson/gomplate/issues/1461).
+
+      Here is the upstream documentation:
+
+      ```
+      slice returns the result of slicing its first argument by the
+      remaining arguments. Thus "slice x 1 2" is, in Go syntax, x[1:2],
+      while "slice x" is x[:], "slice x 1" is x[1:], and "slice x 1 2 3"
+      is x[1:2:3]. The first argument must be a string, slice, or array.
+      ```
+
+      See the [Go language spec](https://go.dev/ref/spec#Slice_expressions) for
+      more details.
+    pipeline: false
+    arguments:
+      - name: item
+        required: true
+        description: the string, slice, or array to slice
+      - name: indexes...
+        required: false
+        description: the indexes to slice the item by (0 to 3 arguments)
+    examples:
+      - |
+        $ gomplate -i '{{ $l := coll.Slice "foo" "bar" "baz" }}{{ if has $l "bar" }}a{{else}}no{{end}} bar'
   - name: coll.Has
     alias: has
     description: |
@@ -71,7 +101,7 @@ funcs:
         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'
+        $ gomplate -i '{{ $l := coll.Slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar'
         there is a bar
       - |
         $ export DATA='{"foo": "bar"}'
@@ -163,7 +193,7 @@ funcs:
         description: the slice or array to append to
     examples:
       - |
-        $ gomplate -i '{{ slice 1 1 2 3 | append 5 }}'
+        $ gomplate -i '{{ coll.Slice 1 1 2 3 | append 5 }}'
         [1 1 2 3 5]
   - name: coll.Prepend
     alias: prepend
@@ -183,7 +213,7 @@ funcs:
         description: the slice or array to prepend to
     examples:
       - |
-        $ gomplate -i '{{ slice 4 3 2 1 | prepend 5 }}'
+        $ gomplate -i '{{ coll.Slice 4 3 2 1 | prepend 5 }}'
         [5 4 3 2 1]
   - name: coll.Uniq
     alias: uniq
@@ -198,7 +228,7 @@ funcs:
         description: the input list
     examples:
       - |
-        $ gomplate -i '{{ slice 1 2 3 2 3 4 1 5 | uniq }}'
+        $ gomplate -i '{{ coll.Slice 1 2 3 2 3 4 1 5 | uniq }}'
         [1 2 3 4 5]
   - name: coll.Flatten
     alias: flatten
@@ -235,7 +265,7 @@ funcs:
         description: the list to reverse
     examples:
       - |
-        $ gomplate -i '{{ slice 4 3 2 1 | reverse }}'
+        $ gomplate -i '{{ coll.Slice 4 3 2 1 | reverse }}'
         [1 2 3 4]
   - name: coll.Sort
     alias: sort
@@ -257,10 +287,10 @@ funcs:
         description: the slice or array to sort
     examples:
       - |
-        $ gomplate -i '{{ slice "foo" "bar" "baz" | coll.Sort }}'
+        $ gomplate -i '{{ coll.Slice "foo" "bar" "baz" | coll.Sort }}'
         [bar baz foo]
       - |
-        $ gomplate -i '{{ sort (slice 3 4 1 2 5) }}'
+        $ gomplate -i '{{ sort (coll.Slice 3 4 1 2 5) }}'
         [1 2 3 4 5]
       - |
         $ cat <<EOF > in.json

diff --git a/docs-src/content/functions/conv.yml b/docs-src/content/functions/conv.yml
@@ -65,7 +65,7 @@ funcs:
 
       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).
+      For creating arrays, see [`coll.Slice`](#coll-slice).
     arguments:
       - name: in...
         required: true
@@ -97,7 +97,7 @@ funcs:
         description: the elements of the slice
     examples:
       - |
-        $ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
+        $ gomplate -i '{{ range coll.Slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
         Hello, Bart
         Hello, Lisa
         Hello, Maggie
@@ -116,7 +116,7 @@ funcs:
         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'
+        $ gomplate -i '{{ $l := coll.Slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar'
         there is a bar
       - |
         $ export DATA='{"foo": "bar"}'
@@ -141,7 +141,7 @@ funcs:
         description: the separator
     examples:
       - |
-        $ gomplate -i '{{ $a := slice 1 2 3 }}{{ join $a "-" }}'
+        $ gomplate -i '{{ $a := coll.Slice 1 2 3 }}{{ join $a "-" }}'
         1-2-3
   - name: conv.URL
     alias: urlParse
@@ -417,5 +417,5 @@ funcs:
         description: the inputs to be converted
     examples:
       - |
-        $ gomplate -i '{{ conv.ToStrings nil 42 true 0xF (slice 1 2 3) }}'
+        $ gomplate -i '{{ conv.ToStrings nil 42 true 0xF (coll.Slice 1 2 3) }}'
         [nil 42 true 15 [1 2 3]]
diff --git a/docs-src/content/functions/func_doc.md.tmpl b/docs-src/content/functions/func_doc.md.tmpl
@@ -1,7 +1,7 @@
 {{ define "argName" }}{{ if not .required }}[{{ .name }}]{{else}}{{ .name }}{{end}}{{ end }}
 
 {{- define "usage" }}### Usage
-{{- $arguments := index . "arguments" | default slice }}
+{{- $arguments := index . "arguments" | default coll.Slice }}
 {{ if has . "rawUsage" }}{{ .rawUsage | strings.TrimSpace }}{{ else }}
 ```go
 {{ .name }}{{ range $a := $arguments }} {{template "argName" $a }}{{end}}

diff --git a/docs-src/content/functions/math.yml b/docs-src/content/functions/math.yml
@@ -58,7 +58,7 @@ funcs:
         description: The input number. Will be converted to a `float64`, or `0` if not convertible
     examples:
       - |
-        $ gomplate -i '{{ range (slice 5.1 42 "3.14" "0xFF" "NaN" "Inf" "-0") }}ceil {{ printf "%#v" . }} = {{ math.Ceil . }}{{"\n"}}{{ end }}'
+        $ gomplate -i '{{ range (coll.Slice 5.1 42 "3.14" "0xFF" "NaN" "Inf" "-0") }}ceil {{ printf "%#v" . }} = {{ math.Ceil . }}{{"\n"}}{{ end }}'
         ceil 5.1 = 6
         ceil 42 = 42
         ceil "3.14" = 4
@@ -93,7 +93,7 @@ funcs:
         description: The input number. Will be converted to a `float64`, or `0` if not convertable
     examples:
       - |
-        $ gomplate -i '{{ range (slice 5.1 42 "3.14" "0xFF" "NaN" "Inf" "-0") }}floor {{ printf "%#v" . }} = {{ math.Floor . }}{{"\n"}}{{ end }}'
+        $ gomplate -i '{{ range (coll.Slice 5.1 42 "3.14" "0xFF" "NaN" "Inf" "-0") }}floor {{ printf "%#v" . }} = {{ math.Floor . }}{{"\n"}}{{ end }}'
         floor 5.1 = 4
         floor 42 = 42
         floor "3.14" = 3
@@ -112,7 +112,7 @@ funcs:
         description: The value to test
     examples:
       - |
-        $ gomplate -i '{{ range (slice 1.0 "-1.0" 5.1 42 "3.14" "foo" "0xFF" "NaN" "Inf" "-0") }}{{ if (math.IsFloat .) }}{{.}} is a float{{"\n"}}{{ end }}{{end}}'
+        $ gomplate -i '{{ range (coll.Slice 1.0 "-1.0" 5.1 42 "3.14" "foo" "0xFF" "NaN" "Inf" "-0") }}{{ if (math.IsFloat .) }}{{.}} is a float{{"\n"}}{{ end }}{{end}}'
         1 is a float
         -1.0 is a float
         5.1 is a float
@@ -128,7 +128,7 @@ funcs:
         description: The value to test
     examples:
       - |
-        $ gomplate -i '{{ range (slice 1.0 "-1.0" 5.1 42 "3.14" "foo" "0xFF" "NaN" "Inf" "-0") }}{{ if (math.IsInt .) }}{{.}} is an integer{{"\n"}}{{ end }}{{end}}'
+        $ gomplate -i '{{ range (coll.Slice 1.0 "-1.0" 5.1 42 "3.14" "foo" "0xFF" "NaN" "Inf" "-0") }}{{ if (math.IsInt .) }}{{.}} is an integer{{"\n"}}{{ end }}{{end}}'
         42 is an integer
         0xFF is an integer
         -0 is an integer
@@ -225,7 +225,7 @@ funcs:
         description: The input number. Will be converted to a `float64`, or `0` if not convertable
     examples:
       - |
-        $ gomplate -i '{{ range (slice -6.5 5.1 42.9 "3.5" 6.5) }}round {{ printf "%#v" . }} = {{ math.Round . }}{{"\n"}}{{ end }}'
+        $ gomplate -i '{{ range (coll.Slice -6.5 5.1 42.9 "3.5" 6.5) }}round {{ printf "%#v" . }} = {{ math.Round . }}{{"\n"}}{{ end }}'
         round -6.5 = -7
         round 5.1 = 5
         round 42.9 = 43

diff --git a/docs-src/content/functions/strings.yml b/docs-src/content/functions/strings.yml
@@ -135,7 +135,7 @@ funcs:
         description: The list to sort
     examples:
       - |
-        $ gomplate -i '{{ (slice "foo" "bar" "baz") | strings.Sort }}'
+        $ gomplate -i '{{ (coll.Slice "foo" "bar" "baz") | strings.Sort }}'
         [bar baz foo]
   - name: strings.Split
     description: |
@@ -267,7 +267,7 @@ funcs:
         description: The input to quote
     examples:
       - |
-        $ gomplate -i "{{ slice \"one word\" \"foo='bar baz'\" | shellQuote }}"
+        $ gomplate -i "{{ coll.Slice \"one word\" \"foo='bar baz'\" | shellQuote }}"
         'one word' 'foo='"'"'bar baz'"'"''
       - |
         $ gomplate -i "{{ strings.ShellQuote \"it's a banana\" }}"
@@ -518,7 +518,7 @@ funcs:
         description: the input(s) to measure
     examples:
       - |
-        $ gomplate -i '{{ range (slice "\u03a9" "\u0030" "\u1430") }}{{ printf "%s is %d bytes and %d runes\n" . (len .) (strings.RuneCount .) }}{{ end }}'
+        $ gomplate -i '{{ range (coll.Slice "\u03a9" "\u0030" "\u1430") }}{{ printf "%s is %d bytes and %d runes\n" . (len .) (strings.RuneCount .) }}{{ end }}'
         Ω is 2 bytes and 1 runes
         0 is 1 bytes and 1 runes
         ᐰ is 3 bytes and 1 runes

diff --git a/docs/content/functions/coll.md b/docs/content/functions/coll.md
@@ -60,7 +60,8 @@ Hello world!
 Hello everybody!
 ```
 
-## `coll.Slice`
+## `coll.Slice` _(deprecated)_
+**Deprecation Notice:** The `slice` alias is deprecated, use the full name `coll.Slice` instead.
 
 **Alias:** `slice`
 
@@ -81,12 +82,50 @@ coll.Slice in...
 ### Examples
 
 ```console
-$ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
+$ gomplate -i '{{ range coll.Slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
 Hello, Bart
 Hello, Lisa
 Hello, Maggie
 ```
 
+## `coll.GoSlice`
+
+This exposes the `slice` function from Go's [`text/template`](https://golang.org/pkg/text/template/#hdr-Functions)
+package. Note that using `slice` will use the `coll.Slice` function instead,
+which may not be desired.
+For some background on this, see [this issue](https://github.com/hairyhenderson/gomplate/issues/1461).
+
+Here is the upstream documentation:
+
+```
+slice returns the result of slicing its first argument by the
+remaining arguments. Thus "slice x 1 2" is, in Go syntax, x[1:2],
+while "slice x" is x[:], "slice x 1" is x[1:], and "slice x 1 2 3"
+is x[1:2:3]. The first argument must be a string, slice, or array.
+```
+
+See the [Go language spec](https://go.dev/ref/spec#Slice_expressions) for
+more details.
+
+### Usage
+
+```go
+coll.GoSlice item [indexes...]
+```
+
+### Arguments
+
+| name | description |
+|------|-------------|
+| `item` | _(required)_ the string, slice, or array to slice |
+| `indexes...` | _(optional)_ the indexes to slice the item by (0 to 3 arguments) |
+
+### Examples
+
+```console
+$ gomplate -i '{{ $l := coll.Slice "foo" "bar" "baz" }}{{ if has $l "bar" }}a{{else}}no{{end}} bar'
+```
+
 ## `coll.Has`
 
 **Alias:** `has`
@@ -109,7 +148,7 @@ coll.Has in item
 ### Examples
 
 ```console
-$ gomplate -i '{{ $l := slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar'
+$ gomplate -i '{{ $l := coll.Slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar'
 there is a bar
 ```
 ```console
@@ -259,7 +298,7 @@ list... | coll.Append value
 ### Examples
 
 ```console
-$ gomplate -i '{{ slice 1 1 2 3 | append 5 }}'
+$ gomplate -i '{{ coll.Slice 1 1 2 3 | append 5 }}'
 [1 1 2 3 5]
 ```
 
@@ -292,7 +331,7 @@ list... | coll.Prepend value
 ### Examples
 
 ```console
-$ gomplate -i '{{ slice 4 3 2 1 | prepend 5 }}'
+$ gomplate -i '{{ coll.Slice 4 3 2 1 | prepend 5 }}'
 [5 4 3 2 1]
 ```
 
@@ -322,7 +361,7 @@ list | coll.Uniq
 ### Examples
 
 ```console
-$ gomplate -i '{{ slice 1 2 3 2 3 4 1 5 | uniq }}'
+$ gomplate -i '{{ coll.Slice 1 2 3 2 3 4 1 5 | uniq }}'
 [1 2 3 4 5]
 ```
 
@@ -388,7 +427,7 @@ list | coll.Reverse
 ### Examples
 
 ```console
-$ gomplate -i '{{ slice 4 3 2 1 | reverse }}'
+$ gomplate -i '{{ coll.Slice 4 3 2 1 | reverse }}'
 [1 2 3 4]
 ```
 
@@ -423,11 +462,11 @@ list | coll.Sort [key]
 ### Examples
 
 ```console
-$ gomplate -i '{{ slice "foo" "bar" "baz" | coll.Sort }}'
+$ gomplate -i '{{ coll.Slice "foo" "bar" "baz" | coll.Sort }}'
 [bar baz foo]
 ```
 ```console
-$ gomplate -i '{{ sort (slice 3 4 1 2 5) }}'
+$ gomplate -i '{{ sort (coll.Slice 3 4 1 2 5) }}'
 [1 2 3 4 5]
 ```
 ```console

diff --git a/docs/content/functions/conv.md b/docs/content/functions/conv.md
@@ -96,7 +96,7 @@ function, as used in [Helm templates](https://docs.helm.sh/chart_template_guide#
 
 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).
+For creating arrays, see [`coll.Slice`](#coll-slice).
 
 ### Usage
 
@@ -151,7 +151,7 @@ conv.Slice in...
 ### Examples
 
 ```console
-$ gomplate -i '{{ range slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
+$ gomplate -i '{{ range coll.Slice "Bart" "Lisa" "Maggie" }}Hello, {{ . }}{{ end }}'
 Hello, Bart
 Hello, Lisa
 Hello, Maggie
@@ -180,7 +180,7 @@ conv.Has in item
 ### Examples
 
 ```console
-$ gomplate -i '{{ $l := slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar'
+$ gomplate -i '{{ $l := coll.Slice "foo" "bar" "baz" }}there is {{ if has $l "bar" }}a{{else}}no{{end}} bar'
 there is a bar
 ```
 ```console
@@ -218,7 +218,7 @@ conv.Join in sep
 ### Examples
 
 ```console
-$ gomplate -i '{{ $a := slice 1 2 3 }}{{ join $a "-" }}'
+$ gomplate -i '{{ $a := coll.Slice 1 2 3 }}{{ join $a "-" }}'
 1-2-3
 ```
 
@@ -668,6 +668,6 @@ conv.ToStrings in...
 ### Examples
 
 ```console
-$ gomplate -i '{{ conv.ToStrings nil 42 true 0xF (slice 1 2 3) }}'
+$ gomplate -i '{{ conv.ToStrings nil 42 true 0xF (coll.Slice 1 2 3) }}'
 [nil 42 true 15 [1 2 3]]
 ```