From 068013272e47549d3d6be1cf8c49b2ad6a129af9 Mon Sep 17 00:00:00 2001 From: Dave Henderson Date: Sun, 23 Oct 2022 12:42:13 -0400 Subject: [PATCH] Deprecate non-pipelineable strings aliases Signed-off-by: Dave Henderson --- docs-src/content/functions/strings.yml | 48 +++++++++++++++++-- docs/content/functions/strings.md | 61 +++++++++++++++++++----- funcs/strings.go | 64 +++++++++++++++++++++++--- 3 files changed, 151 insertions(+), 22 deletions(-) diff --git a/docs-src/content/functions/strings.yml b/docs-src/content/functions/strings.yml index b72f7f7b2..e4796bd37 100644 --- a/docs-src/content/functions/strings.yml +++ b/docs-src/content/functions/strings.yml @@ -139,12 +139,26 @@ funcs: [bar baz foo] - name: strings.Split description: | - Creates a slice by splitting a string on a given delimiter. + _Not to be confused with [`split`](#split), which is deprecated._ + + Slices `input` into the substrings separated by `separator`, returning a + slice of the substrings between those separators. If `input` does not + contain `separator` and `separator` is not empty, returns a single-element + slice whose only element is `input`. + + If `separator` is empty, it will split after each UTF-8 sequence. If + both inputs are empty (i.e. `strings.Split "" ""`), it will return an + empty slice. + + This is equivalent to [`strings.SplitN`](#strings-splitn) with a `count` + of `-1`. + + Note that the delimiter is not included in the resulting elements. pipeline: true arguments: - name: separator required: true - description: the string sequence to split + description: the delimiter to split on, can be multiple characters - name: input required: true description: the input string @@ -155,15 +169,33 @@ funcs: Hello, Bart Hello, Lisa Hello, Maggie + - | + $ gomplate -i '{{range strings.Split "," "One,Two,Three" }}{{.}}{{"\n"}}{{end}}' + One + Two + Three - name: strings.SplitN description: | - Creates a slice by splitting a string on a given delimiter. The count determines - the number of substrings to return. + _Not to be confused with [`splitN`](#splitn), which is deprecated._ + + Slices `input` into the substrings separated by `separator`, returning a + slice of the substrings between those separators. If `input` does not + contain `separator` and `separator` is not empty, returns a single-element + slice whose only element is `input`. + + The `count` determines the number of substrings to return: + + * `count > 0`: at most `count` substrings; the last substring will be the + unsplit remainder. + * `count == 0`: the result is nil (zero substrings) + * `count < 0`: all substrings + + See [`strings.Split`](#strings-split) for more details. pipeline: true arguments: - name: separator required: true - description: the string sequence to split + description: the delimiter to split on, can be multiple characters - name: count required: true description: the maximum number of substrings to return @@ -523,6 +555,7 @@ funcs: 0 is 1 bytes and 1 runes ᐰ is 3 bytes and 1 runes - name: contains + deprecated: Use [`strings.Contains`](#strings-contains) instead description: | **See [`strings.Contains`](#strings-contains) for a pipeline-compatible version** @@ -550,6 +583,7 @@ funcs: no ``` - name: hasPrefix + deprecated: Use [`strings.HasPrefix`](#strings-hasprefix) instead description: | **See [`strings.HasPrefix`](#strings-hasprefix) for a pipeline-compatible version** @@ -577,6 +611,7 @@ funcs: foo ``` - name: hasSuffix + deprecated: Use [`strings.HasSuffix`](#strings-hassuffix) instead description: | **See [`strings.HasSuffix`](#strings-hassuffix) for a pipeline-compatible version** @@ -602,6 +637,7 @@ funcs: http://example.com:80 ``` - name: split + deprecated: Use [`strings.Split`](#strings-split) instead description: | **See [`strings.Split`](#strings-split) for a pipeline-compatible version** @@ -623,6 +659,7 @@ funcs: Hello, Lisa Hello, Maggie - name: splitN + deprecated: Use [`strings.SplitN`](#strings-splitn) instead description: | **See [`strings.SplitN`](#strings-splitn) for a pipeline-compatible version** @@ -646,6 +683,7 @@ funcs: foo bar:baz - name: trim + deprecated: Use [`strings.Trim`](#strings-trim) instead description: | **See [`strings.Trim`](#strings-trim) for a pipeline-compatible version** diff --git a/docs/content/functions/strings.md b/docs/content/functions/strings.md index dc00267eb..57d3965f6 100644 --- a/docs/content/functions/strings.md +++ b/docs/content/functions/strings.md @@ -209,7 +209,21 @@ $ gomplate -i '{{ (coll.Slice "foo" "bar" "baz") | strings.Sort }}' ## `strings.Split` -Creates a slice by splitting a string on a given delimiter. +_Not to be confused with [`split`](#split), which is deprecated._ + +Slices `input` into the substrings separated by `separator`, returning a +slice of the substrings between those separators. If `input` does not +contain `separator` and `separator` is not empty, returns a single-element +slice whose only element is `input`. + +If `separator` is empty, it will split after each UTF-8 sequence. If +both inputs are empty (i.e. `strings.Split "" ""`), it will return an +empty slice. + +This is equivalent to [`strings.SplitN`](#strings-splitn) with a `count` +of `-1`. + +Note that the delimiter is not included in the resulting elements. ### Usage @@ -224,7 +238,7 @@ input | strings.Split separator | name | description | |------|-------------| -| `separator` | _(required)_ the string sequence to split | +| `separator` | _(required)_ the delimiter to split on, can be multiple characters | | `input` | _(required)_ the input string | ### Examples @@ -236,11 +250,30 @@ Hello, Bart Hello, Lisa Hello, Maggie ``` +```console +$ gomplate -i '{{range strings.Split "," "One,Two,Three" }}{{.}}{{"\n"}}{{end}}' +One +Two +Three +``` ## `strings.SplitN` -Creates a slice by splitting a string on a given delimiter. The count determines -the number of substrings to return. +_Not to be confused with [`splitN`](#splitn), which is deprecated._ + +Slices `input` into the substrings separated by `separator`, returning a +slice of the substrings between those separators. If `input` does not +contain `separator` and `separator` is not empty, returns a single-element +slice whose only element is `input`. + +The `count` determines the number of substrings to return: + +* `count > 0`: at most `count` substrings; the last substring will be the + unsplit remainder. +* `count == 0`: the result is nil (zero substrings) +* `count < 0`: all substrings + +See [`strings.Split`](#strings-split) for more details. ### Usage @@ -255,7 +288,7 @@ input | strings.SplitN separator count | name | description | |------|-------------| -| `separator` | _(required)_ the string sequence to split | +| `separator` | _(required)_ the delimiter to split on, can be multiple characters | | `count` | _(required)_ the maximum number of substrings to return | | `input` | _(required)_ the input string | @@ -877,7 +910,8 @@ $ gomplate -i '{{ range (coll.Slice "\u03a9" "\u0030" "\u1430") }}{{ printf "%s ᐰ is 3 bytes and 1 runes ``` -## `contains` +## `contains` _(deprecated)_ +**Deprecation Notice:** Use [`strings.Contains`](#strings-contains) instead **See [`strings.Contains`](#strings-contains) for a pipeline-compatible version** @@ -911,7 +945,8 @@ $ FOO=bar gomplate < input.tmpl no ``` -## `hasPrefix` +## `hasPrefix` _(deprecated)_ +**Deprecation Notice:** Use [`strings.HasPrefix`](#strings-hasprefix) instead **See [`strings.HasPrefix`](#strings-hasprefix) for a pipeline-compatible version** @@ -945,7 +980,8 @@ $ URL=https://example.com gomplate < input.tmpl foo ``` -## `hasSuffix` +## `hasSuffix` _(deprecated)_ +**Deprecation Notice:** Use [`strings.HasSuffix`](#strings-hassuffix) instead **See [`strings.HasSuffix`](#strings-hassuffix) for a pipeline-compatible version** @@ -977,7 +1013,8 @@ $ URL=http://example.com gomplate < input.tmpl http://example.com:80 ``` -## `split` +## `split` _(deprecated)_ +**Deprecation Notice:** Use [`strings.Split`](#strings-split) instead **See [`strings.Split`](#strings-split) for a pipeline-compatible version** @@ -1007,7 +1044,8 @@ Hello, Lisa Hello, Maggie ``` -## `splitN` +## `splitN` _(deprecated)_ +**Deprecation Notice:** Use [`strings.SplitN`](#strings-splitn) instead **See [`strings.SplitN`](#strings-splitn) for a pipeline-compatible version** @@ -1037,7 +1075,8 @@ foo bar:baz ``` -## `trim` +## `trim` _(deprecated)_ +**Deprecation Notice:** Use [`strings.Trim`](#strings-trim) instead **See [`strings.Trim`](#strings-trim) for a pipeline-compatible version** diff --git a/funcs/strings.go b/funcs/strings.go index 65e4a6f29..ab59c0c9f 100644 --- a/funcs/strings.go +++ b/funcs/strings.go @@ -58,12 +58,12 @@ func CreateStringFuncs(ctx context.Context) map[string]interface{} { f["squote"] = ns.Squote // these are legacy aliases with non-pipelinable arg order - f["contains"] = strings.Contains - f["hasPrefix"] = strings.HasPrefix - f["hasSuffix"] = strings.HasSuffix - f["split"] = strings.Split - f["splitN"] = strings.SplitN - f["trim"] = strings.Trim + f["contains"] = ns.oldContains + f["hasPrefix"] = ns.oldHasPrefix + f["hasSuffix"] = ns.oldHasSuffix + f["split"] = ns.oldSplit + f["splitN"] = ns.oldSplitN + f["trim"] = ns.oldTrim return f } @@ -77,6 +77,58 @@ type StringFuncs struct { tag language.Tag } +// ---- legacy aliases with non-pipelinable arg order + +// oldContains - +// +// Deprecated: use [strings.Contains] instead +func (f *StringFuncs) oldContains(s, substr string) bool { + deprecated.WarnDeprecated(f.ctx, "contains is deprecated - use strings.Contains instead") + return strings.Contains(s, substr) +} + +// oldHasPrefix - +// +// Deprecated: use [strings.HasPrefix] instead +func (f *StringFuncs) oldHasPrefix(s, prefix string) bool { + deprecated.WarnDeprecated(f.ctx, "hasPrefix is deprecated - use strings.HasPrefix instead") + return strings.HasPrefix(s, prefix) +} + +// oldHasSuffix - +// +// Deprecated: use [strings.HasSuffix] instead +func (f *StringFuncs) oldHasSuffix(s, suffix string) bool { + deprecated.WarnDeprecated(f.ctx, "hasSuffix is deprecated - use strings.HasSuffix instead") + return strings.HasSuffix(s, suffix) +} + +// oldSplit - +// +// Deprecated: use [strings.Split] instead +func (f *StringFuncs) oldSplit(s, sep string) []string { + deprecated.WarnDeprecated(f.ctx, "split is deprecated - use strings.Split instead") + return strings.Split(s, sep) +} + +// oldSplitN - +// +// Deprecated: use [strings.SplitN] instead +func (f *StringFuncs) oldSplitN(s, sep string, n int) []string { + deprecated.WarnDeprecated(f.ctx, "splitN is deprecated - use strings.SplitN instead") + return strings.SplitN(s, sep, n) +} + +// oldTrim - +// +// Deprecated: use [strings.Trim] instead +func (f *StringFuncs) oldTrim(s, cutset string) string { + deprecated.WarnDeprecated(f.ctx, "trim is deprecated - use strings.Trim instead") + return strings.Trim(s, cutset) +} + +// ---- + // Abbrev - func (StringFuncs) Abbrev(args ...interface{}) (string, error) { str := ""