String Operators

Search…
String Operators
RegEx
This uses golangs native regex functions under the hood - See their docs for the supported syntax.
Case insensitive tip: prefix the regex with (?i) - e.g. test("(?i)cats)".
match(regEx)
This operator returns the substring match details of the given regEx.
capture(regEx)
Capture returns named RegEx capture groups in a map. Can be more convenient than match depending on what you are doing.
test(regEx)
Returns true if the string matches the RegEx, false otherwise.
sub(regEx, replacement)
Substitutes matched substrings. The first parameter is the regEx to match substrings within the original string. The second is a what to replace those matches with. This can refer to capture groups from the first RegEx.
String blocks, bash and newlines
Bash is notorious for chomping on precious trailing newline characters, making it tricky to set strings with newlines properly. In particular, the $( exp ) will trim trailing newlines.
For instance to get this yaml:
1
a: |
2
  cat
Copied!
Using $( exp ) wont work, as it will trim the trailing new line.
1
m=$(echo "cat\n") yq -n '.a = strenv(m)'
2
a: cat
Copied!
However, using printf works:
1
printf -v m "cat\n" ; m="$m" yq -n '.a = strenv(m)'
2
a: |
3
  cat
Copied!
As well as having multiline expressions:
1
m="cat
2
"  yq -n '.a = strenv(m)'
3
a: |
4
  cat
Copied!
Similarly, if you're trying to set the content from a file, and want a trailing new line:
1
IFS= read -rd '' output < <(cat my_file)
2
output=$output ./yq '.data.values = strenv(output)' first.yml
Copied!
Note that versions prior to 4.18 require the 'eval/e' command to be specified.
yq e <exp> <file>
To up (upper) case
Works with unicode characters
Given a sample.yml file of:
1
água
Copied!
then
1
yq 'upcase' sample.yml
Copied!
will output
1
ÁGUA
Copied!
To down (lower) case
Works with unicode characters
Given a sample.yml file of:
1
ÁgUA
Copied!
then
1
yq 'downcase' sample.yml
Copied!
will output
1
água
Copied!
Join strings
Given a sample.yml file of:
1
- cat
2
- meow
3
- 1
4
- null
5
- true
Copied!
then
1
yq 'join("; ")' sample.yml
Copied!
will output
1
cat; meow; 1; ; true
Copied!
Match string
Given a sample.yml file of:
1
foo bar foo
Copied!
then
1
yq 'match("foo")' sample.yml
Copied!
will output
1
string: foo
2
offset: 0
3
length: 3
4
captures: []
Copied!
Match string, case insensitive
Given a sample.yml file of:
1
foo bar FOO
Copied!
then
1
yq '[match("(?i)foo"; "g")]' sample.yml
Copied!
will output
1
- string: foo
2
  offset: 0
3
  length: 3
4
  captures: []
5
- string: FOO
6
  offset: 8
7
  length: 3
8
  captures: []
Copied!
Match with global capture group
Given a sample.yml file of:
1
abc abc
Copied!
then
1
yq '[match("(ab)(c)"; "g")]' sample.yml
Copied!
will output
1
- string: abc
2
  offset: 0
3
  length: 3
4
  captures:
5
    - string: ab
6
      offset: 0
7
      length: 2
8
    - string: c
9
      offset: 2
10
      length: 1
11
- string: abc
12
  offset: 4
13
  length: 3
14
  captures:
15
    - string: ab
16
      offset: 4
17
      length: 2
18
    - string: c
19
      offset: 6
20
      length: 1
Copied!
Match with named capture groups
Given a sample.yml file of:
1
foo bar foo foo  foo
Copied!
then
1
yq '[match("foo (?P<bar123>bar)? foo"; "g")]' sample.yml
Copied!
will output
1
- string: foo bar foo
2
  offset: 0
3
  length: 11
4
  captures:
5
    - string: bar
6
      offset: 4
7
      length: 3
8
      name: bar123
9
- string: foo  foo
10
  offset: 12
11
  length: 8
12
  captures:
13
    - string: null
14
      offset: -1
15
      length: 0
16
      name: bar123
Copied!
Capture named groups into a map
Given a sample.yml file of:
1
xyzzy-14
Copied!
then
1
yq 'capture("(?P<a>[a-z]+)-(?P<n>[0-9]+)")' sample.yml
Copied!
will output
1
a: xyzzy
2
n: "14"
Copied!
Match without global flag
Given a sample.yml file of:
1
cat cat
Copied!
then
1
yq 'match("cat")' sample.yml
Copied!
will output
1
string: cat
2
offset: 0
3
length: 3
4
captures: []
Copied!
Match with global flag
Given a sample.yml file of:
1
cat cat
Copied!
then
1
yq '[match("cat"; "g")]' sample.yml
Copied!
will output
1
- string: cat
2
  offset: 0
3
  length: 3
4
  captures: []
5
- string: cat
6
  offset: 4
7
  length: 3
8
  captures: []
Copied!
Test using regex
Like jq's equivalent, this works like match but only returns true/false instead of full match details
Given a sample.yml file of:
1
- cat
2
- dog
Copied!
then
1
yq '.[] | test("at")' sample.yml
Copied!
will output
1
true
2
false
Copied!
Substitute / Replace string
This uses golang regex, described here Note the use of |= to run in context of the current string value.
Given a sample.yml file of:
1
a: dogs are great
Copied!
then
1
yq '.a |= sub("dogs", "cats")' sample.yml
Copied!
will output
1
a: cats are great
Copied!
Substitute / Replace string with regex
This uses golang regex, described here Note the use of |= to run in context of the current string value.
Given a sample.yml file of:
1
a: cat
2
b: heat
Copied!
then
1
yq '.[] |= sub("(a)", "${1}r")' sample.yml
Copied!
will output
1
a: cart
2
b: heart
Copied!
Custom types: that are really strings
When custom tags are encountered, yq will try to decode the underlying type.
Given a sample.yml file of:
1
a: !horse cat
2
b: !goat heat
Copied!
then
1
yq '.[] |= sub("(a)", "${1}r")' sample.yml
Copied!
will output
1
a: !horse cart
2
b: !goat heart
Copied!
Split strings
Given a sample.yml file of:
1
cat; meow; 1; ; true
Copied!
then
1
yq 'split("; ")' sample.yml
Copied!
will output
1
- cat
2
- meow
3
- "1"
4
- ""
5
- "true"
Copied!
Split strings one match
Given a sample.yml file of:
1
word
Copied!
then
1
yq 'split("; ")' sample.yml
Copied!
will output
1
- word
Copied!
Split into Documents
Style
Last modified 1mo ago