wip

pkg/yqlib/doc/operators/anchor-and-alias-operators.md

@@ -5,6 +5,286 @@ 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.
 
 
+## Merge one map
+see https://yaml.org/type/merge.html
+
+Given a sample.yml file of:
+```yaml
+- &CENTER
+  x: 1
+  y: 2
+- &LEFT
+  x: 0
+  y: 2
+- &BIG
+  r: 10
+- &SMALL
+  r: 1
+- !!merge <<: *CENTER
+  r: 10
+```
+then
+```bash
+yq '.[4] | explode(.)' sample.yml
+```
+will output
+```yaml
+x: 1
+y: 2
+r: 10
+```
+
+## Merge multiple maps
+see https://yaml.org/type/merge.html
+
+Given a sample.yml file of:
+```yaml
+- &CENTER
+  x: 1
+  y: 2
+- &LEFT
+  x: 0
+  y: 2
+- &BIG
+  r: 10
+- &SMALL
+  r: 1
+- !!merge <<:
+    - *CENTER
+    - *BIG
+```
+then
+```bash
+yq '.[4] | explode(.)' sample.yml
+```
+will output
+```yaml
+r: 10
+x: 1
+y: 2
+```
+
+## Override
+see https://yaml.org/type/merge.html
+
+Given a sample.yml file of:
+```yaml
+- &CENTER
+  x: 1
+  y: 2
+- &LEFT
+  x: 0
+  y: 2
+- &BIG
+  r: 10
+- &SMALL
+  r: 1
+- !!merge <<:
+    - *BIG
+    - *LEFT
+    - *SMALL
+  x: 1
+```
+then
+```bash
+yq '.[4] | explode(.)' sample.yml
+```
+will output
+```yaml
+r: 10
+x: 1
+y: 2
+```
+
+## Get anchor
+Given a sample.yml file of:
+```yaml
+a: &billyBob cat
+```
+then
+```bash
+yq '.a | anchor' sample.yml
+```
+will output
+```yaml
+billyBob
+```
+
+## Set anchor
+Given a sample.yml file of:
+```yaml
+a: cat
+```
+then
+```bash
+yq '.a anchor = "foobar"' sample.yml
+```
+will output
+```yaml
+a: &foobar cat
+```
+
+## Set anchor relatively using assign-update
+Given a sample.yml file of:
+```yaml
+a:
+  b: cat
+```
+then
+```bash
+yq '.a anchor |= .b' sample.yml
+```
+will output
+```yaml
+a: &cat
+  b: cat
+```
+
+## Get alias
+Given a sample.yml file of:
+```yaml
+{b: &billyBob meow, a: *billyBob}
+```
+then
+```bash
+yq '.a | alias' sample.yml
+```
+will output
+```yaml
+billyBob
+```
+
+## Set alias
+Given a sample.yml file of:
+```yaml
+{b: &meow purr, a: cat}
+```
+then
+```bash
+yq '.a alias = "meow"' sample.yml
+```
+will output
+```yaml
+{b: &meow purr, a: *meow}
+```
+
+## Set alias to blank does nothing
+Given a sample.yml file of:
+```yaml
+{b: &meow purr, a: cat}
+```
+then
+```bash
+yq '.a alias = ""' sample.yml
+```
+will output
+```yaml
+{b: &meow purr, a: cat}
+```
+
+## Set alias relatively using assign-update
+Given a sample.yml file of:
+```yaml
+{b: &meow purr, a: {f: meow}}
+```
+then
+```bash
+yq '.a alias |= .f' sample.yml
+```
+will output
+```yaml
+{b: &meow purr, a: *meow}
+```
+
+## Explode alias and anchor
+Given a sample.yml file of:
+```yaml
+{f: {a: &a cat, b: *a}}
+```
+then
+```bash
+yq 'explode(.f)' sample.yml
+```
+will output
+```yaml
+{f: {a: cat, b: cat}}
+```
+
+## Explode with no aliases or anchors
+Given a sample.yml file of:
+```yaml
+a: mike
+```
+then
+```bash
+yq 'explode(.a)' sample.yml
+```
+will output
+```yaml
+a: mike
+```
+
+## Explode with alias keys
+Given a sample.yml file of:
+```yaml
+{f: {a: &a cat, *a: b}}
+```
+then
+```bash
+yq 'explode(.f)' sample.yml
+```
+will output
+```yaml
+{f: {a: cat, cat: b}}
+```
+
+## Explode with merge anchors
+Given a sample.yml file of:
+```yaml
+foo: &foo
+  a: foo_a
+  thing: foo_thing
+  c: foo_c
+bar: &bar
+  b: bar_b
+  thing: bar_thing
+  c: bar_c
+foobarList:
+  b: foobarList_b
+  !!merge <<:
+    - *foo
+    - *bar
+  c: foobarList_c
+foobar:
+  c: foobar_c
+  !!merge <<: *foo
+  thing: foobar_thing
+```
+then
+```bash
+yq 'explode(.)' sample.yml
+```
+will output
+```yaml
+foo:
+  a: foo_a
+  thing: foo_thing
+  c: foo_c
+bar:
+  b: bar_b
+  thing: bar_thing
+  c: bar_c
+foobarList:
+  b: bar_b
+  thing: foo_thing
+  c: foobarList_c
+  a: foo_a
+foobar:
+  c: foo_c
+  a: foo_a
+  thing: foobar_thing
+```
+
 ## Dereference and update a field
 Use explode with multiply to dereference an object
 

