Skip to content

Commit

Permalink
Merge pull request #1538 from hairyhenderson/deprecate-non-pipelineab…
Browse files Browse the repository at this point in the history
…le-strings-aliases-1535

Deprecate non-pipelineable strings aliases
  • Loading branch information
hairyhenderson authored Oct 23, 2022
2 parents 92891bd + 0680132 commit 9da2df1
Show file tree
Hide file tree
Showing 3 changed files with 151 additions and 22 deletions.
48 changes: 43 additions & 5 deletions docs-src/content/functions/strings.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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**
Expand Down Expand Up @@ -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**
Expand Down Expand Up @@ -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**
Expand All @@ -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**
Expand All @@ -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**
Expand All @@ -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**
Expand Down
61 changes: 50 additions & 11 deletions docs/content/functions/strings.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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

Expand All @@ -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 |

Expand Down Expand Up @@ -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**

Expand Down Expand Up @@ -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**

Expand Down Expand Up @@ -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**

Expand Down Expand Up @@ -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**

Expand Down Expand Up @@ -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**

Expand Down Expand Up @@ -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**

Expand Down
64 changes: 58 additions & 6 deletions funcs/strings.go
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand All @@ -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 := ""
Expand Down

0 comments on commit 9da2df1

Please sign in to comment.