suyiiyii/yq
1
0
Fork 0
mirror of https://github.com/mikefarah/yq.git synced 2025-01-27 08:55:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update document generation script

Browse Source
This commit is contained in:
Mike Farah 2021-11-03 15:00:28 +11:00
parent 5bedd759a8
commit a41131816a
34 changed files with 111 additions and 1337 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
operators/anchor-and-alias-operators.md
View File

@ -4,12 +4,11 @@ Use the `alias` and `anchor` operators to read and write yaml aliases and anchor
`yq` supports merge aliases (like `<<: *blah`) however this is no longer in the standard yaml spec (1.2) and so `yq` will automatically add the `!!merge` tag to these nodes as it is effectively a custom tag. `yq` supports merge aliases (like `<<: *blah`) however this is no longer in the standard yaml spec (1.2) and so `yq` will automatically add the `!!merge` tag to these nodes as it is effectively a custom tag.
## Merge one map
see [https://yaml.org/type/merge.html](https://yaml.org/type/merge.html) ## Merge one map
see https://yaml.org/type/merge.html
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- &CENTER - &CENTER
x: 1 x: 1
@ -24,15 +23,11 @@ Given a sample.yml file of:
- !!merge <<: *CENTER - !!merge <<: *CENTER
r: 10 r: 10
``` ```
then then
```bash ```bash
yq eval '.[4] | explode(.)' sample.yml yq eval '.[4] | explode(.)' sample.yml
``` ```
will output will output
```yaml ```yaml
x: 1 x: 1
y: 2 y: 2
@ -40,11 +35,9 @@ r: 10
``` ```
## Merge multiple maps ## Merge multiple maps
see https://yaml.org/type/merge.html
see [https://yaml.org/type/merge.html](https://yaml.org/type/merge.html)
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- &CENTER - &CENTER
x: 1 x: 1
@ -60,15 +53,11 @@ Given a sample.yml file of:
- *CENTER - *CENTER
- *BIG - *BIG
``` ```
then then
```bash ```bash
yq eval '.[4] | explode(.)' sample.yml yq eval '.[4] | explode(.)' sample.yml
``` ```
will output will output
```yaml ```yaml
r: 10 r: 10
x: 1 x: 1
@ -76,11 +65,9 @@ y: 2
``` ```
## Override ## Override
see https://yaml.org/type/merge.html
see [https://yaml.org/type/merge.html](https://yaml.org/type/merge.html)
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- &CENTER - &CENTER
x: 1 x: 1
@ -98,15 +85,11 @@ Given a sample.yml file of:
- *SMALL - *SMALL
x: 1 x: 1
``` ```
then then
```bash ```bash
yq eval '.[4] | explode(.)' sample.yml yq eval '.[4] | explode(.)' sample.yml
``` ```
will output will output
```yaml ```yaml
r: 10 r: 10
x: 1 x: 1
@ -114,173 +97,125 @@ y: 2
``` ```
## Get anchor ## Get anchor
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: &billyBob cat a: &billyBob cat
``` ```
then then
```bash ```bash
yq eval '.a | anchor' sample.yml yq eval '.a | anchor' sample.yml
``` ```
will output will output
```yaml ```yaml
billyBob billyBob
``` ```
## Set anchor ## Set anchor
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval '.a anchor = "foobar"' sample.yml yq eval '.a anchor = "foobar"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: &foobar cat a: &foobar cat
``` ```
## Set anchor relatively using assign-update ## Set anchor relatively using assign-update
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: cat b: cat
``` ```
then then
```bash ```bash
yq eval '.a anchor |= .b' sample.yml yq eval '.a anchor |= .b' sample.yml
``` ```
will output will output
```yaml ```yaml
a: &cat a: &cat
b: cat b: cat
``` ```
## Get alias ## Get alias
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
b: &billyBob meow b: &billyBob meow
a: *billyBob a: *billyBob
``` ```
then then
```bash ```bash
yq eval '.a | alias' sample.yml yq eval '.a | alias' sample.yml
``` ```
will output will output
```yaml ```yaml
billyBob billyBob
``` ```
## Set alias ## Set alias
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
b: &meow purr b: &meow purr
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval '.a alias = "meow"' sample.yml yq eval '.a alias = "meow"' sample.yml
``` ```
will output will output
```yaml ```yaml
b: &meow purr b: &meow purr
a: *meow a: *meow
``` ```
## Set alias to blank does nothing ## Set alias to blank does nothing
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
b: &meow purr b: &meow purr
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval '.a alias = ""' sample.yml yq eval '.a alias = ""' sample.yml
``` ```
will output will output
```yaml ```yaml
b: &meow purr b: &meow purr
a: cat a: cat
``` ```
## Set alias relatively using assign-update ## Set alias relatively using assign-update
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
b: &meow purr b: &meow purr
a: a:
f: meow f: meow
``` ```
then then
```bash ```bash
yq eval '.a alias |= .f' sample.yml yq eval '.a alias |= .f' sample.yml
``` ```
will output will output
```yaml ```yaml
b: &meow purr b: &meow purr
a: *meow a: *meow
``` ```
## Explode alias and anchor ## Explode alias and anchor
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
f: f:
a: &a cat a: &a cat
b: *a b: *a
``` ```
then then
```bash ```bash
yq eval 'explode(.f)' sample.yml yq eval 'explode(.f)' sample.yml
``` ```
will output will output
```yaml ```yaml
f: f:
a: cat a: cat
@ -288,43 +223,31 @@ f:
``` ```
## Explode with no aliases or anchors ## Explode with no aliases or anchors
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: mike a: mike
``` ```
then then
```bash ```bash
yq eval 'explode(.a)' sample.yml yq eval 'explode(.a)' sample.yml
``` ```
will output will output
```yaml ```yaml
a: mike a: mike
``` ```
## Explode with alias keys ## Explode with alias keys
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
f: f:
a: &a cat a: &a cat
*a: b *a: b
``` ```
then then
```bash ```bash
yq eval 'explode(.f)' sample.yml yq eval 'explode(.f)' sample.yml
``` ```
will output will output
```yaml ```yaml
f: f:
a: cat a: cat
@ -332,9 +255,7 @@ f:
``` ```
## Explode with merge anchors ## Explode with merge anchors
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo: &foo foo: &foo
a: foo_a a: foo_a
@ -355,15 +276,11 @@ foobar:
!!merge <<: *foo !!merge <<: *foo
thing: foobar_thing thing: foobar_thing
``` ```
then then
```bash ```bash
yq eval 'explode(.)' sample.yml yq eval 'explode(.)' sample.yml
``` ```
will output will output
```yaml ```yaml
foo: foo:
a: foo_a a: foo_a
@ -385,11 +302,9 @@ foobar:
``` ```
## Dereference and update a field ## Dereference and update a field
`Use explode with multiply to dereference an object
\`Use explode with multiply to dereference an object
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
item_value: &item_value item_value: &item_value
value: true value: true
@ -400,15 +315,11 @@ thingTwo:
name: item_2 name: item_2
!!merge <<: *item_value !!merge <<: *item_value
``` ```
then then
```bash ```bash
yq eval '.thingOne |= explode(.) * {"value": false}' sample.yml yq eval '.thingOne |= explode(.) * {"value": false}' sample.yml
``` ```
will output will output
```yaml ```yaml
item_value: &item_value item_value: &item_value
value: true value: true
@ -419,3 +330,4 @@ thingTwo:
name: item_2 name: item_2
!!merge <<: *item_value !!merge <<: *item_value
``` ```

82
operators/assign-update.md
View File

@ -1,15 +1,18 @@
# Assign (Update) # Assign (Update)
This operator is used to update node values. It can be used in either the:
### plain form: `=`
Which will assign the LHS node values to the RHS node values. The RHS expression is run against the matching nodes in the pipeline.
### relative form: `|=`
This will do a similar thing to the plain form, however, the RHS expression is run against _the LHS nodes_. This is useful for updating values based on old values, e.g. increment.
## Create yaml file ## Create yaml file
Running Running
```bash ```bash
yq eval --null-input '.a.b = "cat" | .x = "frog"' yq eval --null-input '.a.b = "cat" | .x = "frog"'
``` ```
will output will output
```yaml ```yaml
a: a:
b: cat b: cat
@ -17,46 +20,34 @@ x: frog
``` ```
## Update node to be the child value ## Update node to be the child value
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: b:
g: foof g: foof
``` ```
then then
```bash ```bash
yq eval '.a |= .b' sample.yml yq eval '.a |= .b' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
g: foof g: foof
``` ```
## Double elements in an array ## Double elements in an array
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- 1 - 1
- 2 - 2
- 3 - 3
``` ```
then then
```bash ```bash
yq eval '.[] |= . * 2' sample.yml yq eval '.[] |= . * 2' sample.yml
``` ```
will output will output
```yaml ```yaml
- 2 - 2
- 4 - 4
@ -64,75 +55,55 @@ will output
``` ```
## Update node from another file ## Update node from another file
Note this will also work when the second file is a scalar (string/number) Note this will also work when the second file is a scalar (string/number)
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: apples a: apples
``` ```
And another sample another.yml file of: And another sample another.yml file of:
```yaml ```yaml
b: bob b: bob
``` ```
then then
```bash ```bash
yq eval-all 'select(fileIndex==0).a = select(fileIndex==1) | select(fileIndex==0)' sample.yml another.yml yq eval-all 'select(fileIndex==0).a = select(fileIndex==1) | select(fileIndex==0)' sample.yml another.yml
``` ```
will output will output
```yaml ```yaml
a: a:
b: bob b: bob
``` ```
## Update node to be the sibling value ## Update node to be the sibling value
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: child b: child
b: sibling b: sibling
``` ```
then then
```bash ```bash
yq eval '.a = .b' sample.yml yq eval '.a = .b' sample.yml
``` ```
will output will output
```yaml ```yaml
a: sibling a: sibling
b: sibling b: sibling
``` ```
## Updated multiple paths ## Updated multiple paths
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: fieldA a: fieldA
b: fieldB b: fieldB
c: fieldC c: fieldC
``` ```
then then
```bash ```bash
yq eval '(.a, .c) = "potatoe"' sample.yml yq eval '(.a, .c) = "potatoe"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: potatoe a: potatoe
b: fieldB b: fieldB
@ -140,69 +111,53 @@ c: potatoe
``` ```
## Update string value ## Update string value
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: apple b: apple
``` ```
then then
```bash ```bash
yq eval '.a.b = "frog"' sample.yml yq eval '.a.b = "frog"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
b: frog b: frog
``` ```
## Update string value via |= ## Update string value via |=
Note there is no difference between `=` and `|=` when the RHS is a scalar Note there is no difference between `=` and `|=` when the RHS is a scalar
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: apple b: apple
``` ```
then then
```bash ```bash
yq eval '.a.b |= "frog"' sample.yml yq eval '.a.b |= "frog"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
b: frog b: frog
``` ```
## Update selected results ## Update deeply selected results
Note that the LHS is wrapped in brackets! This is to ensure we dont first filter out the yaml and then update the snippet.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: apple b: apple
c: cactus c: cactus
``` ```
then then
```bash ```bash
yq eval '(.a[] | select(. == "apple")) = "frog"' sample.yml yq eval '(.a[] | select(. == "apple")) = "frog"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
b: frog b: frog
@ -210,23 +165,17 @@ a:
``` ```
## Update array values ## Update array values
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- candy - candy
- apple - apple
- sandy - sandy
``` ```
then then
```bash ```bash
yq eval '(.[] | select(. == "*andy")) = "bogs"' sample.yml yq eval '(.[] | select(. == "*andy")) = "bogs"' sample.yml
``` ```
will output will output
```yaml ```yaml
- bogs - bogs
- apple - apple
@ -234,41 +183,30 @@ will output
``` ```
## Update empty object ## Update empty object
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
{} {}
``` ```
then then
```bash ```bash
yq eval '.a.b |= "bogs"' sample.yml yq eval '.a.b |= "bogs"' sample.yml
``` ```
will output will output
```yaml ```yaml
{a: {b: bogs}} {a: {b: bogs}}
``` ```
## Update empty object and array ## Update empty object and array
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
{} {}
``` ```
then then
```bash ```bash
yq eval '.a.b.[0] |= "bogs"' sample.yml yq eval '.a.b.[0] |= "bogs"' sample.yml
``` ```
will output will output
```yaml ```yaml
{a: {b: [bogs]}} {a: {b: [bogs]}}
``` ```

79
operators/boolean-operators.md
View File

@ -11,37 +11,27 @@ The `or` and `and` operators take two parameters and return a boolean result.
These are most commonly used with the `select` operator to filter particular nodes. These are most commonly used with the `select` operator to filter particular nodes.
## `or` example ## `or` example
Running Running
```bash ```bash
yq eval --null-input 'true or false' yq eval --null-input 'true or false'
``` ```
will output will output
```yaml ```yaml
true true
``` ```
## `and` example ## `and` example
Running Running
```bash ```bash
yq eval --null-input 'true and false' yq eval --null-input 'true and false'
``` ```
will output will output
```yaml ```yaml
false false
``` ```
## Matching nodes with select, equals and or ## Matching nodes with select, equals and or
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- a: bird - a: bird
b: dog b: dog
@ -50,15 +40,11 @@ Given a sample.yml file of:
- a: cat - a: cat
b: fly b: fly
``` ```
then then
```bash ```bash
yq eval '[.[] | select(.a == "cat" or .b == "dog")]' sample.yml yq eval '[.[] | select(.a == "cat" or .b == "dog")]' sample.yml
``` ```
will output will output
```yaml ```yaml
- a: bird - a: bird
b: dog b: dog
@ -67,50 +53,36 @@ will output
``` ```
## `any` returns true if any boolean in a given array is true ## `any` returns true if any boolean in a given array is true
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- false - false
- true - true
``` ```
then then
```bash ```bash
yq eval 'any' sample.yml yq eval 'any' sample.yml
``` ```
will output will output
```yaml ```yaml
true true
``` ```
## `any` returns false for an empty array ## `any` returns false for an empty array
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
[] []
``` ```
then then
```bash ```bash
yq eval 'any' sample.yml yq eval 'any' sample.yml
``` ```
will output will output
```yaml ```yaml
false false
``` ```
## `any_c` returns true if any element in the array is true for the given condition. ## `any_c` returns true if any element in the array is true for the given condition.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
- rad - rad
@ -119,65 +91,47 @@ b:
- meh - meh
- whatever - whatever
``` ```
then then
```bash ```bash
yq eval '.[] |= any_c(. == "awesome")' sample.yml yq eval '.[] |= any_c(. == "awesome")' sample.yml
``` ```
will output will output
```yaml ```yaml
a: true a: true
b: false b: false
``` ```
## `all` returns true if all booleans in a given array are true ## `all` returns true if all booleans in a given array are true
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- true - true
- true - true
``` ```
then then
```bash ```bash
yq eval 'all' sample.yml yq eval 'all' sample.yml
``` ```
will output will output
```yaml ```yaml
true true
``` ```
## `all` returns true for an empty array ## `all` returns true for an empty array
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
[] []
``` ```
then then
```bash ```bash
yq eval 'all' sample.yml yq eval 'all' sample.yml
``` ```
will output will output
```yaml ```yaml
true true
``` ```
## `all_c` returns true if all elements in the array are true for the given condition. ## `all_c` returns true if all elements in the array are true for the given condition.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
- rad - rad
@ -186,114 +140,83 @@ b:
- meh - meh
- 12 - 12
``` ```
then then
```bash ```bash
yq eval '.[] |= all_c(tag == "!!str")' sample.yml yq eval '.[] |= all_c(tag == "!!str")' sample.yml
``` ```
will output will output
```yaml ```yaml
a: true a: true
b: false b: false
``` ```
## Not true is false ## Not true is false
Running Running
```bash ```bash
yq eval --null-input 'true | not' yq eval --null-input 'true | not'
``` ```
will output will output
```yaml ```yaml
false false
``` ```
## Not false is true ## Not false is true
Running Running
```bash ```bash
yq eval --null-input 'false | not' yq eval --null-input 'false | not'
``` ```
will output will output
```yaml ```yaml
true true
``` ```
## String values considered to be true ## String values considered to be true
Running Running
```bash ```bash
yq eval --null-input '"cat" | not' yq eval --null-input '"cat" | not'
``` ```
will output will output
```yaml ```yaml
false false
``` ```
## Empty string value considered to be true ## Empty string value considered to be true
Running Running
```bash ```bash
yq eval --null-input '"" | not' yq eval --null-input '"" | not'
``` ```
will output will output
```yaml ```yaml
false false
``` ```
## Numbers are considered to be true ## Numbers are considered to be true
Running Running
```bash ```bash
yq eval --null-input '1 | not' yq eval --null-input '1 | not'
``` ```
will output will output
```yaml ```yaml
false false
``` ```
## Zero is considered to be true ## Zero is considered to be true
Running Running
```bash ```bash
yq eval --null-input '0 | not' yq eval --null-input '0 | not'
``` ```
will output will output
```yaml ```yaml
false false
``` ```
## Null is considered to be false ## Null is considered to be false
Running Running
```bash ```bash
yq eval --null-input '~ | not' yq eval --null-input '~ | not'
``` ```
will output will output
```yaml ```yaml
true true
``` ```

16
operators/collect-into-array.md
View File

@ -2,52 +2,40 @@
This creates an array using the expression between the square brackets. This creates an array using the expression between the square brackets.
## Collect empty ## Collect empty
Running Running
```bash ```bash
yq eval --null-input '[]' yq eval --null-input '[]'
``` ```
will output will output
```yaml ```yaml
[] []
``` ```
## Collect single ## Collect single
Running Running
```bash ```bash
yq eval --null-input '["cat"]' yq eval --null-input '["cat"]'
``` ```
will output will output
```yaml ```yaml
- cat - cat
``` ```
## Collect many ## Collect many
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: dog b: dog
``` ```
then then
```bash ```bash
yq eval '[.a, .b]' sample.yml yq eval '[.a, .b]' sample.yml
``` ```
will output will output
```yaml ```yaml
- cat - cat
- dog - dog
``` ```

67
operators/comment-operators.md
View File

@ -5,71 +5,51 @@ Use these comment operators to set or retrieve comments.
Like the `=` and `|=` assign operators, the same syntax applies when updating comments: Like the `=` and `|=` assign operators, the same syntax applies when updating comments:
### plain form: `=` ### plain form: `=`
This will assign the LHS nodes comments to the expression on the RHS. The RHS is run against the matching nodes in the pipeline This will assign the LHS nodes comments to the expression on the RHS. The RHS is run against the matching nodes in the pipeline
### relative form: `|=` ### relative form: `|=`
Similar to the plain form, however the RHS evaluates against each matching LHS node! This is useful if you want to set the comments as a relative expression of the node, for instance its value or path. Similar to the plain form, however the RHS evaluates against each matching LHS node! This is useful if you want to set the comments as a relative expression of the node, for instance its value or path.
## Set line comment ## Set line comment
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval '.a lineComment="single"' sample.yml yq eval '.a lineComment="single"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cat # single a: cat # single
``` ```
## Use update assign to perform relative updates ## Use update assign to perform relative updates
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: dog b: dog
``` ```
then then
```bash ```bash
yq eval '.. lineComment |= .' sample.yml yq eval '.. lineComment |= .' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cat # cat a: cat # cat
b: dog # dog b: dog # dog
``` ```
## Set head comment ## Set head comment
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval '. headComment="single"' sample.yml yq eval '. headComment="single"' sample.yml
``` ```
will output will output
```yaml ```yaml
# single # single
@ -77,21 +57,15 @@ a: cat
``` ```
## Set foot comment, using an expression ## Set foot comment, using an expression
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval '. footComment=.a' sample.yml yq eval '. footComment=.a' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cat a: cat
@ -99,106 +73,87 @@ a: cat
``` ```
## Remove comment ## Remove comment
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat # comment a: cat # comment
b: dog # leave this b: dog # leave this
``` ```
then then
```bash ```bash
yq eval '.a lineComment=""' sample.yml yq eval '.a lineComment=""' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cat a: cat
b: dog # leave this b: dog # leave this
``` ```
## Remove (strip) all comments ## Remove (strip) all comments
Note the use of `...` to ensure key nodes are included. Note the use of `...` to ensure key nodes are included.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat # comment a: cat # comment
# great # great
b: # key comment b: # key comment
``` ```
then then
```bash ```bash
yq eval '... comments=""' sample.yml yq eval '... comments=""' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cat a: cat
b: b:
``` ```
## Get line comment ## Get line comment
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat # meow a: cat # meow
``` ```
then then
```bash ```bash
yq eval '.a | lineComment' sample.yml yq eval '.a | lineComment' sample.yml
``` ```
will output will output
```yaml ```yaml
meow meow
``` ```
## Get head comment ## Get head comment
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
# welcome!
a: cat # meow a: cat # meow
# have a great day
``` ```
then then
```bash ```bash
yq eval '. | headComment' sample.yml yq eval '. | headComment' sample.yml
``` ```
will output will output
```yaml ```yaml
welcome!
``` ```
## Get foot comment ## Get foot comment
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
# welcome!
a: cat # meow a: cat # meow
# have a great day
``` ```
then then
```bash ```bash
yq eval '. | footComment' sample.yml yq eval '. | footComment' sample.yml
``` ```
will output will output
```yaml ```yaml
have a great day
``` ```

33
operators/contains.md
View File

@ -1,33 +1,27 @@
# Contains # Contains
## Array contains array This returns `true` if the context contains the passed in parameter, and false otherwise.
## Array contains array
Array is equal or subset of Array is equal or subset of
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- foobar - foobar
- foobaz - foobaz
- blarp - blarp
``` ```
then then
```bash ```bash
yq eval 'contains(["baz", "bar"])' sample.yml yq eval 'contains(["baz", "bar"])' sample.yml
``` ```
will output will output
```yaml ```yaml
true true
``` ```
## Object included in array ## Object included in array
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
"foo": 12 "foo": 12
"bar": "bar":
@ -36,23 +30,17 @@ Given a sample.yml file of:
- "barp": 12 - "barp": 12
"blip": 13 "blip": 13
``` ```
then then
```bash ```bash
yq eval 'contains({"bar": [{"barp": 12}]})' sample.yml yq eval 'contains({"bar": [{"barp": 12}]})' sample.yml
``` ```
will output will output
```yaml ```yaml
true true
``` ```
## Object not included in array ## Object not included in array
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
"foo": 12 "foo": 12
"bar": "bar":
@ -61,55 +49,40 @@ Given a sample.yml file of:
- "barp": 12 - "barp": 12
"blip": 13 "blip": 13
``` ```
then then
```bash ```bash
yq eval 'contains({"foo": 12, "bar": [{"barp": 15}]})' sample.yml yq eval 'contains({"foo": 12, "bar": [{"barp": 15}]})' sample.yml
``` ```
will output will output
```yaml ```yaml
false false
``` ```
## String contains substring ## String contains substring
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foobar foobar
``` ```
then then
```bash ```bash
yq eval 'contains("bar")' sample.yml yq eval 'contains("bar")' sample.yml
``` ```
will output will output
```yaml ```yaml
true true
``` ```
## String equals string ## String equals string
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
meow meow
``` ```
then then
```bash ```bash
yq eval 'contains("meow")' sample.yml yq eval 'contains("meow")' sample.yml
``` ```
will output will output
```yaml ```yaml
true true
``` ```

27
operators/create-collect-into-object.md
View File

@ -3,68 +3,50 @@
This is used to construct objects (or maps). This can be used against existing yaml, or to create fresh yaml documents. This is used to construct objects (or maps). This can be used against existing yaml, or to create fresh yaml documents.
## Collect empty object ## Collect empty object
Running Running
```bash ```bash
yq eval --null-input '{}' yq eval --null-input '{}'
``` ```
will output will output
```yaml ```yaml
{} {}
``` ```
## Wrap (prefix) existing object ## Wrap (prefix) existing object
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
name: Mike name: Mike
``` ```
then then
```bash ```bash
yq eval '{"wrap": .}' sample.yml yq eval '{"wrap": .}' sample.yml
``` ```
will output will output
```yaml ```yaml
wrap: wrap:
name: Mike name: Mike
``` ```
## Using splat to create multiple objects ## Using splat to create multiple objects
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
name: Mike name: Mike
pets: pets:
- cat - cat
- dog - dog
``` ```
then then
```bash ```bash
yq eval '{.name: .pets.[]}' sample.yml yq eval '{.name: .pets.[]}' sample.yml
``` ```
will output will output
```yaml ```yaml
Mike: cat Mike: cat
Mike: dog Mike: dog
``` ```
## Working with multiple documents ## Working with multiple documents
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
name: Mike name: Mike
pets: pets:
@ -76,15 +58,11 @@ pets:
- monkey - monkey
- sheep - sheep
``` ```
then then
```bash ```bash
yq eval '{.name: .pets.[]}' sample.yml yq eval '{.name: .pets.[]}' sample.yml
``` ```
will output will output
```yaml ```yaml
Mike: cat Mike: cat
Mike: dog Mike: dog
@ -93,15 +71,12 @@ Rosey: sheep
``` ```
## Creating yaml from scratch ## Creating yaml from scratch
Running Running
```bash ```bash
yq eval --null-input '{"wrap": "frog"}' yq eval --null-input '{"wrap": "frog"}'
``` ```
will output will output
```yaml ```yaml
wrap: frog wrap: frog
``` ```

43
operators/delete.md
View File

@ -3,141 +3,103 @@
Deletes matching entries in maps or arrays. Deletes matching entries in maps or arrays.
## Delete entry in map ## Delete entry in map
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: dog b: dog
``` ```
then then
```bash ```bash
yq eval 'del(.b)' sample.yml yq eval 'del(.b)' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cat a: cat
``` ```
## Delete nested entry in map ## Delete nested entry in map
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
a1: fred a1: fred
a2: frood a2: frood
``` ```
then then
```bash ```bash
yq eval 'del(.a.a1)' sample.yml yq eval 'del(.a.a1)' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
a2: frood a2: frood
``` ```
## Delete entry in array ## Delete entry in array
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- 1 - 1
- 2 - 2
- 3 - 3
``` ```
then then
```bash ```bash
yq eval 'del(.[1])' sample.yml yq eval 'del(.[1])' sample.yml
``` ```
will output will output
```yaml ```yaml
- 1 - 1
- 3 - 3
``` ```
## Delete nested entry in array ## Delete nested entry in array
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- a: cat - a: cat
b: dog b: dog
``` ```
then then
```bash ```bash
yq eval 'del(.[0].a)' sample.yml yq eval 'del(.[0].a)' sample.yml
``` ```
will output will output
```yaml ```yaml
- b: dog - b: dog
``` ```
## Delete no matches ## Delete no matches
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: dog b: dog
``` ```
then then
```bash ```bash
yq eval 'del(.c)' sample.yml yq eval 'del(.c)' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cat a: cat
b: dog b: dog
``` ```
## Delete matching entries ## Delete matching entries
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: dog b: dog
c: bat c: bat
``` ```
then then
```bash ```bash
yq eval 'del( .[] | select(. == "*at") )' sample.yml yq eval 'del( .[] | select(. == "*at") )' sample.yml
``` ```
will output will output
```yaml ```yaml
b: dog b: dog
``` ```
## Recursively delete matching keys ## Recursively delete matching keys
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
name: frog name: frog
@ -145,17 +107,14 @@ a:
name: blog name: blog
age: 12 age: 12
``` ```
then then
```bash ```bash
yq eval 'del(.. | select(has("name")).name)' sample.yml yq eval 'del(.. | select(has("name")).name)' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
b: b:
age: 12 age: 12
``` ```

31
operators/document-index.md
View File

@ -3,23 +3,17 @@
Use the `documentIndex` operator (or the `di` shorthand) to select nodes of a particular document. Use the `documentIndex` operator (or the `di` shorthand) to select nodes of a particular document.
## Retrieve a document index ## Retrieve a document index
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
--- ---
a: frog a: frog
``` ```
then then
```bash ```bash
yq eval '.a | documentIndex' sample.yml yq eval '.a | documentIndex' sample.yml
``` ```
will output will output
```yaml ```yaml
0 0
--- ---
@ -27,23 +21,17 @@ will output
``` ```
## Retrieve a document index, shorthand ## Retrieve a document index, shorthand
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
--- ---
a: frog a: frog
``` ```
then then
```bash ```bash
yq eval '.a | di' sample.yml yq eval '.a | di' sample.yml
``` ```
will output will output
```yaml ```yaml
0 0
--- ---
@ -51,70 +39,53 @@ will output
``` ```
## Filter by document index ## Filter by document index
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
--- ---
a: frog a: frog
``` ```
then then
```bash ```bash
yq eval 'select(documentIndex == 1)' sample.yml yq eval 'select(documentIndex == 1)' sample.yml
``` ```
will output will output
```yaml ```yaml
a: frog a: frog
``` ```
## Filter by document index shorthand ## Filter by document index shorthand
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
--- ---
a: frog a: frog
``` ```
then then
```bash ```bash
yq eval 'select(di == 1)' sample.yml yq eval 'select(di == 1)' sample.yml
``` ```
will output will output
```yaml ```yaml
a: frog a: frog
``` ```
## Print Document Index with matches ## Print Document Index with matches
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
--- ---
a: frog a: frog
``` ```
then then
```bash ```bash
yq eval '.a | ({"match": ., "doc": documentIndex})' sample.yml yq eval '.a | ({"match": ., "doc": documentIndex})' sample.yml
``` ```
will output will output
```yaml ```yaml
match: cat match: cat
doc: 0 doc: 0
match: frog match: frog
doc: 1 doc: 1
``` ```

59
operators/entries.md
View File

@ -2,23 +2,17 @@
Similar to the same named functions in `jq` these functions convert to/from an object and an array of key-value pairs. This is most useful for performing operations on keys of maps. Similar to the same named functions in `jq` these functions convert to/from an object and an array of key-value pairs. This is most useful for performing operations on keys of maps.
## to\_entries Map ## to_entries Map
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: 1 a: 1
b: 2 b: 2
``` ```
then then
```bash ```bash
yq eval 'to_entries' sample.yml yq eval 'to_entries' sample.yml
``` ```
will output will output
```yaml ```yaml
- key: a - key: a
value: 1 value: 1
@ -26,23 +20,17 @@ will output
value: 2 value: 2
``` ```
## to\_entries Array ## to_entries Array
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- a - a
- b - b
``` ```
then then
```bash ```bash
yq eval 'to_entries' sample.yml yq eval 'to_entries' sample.yml
``` ```
will output will output
```yaml ```yaml
- key: 0 - key: 0
value: a value: a
@ -50,113 +38,84 @@ will output
value: b value: b
``` ```
## to\_entries null ## to_entries null
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
null null
``` ```
then then
```bash ```bash
yq eval 'to_entries' sample.yml yq eval 'to_entries' sample.yml
``` ```
will output will output
```yaml ```yaml
``` ```
## from\_entries map ## from_entries map
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: 1 a: 1
b: 2 b: 2
``` ```
then then
```bash ```bash
yq eval 'to_entries | from_entries' sample.yml yq eval 'to_entries | from_entries' sample.yml
``` ```
will output will output
```yaml ```yaml
a: 1 a: 1
b: 2 b: 2
``` ```
## from\_entries with numeric key indexes ## from_entries with numeric key indexes
from_entries always creates a map, even for numeric keys
from\_entries always creates a map, even for numeric keys
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- a - a
- b - b
``` ```
then then
```bash ```bash
yq eval 'to_entries | from_entries' sample.yml yq eval 'to_entries | from_entries' sample.yml
``` ```
will output will output
```yaml ```yaml
0: a 0: a
1: b 1: b
``` ```
## Use with\_entries to update keys ## Use with_entries to update keys
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: 1 a: 1
b: 2 b: 2
``` ```
then then
```bash ```bash
yq eval 'with_entries(.key |= "KEY_" + .)' sample.yml yq eval 'with_entries(.key |= "KEY_" + .)' sample.yml
``` ```
will output will output
```yaml ```yaml
KEY_a: 1 KEY_a: 1
KEY_b: 2 KEY_b: 2
``` ```
## Use with\_entries to filter the map ## Use with_entries to filter the map
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: bird b: bird
c: c:
d: dog d: dog
``` ```
then then
```bash ```bash
yq eval 'with_entries(select(.value | has("b")))' sample.yml yq eval 'with_entries(select(.value | has("b")))' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
b: bird b: bird
``` ```

31
operators/env-variable-operators.md
View File

@ -3,106 +3,77 @@
This operator is used to handle environment variables usage in path expressions. While environment variables can, of course, be passed in via your CLI with string interpolation, this often comes with complex quote escaping and can be tricky to write and read. Note that there are two forms, `env` which will parse the environment variable as a yaml (be it a map, array, string, number of boolean) and `strenv` which will always parse the argument as a string. This operator is used to handle environment variables usage in path expressions. While environment variables can, of course, be passed in via your CLI with string interpolation, this often comes with complex quote escaping and can be tricky to write and read. Note that there are two forms, `env` which will parse the environment variable as a yaml (be it a map, array, string, number of boolean) and `strenv` which will always parse the argument as a string.
## Read string environment variable ## Read string environment variable
Running Running
```bash ```bash
myenv="cat meow" yq eval --null-input '.a = env(myenv)' myenv="cat meow" yq eval --null-input '.a = env(myenv)'
``` ```
will output will output
```yaml ```yaml
a: cat meow a: cat meow
``` ```
## Read boolean environment variable ## Read boolean environment variable
Running Running
```bash ```bash
myenv="true" yq eval --null-input '.a = env(myenv)' myenv="true" yq eval --null-input '.a = env(myenv)'
``` ```
will output will output
```yaml ```yaml
a: true a: true
``` ```
## Read numeric environment variable ## Read numeric environment variable
Running Running
```bash ```bash
myenv="12" yq eval --null-input '.a = env(myenv)' myenv="12" yq eval --null-input '.a = env(myenv)'
``` ```
will output will output
```yaml ```yaml
a: 12 a: 12
``` ```
## Read yaml environment variable ## Read yaml environment variable
Running Running
```bash ```bash
myenv="{b: fish}" yq eval --null-input '.a = env(myenv)' myenv="{b: fish}" yq eval --null-input '.a = env(myenv)'
``` ```
will output will output
```yaml ```yaml
a: {b: fish} a: {b: fish}
``` ```
## Read boolean environment variable as a string ## Read boolean environment variable as a string
Running Running
```bash ```bash
myenv="true" yq eval --null-input '.a = strenv(myenv)' myenv="true" yq eval --null-input '.a = strenv(myenv)'
``` ```
will output will output
```yaml ```yaml
a: "true" a: "true"
``` ```
## Read numeric environment variable as a string ## Read numeric environment variable as a string
Running Running
```bash ```bash
myenv="12" yq eval --null-input '.a = strenv(myenv)' myenv="12" yq eval --null-input '.a = strenv(myenv)'
``` ```
will output will output
```yaml ```yaml
a: "12" a: "12"
``` ```
## Dynamic key lookup with environment variable ## Dynamic key lookup with environment variable
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
cat: meow cat: meow
dog: woof dog: woof
``` ```
then then
```bash ```bash
myenv="cat" yq eval '.[env(myenv)]' sample.yml myenv="cat" yq eval '.[env(myenv)]' sample.yml
``` ```
will output will output
```yaml ```yaml
meow meow
``` ```

41
operators/equals.md
View File

@ -13,23 +13,17 @@ select(.a == .b)
``` ```
## Match string ## Match string
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- cat - cat
- goat - goat
- dog - dog
``` ```
then then
```bash ```bash
yq eval '.[] | (. == "*at")' sample.yml yq eval '.[] | (. == "*at")' sample.yml
``` ```
will output will output
```yaml ```yaml
true true
true true
@ -37,23 +31,17 @@ false
``` ```
## Don't match string ## Don't match string
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- cat - cat
- goat - goat
- dog - dog
``` ```
then then
```bash ```bash
yq eval '.[] | (. != "*at")' sample.yml yq eval '.[] | (. != "*at")' sample.yml
``` ```
will output will output
```yaml ```yaml
false false
false false
@ -61,23 +49,17 @@ true
``` ```
## Match number ## Match number
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- 3 - 3
- 4 - 4
- 5 - 5
``` ```
then then
```bash ```bash
yq eval '.[] | (. == 4)' sample.yml yq eval '.[] | (. == 4)' sample.yml
``` ```
will output will output
```yaml ```yaml
false false
true true
@ -85,23 +67,17 @@ false
``` ```
## Dont match number ## Dont match number
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- 3 - 3
- 4 - 4
- 5 - 5
``` ```
then then
```bash ```bash
yq eval '.[] | (. != 4)' sample.yml yq eval '.[] | (. != 4)' sample.yml
``` ```
will output will output
```yaml ```yaml
true true
false false
@ -109,55 +85,40 @@ true
``` ```
## Match nulls ## Match nulls
Running Running
```bash ```bash
yq eval --null-input 'null == ~' yq eval --null-input 'null == ~'
``` ```
will output will output
```yaml ```yaml
true true
``` ```
## Non exisitant key doesn't equal a value ## Non exisitant key doesn't equal a value
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: frog a: frog
``` ```
then then
```bash ```bash
yq eval 'select(.b != "thing")' sample.yml yq eval 'select(.b != "thing")' sample.yml
``` ```
will output will output
```yaml ```yaml
a: frog a: frog
``` ```
## Two non existant keys are equal ## Two non existant keys are equal
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: frog a: frog
``` ```
then then
```bash ```bash
yq eval 'select(.b == .c)' sample.yml yq eval 'select(.b == .c)' sample.yml
``` ```
will output will output
```yaml ```yaml
a: frog a: frog
``` ```

29
operators/file-operators.md
View File

@ -5,75 +5,53 @@ File operators are most often used with merge when needing to merge specific fil
Note that the `fileIndex` operator has a short alias of `fi`. Note that the `fileIndex` operator has a short alias of `fi`.
## Merging files ## Merging files
Note the use of eval-all to ensure all documents are loaded into memory. Note the use of eval-all to ensure all documents are loaded into memory.
```bash ```bash
yq eval-all 'select(fi == 0) * select(filename == "file2.yaml")' file1.yaml file2.yaml yq eval-all 'select(fi == 0) * select(filename == "file2.yaml")' file1.yaml file2.yaml
``` ```
## Get filename ## Get filename
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval 'filename' sample.yml yq eval 'filename' sample.yml
``` ```
will output will output
```yaml ```yaml
sample.yml sample.yml
``` ```
## Get file index ## Get file index
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval 'fileIndex' sample.yml yq eval 'fileIndex' sample.yml
``` ```
will output will output
```yaml ```yaml
0 0
``` ```
## Get file indices of multiple documents ## Get file indices of multiple documents
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
And another sample another.yml file of: And another sample another.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval-all 'fileIndex' sample.yml another.yml yq eval-all 'fileIndex' sample.yml another.yml
``` ```
will output will output
```yaml ```yaml
0 0
--- ---
@ -81,21 +59,16 @@ will output
``` ```
## Get file index alias ## Get file index alias
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval 'fi' sample.yml yq eval 'fi' sample.yml
``` ```
will output will output
```yaml ```yaml
0 0
``` ```

20
operators/has.md
View File

@ -3,24 +3,18 @@
This is operation that returns true if the key exists in a map (or index in an array), false otherwise. This is operation that returns true if the key exists in a map (or index in an array), false otherwise.
## Has map key ## Has map key
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- a: yes - a: yes
- a: ~ - a: ~
- a: - a:
- b: nope - b: nope
``` ```
then then
```bash ```bash
yq eval '.[] | has("a")' sample.yml yq eval '.[] | has("a")' sample.yml
``` ```
will output will output
```yaml ```yaml
true true
true true
@ -29,11 +23,9 @@ false
``` ```
## Select, checking for existence of deep paths ## Select, checking for existence of deep paths
Simply pipe in parent expressions into `has` Simply pipe in parent expressions into `has`
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- a: - a:
b: b:
@ -42,15 +34,11 @@ Given a sample.yml file of:
b: b:
d: dog d: dog
``` ```
then then
```bash ```bash
yq eval '.[] | select(.a.b | has("c"))' sample.yml yq eval '.[] | select(.a.b | has("c"))' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
b: b:
@ -58,25 +46,20 @@ a:
``` ```
## Has array index ## Has array index
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- [] - []
- [1] - [1]
- [1, 2] - [1, 2]
- [1, null] - [1, null]
- [1, 2, 3] - [1, 2, 3]
``` ```
then then
```bash ```bash
yq eval '.[] | has(1)' sample.yml yq eval '.[] | has(1)' sample.yml
``` ```
will output will output
```yaml ```yaml
false false
false false
@ -84,3 +67,4 @@ true
true true
true true
``` ```

13
operators/keys.md
View File

@ -3,45 +3,34 @@
Use the `keys` operator to return map keys or array indices. Use the `keys` operator to return map keys or array indices.
## Map keys ## Map keys
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
dog: woof dog: woof
cat: meow cat: meow
``` ```
then then
```bash ```bash
yq eval 'keys' sample.yml yq eval 'keys' sample.yml
``` ```
will output will output
```yaml ```yaml
- dog - dog
- cat - cat
``` ```
## Array keys ## Array keys
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- apple - apple
- banana - banana
``` ```
then then
```bash ```bash
yq eval 'keys' sample.yml yq eval 'keys' sample.yml
``` ```
will output will output
```yaml ```yaml
- 0 - 0
- 1 - 1
``` ```

25
operators/length.md
View File

@ -3,91 +3,68 @@
Returns the lengths of the nodes. Length is defined according to the type of the node. Returns the lengths of the nodes. Length is defined according to the type of the node.
## String length ## String length
returns length of string returns length of string
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval '.a | length' sample.yml yq eval '.a | length' sample.yml
``` ```
will output will output
```yaml ```yaml
3 3
``` ```
## null length ## null length
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: null a: null
``` ```
then then
```bash ```bash
yq eval '.a | length' sample.yml yq eval '.a | length' sample.yml
``` ```
will output will output
```yaml ```yaml
0 0
``` ```
## Map length ## Map length
returns number of entries returns number of entries
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
c: dog c: dog
``` ```
then then
```bash ```bash
yq eval 'length' sample.yml yq eval 'length' sample.yml
``` ```
will output will output
```yaml ```yaml
2 2
``` ```
## Array length ## Array length
returns number of elements returns number of elements
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- 2 - 2
- 4 - 4
- 6 - 6
- 8 - 8
``` ```
then then
```bash ```bash
yq eval 'length' sample.yml yq eval 'length' sample.yml
``` ```
will output will output
```yaml ```yaml
4 4
``` ```

100
operators/multiply-merge.md
View File

@ -3,21 +3,18 @@
Like the multiple operator in jq, depending on the operands, this multiply operator will do different things. Currently numbers, arrays and objects are supported. Like the multiple operator in jq, depending on the operands, this multiply operator will do different things. Currently numbers, arrays and objects are supported.
## Objects and arrays - merging ## Objects and arrays - merging
Objects are merged deeply matching on matching keys. By default, array values override and are not deeply merged. Objects are merged deeply matching on matching keys. By default, array values override and are not deeply merged.
Note that when merging objects, this operator returns the merged object (not the parent). This will be clearer in the examples below. Note that when merging objects, this operator returns the merged object (not the parent). This will be clearer in the examples below.
### Merge Flags ### Merge Flags
You can control how objects are merged by using one or more of the following flags. Multiple flags can be used together, e.g. `.a *+? .b`. See examples below You can control how objects are merged by using one or more of the following flags. Multiple flags can be used together, e.g. `.a *+? .b`. See examples below
* `+` to append arrays - `+` to append arrays
* `?` to only merge existing fields - `?` to only merge existing fields
* `d` to deeply merge arrays - `d` to deeply merge arrays
### Merging files ### Merging files
Note the use of `eval-all` to ensure all documents are loaded into memory. Note the use of `eval-all` to ensure all documents are loaded into memory.
```bash ```bash
@ -25,23 +22,17 @@ yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' file1.yaml file2.y
``` ```
## Multiply integers ## Multiply integers
Running Running
```bash ```bash
yq eval --null-input '3 * 4' yq eval --null-input '3 * 4'
``` ```
will output will output
```yaml ```yaml
12 12
``` ```
## Merge objects together, returning merged result only ## Merge objects together, returning merged result only
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
field: me field: me
@ -51,15 +42,11 @@ b:
g: wizz g: wizz
fieldB: dog fieldB: dog
``` ```
then then
```bash ```bash
yq eval '.a * .b' sample.yml yq eval '.a * .b' sample.yml
``` ```
will output will output
```yaml ```yaml
field: field:
g: wizz g: wizz
@ -68,9 +55,7 @@ fieldB: dog
``` ```
## Merge objects together, returning parent object ## Merge objects together, returning parent object
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
field: me field: me
@ -80,15 +65,11 @@ b:
g: wizz g: wizz
fieldB: dog fieldB: dog
``` ```
then then
```bash ```bash
yq eval '. * {"a":.b}' sample.yml yq eval '. * {"a":.b}' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
field: field:
@ -102,23 +83,17 @@ b:
``` ```
## Merge keeps style of LHS ## Merge keeps style of LHS
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: {things: great} a: {things: great}
b: b:
also: "me" also: "me"
``` ```
then then
```bash ```bash
yq eval '. * {"a":.b}' sample.yml yq eval '. * {"a":.b}' sample.yml
``` ```
will output will output
```yaml ```yaml
a: {things: great, also: "me"} a: {things: great, also: "me"}
b: b:
@ -126,9 +101,7 @@ b:
``` ```
## Merge arrays ## Merge arrays
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
- 1 - 1
@ -139,15 +112,11 @@ b:
- 4 - 4
- 5 - 5
``` ```
then then
```bash ```bash
yq eval '. * {"a":.b}' sample.yml yq eval '. * {"a":.b}' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
- 3 - 3
@ -160,9 +129,7 @@ b:
``` ```
## Merge, only existing fields ## Merge, only existing fields
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
thing: one thing: one
@ -171,24 +138,18 @@ b:
missing: two missing: two
thing: two thing: two
``` ```
then then
```bash ```bash
yq eval '.a *? .b' sample.yml yq eval '.a *? .b' sample.yml
``` ```
will output will output
```yaml ```yaml
thing: two thing: two
cat: frog cat: frog
``` ```
## Merge, appending arrays ## Merge, appending arrays
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
array: array:
@ -203,15 +164,11 @@ b:
- animal: cat - animal: cat
value: banana value: banana
``` ```
then then
```bash ```bash
yq eval '.a *+ .b' sample.yml yq eval '.a *+ .b' sample.yml
``` ```
will output will output
```yaml ```yaml
array: array:
- 1 - 1
@ -224,9 +181,7 @@ value: banana
``` ```
## Merge, only existing fields, appending arrays ## Merge, only existing fields, appending arrays
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
thing: thing:
@ -239,15 +194,11 @@ b:
another: another:
- 1 - 1
``` ```
then then
```bash ```bash
yq eval '.a *?+ .b' sample.yml yq eval '.a *?+ .b' sample.yml
``` ```
will output will output
```yaml ```yaml
thing: thing:
- 1 - 1
@ -257,11 +208,9 @@ thing:
``` ```
## Merge, deeply merging arrays ## Merge, deeply merging arrays
Merging arrays deeply means arrays are merge like objects, with indexes as their key. In this case, we merge the first item in the array, and do nothing with the second. Merging arrays deeply means arrays are merge like objects, with indexes as their key. In this case, we merge the first item in the array, and do nothing with the second.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
- name: fred - name: fred
@ -272,15 +221,11 @@ b:
- name: fred - name: fred
age: 34 age: 34
``` ```
then then
```bash ```bash
yq eval '.a *d .b' sample.yml yq eval '.a *d .b' sample.yml
``` ```
will output will output
```yaml ```yaml
- name: fred - name: fred
age: 34 age: 34
@ -289,11 +234,13 @@ will output
``` ```
## Merge arrays of objects together, matching on a key ## Merge arrays of objects together, matching on a key
It's a complex command, the trickyness comes from needing to have the right context in the expressions.
First we save the second array into a variable '$two' which lets us reference it later.
We then need to update the first array. We will use the relative update (|=) because we need to update relative to the current element of the array in the LHS in the RHS expression.
We set the current element of the first array as $cur. Now we multiply (merge) $cur with the matching entry in $two, by passing $two through a select filter.
It's a complex command, the trickyness comes from needing to have the right context in the expressions. First we save the second array into a variable '$two' which lets us reference it later. We then need to update the first array. We will use the relative update (|=) because we need to update relative to the current element of the array in the LHS in the RHS expression. We set the current element of the first array as $cur. Now we multiply (merge) $cur with the matching entry in $two, by passing $two through a select filter.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- a: apple - a: apple
b: appleB b: appleB
@ -302,9 +249,7 @@ Given a sample.yml file of:
- a: banana - a: banana
b: bananaB b: bananaB
``` ```
And another sample another.yml file of: And another sample another.yml file of:
```yaml ```yaml
- a: banana - a: banana
c: bananaC c: bananaC
@ -313,15 +258,11 @@ And another sample another.yml file of:
- a: dingo - a: dingo
c: dingoC c: dingoC
``` ```
then then
```bash ```bash
yq eval-all '(select(fi==1) | .[]) as $two | select(fi==0) | .[] |= (. as $cur | $cur * ($two | select(.a == $cur.a)))' sample.yml another.yml yq eval-all '(select(fi==1) | .[]) as $two | select(fi==0) | .[] |= (. as $cur | $cur * ($two | select(.a == $cur.a)))' sample.yml another.yml
``` ```
will output will output
```yaml ```yaml
- a: apple - a: apple
b: appleB2 b: appleB2
@ -333,22 +274,16 @@ will output
``` ```
## Merge to prefix an element ## Merge to prefix an element
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: dog b: dog
``` ```
then then
```bash ```bash
yq eval '. * {"a": {"c": .a}}' sample.yml yq eval '. * {"a": {"c": .a}}' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
c: cat c: cat
@ -356,9 +291,7 @@ b: dog
``` ```
## Merge with simple aliases ## Merge with simple aliases
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: &cat a: &cat
c: frog c: frog
@ -367,24 +300,18 @@ b:
c: c:
g: thongs g: thongs
``` ```
then then
```bash ```bash
yq eval '.c * .b' sample.yml yq eval '.c * .b' sample.yml
``` ```
will output will output
```yaml ```yaml
g: thongs g: thongs
f: *cat f: *cat
``` ```
## Merge copies anchor names ## Merge copies anchor names
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
c: &cat frog c: &cat frog
@ -393,24 +320,18 @@ b:
c: c:
g: thongs g: thongs
``` ```
then then
```bash ```bash
yq eval '.c * .a' sample.yml yq eval '.c * .a' sample.yml
``` ```
will output will output
```yaml ```yaml
g: thongs g: thongs
c: &cat frog c: &cat frog
``` ```
## Merge with merge anchors ## Merge with merge anchors
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo: &foo foo: &foo
a: foo_a a: foo_a
@ -431,20 +352,17 @@ foobar:
!!merge <<: *foo !!merge <<: *foo
thing: foobar_thing thing: foobar_thing
``` ```
then then
```bash ```bash
yq eval '.foobar * .foobarList' sample.yml yq eval '.foobar * .foobarList' sample.yml
``` ```
will output will output
```yaml ```yaml
c: foobarList_c c: foobarList_c
<<: !!merge <<:
- *foo - *foo
- *bar - *bar
thing: foobar_thing thing: foobar_thing
b: foobarList_b b: foobarList_b
``` ```

31
operators/path.md
View File

@ -5,112 +5,82 @@ The path operator can be used to get the traversal paths of matching nodes in an
You can get the key/index of matching nodes by using the `path` operator to return the path array then piping that through `.[-1]` to get the last element of that array, the key. You can get the key/index of matching nodes by using the `path` operator to return the path array then piping that through `.[-1]` to get the last element of that array, the key.
## Map path ## Map path
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: cat b: cat
``` ```
then then
```bash ```bash
yq eval '.a.b | path' sample.yml yq eval '.a.b | path' sample.yml
``` ```
will output will output
```yaml ```yaml
- a - a
- b - b
``` ```
## Get map key ## Get map key
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: cat b: cat
``` ```
then then
```bash ```bash
yq eval '.a.b | path | .[-1]' sample.yml yq eval '.a.b | path | .[-1]' sample.yml
``` ```
will output will output
```yaml ```yaml
b b
``` ```
## Array path ## Array path
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
- cat - cat
- dog - dog
``` ```
then then
```bash ```bash
yq eval '.a.[] | select(. == "dog") | path' sample.yml yq eval '.a.[] | select(. == "dog") | path' sample.yml
``` ```
will output will output
```yaml ```yaml
- a - a
- 1 - 1
``` ```
## Get array index ## Get array index
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
- cat - cat
- dog - dog
``` ```
then then
```bash ```bash
yq eval '.a.[] | select(. == "dog") | path | .[-1]' sample.yml yq eval '.a.[] | select(. == "dog") | path | .[-1]' sample.yml
``` ```
will output will output
```yaml ```yaml
1 1
``` ```
## Print path and value ## Print path and value
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
- cat - cat
- dog - dog
- frog - frog
``` ```
then then
```bash ```bash
yq eval '.a.[] | select(. == "*og") | [{"path":path, "value":.}]' sample.yml yq eval '.a.[] | select(. == "*og") | [{"path":path, "value":.}]' sample.yml
``` ```
will output will output
```yaml ```yaml
- path: - path:
- a - a
@ -121,3 +91,4 @@ will output
- 2 - 2
value: frog value: frog
``` ```

13
operators/pipe.md
View File

@ -3,46 +3,35 @@
Pipe the results of an expression into another. Like the bash operator. Pipe the results of an expression into another. Like the bash operator.
## Simple Pipe ## Simple Pipe
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: cat b: cat
``` ```
then then
```bash ```bash
yq eval '.a | .b' sample.yml yq eval '.a | .b' sample.yml
``` ```
will output will output
```yaml ```yaml
cat cat
``` ```
## Multiple updates ## Multiple updates
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cow a: cow
b: sheep b: sheep
c: same c: same
``` ```
then then
```bash ```bash
yq eval '.a = "cat" | .b = "dog"' sample.yml yq eval '.a = "cat" | .b = "dog"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cat a: cat
b: dog b: dog
c: same c: same
``` ```

40
operators/recursive-descent-glob.md
View File

@ -3,7 +3,6 @@
This operator recursively matches (or globs) all children nodes given of a particular element, including that node itself. This is most often used to apply a filter recursively against all matches. It can be used in either the This operator recursively matches (or globs) all children nodes given of a particular element, including that node itself. This is most often used to apply a filter recursively against all matches. It can be used in either the
## match values form `..` ## match values form `..`
This will, like the `jq` equivalent, recursively match all _value_ nodes. Use it to find/manipulate particular values. This will, like the `jq` equivalent, recursively match all _value_ nodes. Use it to find/manipulate particular values.
For instance to set the `style` of all _value_ nodes in a yaml doc, excluding map keys: For instance to set the `style` of all _value_ nodes in a yaml doc, excluding map keys:
@ -13,7 +12,6 @@ yq eval '.. style= "flow"' file.yaml
``` ```
## match values and map keys form `...` ## match values and map keys form `...`
The also includes map keys in the results set. This is particularly useful in YAML as unlike JSON, map keys can have their own styling, tags and use anchors and aliases. The also includes map keys in the results set. This is particularly useful in YAML as unlike JSON, map keys can have their own styling, tags and use anchors and aliases.
For instance to set the `style` of all nodes in a yaml doc, including the map keys: For instance to set the `style` of all nodes in a yaml doc, including the map keys:
@ -21,34 +19,25 @@ For instance to set the `style` of all nodes in a yaml doc, including the map ke
```bash ```bash
yq eval '... style= "flow"' file.yaml yq eval '... style= "flow"' file.yaml
``` ```
## Recurse map (values only) ## Recurse map (values only)
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: frog a: frog
``` ```
then then
```bash ```bash
yq eval '..' sample.yml yq eval '..' sample.yml
``` ```
will output will output
```yaml ```yaml
a: frog a: frog
frog frog
``` ```
## Recursively find nodes with keys ## Recursively find nodes with keys
Note that this example has wrapped the expression in `[]` to show that there are two matches returned. You do not have to wrap in `[]` in your path expression. Note that this example has wrapped the expression in `[]` to show that there are two matches returned. You do not have to wrap in `[]` in your path expression.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
name: frog name: frog
@ -56,15 +45,11 @@ a:
name: blog name: blog
age: 12 age: 12
``` ```
then then
```bash ```bash
yq eval '[.. | select(has("name"))]' sample.yml yq eval '[.. | select(has("name"))]' sample.yml
``` ```
will output will output
```yaml ```yaml
- name: frog - name: frog
b: b:
@ -75,9 +60,7 @@ will output
``` ```
## Recursively find nodes with values ## Recursively find nodes with values
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
nameA: frog nameA: frog
@ -85,38 +68,28 @@ a:
nameB: frog nameB: frog
age: 12 age: 12
``` ```
then then
```bash ```bash
yq eval '.. | select(. == "frog")' sample.yml yq eval '.. | select(. == "frog")' sample.yml
``` ```
will output will output
```yaml ```yaml
frog frog
frog frog
``` ```
## Recurse map (values and keys) ## Recurse map (values and keys)
Note that the map key appears in the results Note that the map key appears in the results
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: frog a: frog
``` ```
then then
```bash ```bash
yq eval '...' sample.yml yq eval '...' sample.yml
``` ```
will output will output
```yaml ```yaml
a: frog a: frog
a a
@ -124,23 +97,17 @@ frog
``` ```
## Aliases are not traversed ## Aliases are not traversed
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: &cat a: &cat
c: frog c: frog
b: *cat b: *cat
``` ```
then then
```bash ```bash
yq eval '[..]' sample.yml yq eval '[..]' sample.yml
``` ```
will output will output
```yaml ```yaml
- a: &cat - a: &cat
c: frog c: frog
@ -152,9 +119,7 @@ will output
``` ```
## Merge docs are not traversed ## Merge docs are not traversed
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo: &foo foo: &foo
a: foo_a a: foo_a
@ -175,15 +140,11 @@ foobar:
!!merge <<: *foo !!merge <<: *foo
thing: foobar_thing thing: foobar_thing
``` ```
then then
```bash ```bash
yq eval '.foobar | [..]' sample.yml yq eval '.foobar | [..]' sample.yml
``` ```
will output will output
```yaml ```yaml
- c: foobar_c - c: foobar_c
!!merge <<: *foo !!merge <<: *foo
@ -192,3 +153,4 @@ will output
- *foo - *foo
- foobar_thing - foobar_thing
``` ```

22
operators/reduce.md
View File

@ -17,81 +17,61 @@ On the LHS we are configuring the collection of items that will be reduced `<exp
On the RHS there is `<init>`, the starting value of the accumulator and `<block>`, the expression that will update the accumulator for each element in the collection. Note that within the block expression, `.` will evaluate to the current value of the accumulator. On the RHS there is `<init>`, the starting value of the accumulator and `<block>`, the expression that will update the accumulator for each element in the collection. Note that within the block expression, `.` will evaluate to the current value of the accumulator.
## yq vs jq syntax ## yq vs jq syntax
Reduce syntax in `yq` is a little different from `jq` - as `yq` (currently) isn't as sophisticated as `jq` and its only supports infix notation (e.g. a + b, where the operator is in the middle of the two parameters) - where as `jq` uses a mix of infix notation with _prefix_ notation (e.g. `reduce a b` is like writing `+ a b`). Reduce syntax in `yq` is a little different from `jq` - as `yq` (currently) isn't as sophisticated as `jq` and its only supports infix notation (e.g. a + b, where the operator is in the middle of the two parameters) - where as `jq` uses a mix of infix notation with _prefix_ notation (e.g. `reduce a b` is like writing `+ a b`).
To that end, the reduce operator is called `ireduce` for backwards compatability if a `jq` like prefix version of `reduce` is ever added. To that end, the reduce operator is called `ireduce` for backwards compatability if a `jq` like prefix version of `reduce` is ever added.
## Sum numbers ## Sum numbers
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- 10 - 10
- 2 - 2
- 5 - 5
- 3 - 3
``` ```
then then
```bash ```bash
yq eval '.[] as $item ireduce (0; . + $item)' sample.yml yq eval '.[] as $item ireduce (0; . + $item)' sample.yml
``` ```
will output will output
```yaml ```yaml
20 20
``` ```
## Merge all yaml files together ## Merge all yaml files together
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
And another sample another.yml file of: And another sample another.yml file of:
```yaml ```yaml
b: dog b: dog
``` ```
then then
```bash ```bash
yq eval-all '. as $item ireduce ({}; . * $item )' sample.yml another.yml yq eval-all '. as $item ireduce ({}; . * $item )' sample.yml another.yml
``` ```
will output will output
```yaml ```yaml
a: cat a: cat
b: dog b: dog
``` ```
## Convert an array to an object ## Convert an array to an object
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- name: Cathy - name: Cathy
has: apples has: apples
- name: Bob - name: Bob
has: bananas has: bananas
``` ```
then then
```bash ```bash
yq eval '.[] as $item ireduce ({}; .[$item | .name] = ($item | .has) )' sample.yml yq eval '.[] as $item ireduce ({}; .[$item | .name] = ($item | .has) )' sample.yml
``` ```
will output will output
```yaml ```yaml
Cathy: apples Cathy: apples
Bob: bananas Bob: bananas
``` ```

13
operators/select.md
View File

@ -3,50 +3,39 @@
Select is used to filter arrays and maps by a boolean expression. Select is used to filter arrays and maps by a boolean expression.
## Select elements from array ## Select elements from array
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- cat - cat
- goat - goat
- dog - dog
``` ```
then then
```bash ```bash
yq eval '.[] | select(. == "*at")' sample.yml yq eval '.[] | select(. == "*at")' sample.yml
``` ```
will output will output
```yaml ```yaml
cat cat
goat goat
``` ```
## Select and update matching values in map ## Select and update matching values in map
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
things: cat things: cat
bob: goat bob: goat
horse: dog horse: dog
``` ```
then then
```bash ```bash
yq eval '(.a.[] | select(. == "*at")) |= "rabbit"' sample.yml yq eval '(.a.[] | select(. == "*at")) |= "rabbit"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
things: rabbit things: rabbit
bob: rabbit bob: rabbit
horse: dog horse: dog
``` ```

13
operators/sort-keys.md
View File

@ -11,23 +11,17 @@ diff file1.yml file2.yml
``` ```
## Sort keys of map ## Sort keys of map
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
c: frog c: frog
a: blah a: blah
b: bing b: bing
``` ```
then then
```bash ```bash
yq eval 'sortKeys(.)' sample.yml yq eval 'sortKeys(.)' sample.yml
``` ```
will output will output
```yaml ```yaml
a: blah a: blah
b: bing b: bing
@ -35,11 +29,9 @@ c: frog
``` ```
## Sort keys recursively ## Sort keys recursively
Note the array elements are left unsorted, but maps inside arrays are sorted Note the array elements are left unsorted, but maps inside arrays are sorted
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
bParent: bParent:
c: dog c: dog
@ -55,15 +47,11 @@ aParent:
- b: ew - b: ew
a: apple a: apple
``` ```
then then
```bash ```bash
yq eval 'sortKeys(..)' sample.yml yq eval 'sortKeys(..)' sample.yml
``` ```
will output will output
```yaml ```yaml
aParent: aParent:
x: x:
@ -79,3 +67,4 @@ bParent:
- 2 - 2
c: dog c: dog
``` ```

12
operators/split-into-documents.md
View File

@ -3,37 +3,29 @@
This operator splits all matches into separate documents This operator splits all matches into separate documents
## Split empty ## Split empty
Running Running
```bash ```bash
yq eval --null-input 'splitDoc' yq eval --null-input 'splitDoc'
``` ```
will output will output
```yaml ```yaml
``` ```
## Split array ## Split array
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- a: cat - a: cat
- b: dog - b: dog
``` ```
then then
```bash ```bash
yq eval '.[] | splitDoc' sample.yml yq eval '.[] | splitDoc' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cat a: cat
--- ---
b: dog b: dog
``` ```

120
operators/string-operators.md
View File

@ -1,13 +1,10 @@
# String Operators # String Operators
## String Operators ## RegEx
This uses golangs native regex functions under the hood - See https://github.com/google/re2/wiki/Syntax for the supported syntax.
### RegEx
This uses golangs native regex functions under the hood - See [https://github.com/google/re2/wiki/Syntax](https://github.com/google/re2/wiki/Syntax) for the supported syntax.
## String blocks, bash and newlines ## 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_. 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: For instance to get this yaml:
@ -25,7 +22,6 @@ a: cat
``` ```
However, using printf works: However, using printf works:
``` ```
printf -v m "cat\n" ; m="$m" yq e -n '.a = strenv(m)' printf -v m "cat\n" ; m="$m" yq e -n '.a = strenv(m)'
a: | a: |
@ -33,7 +29,6 @@ a: |
``` ```
As well as having multiline expressions: As well as having multiline expressions:
``` ```
m="cat m="cat
" yq e -n '.a = strenv(m)' " yq e -n '.a = strenv(m)'
@ -48,10 +43,8 @@ IFS= read -rd '' output < <(cat my_file)
output=$output ./yq e '.data.values = strenv(output)' first.yml output=$output ./yq e '.data.values = strenv(output)' first.yml
``` ```
### Join strings ## Join strings
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- cat - cat
- meow - meow
@ -59,35 +52,25 @@ Given a sample.yml file of:
- null - null
- true - true
``` ```
then then
```bash ```bash
yq eval 'join("; ")' sample.yml yq eval 'join("; ")' sample.yml
``` ```
will output will output
```yaml ```yaml
cat; meow; 1; ; true cat; meow; 1; ; true
``` ```
### Match string ## Match string
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo bar foo foo bar foo
``` ```
then then
```bash ```bash
yq eval 'match("foo")' sample.yml yq eval 'match("foo")' sample.yml
``` ```
will output will output
```yaml ```yaml
string: foo string: foo
offset: 0 offset: 0
@ -95,22 +78,16 @@ length: 3
captures: [] captures: []
``` ```
### Match string, case insensitive ## Match string, case insensitive
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo bar FOO foo bar FOO
``` ```
then then
```bash ```bash
yq eval '[match("(?i)foo"; "g")]' sample.yml yq eval '[match("(?i)foo"; "g")]' sample.yml
``` ```
will output will output
```yaml ```yaml
- string: foo - string: foo
offset: 0 offset: 0
@ -122,22 +99,16 @@ will output
captures: [] captures: []
``` ```
### Match with capture groups ## Match with capture groups
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
abc abc abc abc
``` ```
then then
```bash ```bash
yq eval '[match("(abc)+"; "g")]' sample.yml yq eval '[match("(abc)+"; "g")]' sample.yml
``` ```
will output will output
```yaml ```yaml
- string: abc - string: abc
offset: 0 offset: 0
@ -155,22 +126,16 @@ will output
length: 3 length: 3
``` ```
### Match with named capture groups ## Match with named capture groups
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo bar foo foo foo foo bar foo foo foo
``` ```
then then
```bash ```bash
yq eval '[match("foo (?P<bar123>bar)? foo"; "g")]' sample.yml yq eval '[match("foo (?P<bar123>bar)? foo"; "g")]' sample.yml
``` ```
will output will output
```yaml ```yaml
- string: foo bar foo - string: foo bar foo
offset: 0 offset: 0
@ -190,43 +155,31 @@ will output
name: bar123 name: bar123
``` ```
### Capture named groups into a map ## Capture named groups into a map
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
xyzzy-14 xyzzy-14
``` ```
then then
```bash ```bash
yq eval 'capture("(?P<a>[a-z]+)-(?P<n>[0-9]+)")' sample.yml yq eval 'capture("(?P<a>[a-z]+)-(?P<n>[0-9]+)")' sample.yml
``` ```
will output will output
```yaml ```yaml
a: xyzzy a: xyzzy
n: "14" n: "14"
``` ```
### Match without global flag ## Match without global flag
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
cat cat cat cat
``` ```
then then
```bash ```bash
yq eval 'match("cat")' sample.yml yq eval 'match("cat")' sample.yml
``` ```
will output will output
```yaml ```yaml
string: cat string: cat
offset: 0 offset: 0
@ -234,22 +187,16 @@ length: 3
captures: [] captures: []
``` ```
### Match with global flag ## Match with global flag
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
cat cat cat cat
``` ```
then then
```bash ```bash
yq eval '[match("cat"; "g")]' sample.yml yq eval '[match("cat"; "g")]' sample.yml
``` ```
will output will output
```yaml ```yaml
- string: cat - string: cat
offset: 0 offset: 0
@ -261,92 +208,70 @@ will output
captures: [] captures: []
``` ```
### Test using regex ## Test using regex
Like jq'q equivalant, this works like match but only returns true/false instead of full match details Like jq'q equivalant, this works like match but only returns true/false instead of full match details
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- cat - cat
- dog - dog
``` ```
then then
```bash ```bash
yq eval '.[] | test("at")' sample.yml yq eval '.[] | test("at")' sample.yml
``` ```
will output will output
```yaml ```yaml
true true
false false
``` ```
### Substitute / Replace string ## Substitute / Replace string
This uses golang regex, described [here](https://github.com/google/re2/wiki/Syntax)
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. Note the use of `|=` to run in context of the current string value.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: dogs are great a: dogs are great
``` ```
then then
```bash ```bash
yq eval '.a |= sub("dogs", "cats")' sample.yml yq eval '.a |= sub("dogs", "cats")' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cats are great a: cats are great
``` ```
### Substitute / Replace string with regex ## Substitute / Replace string with regex
This uses golang regex, described [here](https://github.com/google/re2/wiki/Syntax)
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. Note the use of `|=` to run in context of the current string value.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: heat b: heat
``` ```
then then
```bash ```bash
yq eval '.[] |= sub("(a)", "${1}r")' sample.yml yq eval '.[] |= sub("(a)", "${1}r")' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cart a: cart
b: heart b: heart
``` ```
### Split strings ## Split strings
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
cat; meow; 1; ; true cat; meow; 1; ; true
``` ```
then then
```bash ```bash
yq eval 'split("; ")' sample.yml yq eval 'split("; ")' sample.yml
``` ```
will output will output
```yaml ```yaml
- cat - cat
- meow - meow
@ -355,22 +280,17 @@ will output
- "true" - "true"
``` ```
### Split strings one match ## Split strings one match
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
word word
``` ```
then then
```bash ```bash
yq eval 'split("; ")' sample.yml yq eval 'split("; ")' sample.yml
``` ```
will output will output
```yaml ```yaml
- word - word
``` ```

73
operators/style.md
View File

@ -3,23 +3,17 @@
The style operator can be used to get or set the style of nodes (e.g. string style, yaml style) The style operator can be used to get or set the style of nodes (e.g. string style, yaml style)
## Update and set style of a particular node (simple) ## Update and set style of a particular node (simple)
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: thing b: thing
c: something c: something
``` ```
then then
```bash ```bash
yq eval '.a.b = "new" | .a.b style="double"' sample.yml yq eval '.a.b = "new" | .a.b style="double"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
b: "new" b: "new"
@ -27,23 +21,17 @@ a:
``` ```
## Update and set style of a particular node using path variables ## Update and set style of a particular node using path variables
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: thing b: thing
c: something c: something
``` ```
then then
```bash ```bash
yq eval 'with(.a.b ; . = "new" | . style="double")' sample.yml yq eval 'with(.a.b ; . = "new" | . style="double")' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
b: "new" b: "new"
@ -51,24 +39,18 @@ a:
``` ```
## Set tagged style ## Set tagged style
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: 5 b: 5
c: 3.2 c: 3.2
e: true e: true
``` ```
then then
```bash ```bash
yq eval '.. style="tagged"' sample.yml yq eval '.. style="tagged"' sample.yml
``` ```
will output will output
```yaml ```yaml
!!map !!map
a: !!str cat a: !!str cat
@ -78,24 +60,18 @@ e: !!bool true
``` ```
## Set double quote style ## Set double quote style
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: 5 b: 5
c: 3.2 c: 3.2
e: true e: true
``` ```
then then
```bash ```bash
yq eval '.. style="double"' sample.yml yq eval '.. style="double"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: "cat" a: "cat"
b: "5" b: "5"
@ -104,24 +80,18 @@ e: "true"
``` ```
## Set double quote style on map keys too ## Set double quote style on map keys too
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: 5 b: 5
c: 3.2 c: 3.2
e: true e: true
``` ```
then then
```bash ```bash
yq eval '... style="double"' sample.yml yq eval '... style="double"' sample.yml
``` ```
will output will output
```yaml ```yaml
"a": "cat" "a": "cat"
"b": "5" "b": "5"
@ -130,24 +100,18 @@ will output
``` ```
## Set single quote style ## Set single quote style
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: 5 b: 5
c: 3.2 c: 3.2
e: true e: true
``` ```
then then
```bash ```bash
yq eval '.. style="single"' sample.yml yq eval '.. style="single"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: 'cat' a: 'cat'
b: '5' b: '5'
@ -156,24 +120,18 @@ e: 'true'
``` ```
## Set literal quote style ## Set literal quote style
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: 5 b: 5
c: 3.2 c: 3.2
e: true e: true
``` ```
then then
```bash ```bash
yq eval '.. style="literal"' sample.yml yq eval '.. style="literal"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: |- a: |-
cat cat
@ -186,24 +144,18 @@ e: |-
``` ```
## Set folded quote style ## Set folded quote style
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: 5 b: 5
c: 3.2 c: 3.2
e: true e: true
``` ```
then then
```bash ```bash
yq eval '.. style="folded"' sample.yml yq eval '.. style="folded"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: >- a: >-
cat cat
@ -216,49 +168,37 @@ e: >-
``` ```
## Set flow quote style ## Set flow quote style
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: 5 b: 5
c: 3.2 c: 3.2
e: true e: true
``` ```
then then
```bash ```bash
yq eval '.. style="flow"' sample.yml yq eval '.. style="flow"' sample.yml
``` ```
will output will output
```yaml ```yaml
{a: cat, b: 5, c: 3.2, e: true} {a: cat, b: 5, c: 3.2, e: true}
``` ```
## Reset style - or pretty print ## Reset style - or pretty print
Set empty (default) quote style, note the usage of `...` to match keys too. Note that there is a `--prettyPrint/-P` short flag for this. Set empty (default) quote style, note the usage of `...` to match keys too. Note that there is a `--prettyPrint/-P` short flag for this.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
"b": 5 "b": 5
'c': 3.2 'c': 3.2
"e": true "e": true
``` ```
then then
```bash ```bash
yq eval '... style=""' sample.yml yq eval '... style=""' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cat a: cat
b: 5 b: 5
@ -267,45 +207,34 @@ e: true
``` ```
## Set style relatively with assign-update ## Set style relatively with assign-update
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: single a: single
b: double b: double
``` ```
then then
```bash ```bash
yq eval '.[] style |= .' sample.yml yq eval '.[] style |= .' sample.yml
``` ```
will output will output
```yaml ```yaml
a: 'single' a: 'single'
b: "double" b: "double"
``` ```
## Read style ## Read style
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
{a: "cat", b: 'thing'} {a: "cat", b: 'thing'}
``` ```
then then
```bash ```bash
yq eval '.. | style' sample.yml yq eval '.. | style' sample.yml
``` ```
will output will output
```yaml ```yaml
flow flow
double double
single single
``` ```

41
operators/subtract.md
View File

@ -1,148 +1,113 @@
# Subtract # Subtract
You can use subtract to subtract numbers, as well as removing elements from an array.
## Array subtraction ## Array subtraction
Running Running
```bash ```bash
yq eval --null-input '[1,2] - [2,3]' yq eval --null-input '[1,2] - [2,3]'
``` ```
will output will output
```yaml ```yaml
- 1 - 1
``` ```
## Array subtraction with nested array ## Array subtraction with nested array
Running Running
```bash ```bash
yq eval --null-input '[[1], 1, 2] - [[1], 3]' yq eval --null-input '[[1], 1, 2] - [[1], 3]'
``` ```
will output will output
```yaml ```yaml
- 1 - 1
- 2 - 2
``` ```
## Array subtraction with nested object ## Array subtraction with nested object
Note that order of the keys does not matter Note that order of the keys does not matter
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- a: b - a: b
c: d c: d
- a: b - a: b
``` ```
then then
```bash ```bash
yq eval '. - [{"c": "d", "a": "b"}]' sample.yml yq eval '. - [{"c": "d", "a": "b"}]' sample.yml
``` ```
will output will output
```yaml ```yaml
- a: b - a: b
``` ```
## Number subtraction - float ## Number subtraction - float
If the lhs or rhs are floats then the expression will be calculated with floats. If the lhs or rhs are floats then the expression will be calculated with floats.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: 3 a: 3
b: 4.5 b: 4.5
``` ```
then then
```bash ```bash
yq eval '.a = .a - .b' sample.yml yq eval '.a = .a - .b' sample.yml
``` ```
will output will output
```yaml ```yaml
a: -1.5 a: -1.5
b: 4.5 b: 4.5
``` ```
## Number subtraction - float ## Number subtraction - float
If the lhs or rhs are floats then the expression will be calculated with floats. If the lhs or rhs are floats then the expression will be calculated with floats.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: 3 a: 3
b: 4.5 b: 4.5
``` ```
then then
```bash ```bash
yq eval '.a = .a - .b' sample.yml yq eval '.a = .a - .b' sample.yml
``` ```
will output will output
```yaml ```yaml
a: -1.5 a: -1.5
b: 4.5 b: 4.5
``` ```
## Number subtraction - int ## Number subtraction - int
If both the lhs and rhs are ints then the expression will be calculated with ints. If both the lhs and rhs are ints then the expression will be calculated with ints.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: 3 a: 3
b: 4 b: 4
``` ```
then then
```bash ```bash
yq eval '.a = .a - .b' sample.yml yq eval '.a = .a - .b' sample.yml
``` ```
will output will output
```yaml ```yaml
a: -1 a: -1
b: 4 b: 4
``` ```
## Decrement numbers ## Decrement numbers
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: 3 a: 3
b: 5 b: 5
``` ```
then then
```bash ```bash
yq eval '.[] -= 1' sample.yml yq eval '.[] -= 1' sample.yml
``` ```
will output will output
```yaml ```yaml
a: 2 a: 2
b: 4 b: 4
``` ```

19
operators/tag.md
View File

@ -3,9 +3,7 @@
The tag operator can be used to get or set the tag of nodes (e.g. `!!str`, `!!int`, `!!bool`). The tag operator can be used to get or set the tag of nodes (e.g. `!!str`, `!!int`, `!!bool`).
## Get tag ## Get tag
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: 5 b: 5
@ -13,15 +11,11 @@ c: 3.2
e: true e: true
f: [] f: []
``` ```
then then
```bash ```bash
yq eval '.. | tag' sample.yml yq eval '.. | tag' sample.yml
``` ```
will output will output
```yaml ```yaml
!!map !!map
!!str !!str
@ -32,47 +26,36 @@ will output
``` ```
## Set custom tag ## Set custom tag
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: str a: str
``` ```
then then
```bash ```bash
yq eval '.a tag = "!!mikefarah"' sample.yml yq eval '.a tag = "!!mikefarah"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: !!mikefarah str a: !!mikefarah str
``` ```
## Find numbers and convert them to strings ## Find numbers and convert them to strings
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
b: 5 b: 5
c: 3.2 c: 3.2
e: true e: true
``` ```
then then
```bash ```bash
yq eval '(.. | select(tag == "!!int")) tag= "!!str"' sample.yml yq eval '(.. | select(tag == "!!int")) tag= "!!str"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: cat a: cat
b: "5" b: "5"
c: 3.2 c: 3.2
e: true e: true
``` ```

147
operators/traverse-read.md
View File

@ -3,381 +3,277 @@
This is the simplest (and perhaps most used) operator, it is used to navigate deeply into yaml structures. This is the simplest (and perhaps most used) operator, it is used to navigate deeply into yaml structures.
## Simple map navigation ## Simple map navigation
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: apple b: apple
``` ```
then then
```bash ```bash
yq eval '.a' sample.yml yq eval '.a' sample.yml
``` ```
will output will output
```yaml ```yaml
b: apple b: apple
``` ```
## Splat ## Splat
Often used to pipe children into other operators Often used to pipe children into other operators
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- b: apple - b: apple
- c: banana - c: banana
``` ```
then then
```bash ```bash
yq eval '.[]' sample.yml yq eval '.[]' sample.yml
``` ```
will output will output
```yaml ```yaml
b: apple b: apple
c: banana c: banana
``` ```
## Optional Splat ## Optional Splat
Just like splat, but won't error if you run it against scalars Just like splat, but won't error if you run it against scalars
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
cat cat
``` ```
then then
```bash ```bash
yq eval '.[]' sample.yml yq eval '.[]' sample.yml
``` ```
will output will output
```yaml ```yaml
``` ```
## Special characters ## Special characters
Use quotes with brackets around path elements with special characters Use quotes with brackets around path elements with special characters
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
"{}": frog "{}": frog
``` ```
then then
```bash ```bash
yq eval '.["{}"]' sample.yml yq eval '.["{}"]' sample.yml
``` ```
will output will output
```yaml ```yaml
frog frog
``` ```
## Nested special characters ## Nested special characters
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
"key.withdots": "key.withdots":
"another.key": apple "another.key": apple
``` ```
then then
```bash ```bash
yq eval '.a["key.withdots"]["another.key"]' sample.yml yq eval '.a["key.withdots"]["another.key"]' sample.yml
``` ```
will output will output
```yaml ```yaml
apple apple
``` ```
## Keys with spaces ## Keys with spaces
Use quotes with brackets around path elements with special characters Use quotes with brackets around path elements with special characters
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
"red rabbit": frog "red rabbit": frog
``` ```
then then
```bash ```bash
yq eval '.["red rabbit"]' sample.yml yq eval '.["red rabbit"]' sample.yml
``` ```
will output will output
```yaml ```yaml
frog frog
``` ```
## Dynamic keys ## Dynamic keys
Expressions within [] can be used to dynamically lookup / calculate keys
Expressions within \[] can be used to dynamically lookup / calculate keys
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
b: apple b: apple
apple: crispy yum apple: crispy yum
banana: soft yum banana: soft yum
``` ```
then then
```bash ```bash
yq eval '.[.b]' sample.yml yq eval '.[.b]' sample.yml
``` ```
will output will output
```yaml ```yaml
crispy yum crispy yum
``` ```
## Children don't exist ## Children don't exist
Nodes are added dynamically while traversing Nodes are added dynamically while traversing
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
c: banana c: banana
``` ```
then then
```bash ```bash
yq eval '.a.b' sample.yml yq eval '.a.b' sample.yml
``` ```
will output will output
```yaml ```yaml
null null
``` ```
## Optional identifier ## Optional identifier
Like jq, does not output an error when the yaml is not an array or object as expected Like jq, does not output an error when the yaml is not an array or object as expected
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- 1 - 1
- 2 - 2
- 3 - 3
``` ```
then then
```bash ```bash
yq eval '.a?' sample.yml yq eval '.a?' sample.yml
``` ```
will output will output
```yaml ```yaml
``` ```
## Wildcard matching ## Wildcard matching
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
cat: apple cat: apple
mad: things mad: things
``` ```
then then
```bash ```bash
yq eval '.a."*a*"' sample.yml yq eval '.a."*a*"' sample.yml
``` ```
will output will output
```yaml ```yaml
apple apple
things things
``` ```
## Aliases ## Aliases
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: &cat a: &cat
c: frog c: frog
b: *cat b: *cat
``` ```
then then
```bash ```bash
yq eval '.b' sample.yml yq eval '.b' sample.yml
``` ```
will output will output
```yaml ```yaml
*cat *cat
``` ```
## Traversing aliases with splat ## Traversing aliases with splat
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: &cat a: &cat
c: frog c: frog
b: *cat b: *cat
``` ```
then then
```bash ```bash
yq eval '.b[]' sample.yml yq eval '.b[]' sample.yml
``` ```
will output will output
```yaml ```yaml
frog frog
``` ```
## Traversing aliases explicitly ## Traversing aliases explicitly
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: &cat a: &cat
c: frog c: frog
b: *cat b: *cat
``` ```
then then
```bash ```bash
yq eval '.b.c' sample.yml yq eval '.b.c' sample.yml
``` ```
will output will output
```yaml ```yaml
frog frog
``` ```
## Traversing arrays by index ## Traversing arrays by index
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- 1 - 1
- 2 - 2
- 3 - 3
``` ```
then then
```bash ```bash
yq eval '.[0]' sample.yml yq eval '.[0]' sample.yml
``` ```
will output will output
```yaml ```yaml
1 1
``` ```
## Traversing nested arrays by index ## Traversing nested arrays by index
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
[[], [cat]] [[], [cat]]
``` ```
then then
```bash ```bash
yq eval '.[1][0]' sample.yml yq eval '.[1][0]' sample.yml
``` ```
will output will output
```yaml ```yaml
cat cat
``` ```
## Maps with numeric keys ## Maps with numeric keys
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
2: cat 2: cat
``` ```
then then
```bash ```bash
yq eval '.[2]' sample.yml yq eval '.[2]' sample.yml
``` ```
will output will output
```yaml ```yaml
cat cat
``` ```
## Maps with non existing numeric keys ## Maps with non existing numeric keys
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: b a: b
``` ```
then then
```bash ```bash
yq eval '.[0]' sample.yml yq eval '.[0]' sample.yml
``` ```
will output will output
```yaml ```yaml
null null
``` ```
## Traversing merge anchors ## Traversing merge anchors
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo: &foo foo: &foo
a: foo_a a: foo_a
@ -398,23 +294,17 @@ foobar:
!!merge <<: *foo !!merge <<: *foo
thing: foobar_thing thing: foobar_thing
``` ```
then then
```bash ```bash
yq eval '.foobar.a' sample.yml yq eval '.foobar.a' sample.yml
``` ```
will output will output
```yaml ```yaml
foo_a foo_a
``` ```
## Traversing merge anchors with override ## Traversing merge anchors with override
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo: &foo foo: &foo
a: foo_a a: foo_a
@ -435,23 +325,17 @@ foobar:
!!merge <<: *foo !!merge <<: *foo
thing: foobar_thing thing: foobar_thing
``` ```
then then
```bash ```bash
yq eval '.foobar.c' sample.yml yq eval '.foobar.c' sample.yml
``` ```
will output will output
```yaml ```yaml
foo_c foo_c
``` ```
## Traversing merge anchors with local override ## Traversing merge anchors with local override
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo: &foo foo: &foo
a: foo_a a: foo_a
@ -472,23 +356,17 @@ foobar:
!!merge <<: *foo !!merge <<: *foo
thing: foobar_thing thing: foobar_thing
``` ```
then then
```bash ```bash
yq eval '.foobar.thing' sample.yml yq eval '.foobar.thing' sample.yml
``` ```
will output will output
```yaml ```yaml
foobar_thing foobar_thing
``` ```
## Splatting merge anchors ## Splatting merge anchors
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo: &foo foo: &foo
a: foo_a a: foo_a
@ -509,15 +387,11 @@ foobar:
!!merge <<: *foo !!merge <<: *foo
thing: foobar_thing thing: foobar_thing
``` ```
then then
```bash ```bash
yq eval '.foobar[]' sample.yml yq eval '.foobar[]' sample.yml
``` ```
will output will output
```yaml ```yaml
foo_c foo_c
foo_a foo_a
@ -525,11 +399,9 @@ foobar_thing
``` ```
## Traversing merge anchor lists ## Traversing merge anchor lists
Note that the later merge anchors override previous Note that the later merge anchors override previous
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo: &foo foo: &foo
a: foo_a a: foo_a
@ -550,23 +422,17 @@ foobar:
!!merge <<: *foo !!merge <<: *foo
thing: foobar_thing thing: foobar_thing
``` ```
then then
```bash ```bash
yq eval '.foobarList.thing' sample.yml yq eval '.foobarList.thing' sample.yml
``` ```
will output will output
```yaml ```yaml
bar_thing bar_thing
``` ```
## Splatting merge anchor lists ## Splatting merge anchor lists
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
foo: &foo foo: &foo
a: foo_a a: foo_a
@ -587,15 +453,11 @@ foobar:
!!merge <<: *foo !!merge <<: *foo
thing: foobar_thing thing: foobar_thing
``` ```
then then
```bash ```bash
yq eval '.foobarList[]' sample.yml yq eval '.foobarList[]' sample.yml
``` ```
will output will output
```yaml ```yaml
bar_b bar_b
foo_a foo_a
@ -604,25 +466,20 @@ foobarList_c
``` ```
## Select multiple indices ## Select multiple indices
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
- a - a
- b - b
- c - c
``` ```
then then
```bash ```bash
yq eval '.a[0, 2]' sample.yml yq eval '.a[0, 2]' sample.yml
``` ```
will output will output
```yaml ```yaml
a a
c c
``` ```

11
operators/union.md
View File

@ -3,15 +3,11 @@
This operator is used to combine different results together. This operator is used to combine different results together.
## Combine scalars ## Combine scalars
Running Running
```bash ```bash
yq eval --null-input '1, true, "cat"' yq eval --null-input '1, true, "cat"'
``` ```
will output will output
```yaml ```yaml
1 1
true true
@ -19,24 +15,19 @@ cat
``` ```
## Combine selected paths ## Combine selected paths
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: fieldA a: fieldA
b: fieldB b: fieldB
c: fieldC c: fieldC
``` ```
then then
```bash ```bash
yq eval '.a, .c' sample.yml yq eval '.a, .c' sample.yml
``` ```
will output will output
```yaml ```yaml
fieldA fieldA
fieldC fieldC
``` ```

25
operators/unique.md
View File

@ -3,24 +3,18 @@
This is used to filter out duplicated items in an array. This is used to filter out duplicated items in an array.
## Unique array of scalars (string/numbers) ## Unique array of scalars (string/numbers)
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- 1 - 1
- 2 - 2
- 3 - 3
- 2 - 2
``` ```
then then
```bash ```bash
yq eval 'unique' sample.yml yq eval 'unique' sample.yml
``` ```
will output will output
```yaml ```yaml
- 1 - 1
- 2 - 2
@ -28,60 +22,46 @@ will output
``` ```
## Unique nulls ## Unique nulls
Unique works on the node value, so it considers different representations of nulls to be different Unique works on the node value, so it considers different representations of nulls to be different
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- ~ - ~
- null - null
- ~ - ~
- null - null
``` ```
then then
```bash ```bash
yq eval 'unique' sample.yml yq eval 'unique' sample.yml
``` ```
will output will output
```yaml ```yaml
- ~ - ~
- null - null
``` ```
## Unique all nulls ## Unique all nulls
Run against the node tag to unique all the nulls Run against the node tag to unique all the nulls
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- ~ - ~
- null - null
- ~ - ~
- null - null
``` ```
then then
```bash ```bash
yq eval 'unique_by(tag)' sample.yml yq eval 'unique_by(tag)' sample.yml
``` ```
will output will output
```yaml ```yaml
- ~ - ~
``` ```
## Unique array object fields ## Unique array object fields
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- name: harry - name: harry
pet: cat pet: cat
@ -90,18 +70,15 @@ Given a sample.yml file of:
- name: harry - name: harry
pet: dog pet: dog
``` ```
then then
```bash ```bash
yq eval 'unique_by(.name)' sample.yml yq eval 'unique_by(.name)' sample.yml
``` ```
will output will output
```yaml ```yaml
- name: harry - name: harry
pet: cat pet: cat
- name: billy - name: billy
pet: dog pet: dog
``` ```

31
operators/variable-operators.md
View File

@ -5,53 +5,39 @@ Like the `jq` equivalents, variables are sometimes required for the more complex
Note that there is also an additional `ref` operator that holds a reference (instead of a copy) of the path, allowing you to make multiple changes to the same path. Note that there is also an additional `ref` operator that holds a reference (instead of a copy) of the path, allowing you to make multiple changes to the same path.
## Single value variable ## Single value variable
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: cat a: cat
``` ```
then then
```bash ```bash
yq eval '.a as $foo | $foo' sample.yml yq eval '.a as $foo | $foo' sample.yml
``` ```
will output will output
```yaml ```yaml
cat cat
``` ```
## Multi value variable ## Multi value variable
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
- cat - cat
- dog - dog
``` ```
then then
```bash ```bash
yq eval '.[] as $foo | $foo' sample.yml yq eval '.[] as $foo | $foo' sample.yml
``` ```
will output will output
```yaml ```yaml
cat cat
dog dog
``` ```
## Using variables as a lookup ## Using variables as a lookup
Example taken from [jq](https://stedolan.github.io/jq/manual/#Variable/SymbolicBindingOperator:...as$identifier|...) Example taken from [jq](https://stedolan.github.io/jq/manual/#Variable/SymbolicBindingOperator:...as$identifier|...)
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
"posts": "posts":
- "title": Frist psot - "title": Frist psot
@ -62,15 +48,11 @@ Given a sample.yml file of:
"anon": Anonymous Coward "anon": Anonymous Coward
"person1": Person McPherson "person1": Person McPherson
``` ```
then then
```bash ```bash
yq eval '.realnames as $names | .posts[] | {"title":.title, "author": $names[.author]}' sample.yml yq eval '.realnames as $names | .posts[] | {"title":.title, "author": $names[.author]}' sample.yml
``` ```
will output will output
```yaml ```yaml
title: Frist psot title: Frist psot
author: Anonymous Coward author: Anonymous Coward
@ -79,49 +61,38 @@ author: Person McPherson
``` ```
## Using variables to swap values ## Using variables to swap values
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a_value a: a_value
b: b_value b: b_value
``` ```
then then
```bash ```bash
yq eval '.a as $x | .b as $y | .b = $x | .a = $y' sample.yml yq eval '.a as $x | .b as $y | .b = $x | .a = $y' sample.yml
``` ```
will output will output
```yaml ```yaml
a: b_value a: b_value
b: a_value b: a_value
``` ```
## Use ref to reference a path repeatedly ## Use ref to reference a path repeatedly
Note: You may find the `with` operator more useful. Note: You may find the `with` operator more useful.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
b: thing b: thing
c: something c: something
``` ```
then then
```bash ```bash
yq eval '.a.b ref $x | $x = "new" | $x style="double"' sample.yml yq eval '.a.b ref $x | $x = "new" | $x style="double"' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
b: "new" b: "new"
c: something c: something
``` ```

19
operators/with.md
View File

@ -3,23 +3,17 @@
Use the `with` operator to conveniently make multiple updates to a deeply nested path, or to update array elements relatively to each other. The first argument expression sets the root context, and the second expression runs against that root context. Use the `with` operator to conveniently make multiple updates to a deeply nested path, or to update array elements relatively to each other. The first argument expression sets the root context, and the second expression runs against that root context.
## Update and style ## Update and style
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
deeply: deeply:
nested: value nested: value
``` ```
then then
```bash ```bash
yq eval 'with(.a.deeply.nested; . = "newValue" | . style="single")' sample.yml yq eval 'with(.a.deeply.nested; . = "newValue" | . style="single")' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
deeply: deeply:
@ -27,24 +21,18 @@ a:
``` ```
## Update multiple deeply nested properties ## Update multiple deeply nested properties
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
a: a:
deeply: deeply:
nested: value nested: value
other: thing other: thing
``` ```
then then
```bash ```bash
yq eval 'with(.a.deeply; .nested = "newValue" | .other= "newThing")' sample.yml yq eval 'with(.a.deeply; .nested = "newValue" | .other= "newThing")' sample.yml
``` ```
will output will output
```yaml ```yaml
a: a:
deeply: deeply:
@ -53,25 +41,19 @@ a:
``` ```
## Update array elements relatively ## Update array elements relatively
The second expression runs with each element of the array as it's contextual root. This allows you to make updates relative to the element. The second expression runs with each element of the array as it's contextual root. This allows you to make updates relative to the element.
Given a sample.yml file of: Given a sample.yml file of:
```yaml ```yaml
myArray: myArray:
- a: apple - a: apple
- a: banana - a: banana
``` ```
then then
```bash ```bash
yq eval 'with(.myArray[]; .b = .a + " yum")' sample.yml yq eval 'with(.myArray[]; .b = .a + " yum")' sample.yml
``` ```
will output will output
```yaml ```yaml
myArray: myArray:
- a: apple - a: apple
@ -79,3 +61,4 @@ myArray:
- a: banana - a: banana
b: banana yum b: banana yum
``` ```