pkg/yqlib/doc/operators/env-variable-operators.md

@@ -95,10 +95,7 @@ The env variable can be any valid yq expression.
 
 Given a sample.yml file of:
 ```yaml
-a:
-  b:
-    - name: dog
-    - name: cat
+{a: {b: [{name: dog}, {name: cat}]}}
 ```
 then
 ```bash
@@ -106,17 +103,13 @@ pathEnv=".a.b[0].name"  valueEnv="moo" yq 'eval(strenv(pathEnv)) = strenv(valueE
 ```
 will output
 ```yaml
-a:
-  b:
-    - name: moo
-    - name: cat
+{a: {b: [{name: moo}, {name: cat}]}}
 ```
 
 ## Dynamic key lookup with environment variable
 Given a sample.yml file of:
 ```yaml
-cat: meow
-dog: woof
+{cat: meow, dog: woof}
 ```
 then
 ```bash
@@ -220,7 +213,7 @@ Error: variable ${myEmptyEnv} set but empty
 ## Replace string environment variable in document
 Given a sample.yml file of:
 ```yaml
-v: ${myenv}
+{v: '${myenv}'}
 ```
 then
 ```bash
@@ -228,7 +221,7 @@ myenv="cat meow" yq '.v |= envsubst' sample.yml
 ```
 will output
 ```yaml
