use addChild methods

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

@@ -10,6 +10,56 @@ This will set the LHS nodes' comments equal to the expression on the RHS. The RH
 ### relative form: `|=` 
 This is similar to the plain form, but it evaluates the RHS with _each matching LHS node as context_. 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 the comment on the key node for more reliability (see below).
+
+Given a sample.yml file of:
+```yaml
+a: cat
+```
+then
+```bash
+yq '.a line_comment="single"' sample.yml
+```
+will output
+```yaml
+a: cat # single
+```
+
+## Set line comment of a maps/arrays
+For maps and arrays, you need to set the line comment on the _key_ node. This will also work for scalars.
+
+Given a sample.yml file of:
+```yaml
+a:
+  b: things
+```
+then
+```bash
+yq '(.a | key) line_comment="single"' sample.yml
+```
+will output
+```yaml
+a: # single
+  b: things
+```
+
+## Use update assign to perform relative updates
+Given a sample.yml file of:
+```yaml
+a: cat
+b: dog
+```
+then
+```bash
+yq '.. line_comment |= .' sample.yml
+```
+will output
+```yaml
+a: cat # cat
+b: dog # dog
+```
+
 ## Where is the comment - map key example
 The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. 'p' indicates the path, 'isKey' is if the node is a map key (as opposed to a map value).
 From this, you can see the 'hello-world-comment' is actually on the 'hello' key
@@ -52,3 +102,239 @@ will output
   fc: ""
 ```
 
+## Retrieve comment - map key example
+From the previous example, we know that the comment is on the 'hello' _key_ as a lineComment
+
+Given a sample.yml file of:
+```yaml
+hello: # hello-world-comment
+  message: world
+```
+then
+```bash
+yq '.hello | key | line_comment' sample.yml
+```
+will output
+```yaml
+hello-world-comment
+```
+
+## Where is the comment - array example
+The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. 'p' indicates the path, 'isKey' is if the node is a map key (as opposed to a map value).
+From this, you can see the 'under-name-comment' is actually on the first child
+
+Given a sample.yml file of:
+```yaml
+name:
+  # under-name-comment
+  - first-array-child
+```
+then
+```bash
+yq '[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]' sample.yml
+```
+will output
+```yaml
+- p: ""
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name
+  isKey: true
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name
+  isKey: false
+  hc: ""
+  lc: ""
+  fc: ""
+- p: name.0
+  isKey: false
+  hc: under-name-comment
+  lc: ""
+  fc: ""
+```
+
+## Retrieve comment - array example
+From the previous example, we know that the comment is on the first child as a headComment
+
+Given a sample.yml file of:
+```yaml
+name:
+  # under-name-comment
+  - first-array-child
+```
+then
+```bash
+yq '.name[0] | headComment' sample.yml
+```
+will output
+```yaml
+under-name-comment
+```
+
+## Set head comment
+Given a sample.yml file of:
+```yaml
+a: cat
+```
+then
+```bash
+yq '. head_comment="single"' sample.yml
+```
+will output
+```yaml
+# single
+
+a: cat
+```
+
+## Set head comment of a map entry
+Given a sample.yml file of:
+```yaml
+f: foo
+a:
+  b: cat
+```
+then
+```bash
+yq '(.a | key) head_comment="single"' sample.yml
+```
+will output
+```yaml
+f: foo
+# single
+a:
+  b: cat
+```
+
+## Set foot comment, using an expression
+Given a sample.yml file of:
+```yaml
+a: cat
+```
+then
+```bash
+yq '. foot_comment=.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 '.a line_comment=""' sample.yml
+```
+will output
+```yaml
+a: cat
+b: dog # leave this
+```
+
+## Remove (strip) all comments
+Note the use of `...` to ensure key nodes are included.
+
+Given a sample.yml file of:
+```yaml
+# hi
+
+a: cat # comment
+# great
+b: # key comment
+```
+then
+```bash
+yq '... comments=""' sample.yml
+```
+will output
+```yaml
+a: cat
+b:
+```
+
+## Get line comment
+Given a sample.yml file of:
+```yaml
+# welcome!
+
+a: cat # meow
+# have a great day
+```
+then
+```bash
+yq '.a | line_comment' sample.yml
+```
+will output
+```yaml
+meow
+```
+
+## Get head comment
+Given a sample.yml file of:
+```yaml
+# welcome!
+
+a: cat # meow
+
+# have a great day
+```
+then
+```bash
+yq '. | head_comment' sample.yml
+```
+will output
+```yaml
+welcome!
+
+```
+
+## Head comment with document split
+Given a sample.yml file of:
+```yaml
+# welcome!
+---
+# bob
+a: cat # meow
+
+# have a great day
+```
+then
+```bash
+yq 'head_comment' sample.yml
+```
+will output
+```yaml
+welcome!
+bob
+```
+
+## Get foot comment
+Given a sample.yml file of:
+```yaml
+# welcome!
+
+a: cat # meow
+
+# have a great day
+# no really
+```
+then
+```bash
+yq '. | foot_comment' sample.yml
+```
+will output
+```yaml
+have a great day
+no really
+```
+

pkg/yqlib/doc/operators/create-collect-into-object.md

@@ -56,7 +56,6 @@ will output
 ```yaml
 Mike: cat
 Mike: dog
