include docs for tracking

pkg/yqlib/doc/.gitignore

@@ -1 +0,0 @@
-*.md

pkg/yqlib/doc/Collect into Array.md

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

pkg/yqlib/doc/Collect into Object.md

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

pkg/yqlib/doc/Comments Operator.md

@@ -0,0 +1,120 @@
+Use these comment operators to set or retrieve comments.
+## Examples
+### Set line comment
+Given a sample.yml file of:
+```yaml
+a: cat
+```
+then
+```bash
+yq eval '.a lineComment="single"' sample.yml
+```
+will output
+```yaml
+a: cat # single
+```
+
+### Set head comment
+Given a sample.yml file of:
+```yaml
+a: cat
+```
+then
+```bash
+yq eval '. headComment="single"' sample.yml
+```
+will output
+```yaml
+# single
+
+a: cat
+```
+
+### Set foot comment, using an expression
+Given a sample.yml file of:
+```yaml
+a: cat
+```
+then
+```bash
+yq eval '. footComment=.a' sample.yml
+```
+will output
+```yaml
+a: cat
+
+# cat
+```
+
+### Remove comment
+Given a sample.yml file of:
+```yaml
+a: cat # comment
+b: dog # leave this
+```
+then
+```bash
+yq eval '.a lineComment=""' sample.yml
+```
+will output
+```yaml
+a: cat
+b: dog # leave this
+```
+
+### Remove all comments
+Given a sample.yml file of:
+```yaml
+a: cat # comment
+```
+then
+```bash
+yq eval '.. comments=""' sample.yml
+```
+will output
+```yaml
+a: cat
+```
+
+### Get line comment
+Given a sample.yml file of:
+```yaml
+a: cat # meow
+```
+then
+```bash
+yq eval '.a | lineComment' sample.yml
+```
+will output
+```yaml
+meow
+```
+
+### Get head comment
+Given a sample.yml file of:
+```yaml
+a: cat # meow
+```
+then
+```bash
+yq eval '. | headComment' sample.yml
+```
+will output
+```yaml
+welcome!
+```
+
+### Get foot comment
+Given a sample.yml file of:
+```yaml
+a: cat # meow
+```
+then
+```bash
+yq eval '. | footComment' sample.yml
+```
+will output
+```yaml
+have a great day
+```
+

pkg/yqlib/doc/Delete Operator.md

@@ -0,0 +1,48 @@
+Deletes matching entries in maps or arrays.
+## Examples
+### Delete entry in map
+Given a sample.yml file of:
+```yaml
+a: cat
+b: dog
+```
+then
+```bash
+yq eval 'del(.b)' sample.yml
+```
+will output
+```yaml
+{a: cat}
+```
+
+### Delete entry in array
+Given a sample.yml file of:
+```yaml
+- 1
+- 2
+- 3
+```
+then
+```bash
+yq eval 'del(.[1])' sample.yml
+```
+will output
+```yaml
+[1, 3]
+```
+
+### Delete no matches
+Given a sample.yml file of:
+```yaml
+a: cat
+b: dog
+```
+then
+```bash
+yq eval 'del(.c)' sample.yml
+```
+will output
+```yaml
+{a: cat, b: dog}
+```
+

pkg/yqlib/doc/Document Index Operator.md

@@ -0,0 +1,56 @@
+
+## Examples
+### Retrieve a document index
+Given a sample.yml file of:
+```yaml
+a: cat
+---
+a: frog
+```
+then
+```bash
+yq eval '.a | documentIndex' sample.yml
+```
+will output
+```yaml
+0
+---
+1
+```
+
+### Filter by document index
+Given a sample.yml file of:
+```yaml
+a: cat
+---
+a: frog
+```
+then
+```bash
+yq eval 'select(. | documentIndex == 1)' sample.yml
+```
+will output
+```yaml
+a: frog
+```
+
+### Print Document Index with matches
+Given a sample.yml file of:
+```yaml
+a: cat
+---
+a: frog
+```
+then
+```bash
+yq eval '.a | ({"match": ., "doc": (. | documentIndex)})' sample.yml
+```
+will output
+```yaml
+match: cat
+doc: 0
+---
+match: frog
+doc: 1
+```
+

pkg/yqlib/doc/Equals Operator.md