-v: cat meow
+{v: 'cat meow'}
 ```
 
 ## (Default) Return all envsubst errors

pkg/yqlib/doc/operators/equals.md

@@ -21,113 +21,3 @@ The not equals `!=` operator returns `false` if the LHS is equal to the RHS.
 - select operator [here](https://mikefarah.gitbook.io/yq/operators/select)
 
 
-## Match string
-Given a sample.yml file of:
-```yaml
-- cat
-- goat
-- dog
-```
-then
-```bash
-yq '.[] | (. == "*at")' sample.yml
-```
-will output
-```yaml
-true
-true
-false
-```
-
-## Don't match string
-Given a sample.yml file of:
-```yaml
-- cat
-- goat
-- dog
-```
-then
-```bash
-yq '.[] | (. != "*at")' sample.yml
-```
-will output
-```yaml
-false
-false
-true
-```
-
-## Match number
-Given a sample.yml file of:
-```yaml
-- 3
-- 4
-- 5
-```
-then
-```bash
-yq '.[] | (. == 4)' sample.yml
-```
-will output
-```yaml
-false
-true
-false
-```
-
-## Don't match number
-Given a sample.yml file of:
-```yaml
-- 3
-- 4
-- 5
-```
-then
-```bash
-yq '.[] | (. != 4)' sample.yml
-```
-will output
-```yaml
-true
-false
-true
-```
-
-## Match nulls
-Running
-```bash
-yq --null-input 'null == ~'
-```
-will output
-```yaml
-true
-```
-
-## Non existent key doesn't equal a value
-Given a sample.yml file of:
-```yaml
-a: frog
-```
-then
-```bash
-yq 'select(.b != "thing")' sample.yml
-```
-will output
-```yaml
-a: frog
-```
-
-## Two non existent keys are equal
-Given a sample.yml file of:
-```yaml
-a: frog
-```
-then
-```bash
-yq 'select(.b == .c)' sample.yml
-```
-will output
-```yaml
-a: frog
-```
-

pkg/yqlib/doc/operators/eval.md

@@ -9,11 +9,7 @@ Tip: This can be a useful way to parameterise complex scripts.
 ## Dynamically evaluate a path
 Given a sample.yml file of:
 ```yaml
-pathExp: .a.b[] | select(.name == "cat")
-a:
-  b:
-    - name: dog
-    - name: cat
+{pathExp: '.a.b[] | select(.name == "cat")', a: {b: [{name: dog}, {name: cat}]}}
 ```
 then
 ```bash
@@ -21,7 +17,7 @@ yq 'eval(.pathExp)' sample.yml
 ```
 will output
 ```yaml
-name: cat
+{name: cat}
 ```
 
 ## Dynamically update a path from an environment variable
@@ -29,10 +25,7 @@ The env variable can be any valid yq expression.
 
 Given a sample.yml file of:
 ```yaml
-a:
-  b:
-    - name: dog
-    - name: cat
+{a: {b: [{name: dog}, {name: cat}]}}
 ```
 then
 ```bash
@@ -40,9 +33,6 @@ pathEnv=".a.b[0].name"  valueEnv="moo" yq 'eval(strenv(pathEnv)) = strenv(valueE
 ```
 will output
 ```yaml
-a:
-  b:
-    - name: moo
-    - name: cat
+{a: {b: [{name: moo}, {name: cat}]}}
 ```
 

pkg/yqlib/doc/operators/file-operators.md

@@ -13,7 +13,7 @@ yq eval-all 'select(fi == 0) * select(filename == "file2.yaml")' file1.yaml file
 ## Get filename
 Given a sample.yml file of:
 ```yaml
-a: cat
+{a: cat}
 ```
 then
 ```bash
@@ -27,7 +27,7 @@ sample.yml
 ## Get file index
 Given a sample.yml file of:
 ```yaml
-a: cat
+{a: cat}
 ```
 then
 ```bash
@@ -41,11 +41,11 @@ will output
 ## Get file indices of multiple documents
 Given a sample.yml file of:
 ```yaml
-a: cat
+{a: cat}
 ```
 And another sample another.yml file of:
 ```yaml
-a: cat
+{a: cat}
 ```
 then
 ```bash
@@ -61,7 +61,7 @@ will output
 ## Get file index alias
 Given a sample.yml file of:
 ```yaml
-a: cat
+{a: cat}
 ```
 then
 ```bash

pkg/yqlib/doc/operators/traverse-read.md

@@ -5,8 +5,7 @@ This is the simplest (and perhaps most used) operator. It is used to navigate de
 ## Simple map navigation
 Given a sample.yml file of:
 ```yaml
-a:
-  b: apple
+{a: {b: apple}}
 ```
 then
 ```bash
@@ -14,7 +13,7 @@ yq '.a' sample.yml
 ```
 will output
 ```yaml