----
 Rosey: monkey
 Rosey: sheep
 ```

pkg/yqlib/doc/operators/document-index.md

@@ -85,7 +85,6 @@ will output
 ```yaml
 match: cat
 doc: 0
----
 match: frog
 doc: 1
 ```

pkg/yqlib/doc/operators/keys.md

@@ -2,10 +2,119 @@
 
 Use the `keys` operator to return map keys or array indices. 
 
+## Map keys
+Given a sample.yml file of:
+```yaml
+{dog: woof, cat: meow}
+```
+then
+```bash
+yq 'keys' sample.yml
+```
+will output
+```yaml
+- dog
+- cat
+```
+
+## Array keys
+Given a sample.yml file of:
+```yaml
+[apple, banana]
+```
+then
+```bash
+yq 'keys' sample.yml
+```
+will output
+```yaml
+- 0
+- 1
+```
+
+## Retrieve array key
+Given a sample.yml file of:
+```yaml
+[1, 2, 3]
+```
+then
+```bash
+yq '.[1] | key' sample.yml
+```
+will output
+```yaml
+1
+```
+
+## Retrieve map key
+Given a sample.yml file of:
+```yaml
+a: thing
+```
+then
+```bash
+yq '.a | key' sample.yml
+```
+will output
+```yaml
+a
+```
+
+## No key
+Given a sample.yml file of:
+```yaml
+{}
+```
+then
+```bash
+yq 'key' sample.yml
+```
+will output
+```yaml
+```
+
+## Update map key
+Given a sample.yml file of:
+```yaml
+a:
+  x: 3
+  y: 4
+```
+then
+```bash
+yq '(.a.x | key) = "meow"' sample.yml
+```
+will output
+```yaml
+a:
+  meow: 3
+  y: 4
+```
+
+## Get comment from map key
+Given a sample.yml file of:
+```yaml
+a:
+  # comment on key
+  x: 3
+  y: 4
+```
+then
+```bash
+yq '.a.x | key | headComment' sample.yml
+```
+will output
+```yaml
+comment on key
+```
+
 ## Check node is a key
 Given a sample.yml file of:
 ```yaml
-a: frog
+a:
+  b:
+    - cat
+  c: frog
 ```
 then
 ```bash
@@ -18,9 +127,20 @@ will output
   tag: '!!map'
 - p: a
   isKey: true
-  tag: null
-  '!!str': null
+  tag: '!!str'
 - p: a
+  isKey: false
+  tag: '!!map'
+- p: a.c
+  isKey: true
+  tag: '!!str'
+- p: a.b
+  isKey: false
+  tag: '!!seq'
+- p: a.b.0
+  isKey: false
+  tag: '!!str'
+- p: a.c
   isKey: false
   tag: '!!str'
 ```

pkg/yqlib/doc/operators/length.md

@@ -7,7 +7,7 @@ returns length of string
 
 Given a sample.yml file of:
 ```yaml
-a: cat
+{a: cat}
 ```
 then
 ```bash
@@ -21,7 +21,7 @@ will output
 ## null length
 Given a sample.yml file of:
 ```yaml
-a: null
+{a: null}
 ```
 then
 ```bash
@@ -37,8 +37,7 @@ returns number of entries
 
 Given a sample.yml file of:
 ```yaml
-a: cat
-c: dog
+{a: cat, c: dog}
 ```
 then
 ```bash
