yq/pkg/yqlib/doc/String Operators.md

257 lines
3.5 KiB
Markdown
Raw Normal View History

2021-01-14 04:05:50 +00:00
# String Operators
2021-01-14 03:46:50 +00:00
2021-07-09 05:33:41 +00:00
## RegEx
This uses golangs native regex functions under the hood - See https://github.com/google/re2/wiki/Syntax for the supported syntax.
## Join strings
Given a sample.yml file of:
```yaml
- cat
- meow
- 1
- null
- true
```
then
```bash
yq eval 'join("; ")' sample.yml
```
will output
```yaml
cat; meow; 1; ; true
```
## Match string
Given a sample.yml file of:
```yaml
2021-07-11 01:08:18 +00:00
foo bar foo
2021-07-09 05:33:41 +00:00
```
then
```bash
2021-07-11 01:08:18 +00:00
yq eval 'match("foo")' sample.yml
2021-07-09 05:33:41 +00:00
```
will output
```yaml
2021-07-11 01:08:18 +00:00
string: foo
offset: 0
length: 3
2021-07-09 05:33:41 +00:00
captures: []
```
## Match string, case insensitive
Given a sample.yml file of:
```yaml
2021-07-11 01:08:18 +00:00
foo bar FOO
2021-07-09 05:33:41 +00:00
```
then
```bash
2021-07-16 00:18:25 +00:00
yq eval '[match("(?i)foo"; "g")]' sample.yml
2021-07-09 05:33:41 +00:00
```
will output
```yaml
2021-07-16 00:18:25 +00:00
- string: foo
offset: 0
length: 3
captures: []
- string: FOO
offset: 8
length: 3
captures: []
2021-07-09 05:33:41 +00:00
```
## Match with capture groups
Given a sample.yml file of:
```yaml
2021-07-11 01:08:18 +00:00
abc abc
2021-07-09 05:33:41 +00:00
```
then
```bash
2021-07-16 00:18:25 +00:00
yq eval '[match("(abc)+"; "g")]' sample.yml
2021-07-09 05:33:41 +00:00
```
will output
```yaml
2021-07-16 00:18:25 +00:00
- string: abc
offset: 0
length: 3
captures:
- string: abc
offset: 0
length: 3
- string: abc
offset: 4
length: 3
captures:
- string: abc
offset: 4
length: 3
2021-07-09 05:33:41 +00:00
```
## Match with named capture groups
2021-01-14 04:05:50 +00:00
Given a sample.yml file of:
```yaml
2021-07-11 01:08:18 +00:00
foo bar foo foo foo
2021-01-14 04:05:50 +00:00
```
then
```bash
2021-07-16 00:18:25 +00:00
yq eval '[match("foo (?P<bar123>bar)? foo"; "g")]' sample.yml
2021-01-14 04:05:50 +00:00
```
will output
```yaml
2021-07-16 00:18:25 +00:00
- string: foo bar foo
offset: 0
length: 11
captures:
- string: bar
offset: 4
length: 3
name: bar123
- string: foo foo
offset: 12
length: 8
captures:
- string: null
offset: -1
length: 0
name: bar123
2021-07-11 01:08:18 +00:00
```
## Capture named groups into a map
Given a sample.yml file of:
```yaml
xyzzy-14
```
then
```bash
yq eval 'capture("(?P<a>[a-z]+)-(?P<n>[0-9]+)")' sample.yml
```
will output
```yaml
a: xyzzy
n: "14"
2021-01-14 04:05:50 +00:00
```
2021-07-09 05:33:41 +00:00
## Match without global flag
Given a sample.yml file of:
```yaml
cat cat
```
then
```bash
yq eval 'match("cat")' sample.yml
```
will output
```yaml
string: cat
offset: 0
length: 3
captures: []
```
## Match with global flag
Given a sample.yml file of:
```yaml
cat cat
```
then
```bash
2021-07-16 00:18:25 +00:00
yq eval '[match("cat"; "g")]' sample.yml
2021-07-09 05:33:41 +00:00
```
will output
```yaml
2021-07-16 00:18:25 +00:00
- string: cat
offset: 0
length: 3
captures: []
- string: cat
offset: 4
length: 3
captures: []
2021-07-09 05:33:41 +00:00
```
2021-07-09 05:54:56 +00:00
## Test using regex
Like jq'q equivalant, this works like match but only returns true/false instead of full match details
Given a sample.yml file of:
```yaml
- cat
- dog
```
then
```bash
yq eval '.[] | test("at")' sample.yml
```
will output
```yaml
true
false
```
2021-07-09 05:33:41 +00:00
## Substitute / Replace string
This uses golang regex, described [here](https://github.com/google/re2/wiki/Syntax)
Note the use of `|=` to run in context of the current string value.
Given a sample.yml file of:
```yaml
a: dogs are great
```
then
```bash
yq eval '.a |= sub("dogs", "cats")' sample.yml
```
will output
```yaml
a: cats are great
```
## Substitute / Replace string with regex
This uses golang regex, described [here](https://github.com/google/re2/wiki/Syntax)
Note the use of `|=` to run in context of the current string value.
Given a sample.yml file of:
```yaml
a: cat
b: heat
```
then
```bash
yq eval '.[] |= sub("(a)", "${1}r")' sample.yml
```
will output
```yaml
a: cart
b: heart
```
## Split strings
Given a sample.yml file of:
```yaml
cat; meow; 1; ; true
```
then
```bash
yq eval 'split("; ")' sample.yml
```
will output
```yaml
- cat
- meow
- "1"
- ""
- "true"
```
## Split strings one match
Given a sample.yml file of:
```yaml
word
```
then
```bash
yq eval 'split("; ")' sample.yml
```
will output
```yaml
- word
```