-b: apple
+{b: apple}
 ```
 
 ## Splat
@@ -22,8 +21,7 @@ Often used to pipe children into other operators
 
 Given a sample.yml file of:
 ```yaml
-- b: apple
-- c: banana
+[{b: apple}, {c: banana}]
 ```
 then
 ```bash
@@ -31,8 +29,8 @@ yq '.[]' sample.yml
 ```
 will output
 ```yaml
-b: apple
-c: banana
+{b: apple}
+{c: banana}
 ```
 
 ## Optional Splat
@@ -40,7 +38,7 @@ Just like splat, but won't error if you run it against scalars
 
 Given a sample.yml file of:
 ```yaml
-cat
+"cat"
 ```
 then
 ```bash
@@ -55,7 +53,7 @@ Use quotes with square brackets around path elements with special characters
 
 Given a sample.yml file of:
 ```yaml
-"{}": frog
+{"{}": frog}
 ```
 then
 ```bash
@@ -87,7 +85,7 @@ Use quotes with square brackets around path elements with special characters
 
 Given a sample.yml file of:
 ```yaml
-"red rabbit": frog
+{"red rabbit": frog}
 ```
 then
 ```bash
@@ -103,9 +101,7 @@ Expressions within [] can be used to dynamically lookup / calculate keys
 
 Given a sample.yml file of:
 ```yaml
-b: apple
-apple: crispy yum
-banana: soft yum
+{b: apple, apple: crispy yum, banana: soft yum}
 ```
 then
 ```bash
@@ -121,7 +117,7 @@ Nodes are added dynamically while traversing
 
 Given a sample.yml file of:
 ```yaml
-c: banana
+{c: banana}
 ```
 then
 ```bash
@@ -137,9 +133,7 @@ Like jq, does not output an error when the yaml is not an array or object as exp
 
 Given a sample.yml file of:
 ```yaml
-- 1
-- 2
-- 3
+[1, 2, 3]
 ```
 then
 ```bash
@@ -152,9 +146,7 @@ will output
 ## Wildcard matching
 Given a sample.yml file of:
 ```yaml
-a:
-  cat: apple
-  mad: things
+{a: {cat: apple, mad: things}}
 ```
 then
 ```bash
@@ -169,9 +161,7 @@ things
 ## Aliases
 Given a sample.yml file of:
 ```yaml
-a: &cat
-  c: frog
-b: *cat
+{a: &cat {c: frog}, b: *cat}
 ```
 then
 ```bash
@@ -185,9 +175,7 @@ will output
 ## Traversing aliases with splat
 Given a sample.yml file of:
 ```yaml
-a: &cat
-  c: frog
-b: *cat
+{a: &cat {c: frog}, b: *cat}
 ```
 then
 ```bash
@@ -201,9 +189,7 @@ frog
 ## Traversing aliases explicitly
 Given a sample.yml file of:
 ```yaml
-a: &cat
-  c: frog
-b: *cat
+{a: &cat {c: frog}, b: *cat}
 ```
 then
 ```bash
@@ -217,9 +203,7 @@ frog
 ## Traversing arrays by index
 Given a sample.yml file of:
 ```yaml
-- 1
-- 2
-- 3
+[1, 2, 3]
 ```
 then
 ```bash
@@ -247,7 +231,7 @@ cat
 ## Maps with numeric keys
 Given a sample.yml file of:
 ```yaml
-2: cat
+{2: cat}
 ```
 then
 ```bash
@@ -261,7 +245,7 @@ cat
 ## Maps with non existing numeric keys
 Given a sample.yml file of:
 ```yaml
-a: b
+{a: b}
 ```
 then
 ```bash
@@ -468,10 +452,7 @@ foobarList_c
 ## Select multiple indices
 Given a sample.yml file of:
 ```yaml
-a:
-  - a
-  - b
-  - c
+{a: [a, b, c]}
 ```
 then
 ```bash