@@ -54,10 +53,7 @@ returns number of elements
 
 Given a sample.yml file of:
 ```yaml
-- 2
-- 4
-- 6
-- 8
+[2, 4, 6, 8]
 ```
 then
 ```bash

pkg/yqlib/doc/operators/load.md

@@ -48,7 +48,7 @@ bXkgc2VjcmV0IGNoaWxsaSByZWNpcGUgaXMuLi4u
 ## Simple example
 Given a sample.yml file of:
 ```yaml
-myFile: ../../examples/thing.yml
+{myFile: ../../examples/thing.yml}
 ```
 then
 ```bash
@@ -65,8 +65,7 @@ Note that you can modify the filename in the load operator if needed.
 
 Given a sample.yml file of:
 ```yaml
-something:
-  file: thing.yml
+{something: {file: thing.yml}}
 ```
 then
 ```bash
@@ -74,9 +73,7 @@ yq '.something |= load("../../examples/" + .file)' sample.yml
 ```
 will output
 ```yaml
-something:
-  a: apple is included
-  b: cool.
+{something: {a: apple is included, b: cool.}}
 ```
 
 ## Replace _all_ nodes with referenced file
@@ -84,11 +81,7 @@ Recursively match all the nodes (`..`) and then filter the ones that have a 'fil
 
 Given a sample.yml file of:
 ```yaml
-something:
-  file: thing.yml
-over:
-  here:
-    - file: thing.yml
+{something: {file: thing.yml}, over: {here: [{file: thing.yml}]}}
 ```
 then
 ```bash
@@ -96,13 +89,7 @@ yq '(.. | select(has("file"))) |= load("../../examples/" + .file)' sample.yml
 ```
 will output
 ```yaml
-something:
-  a: apple is included
-  b: cool.
-over:
-  here:
-    - a: apple is included
-      b: cool.
+{something: {a: apple is included, b: cool.}, over: {here: [{a: apple is included, b: cool.}]}}
 ```
 
 ## Replace node with referenced file as string
@@ -110,8 +97,7 @@ This will work for any text based file
 
 Given a sample.yml file of:
 ```yaml
-something:
-  file: thing.yml
+{something: {file: thing.yml}}
 ```
 then
 ```bash
@@ -119,9 +105,7 @@ yq '.something |= load_str("../../examples/" + .file)' sample.yml
 ```
 will output
 ```yaml
-something: |-
-  a: apple is included
-  b: cool.
+{something: "a: apple is included\nb: cool."}
 ```
 
 ## Load from XML
@@ -172,9 +156,7 @@ yq '. *= load_props("../../examples/small.properties")' sample.yml
 ```
 will output
 ```yaml
-this:
-  is: a properties file
-  cool: ay
+is
 ```
 
 ## Load from base64 encoded file

pkg/yqlib/doc/operators/map.md

@@ -5,9 +5,7 @@ Maps values of an array. Use `map_values` to map values of an object.
 ## Map array
 Given a sample.yml file of:
 ```yaml
-- 1
-- 2
-- 3
+[1, 2, 3]
 ```
 then
 ```bash
@@ -15,17 +13,13 @@ yq 'map(. + 1)' sample.yml
 ```
 will output
 ```yaml
-- 2
-- 3
-- 4
+[2, 3, 4]
 ```
 
 ## Map object values
 Given a sample.yml file of:
 ```yaml
-a: 1
-b: 2
-c: 3
+{a: 1, b: 2, c: 3}
 ```
 then
 ```bash
@@ -33,8 +27,6 @@ yq 'map_values(. + 1)' sample.yml
 ```
 will output
 ```yaml
-a: 2
-b: 3
-c: 4
+{a: 2, b: 3, c: 4}
 ```
 

pkg/yqlib/doc/operators/modulo.md

@@ -7,8 +7,7 @@ If the lhs and rhs are ints then the expression will be calculated with ints.
 
 Given a sample.yml file of:
 ```yaml
-a: 13
-b: 2
+{a: 13, b: 2}
 ```
 then
 ```bash
@@ -16,8 +15,7 @@ yq '.a = .a % .b' sample.yml
 ```
 will output
 ```yaml
-a: 1
-b: 2
+{a: 1, b: 2}
 ```
 
 ## Number modulo - float
@@ -25,8 +23,7 @@ If the lhs or rhs are floats then the expression will be calculated with floats.
 
 Given a sample.yml file of:
 ```yaml