@@ -0,0 +1,62 @@
+## Equals Operator
+
+This is a boolean operator that will return ```true``` if the LHS is equal to the RHS and ``false`` otherwise.
+
+```
+.a == .b
+```
+
+It is most often used with the select operator to find particular nodes:
+
+```
+select(.a == .b)
+```
+
+
+## Examples
+### Match string
+Given a sample.yml file of:
+```yaml
+- cat
+- goat
+- dog
+```
+then
+```bash
+yq eval '.[] | (. == "*at")' sample.yml
+```
+will output
+```yaml
+true
+true
+false
+```
+
+### Match number
+Given a sample.yml file of:
+```yaml
+- 3
+- 4
+- 5
+```
+then
+```bash
+yq eval '.[] | (. == 4)' sample.yml
+```
+will output
+```yaml
+false
+true
+false
+```
+
+### Match nulls
+Running
+```bash
+yq eval --null-input 'null == ~'
+```
+will output
+```yaml
+true
+```
+

pkg/yqlib/doc/Explode Operator.md

@@ -0,0 +1,95 @@
+Explodes (or dereferences) aliases and anchors.
+## Examples
+### Explode alias and anchor
+Given a sample.yml file of:
+```yaml
+f:
+  a: &a cat
+  b: *a
+```
+then
+```bash
+yq eval '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 eval '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 eval '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 eval '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
+  a: foo_a
+  thing: bar_thing
+  c: foobarList_c
+foobar:
+  c: foo_c
+  a: foo_a
+  thing: foobar_thing
+```
+

pkg/yqlib/doc/Multiply Operator.md

