Deprecate non-pipelineable strings aliases

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

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

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 := ""