-a: 12
-b: 2.5
+{a: 12, b: 2.5}
 ```
 then
 ```bash
@@ -34,8 +31,7 @@ yq '.a = .a % .b' sample.yml
 ```
 will output
 ```yaml
-a: !!float 2
-b: 2.5
+{a: !!float 2, b: 2.5}
 ```
 
 ## Number modulo - int by zero
@@ -43,8 +39,7 @@ If the lhs is an int and rhs is a 0 the result is an error.
 
 Given a sample.yml file of:
 ```yaml
-a: 1
-b: 0
+{a: 1, b: 0}
 ```
 then
 ```bash
@@ -60,8 +55,7 @@ If the lhs is a float and rhs is a 0 the result is NaN.
 
 Given a sample.yml file of:
 ```yaml
-a: 1.1
-b: 0
+{a: 1.1, b: 0}
 ```
 then
 ```bash
@@ -69,7 +63,6 @@ yq '.a = .a % .b' sample.yml
 ```
 will output
 ```yaml
-a: !!float NaN
-b: 0
+{a: !!float NaN, b: 0}
 ```
 

pkg/yqlib/doc/operators/path.md

@@ -10,8 +10,7 @@ Use `setpath` to set a value to the path array returned by `path`, and similarly
 ## Map path
 Given a sample.yml file of:
 ```yaml
-a:
-  b: cat
+{a: {b: cat}}
 ```
 then
 ```bash
@@ -26,8 +25,7 @@ will output
 ## Get map key
 Given a sample.yml file of:
 ```yaml
-a:
-  b: cat
+{a: {b: cat}}
 ```
 then
 ```bash
@@ -41,9 +39,7 @@ b
 ## Array path
 Given a sample.yml file of:
 ```yaml
-a:
-  - cat
-  - dog
+{a: [cat, dog]}
 ```
 then
 ```bash
@@ -58,9 +54,7 @@ will output
 ## Get array index
 Given a sample.yml file of:
 ```yaml
-a:
-  - cat
-  - dog
+{a: [cat, dog]}
 ```
 then
 ```bash
@@ -74,10 +68,7 @@ will output
 ## Print path and value
 Given a sample.yml file of:
 ```yaml
-a:
-  - cat
-  - dog
-  - frog
+{a: [cat, dog, frog]}
 ```
 then
 ```bash
@@ -98,8 +89,7 @@ will output
 ## Set path
 Given a sample.yml file of:
 ```yaml
-a:
-  b: cat
+{a: {b: cat}}
 ```
 then
 ```bash
@@ -107,8 +97,7 @@ yq 'setpath(["a", "b"]; "things")' sample.yml
 ```
 will output
 ```yaml
-a:
-  b: things
+{a: {b: things}}
 ```
 
 ## Set on empty document
@@ -183,10 +172,7 @@ Notice delpaths takes an _array_ of paths.
 
 Given a sample.yml file of:
 ```yaml
-a:
-  b: cat
-  c: dog
-  d: frog
+{a: {b: cat, c: dog, d: frog}}
 ```
 then
 ```bash
@@ -194,8 +180,7 @@ yq 'delpaths([["a", "c"], ["a", "d"]])' sample.yml
 ```
 will output
 ```yaml
-a:
-  b: cat
+{a: {b: cat}}
 ```
 
 ## Delete array path

pkg/yqlib/doc/operators/pick.md

@@ -31,9 +31,7 @@ Note that the order of the indices matches the pick order and non existent indic
 
 Given a sample.yml file of:
 ```yaml
-- cat
-- leopard
-- lion
+[cat, leopard, lion]
 ```
 then
 ```bash
@@ -41,7 +39,6 @@ yq 'pick([2, 0, 734, -5])' sample.yml
 ```
 will output
 ```yaml
-- lion
-- cat
+[lion, cat]
 ```
 

pkg/yqlib/doc/operators/reverse.md

@@ -5,9 +5,7 @@ Reverses the order of the items in an array
 ## Reverse
 Given a sample.yml file of:
 ```yaml
-- 1
-- 2
-- 3
+[1, 2, 3]
 ```
 then
 ```bash
@@ -15,9 +13,7 @@ yq 'reverse' sample.yml
 ```
 will output
 ```yaml