@@ -0,0 +1,196 @@
+Like the multiple operator in `jq`, depending on the operands, this multiply operator will do different things. Currently only objects are supported, which have the effect of merging the RHS into the LHS.
+
+Upcoming versions of `yq` will add support for other types of multiplication (numbers, strings).
+
+Note that when merging objects, this operator returns the merged object (not the parent). This will be clearer in the examples below.
+## Examples
+### Merge objects together, returning merged result only
+Given a sample.yml file of:
+```yaml
+a:
+  field: me
+  fieldA: cat
+b:
+  field:
+    g: wizz
+  fieldB: dog
+```
+then
+```bash
+yq eval '.a * .b' sample.yml
+```
+will output
+```yaml
+field:
+  g: wizz
+fieldA: cat
+fieldB: dog
+```
+
+### Merge objects together, returning parent object
+Given a sample.yml file of:
+```yaml
+a:
+  field: me
+  fieldA: cat
+b:
+  field:
+    g: wizz
+  fieldB: dog
+```
+then
+```bash
+yq eval '. * {"a":.b}' sample.yml
+```
+will output
+```yaml
+a:
+  field:
+    g: wizz
+  fieldA: cat
+  fieldB: dog
+b:
+  field:
+    g: wizz
+  fieldB: dog
+```
+
+### Merge keeps style of LHS
+Given a sample.yml file of:
+```yaml
+a: {things: great}
+b:
+  also: "me"
+```
+then
+```bash
+yq eval '. * {"a":.b}' sample.yml
+```
+will output
+```yaml
+a: {things: great, also: "me"}
+b:
+  also: "me"
+```
+
+### Merge arrays
+Given a sample.yml file of:
+```yaml
+a:
+  - 1
+  - 2
+  - 3
+b:
+  - 3
+  - 4
+  - 5
+```
+then
+```bash
+yq eval '. * {"a":.b}' sample.yml
+```
+will output
+```yaml
+a:
+  - 3
+  - 4
+  - 5
+b:
+  - 3
+  - 4
+  - 5
+```
+
+### Merge to prefix an element
+Given a sample.yml file of:
+```yaml
+a: cat
+b: dog
+```
+then
+```bash
+yq eval '. * {"a": {"c": .a}}' sample.yml
+```
+will output
+```yaml
+a:
+  c: cat
+b: dog
+```
+
+### Merge with simple aliases
+Given a sample.yml file of:
+```yaml
+a: &cat
+  c: frog
+b:
+  f: *cat
+c:
+  g: thongs
+```
+then
+```bash
+yq eval '.c * .b' sample.yml
+```
+will output
+```yaml
+g: thongs
+f: *cat
+```
+
+### Merge does not copy anchor names
+Given a sample.yml file of:
+```yaml
+a:
+  c: &cat frog
+b:
+  f: *cat
+c:
+  g: thongs
+```
+then
+```bash
+yq eval '.c * .a' sample.yml
+```
+will output
+```yaml
+g: thongs
+c: frog
+```
+
+### Merge 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 eval '.foobar * .foobarList' sample.yml
+```
+will output
+```yaml
+c: foobarList_c
+<<:
+  - *foo
+  - *bar
+thing: foobar_thing
+b: foobarList_b
+```
+

pkg/yqlib/doc/Not Operator.md

@@ -0,0 +1,72 @@
+This is a boolean operator and will return `true` when given a `false` value (including null), and `false` otherwise.
+## Examples
+### Not true is false
+Running
+```bash
+yq eval --null-input 'true | not'
+```
+will output
+```yaml
+false
+```
+
+### Not false is true
+Running
+```bash
+yq eval --null-input 'false | not'
+```
+will output
+```yaml
+true
+```
+
+### String values considered to be true
+Running
+```bash
+yq eval --null-input '"cat" | not'
+```
+will output
+```yaml
+false
+```
+
+### Empty string value considered to be true
+Running
+```bash
+yq eval --null-input '"" | not'
+```
+will output
+```yaml
+false
+```
+
+### Numbers are considered to be true
+Running
+```bash
+yq eval --null-input '1 | not'
+```
+will output
+```yaml
+false
+```
+
+### Zero is considered to be true
+Running
+```bash
+yq eval --null-input '0 | not'
+```
+will output
+```yaml
+false
+```
+
+### Null is considered to be false
+Running
+```bash
+yq eval --null-input '~ | not'
+```
+will output
+```yaml
+true
+```
+

pkg/yqlib/doc/Recursive Descent Operator.md

@@ -0,0 +1,139 @@
+This operator recursively matches 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, for instance to set the `style` of all nodes in a yaml doc:
+
+```bash
+yq eval '.. style = "flow"' file.yaml
+```
+## Examples
+### Matches single scalar value
+Given a sample.yml file of:
+```yaml
+cat
+```
+then
+```bash
+yq eval '..' sample.yml
+```
+will output
+```yaml
+cat
+```
+
+### Map
+Given a sample.yml file of:
+```yaml
+a:
+  b: apple
+```
+then
+```bash
+yq eval '..' sample.yml
+```
+will output
+```yaml
+a:
+  b: apple
+b: apple
+apple
+```
+
+### Array
+Given a sample.yml file of:
+```yaml
+- 1
+- 2
+- 3
+```
+then
+```bash
+yq eval '..' sample.yml
+```
+will output
+```yaml
+- 1
+- 2
+- 3
+1
+2
+3
+```
+
+### Array of maps
+Given a sample.yml file of:
+```yaml
+- a: cat
+- 2
+- true
+```
+then
+```bash
+yq eval '..' sample.yml
+```
+will output
+```yaml
+- a: cat
+- 2
+- true
+a: cat
+cat
+2
+true
+```
+
+### Aliases are not traversed
+Given a sample.yml file of:
+```yaml
+a: &cat
+  c: frog
+b: *cat
+```
+then
+```bash
+yq eval '..' sample.yml
+```
+will output
+```yaml
+a: &cat
+  c: frog
+b: *cat
+&cat
+c: frog
+frog
+*cat
+```
+
+### Merge docs are not traversed
+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
+c: foobar_c
+!!merge <<: *foo
+thing: foobar_thing
+foobar_c
+*foo
+foobar_thing
+```
+

pkg/yqlib/doc/Style Operator.md

@@ -0,0 +1,79 @@
+
+## Examples
+### Example 0
+Given a sample.yml file of:
+```yaml
+a: cat
+```
+then
+```bash
+yq eval '.a style="single"' sample.yml
+```
+will output
+```yaml
+{a: 'cat'}
+```
+
+### Set style using a path
+Given a sample.yml file of:
+```yaml
+a: cat
+b: double
+```
+then
+```bash
+yq eval '.a style=.b' sample.yml
+```
+will output
+```yaml
+{a: "cat", b: double}
+```
+
+### Example 2
+Given a sample.yml file of:
+```yaml
+a: cat
+b: dog
+```
+then
+```bash
+yq eval '.. style=""' sample.yml
+```
+will output
+```yaml
+a: cat
+b: dog
+```
+
+### Example 3
+Given a sample.yml file of:
+```yaml
+a: cat
+b: thing
+```
+then
+```bash
+yq eval '.. | style' sample.yml
+```
+will output
+```yaml
+flow
+double
+single
+```
+
+### Example 4
+Given a sample.yml file of:
+```yaml
+a: cat
+```
+then
+```bash
+yq eval '.. | style' sample.yml
+```
+will output
+```yaml
+
+
+```
+

