docs

pkg/yqlib/doc/Mulitply Operator.md

@@ -0,0 +1,121 @@
+# Mulitply Operator
+## Examples
+### Merge objects together
+sample.yml:
+```yaml
+{a: {also: me}, b: {also: {g: wizz}}}
+```
+Expression
+```bash
+yq '. * {"a":.b}' < sample.yml
+```
+Result
+```yaml
+{a: {also: {g: wizz}}, b: {also: {g: wizz}}}
+```
+### Merge keeps style of LHS
+sample.yml:
+```yaml
+a: {things: great}
+b:
+  also: "me"
+
+```
+Expression
+```bash
+yq '. * {"a":.b}' < sample.yml
+```
+Result
+```yaml
+a: {things: great, also: "me"}
+b:
+  also: "me"
+```
+### Merge arrays
+sample.yml:
+```yaml
+{a: [1,2,3], b: [3,4,5]}
+```
+Expression
+```bash
+yq '. * {"a":.b}' < sample.yml
+```
+Result
+```yaml
+{a: [3, 4, 5], b: [3, 4, 5]}
+```
+### Merge to prefix an element
+sample.yml:
+```yaml
+{a: cat, b: dog}
+```
+Expression
+```bash
+yq '. * {"a": {"c": .a}}' < sample.yml
+```
+Result
+```yaml
+{a: {c: cat}, b: dog}
+```
+### Merge with simple aliases
+sample.yml:
+```yaml
+{a: &cat {c: frog}, b: {f: *cat}, c: {g: thongs}}
+```
+Expression
+```bash
+yq '.c * .b' < sample.yml
+```
+Result
+```yaml
+{g: thongs, f: *cat}
+```
+### Merge does not copy anchor names
+sample.yml:
+```yaml
+{a: {c: &cat frog}, b: {f: *cat}, c: {g: thongs}}
+```
+Expression
+```bash
+yq '.c * .a' < sample.yml
+```
+Result
+```yaml
+{g: thongs, c: frog}
+```
+### Merge with merge anchors
+sample.yml:
+```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
+  <<: [*foo,*bar]
+  c: foobarList_c
+
+foobar:
+  c: foobar_c
+  <<: *foo
+  thing: foobar_thing
+
+```
+Expression
+```bash
+yq '.foobar * .foobarList' < sample.yml
+```
+Result
+```yaml
+c: foobarList_c
+<<: [*foo, *bar]
+thing: foobar_thing
+b: foobarList_b
+```

pkg/yqlib/doc/Select Operator.md

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

pkg/yqlib/doc/Traverse Operator.md

@@ -0,0 +1,353 @@
+This is the simples (and perhaps most used) operator, it is used to navigate deeply into yaml structurse.
+## Examples
+### Simple map navigation
+Given a sample.yml file of:
+```yaml
+a:
+  b: apple
+```
+then
+```bash
+yq eval '.a' sample.yml
+```
+will output
+```yaml
+b: apple
+```
+
+### Splat
+Often used to pipe children into other operators
+
+Given a sample.yml file of:
+```yaml
+- b: apple
+- c: banana
+```
+then
+```bash
+yq eval '.[]' sample.yml
+```
+will output
+```yaml
+b: apple
+c: banana
+```
+
+### Children don't exist
+Nodes are added dynamically while traversing
+
+Given a sample.yml file of:
+```yaml
+c: banana
+```
+then
+```bash
+yq eval '.a.b' sample.yml
+```
+will output
+```yaml
+null
+```
+
+### Wildcard matching
+Given a sample.yml file of:
+```yaml
+a:
+  cat: apple
+  mad: things
+```
+then
+```bash
+yq eval '.a."*a*"' sample.yml
+```
+will output
+```yaml
+apple
+things
+```
+
+### Aliases
+Given a sample.yml file of:
+```yaml
+a: &cat
+  c: frog
+b: *cat
+```
+then
+```bash
+yq eval '.b' sample.yml
+```
+will output
+```yaml
+*cat
+```
+
+### Traversing aliases with splat
+Given a sample.yml file of:
+```yaml
+a: &cat
+  c: frog
+b: *cat
+```
+then
+```bash
+yq eval '.b.[]' sample.yml
+```
+will output
+```yaml
+frog
+```
+
+### Traversing aliases explicitly
+Given a sample.yml file of:
+```yaml
+a: &cat
+  c: frog
+b: *cat
+```
+then
+```bash
+yq eval '.b.c' sample.yml
+```
+will output
+```yaml
+frog
+```
+
+### Traversing arrays by index
+Given a sample.yml file of:
+```yaml
+- 1
+- 2
+- 3
+```
+then
+```bash
+yq eval '[0]' sample.yml
+```
+will output
+```yaml
+1
+```
+
+### Maps with numeric keys
+Given a sample.yml file of:
+```yaml
+2: cat
+```
+then
+```bash
+yq eval '[2]' sample.yml
+```
+will output
+```yaml
+cat
+```
+
+### Maps with non existing numeric keys
+Given a sample.yml file of:
+```yaml
+a: b
+```
+then
+```bash
+yq eval '[0]' sample.yml
+```
+will output
+```yaml
+null
+```
+
+### Traversing 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 eval '.foobar.a' sample.yml
+```
+will output
+```yaml
+foo_a
+```
+
+### Traversing merge anchors with override
+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 eval '.foobar.c' sample.yml
+```
+will output
+```yaml
+foo_c
+```
+
+### Traversing merge anchors with local override
+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 eval '.foobar.thing' sample.yml
+```
+will output
+```yaml
+foobar_thing
+```
+
+### Splatting 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 eval '.foobar.[]' sample.yml
+```
+will output
+```yaml
+foo_c
+foo_a
+foobar_thing
+```
+
+### Traversing merge anchor lists
+Note that the later merge anchors override previous
+
+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 eval '.foobarList.thing' sample.yml
+```
+will output
+```yaml
+bar_thing
+```
+
+### Splatting merge anchor lists
+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 eval '.foobarList.[]' sample.yml
+```
+will output
+```yaml
+bar_b
+foo_a
+bar_thing
+foobarList_c
+```
+