-- 3
-- 2
-- 1
+[3, 2, 1]
 ```
 
 ## Sort descending by string field
@@ -25,9 +21,7 @@ Use sort with reverse to sort in descending order.
 
 Given a sample.yml file of:
 ```yaml
-- a: banana
-- a: cat
-- a: apple
+[{a: banana}, {a: cat}, {a: apple}]
 ```
 then
 ```bash
@@ -35,8 +29,6 @@ yq 'sort_by(.a) | reverse' sample.yml
 ```
 will output
 ```yaml
-- a: cat
-- a: banana
-- a: apple
+[{a: cat}, {a: banana}, {a: apple}]
 ```
 

pkg/yqlib/doc/operators/slice-array.md

@@ -7,10 +7,7 @@ You may leave out the first or second number, which will will refer to the start
 ## Slicing arrays
 Given a sample.yml file of:
 ```yaml
-- cat
-- dog
-- frog
-- cow
+[cat, dog, frog, cow]
 ```
 then
 ```bash
@@ -27,10 +24,7 @@ Starts from the start of the array
 
 Given a sample.yml file of:
 ```yaml
-- cat
-- dog
-- frog
-- cow
+[cat, dog, frog, cow]
 ```
 then
 ```bash
@@ -47,10 +41,7 @@ Finishes at the end of the array
 
 Given a sample.yml file of:
 ```yaml
-- cat
-- dog
-- frog
-- cow
+[cat, dog, frog, cow]
 ```
 then
 ```bash
@@ -65,10 +56,7 @@ will output
 ## Slicing arrays - use negative numbers to count backwards from the end
 Given a sample.yml file of:
 ```yaml
-- cat
-- dog
-- frog
-- cow
+[cat, dog, frog, cow]
 ```
 then
 ```bash
@@ -85,10 +73,7 @@ using an expression to find the index
 
 Given a sample.yml file of:
 ```yaml
-- cat
-- dog
-- frog
-- cow
+[cat, dog, frog, cow]
 ```
 then
 ```bash

pkg/yqlib/doc/operators/sort-keys.md