pkg/yqlib/doc/Update Assign Operator.md

@@ -0,0 +1,93 @@
+Updates the LHS using the expression on the RHS. Note that the RHS runs against the _original_ LHS value, so that you can evaluate a new value based on the old (e.g. increment).
+## Examples
+### Update parent to be the child value
+Given a sample.yml file of:
+```yaml
+a:
+  b:
+    g: foof
+```
+then
+```bash
+yq eval '.a |= .b' sample.yml
+```
+will output
+```yaml
+{a: {g: foof}}
+```
+
+### Update string value
+Given a sample.yml file of:
+```yaml
+a:
+  b: apple
+```
+then
+```bash
+yq eval '.a.b |= "frog"' sample.yml
+```
+will output
+```yaml
+{a: {b: frog}}
+```
+
+### Update selected results
+Given a sample.yml file of:
+```yaml
+a:
+  b: apple
+  c: cactus
+```
+then
+```bash
+yq eval '.a[] | select(. == "apple") |= "frog"' sample.yml
+```
+will output
+```yaml
+{a: {b: frog, c: cactus}}
+```
+
+### Update array values
+Given a sample.yml file of:
+```yaml
+- candy
+- apple
+- sandy
+```
+then
+```bash
+yq eval '.[] | select(. == "*andy") |= "bogs"' sample.yml
+```
+will output
+```yaml
+[bogs, apple, bogs]
+```
+
+### Update empty object
+Given a sample.yml file of:
+```yaml
+'': null
+```
+then
+```bash
+yq eval '.a.b |= "bogs"' sample.yml
+```
+will output
+```yaml
+{a: {b: bogs}}
+```
+
+### Update empty object and array
+Given a sample.yml file of:
+```yaml
+'': null
+```
+then
+```bash
+yq eval '.a.b[0] |= "bogs"' sample.yml
+```
+will output
+```yaml
+{a: {b: [bogs]}}
+```
+

pkg/yqlib/doc/headers/Collect into Array.md

@@ -0,0 +1,4 @@
+# Collect into Array
+
+This creates an array using the expression between the square brackets.
+

pkg/yqlib/doc/headers/Collect into Object.md

@@ -0,0 +1 @@
+This is used to construct objects (or maps). This can be used against existing yaml, or to create fresh yaml documents.

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

@@ -0,0 +1 @@
+Use these comment operators to set or retrieve comments.

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

@@ -0,0 +1 @@
+Deletes matching entries in maps or arrays.

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

@@ -0,0 +1,14 @@
+## Equals Operator
+
+This is a boolean operator that will return ```true``` if the LHS is equal to the RHS and ``false`` otherwise.
+
+```
+.a == .b
+```
+
+It is most often used with the select operator to find particular nodes:
+
+```
+select(.a == .b)
+```
+

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

@@ -0,0 +1 @@
+Explodes (or dereferences) aliases and anchors.

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

@@ -0,0 +1,5 @@
+Like the multiple operator in `jq`, depending on the operands, this multiply operator will do different things. Currently only objects are supported, which have the effect of merging the RHS into the LHS.
+
+Upcoming versions of `yq` will add support for other types of multiplication (numbers, strings).
+
+Note that when merging objects, this operator returns the merged object (not the parent). This will be clearer in the examples below.

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

@@ -0,0 +1 @@
+This is a boolean operator and will return `true` when given a `false` value (including null), and `false` otherwise.

pkg/yqlib/doc/headers/Recursive Descent Operator.md

@@ -0,0 +1,5 @@
+This operator recursively matches 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, for instance to set the `style` of all nodes in a yaml doc:
+
+```bash
+yq eval '.. style= "flow"' file.yaml
+```

pkg/yqlib/doc/headers/Update Assign Operator.md

@@ -0,0 +1 @@
+Updates the LHS using the expression on the RHS. Note that the RHS runs against the _original_ LHS value, so that you can evaluate a new value based on the old (e.g. increment).