pkg/yqlib/doc/Union Operator.md

@@ -0,0 +1,49 @@
+This operator is used to combine different results together.
+## Examples
+### Combine scalars
+Running
+```bash
+yq eval --null-input '1, true, "cat"'
+```
+will output
+```yaml
+1
+true
+cat
+```
+
+### Combine selected paths
+Given a sample.yml file of:
+```yaml
+a: fieldA
+b: fieldB
+c: fieldC
+```
+then
+```bash
+yq eval '.a, .c' sample.yml
+```
+will output
+```yaml
+fieldA
+fieldC
+```
+
+### Combine selected paths
+Given a sample.yml file of:
+```yaml
+a: fieldA
+b: fieldB
+c: fieldC
+```
+then
+```bash
+yq eval '(.a, .c) |= "potatoe"' sample.yml
+```
+will output
+```yaml
+a: potatoe
+b: fieldB
+c: potatoe
+```
+

pkg/yqlib/doc/Update Assign Operator.md

@@ -13,7 +13,26 @@ yq eval '.a |= .b' sample.yml
 ```
 will output
 ```yaml
-{a: {g: foof}}
+a:
+  g: foof
+```
+
+### Updated multiple paths
+Given a sample.yml file of:
+```yaml
+a: fieldA
+b: fieldB
+c: fieldC
+```
+then
+```bash
+yq eval '(.a, .c) |= "potatoe"' sample.yml
+```
+will output
+```yaml
+a: potatoe
+b: fieldB
+c: potatoe
 ```
 
 ### Update string value
@@ -28,7 +47,8 @@ yq eval '.a.b |= "frog"' sample.yml
 ```
 will output
 ```yaml
-{a: {b: frog}}
+a:
+  b: frog
 ```
 
 ### Update selected results
@@ -44,7 +64,9 @@ yq eval '.a[] | select(. == "apple") |= "frog"' sample.yml
 ```
 will output
 ```yaml
-{a: {b: frog, c: cactus}}
+a:
+  b: frog
+  c: cactus
 ```
 
 ### Update array values
@@ -60,7 +82,9 @@ yq eval '.[] | select(. == "*andy") |= "bogs"' sample.yml
 ```
 will output
 ```yaml
-[bogs, apple, bogs]
+- bogs
+- apple
+- bogs
 ```
 
 ### Update empty object
@@ -74,7 +98,9 @@ yq eval '.a.b |= "bogs"' sample.yml
 ```
 will output
 ```yaml
-{a: {b: bogs}}
+'': null
+a:
+  b: bogs
 ```
 
 ### Update empty object and array
@@ -88,6 +114,9 @@ yq eval '.a.b[0] |= "bogs"' sample.yml
 ```
 will output
 ```yaml
-{a: {b: [bogs]}}
+'': null
+a:
+  b:
+    - bogs
 ```
 

pkg/yqlib/doc/headers/Select Operator.md

@@ -0,0 +1 @@
+Select is used to filter arrays and maps by a boolean expression.

pkg/yqlib/doc/headers/Traverse Operator.md

@@ -0,0 +1 @@
+This is the simples (and perhaps most used) operator, it is used to navigate deeply into yaml structurse.

pkg/yqlib/doc/headers/Union Operator.md

@@ -0,0 +1 @@
+This operator is used to combine different results together.