@@ -18,9 +18,7 @@ See [here](https://mikefarah.gitbook.io/yq/operators/entries#custom-sort-map-key
 ## Sort keys of map
 Given a sample.yml file of:
 ```yaml
-c: frog
-a: blah
-b: bing
+{c: frog, a: blah, b: bing}
 ```
 then
 ```bash
@@ -28,9 +26,7 @@ yq 'sort_keys(.)' sample.yml
 ```
 will output
 ```yaml
-a: blah
-b: bing
-c: frog
+{a: blah, b: bing, c: frog}
 ```
 
 ## Sort keys recursively
@@ -38,19 +34,7 @@ Note the array elements are left unsorted, but maps inside arrays are sorted
 
 Given a sample.yml file of:
 ```yaml
-bParent:
-  c: dog
-  array:
-    - 3
-    - 1
-    - 2
-aParent:
-  z: donkey
-  x:
-    - c: yum
-      b: delish
-    - b: ew
-      a: apple
+{bParent: {c: dog, array: [3, 1, 2]}, aParent: {z: donkey, x: [{c: yum, b: delish}, {b: ew, a: apple}]}}
 ```
 then
 ```bash
@@ -58,18 +42,6 @@ yq 'sort_keys(..)' sample.yml
 ```
 will output
 ```yaml
-aParent:
-  x:
-    - b: delish
-      c: yum
-    - a: apple
-      b: ew
-  z: donkey
-bParent:
-  array:
-    - 3
-    - 1
-    - 2
-  c: dog
+{aParent: {x: [{b: delish, c: yum}, {a: apple, b: ew}], z: donkey}, bParent: {array: [3, 1, 2], c: dog}}
 ```
 

pkg/yqlib/doc/operators/sort.md

@@ -10,9 +10,7 @@ Note that at this stage, `yq` only sorts scalar fields.
 ## Sort by string field
 Given a sample.yml file of:
 ```yaml
-- a: banana
-- a: cat
-- a: apple
+[{a: banana}, {a: cat}, {a: apple}]
 ```
 then
 ```bash
@@ -20,19 +18,13 @@ yq 'sort_by(.a)' sample.yml
 ```
 will output
 ```yaml
-- a: apple
-- a: banana
-- a: cat
+[{a: apple}, {a: banana}, {a: cat}]
 ```
 
 ## Sort by multiple fields
 Given a sample.yml file of:
 ```yaml
-- a: dog
-- a: cat
-  b: banana
-- a: cat
-  b: apple
+[{a: dog}, {a: cat, b: banana}, {a: cat, b: apple}]
 ```
 then
 ```bash
@@ -40,11 +32,7 @@ yq 'sort_by(.a, .b)' sample.yml
 ```
 will output
 ```yaml
-- a: cat
-  b: apple
-- a: cat
-  b: banana
-- a: dog
+[{a: cat, b: apple}, {a: cat, b: banana}, {a: dog}]
 ```
 
 ## Sort descending by string field
@@ -52,9 +40,7 @@ Use sort with reverse to sort in descending order.
 
 Given a sample.yml file of:
 ```yaml
-- a: banana
-- a: cat
-- a: apple
+[{a: banana}, {a: cat}, {a: apple}]
 ```
 then
 ```bash
@@ -62,9 +48,7 @@ yq 'sort_by(.a) | reverse' sample.yml
 ```
 will output
 ```yaml
-- a: cat
-- a: banana
-- a: apple
+[{a: cat}, {a: banana}, {a: apple}]
 ```
 
 ## Sort array in place
@@ -114,14 +98,7 @@ Note the order of the elements in unchanged when equal in sorting.
 
 Given a sample.yml file of:
 ```yaml
-- a: banana
-  b: 1
-- a: banana
-  b: 2
-- a: banana
-  b: 3
-- a: banana
-  b: 4
+[{a: banana, b: 1}, {a: banana, b: 2}, {a: banana, b: 3}, {a: banana, b: 4}]
 ```
 then
 ```bash
@@ -129,22 +106,13 @@ yq 'sort_by(.a)' sample.yml
 ```
 will output
 ```yaml
-- a: banana
-  b: 1
-- a: banana
-  b: 2
-- a: banana
-  b: 3
-- a: banana
-  b: 4
+[{a: banana, b: 1}, {a: banana, b: 2}, {a: banana, b: 3}, {a: banana, b: 4}]
 ```
 
 ## Sort by numeric field
 Given a sample.yml file of:
 ```yaml
-- a: 10
-- a: 100
-- a: 1
+[{a: 10}, {a: 100}, {a: 1}]
 ```
 then
 ```bash
@@ -152,17 +120,13 @@ yq 'sort_by(.a)' sample.yml
 ```
 will output
 ```yaml
-- a: 1
-- a: 10
-- a: 100
+[{a: 1}, {a: 10}, {a: 100}]
 ```
 
 ## Sort by custom date field
 Given a sample.yml file of:
 ```yaml
-- a: 12-Jun-2011
-- a: 23-Dec-2010
-- a: 10-Aug-2011
+[{a: 12-Jun-2011}, {a: 23-Dec-2010}, {a: 10-Aug-2011}]
 ```
 then
 ```bash
@@ -170,21 +134,13 @@ yq 'with_dtf("02-Jan-2006"; sort_by(.a))' sample.yml
 ```
 will output
 ```yaml
-- a: 23-Dec-2010
-- a: 12-Jun-2011
-- a: 10-Aug-2011
+[{a: 23-Dec-2010}, {a: 12-Jun-2011}, {a: 10-Aug-2011}]
 ```
 
 ## Sort, nulls come first
 Given a sample.yml file of:
 ```yaml
-- 8
-- 3
-- null
-- 6
-- true
-- false
-- cat
+[8, 3, null, 6, true, false, cat]
 ```
 then
 ```bash
@@ -192,12 +148,6 @@ yq 'sort' sample.yml
 ```
 will output
 ```yaml
-- null
-- false
-- true
-- 3
-- 6
-- 8
-- cat
+[null, false, true, 3, 6, 8, cat]
 ```
 

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

@@ -91,11 +91,7 @@ will output
 ## Join strings
 Given a sample.yml file of:
 ```yaml
-- cat
-- meow
-- 1
-- null
-- true
+[cat, meow, 1, null, true]
 ```
 then
 ```bash
@@ -109,10 +105,7 @@ cat; meow; 1; ; true
 ## Trim strings
 Given a sample.yml file of:
 ```yaml
-- ' cat'
-- 'dog '
-- ' cow cow '
-- horse
+[' cat', 'dog ', ' cow cow ', horse]
 ```
 then
 ```bash
@@ -284,8 +277,7 @@ Like jq's equivalent, this works like match but only returns true/false instead
 
 Given a sample.yml file of:
 ```yaml
-- cat
-- dog
+[cat, dog]
 ```
 then
 ```bash
@@ -354,7 +346,7 @@ b: !goat heart
 ## Split strings
 Given a sample.yml file of:
 ```yaml
-cat; meow; 1; ; true
+"cat; meow; 1; ; true"
 ```
 then
 ```bash
@@ -372,7 +364,7 @@ will output
 ## Split strings one match
 Given a sample.yml file of:
 ```yaml
-word
+"word"
 ```
 then
 ```bash

pkg/yqlib/doc/operators/subtract.md

@@ -28,9 +28,7 @@ Note that order of the keys does not matter
 
 Given a sample.yml file of:
 ```yaml
-- a: b
-  c: d
-- a: b
+[{a: b, c: d}, {a: b}]
 ```
 then
 ```bash
@@ -38,7 +36,7 @@ yq '. - [{"c": "d", "a": "b"}]' sample.yml
 ```
 will output
 ```yaml
-- a: b
+[{a: b}]
 ```
 
 ## Number subtraction - float
@@ -46,8 +44,7 @@ If the lhs or rhs are floats then the expression will be calculated with floats.
 
 Given a sample.yml file of:
 ```yaml
-a: 3
-b: 4.5
+{a: 3, b: 4.5}
 ```
 then
 ```bash
@@ -55,8 +52,7 @@ yq '.a = .a - .b' sample.yml
 ```
 will output
 ```yaml
-a: -1.5
-b: 4.5
+{a: -1.5, b: 4.5}
 ```
 
 ## Number subtraction - int
@@ -64,8 +60,7 @@ If both the lhs and rhs are ints then the expression will be calculated with int
 
 Given a sample.yml file of:
 ```yaml
-a: 3
-b: 4
+{a: 3, b: 4}
 ```
 then
 ```bash
@@ -73,15 +68,13 @@ yq '.a = .a - .b' sample.yml
 ```
 will output
 ```yaml
-a: -1
-b: 4
+{a: -1, b: 4}
 ```
 
 ## Decrement numbers
 Given a sample.yml file of:
 ```yaml
-a: 3
-b: 5
+{a: 3, b: 5}
 ```
 then
 ```bash
@@ -89,8 +82,7 @@ yq '.[] -= 1' sample.yml
 ```
 will output
 ```yaml
-a: 2
-b: 4
+{a: 2, b: 4}
 ```
 
 ## Date subtraction

pkg/yqlib/doc/operators/tag.md

@@ -5,11 +5,7 @@ The tag operator can be used to get or set the tag of nodes (e.g. `!!str`, `!!in
 ## Get tag
 Given a sample.yml file of:
 ```yaml
-a: cat
-b: 5
-c: 3.2
-e: true
-f: []
+{a: cat, b: 5, c: 3.2, e: true, f: []}
 ```
 then
 ```bash
@@ -28,11 +24,7 @@ will output
 ## type is an alias for tag
 Given a sample.yml file of:
 ```yaml
-a: cat
-b: 5
-c: 3.2
-e: true
-f: []
+{a: cat, b: 5, c: 3.2, e: true, f: []}
 ```
 then
 ```bash
@@ -51,7 +43,7 @@ will output
 ## Set custom tag
 Given a sample.yml file of:
 ```yaml
-a: str
+{a: str}
 ```
 then
 ```bash
@@ -59,16 +51,13 @@ yq '.a tag = "!!mikefarah"' sample.yml
 ```
 will output
 ```yaml
-a: !!mikefarah str
+{a: !!mikefarah str}
 ```
 
 ## Find numbers and convert them to strings
 Given a sample.yml file of:
 ```yaml
-a: cat
-b: 5
-c: 3.2
-e: true
+{a: cat, b: 5, c: 3.2, e: true}
 ```
 then
 ```bash
@@ -76,9 +65,6 @@ yq '(.. | select(tag == "!!int")) tag= "!!str"' sample.yml
 ```
 will output
 ```yaml
-a: cat
-b: "5"
-c: 3.2
-e: true
+{a: cat, b: "5", c: 3.2, e: true}
 ```
 

pkg/yqlib/doc/operators/unique.md

@@ -8,10 +8,7 @@ Note that unique maintains the original order of the array.
 
 Given a sample.yml file of:
 ```yaml
-- 2
-- 1
-- 3
-- 2
+[2, 1, 3, 2]
 ```
 then
 ```bash
@@ -19,9 +16,7 @@ yq 'unique' sample.yml
 ```
 will output
 ```yaml
-- 2
-- 1
-- 3
+[2, 1, 3]
 ```
 
 ## Unique nulls
@@ -29,10 +24,7 @@ Unique works on the node value, so it considers different representations of nul
 
 Given a sample.yml file of:
 ```yaml
-- ~
-- null
-- ~
-- null
+[~, null, ~, null]
 ```
 then
 ```bash
@@ -40,8 +32,7 @@ yq 'unique' sample.yml
 ```
 will output
 ```yaml
-- ~
-- null
+[~, null]
 ```
 
 ## Unique all nulls
@@ -49,10 +40,7 @@ Run against the node tag to unique all the nulls
 
 Given a sample.yml file of:
 ```yaml
-- ~
-- null
-- ~
-- null
+[~, null, ~, null]
 ```
 then
 ```bash
@@ -60,18 +48,13 @@ yq 'unique_by(tag)' sample.yml
 ```
 will output
 ```yaml
-- ~
+[~]
 ```
 
 ## Unique array object fields
 Given a sample.yml file of:
 ```yaml
-- name: harry
-  pet: cat
-- name: billy
-  pet: dog
-- name: harry
-  pet: dog
+[{name: harry, pet: cat}, {name: billy, pet: dog}, {name: harry, pet: dog}]
 ```
 then
 ```bash
@@ -79,9 +62,6 @@ yq 'unique_by(.name)' sample.yml
 ```
 will output
 ```yaml
-- name: harry
-  pet: cat
-- name: billy
-  pet: dog
+[{name: harry, pet: cat}, {name: billy, pet: dog}]
 ```
 

pkg/yqlib/doc/usage/csv-tsv.md

@@ -111,3 +111,98 @@ Gary,1
 Samantha's Rabbit,2
 ```
 
+## Encode array of objects to csv - missing fields behaviour
+First entry is used to determine the headers, and it is missing 'likesApples', so it is not included in the csv. Second entry does not have 'numberOfCats' so that is blank
+
+Given a sample.yml file of:
+```yaml
+- name: Gary
+  numberOfCats: 1
+  height: 168.8
+- name: Samantha's Rabbit
+  height: -188.8
+  likesApples: false
+
+```
+then
+```bash
+yq -o=csv sample.yml
+```
+will output
+```csv
+name,numberOfCats,height
+Gary,1,168.8
+Samantha's Rabbit,,-188.8
+```
+
+## Parse CSV into an array of objects
+First row is assumed to be the header row.
+
+Given a sample.csv file of:
+```csv
+name,numberOfCats,likesApples,height
+Gary,1,true,168.8
+Samantha's Rabbit,2,false,-188.8
+
+```
+then
+```bash
+yq -p=csv sample.csv
+```
+will output
+```yaml
+- name: Gary
+  numberOfCats: 1
+  likesApples: true
+  height: 168.8
+- name: Samantha's Rabbit
+  numberOfCats: 2
+  likesApples: false
+  height: -188.8
+```
+
+## Parse TSV into an array of objects
+First row is assumed to be the header row.
+
+Given a sample.tsv file of:
+```tsv
+name	numberOfCats	likesApples	height
+Gary	1	true	168.8
+Samantha's Rabbit	2	false	-188.8
+
+```
+then
+```bash
+yq -p=tsv sample.tsv
+```
+will output
+```yaml
+- name: Gary
+  numberOfCats: 1
+  likesApples: true
+  height: 168.8
+- name: Samantha's Rabbit
+  numberOfCats: 2
+  likesApples: false
+  height: -188.8
+```
+
+## Round trip
+Given a sample.csv file of:
+```csv
+name,numberOfCats,likesApples,height
+Gary,1,true,168.8
+Samantha's Rabbit,2,false,-188.8
+
+```
+then
+```bash
+yq -p=csv -o=csv '(.[] | select(.name == "Gary") | .numberOfCats) = 3' sample.csv
+```
+will output
+```csv
+name,numberOfCats,likesApples,height
+Gary,3,true,168.8
+Samantha's Rabbit,2,false,-188.8
+```
+