From 5184fa4494d93c7dbe016c41ae282d016aa9590e Mon Sep 17 00:00:00 2001 From: Dave Henderson Date: Tue, 26 Jul 2022 13:29:27 -0400 Subject: Add coll.GoSlice and deprecate slice alias Signed-off-by: Dave Henderson --- docs-src/content/functions/coll.yml | 46 ++++++++++++++++++++++++----- docs-src/content/functions/conv.yml | 10 +++---- docs-src/content/functions/func_doc.md.tmpl | 2 +- docs-src/content/functions/math.yml | 10 +++---- docs-src/content/functions/strings.yml | 6 ++-- 5 files changed, 52 insertions(+), 22 deletions(-) (limited to 'docs-src/content') diff --git a/docs-src/content/functions/coll.yml b/docs-src/content/functions/coll.yml index cf267fe1..a82e3f59 100644 --- 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 < in.json diff --git a/docs-src/content/functions/conv.yml b/docs-src/content/functions/conv.yml index 10aa2fc3..884ba35b 100644 --- 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 index 0e8668de..36adc712 100644 --- 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 index 385b53d0..99c2a846 100644 --- 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 index bdc127aa..b72f7f7b 100644 --- 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 -- cgit v1.2.3