wip update docs

mkdocs/convert.md

@@ -1,5 +1,7 @@
-### Yaml to Json
-To convert output to json, use the --tojson (or -j) flag. This can only be used with the read command.
+## Yaml to Json
+To convert output to json, use the --tojson (or -j) flag. This is supported by all commands.
+
+Each matching yaml node will be converted to json and printed out on a separate line.
 
 Given a sample.yaml file of:
 ```yaml
@@ -8,7 +10,7 @@ b:
 ```
 then
 ```bash
-yq r -j sample.yaml b.c
+yq r -j sample.yaml
 ```
 
 will output
@@ -16,7 +18,25 @@ will output
 {"b":{"c":2}}
 ```
 
-### Json to Yaml
+Given a sample.yaml file of:
+```yaml
+bob:
+  c: 2
+bab:
+  c: 5
+```
+then
+```bash
+yq r -j sample.yaml b*
+```
+
+will output
+```json
+{"c":2}
+{"c":5}
+```
+
+## Json to Yaml
 To read in json, just pass in a json file instead of yaml, it will just work :)
 
 e.g given a json file

mkdocs/create.md

@@ -1,10 +1,12 @@
+```
+yq n <path_expression> <new value>
+```
+
 Yaml files can be created using the 'new' command. This works in the same way as the write command, but you don't pass in an existing Yaml file. Currently this does not support creating multiple documents in a single yaml file.
 
-```
-yq n <path> <new value>
-```
+See docs for [path expression](path_expressions.md)
 
-### Creating a simple yaml file
+## Creating a simple yaml file
 ```bash
 yq n b.c cat
 ```
@@ -14,13 +16,16 @@ b:
   c: cat
 ```
 
-### Creating using a create script
+## Creating using a create script
 Create scripts follow the same format as the update scripts.
 
 Given a script create_instructions.yaml of:
 ```yaml
-b.c: 3
-b.e[+].name: Howdy Partner
+- command: update 
+  path: b.c
+  value:
+    #great 
+    things: frog # wow!
 ```
 then
 
@@ -30,15 +35,13 @@ yq n -s create_instructions.yaml
 will output:
 ```yaml
 b:
-  c: 3
-  e:
-    - name: Howdy Partner
+  c:
+    #great
+    things: frog # wow!
 ```
 
 You can also pipe the instructions in:
 
 ```bash
 cat create_instructions.yaml | yq n -s -
-```
-
-{!snippets/niche.md!}
+```

mkdocs/delete.md

@@ -1,8 +1,13 @@
 ```
-yq d <yaml_file> <path_to_delete>
+yq delete <yaml_file|-> <path_expression>
 ```
 
-### To Stdout
+The delete command will delete all the matching nodes for the path expression in the given yaml input.
+
+See docs for [path expression](path_expressions.md) for more details.
+
+
+## Deleting from a simple document
 Given a sample.yaml file of:
 ```yaml
 b:
@@ -13,141 +18,29 @@ then
 ```bash
 yq d sample.yaml b.c
 ```
-will output:
+will output
 ```yaml
 b:
   apples: green
 ```
 
-### From STDIN
+## From STDIN
+Use "-" (without quotes) in-place of a file name if you wish to pipe in input from STDIN.
+
 ```bash
 cat sample.yaml | yq d - b.c
 ```
 
-### Deleting array elements
-Given a sample.yaml file of:
-```yaml
-b:
-  c: 
-    - 1
-    - 2
-    - 3
-```
-then
-```bash
-yq d sample.yaml 'b.c[1]'
-```
-will output:
-```yaml
-b:
-  c:
-  - 1
-  - 3
-```
-
-### Deleting nodes in-place
-Given a sample.yaml file of:
-```yaml
-b:
-  c: 2
-  apples: green
-```
-then
+## Deleting in-place
 ```bash
 yq d -i sample.yaml b.c
 ```
 will update the sample.yaml file so that the 'c' node is deleted
 
 
-### Splat
-Given a sample.yaml file of:
-```yaml
----
-bob:
-  item1:
-    cats: bananas
-    dogs: woof
-  item2:
-    cats: apples
-    dogs: woof2
-  thing:
-    cats: oranges
-    dogs: woof3
-```
-then
-```bash
-yq d sample.yaml bob.*.cats
-```
-will output:
-```yaml
----
-bob:
-  item1:
-    dogs: woof
-  item2:
-    dogs: woof2
-  thing:
-    dogs: woof3
-```
+## Multiple Documents
 
-### Prefix Splat
-Given a sample.yaml file of:
-```yaml
----
-bob:
-  item1:
-    cats: bananas
-    dogs: woof
-  item2:
-    cats: apples
-    dogs: woof2
-  thing:
-    cats: oranges
-    dogs: woof3
-```
-then
-```bash
-yq d sample.yaml bob.item*.cats
-```
-will output:
-```yaml
----
-bob:
-  item1:
-    dogs: woof
-  item2:
-    dogs: woof2
-  thing:
-    cats: oranges
-    dogs: woof3
-```
-
-### Array Splat
-Given a sample.yaml file of:
-```yaml
----
-bob:
-- cats: bananas
-  dogs: woof
-- cats: apples
-  dogs: woof2
-- cats: oranges
-  dogs: woof3
-```
-then
-```bash
-yq d sample.yaml bob.[*].cats
-```
-will output:
-```yaml
----
-bob:
-- dogs: woof
-- dogs: woof2
-- dogs: woof3
-```
-
-### Multiple Documents - delete from single document
+### Delete from single document
 Given a sample.yaml file of:
 ```yaml
 something: else
@@ -170,7 +63,7 @@ b:
   c: 2
 ```
 
-### Multiple Documents - delete from all documents
+### Delete from all documents
 Given a sample.yaml file of:
 ```yaml
 something: else
@@ -191,7 +84,3 @@ something: else
 b:
   c: 2
 ```
-
-Note that '*' is in quotes to avoid being interpreted by your shell.
-
-{!snippets/niche.md!}

mkdocs/index.md

@@ -20,7 +20,7 @@ sudo apt install yq -y
 ```
 or, [Download latest binary](https://github.com/mikefarah/yq/releases/latest) or alternatively:
 ```
-go get gopkg.in/mikefarah/yq.v2
+GO111MODULE=on go get github.com/mikefarah/yq/v3
 ```
 
 [View on GitHub](https://github.com/mikefarah/yq)

mkdocs/merge.md

@@ -6,7 +6,7 @@ yq m <yaml_file> <path>...
 ```
 
 
-### To Stdout
+## Merge example
 Given a data1.yaml file of:
 ```yaml
 a: simple
@@ -30,25 +30,13 @@ c:
   test: 1
 ```
 
-### Updating files in-place
-Given a data1.yaml file of:
-```yaml
-a: simple
-b: [1, 2]
-```
-and data2.yaml file of:
-```yaml
-a: other
-c:
-  test: 1
-```
-then
+## Updating files in-place
 ```bash
 yq m -i data1.yaml data2.yaml
 ```
-will update the data1.yaml file so that the value of 'c' is 'test: 1'.
+will update the data1.yaml file with the merged result.
 
-### Overwrite values
+## Overwrite values
 Given a data1.yaml file of:
 ```yaml
 a: simple
@@ -102,7 +90,7 @@ d: false
 
 Notice that 'b' does not result in the merging of the values within an array. 
 
-### Append values with arrays
+## Append values with arrays
 Given a data1.yaml file of:
 ```yaml
 a: simple
@@ -133,9 +121,8 @@ d: hi
 
 Note that the 'b' array has concatenated the values from the second data file. Also note that other map keys are not overridden (field a).
 
-Append cannot be used with overwrite, if both flags are given then append is ignored.
-
-### Multiple Documents - merge into single document
+## Multiple Documents
+### Merge into single document
 Currently yq only has multi-document support for the _first_ document being merged into. The remaining yaml files will have their first document selected.
 
 Given a data1.yaml file of:
@@ -161,7 +148,7 @@ a: simple
 b: dog
 ```
 
-### Multiple Documents - merge into all documents
+### Merge into all documents
 Currently yq only has multi-document support for the _first_ document being merged into. The remaining yaml files will have their first document selected.
 
 Given a data1.yaml file of:

mkdocs/path_expressions.md

@@ -0,0 +1,208 @@
+Path expressions are used to deeply navigate and match particular yaml nodes.
+
+_As a general rule, you should wrap paths in quotes to prevent your CLI from processing '*, []' and other special characters._
+
+## Simple expressions
+
+### Maps
+
+a.b.c
+
+```yaml
+a:
+  b:
+    c: thing # MATCHES
+```
+
+### Arrays
+
+a.b[1].c
+
+```yaml
+a:
+  b:
+  - c: thing0 
+  - c: thing1 # MATCHES
+  - c: thing2
+```
+
+#### Appending to arrays
+(e.g. when using the write command)
+
+a.b[+].c
+
+
+```yaml
+a:
+  b:
+  - c: thing0 
+```
+
+Will add a new entry:
+
+```yaml
+a:
+  b:
+  - c: thing0 
+  - c: thing1 # NEW entry from [+] on B array.
+```
+
+
+## Splat
+
+### Maps
+a.*.c
+
+```yaml
+a:
+  b1:
+    c: thing # MATCHES
+    d: whatever
+  b2:
+    c: thing # MATCHES
+    f: something irrelevant
+```
+
+#### Prefix splat
+
+bob.item*.cats
+
+```yaml
+bob:
+  item:
+    cats: bananas # MATCHES
+  something:
+    cats: lemons
+  itemThing:
+    cats: more bananas # MATCHES
+  item2:
+    cats: apples # MATCHES
+  thing:
+    cats: oranges
+```
+
+### Arrays
+a.b[*].c
+
+```yaml
+a:
+  b:
+  - c: thing0 # MATCHES
+    d: what..ever
+  - c: thing1 # MATCHES
+    d: blarh
+  - c: thing2 # MATCHES
+    f: thingamabob
+```
+
+## Deep Splat
+
+'**' will match arbitrary nodes for both maps and arrays:
+
+a.**.c
+
+```yaml
+a:
+  b1:
+    c: thing1 # MATCHES
+    d: cat cat
+  b2:
+    c: thing2 # MATCHES
+    d: dog dog
+  b3:
+    d:
+    - f:
+        c: thing3 # MATCHES
+        d: beep
+    - f:
+        g:
+          c: thing4 # MATCHES
+          d: boop
+    - d: mooo
+```
+
+
+## Search by children nodes
+
+a.(b.d==cat).b.c
+
+```yaml
+a:
+  - b:
+      c: thing0
+      d: leopard
+    ba: fast
+  - b:
+      c: thing1 # MATCHES
+      d: cat
+    ba: meowy
+  - b:
+      c: thing2
+      d: caterpillar
+    ba: icky
+  - b:
+      c: thing3 # MATCHES
+      d: cat
+    ba: also meowy
+```
+
+### With prefixes
+
+a.(b.d==cat*).c
+
+```yaml
+a:
+  - b:
+      c: thing0
+      d: leopard
+    ba: fast
+  - b:
+      c: thing1 # MATCHES
+      d: cat
+    ba: meowy
+  - b:
+      c: thing2 # MATCHES
+      d: caterpillar
+    ba: icky
+  - b:
+      c: thing3 # MATCHES
+      d: cat
+    ba: also meowy
+```
+
+
+## Special Characters
+
+
+### Keys with dots
+When specifying a key that has a dot use key lookup indicator.
+
+```yaml
+b:
+  foo.bar: 7
+```
+
+```bash
+yaml r sample.yaml 'b[foo.bar]'
+```
+
+```bash
+yaml w sample.yaml 'b[foo.bar]' 9
+```
+
+Any valid yaml key can be specified as part of a key lookup.
+
+Note that the path is in quotes to avoid the square brackets being interpreted by your shell.
+
+### Keys (and values) with leading dashes
+The flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags, if they start if a dash.
+
+```bash
+yq n -j -- --key --value
+```
+
+Will result in
+
+```
+--key: --value
+```

mkdocs/prefix.md

@@ -1,28 +1,12 @@
-Paths can be prefixed using the 'prefix' command.
-The complete yaml content will be nested inside the new prefix path.
-
 ```
 yq p <yaml_file> <path>
 ```
 
-### To Stdout
-Given a data1.yaml file of:
-```yaml
-a: simple
-b: [1, 2]
-```
-then
-```bash
-yq p data1.yaml c
-```
-will output:
-```yaml
-c:
-  a: simple
-  b: [1, 2]
-```
+Prefixes a yaml document with the given path expression. The complete yaml content will be nested inside the new prefix path.
 
-### Arbitrary depth
+See docs for [path expression](path_expressions.md) for more details.
+
+## Prefix a document
 Given a data1.yaml file of:
 ```yaml
 a:
@@ -40,19 +24,14 @@ c:
       b: [1, 2]
 ```
 
-### Updating files in-place
-Given a data1.yaml file of:
-```yaml
-a: simple
-b: [1, 2]
-```
-then
+## Updating files in-place
 ```bash
 yq p -i data1.yaml c
 ```
-will update the data1.yaml file so that the path 'c' is prefixed to all other paths.
+will update the data1.yaml file so that the path 'c' prefixes the document.
 
-### Multiple Documents - prefix a single document
+## Multiple Documents
+### Prefix a single document
 Given a data1.yaml file of:
 ```yaml
 something: else
@@ -73,7 +52,7 @@ c:
   b: cat
 ```
 
-### Multiple Documents - prefix all documents
+### Prefix all documents
 Given a data1.yaml file of:
 ```yaml
 something: else

mkdocs/read.md

@@ -1,10 +1,14 @@
 ```
-yq r <yaml_file|json_file> <path>
+yq r <yaml_file|json_file> <path_expression>
 ```
 
-{!snippets/works_with_json.md!}
+TALK PRINTING ABOUT KEYS AND VALUES
 
-### Basic
+Returns the matching nodes of the path expression for the given yaml file (or STDIN).
+
+See docs for [path expression](path_expressions.md) for more details.
+
+## Basic
 Given a sample.yaml file of:
 ```yaml
 b:
@@ -16,59 +20,16 @@ yq r sample.yaml b.c
 ```
 will output the value of '2'.
 
-### From Stdin
+## From Stdin
 Given a sample.yaml file of:
 ```bash
 cat sample.yaml | yq r - b.c
 ```
 will output the value of '2'.
 
-### Splat
-Given a sample.yaml file of:
-```yaml
----
-bob:
-  item1:
-    cats: bananas
-  item2:
-    cats: apples
-  thing:
-    cats: oranges
-```
-then
-```bash
-yq r sample.yaml bob.*.cats
-```
-will output
-```yaml
-- bananas
-- apples
-- oranges
-```
 
-### Prefix Splat
-Given a sample.yaml file of:
-```yaml
----
-bob:
-  item1:
-    cats: bananas
-  item2:
-    cats: apples
-  thing:
-    cats: oranges
-```
-then
-```bash
-yq r sample.yaml bob.item*.cats
-```
-will output
-```yaml
-- bananas
-- apples
-```
-
-### Multiple Documents - specify a single document
+## Multiple Documents
+### Reading from a single document
 Given a sample.yaml file of:
 ```yaml
 something: else
@@ -82,7 +43,7 @@ yq r -d1 sample.yaml b.c
 ```
 will output the value of '2'.
 
-### Multiple Documents - read all documents
+### Read from all documents
 Reading all documents will return the result as an array. This can be converted to json using the '-j' flag if desired.
 
 Given a sample.yaml file of:
@@ -105,46 +66,4 @@ will output:
 - Fred
 - Stella
 - Android
-```
-
-### Arrays
-You can give an index to access a specific element:
-e.g.: given a sample file of
-```yaml
-b:
-  e:
-    - name: fred
-      value: 3
-    - name: sam
-      value: 4
-```
-then
-```
-yq r sample.yaml 'b.e[1].name'
-```
-will output 'sam'
-
-Note that the path is in quotes to avoid the square brackets being interpreted by your shell.
-
-### Array Splat
-e.g.: given a sample file of
-```yaml
-b:
-  e:
-    - name: fred
-      value: 3
-    - name: sam
-      value: 4
-```
-then
-```
-yq r sample.yaml 'b.e[*].name'
-```
-will output:
-```
-- fred
-- sam
-```
-Note that the path is in quotes to avoid the square brackets being interpreted by your shell.
-
-{!snippets/niche.md!}
+```

mkdocs/snippets/niche.md

@@ -1,35 +0,0 @@
-### Keys with dots
-When specifying a key that has a dot use key lookup indicator.
-
-```yaml
-b:
-  foo.bar: 7
-```
-
-```bash
-yaml r sample.yaml 'b[foo.bar]'
-```
-
-```bash
-yaml w sample.yaml 'b[foo.bar]' 9
-```
-
-Any valid yaml key can be specified as part of a key lookup.
-
-Note that the path is in quotes to avoid the square brackets being interpreted by your shell.
-
-### Keys (and values) with leading dashes
-If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error).
-
-To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so:
-
-
-```bash
-yq n -t -- --key --value
-```
-
-Will result in
-
-```
---key: --value
-```

mkdocs/snippets/works_with_json.md

@@ -1 +0,0 @@
-This command can take a json file as input too, and will output yaml unless specified to export as json (-j)

mkdocs/write.md

@@ -1,8 +1,12 @@
 ```
-yq w <yaml_file> <path> <new value>
+yq w <yaml_file> <path_expression> <new value>
 ```
 
-### To Stdout
+Updates all the matching nodes of path expression to the supplied value.
+
+See docs for [path expression](path_expressions.md) for more details.
+
+## Basic
 Given a sample.yaml file of:
 ```yaml
 b:
@@ -18,12 +22,18 @@ b:
   c: cat
 ```
 
-### From STDIN
+### Updating files in-place
+```bash
+yq w -i sample.yaml b.c cat
+```
+will update the sample.yaml file so that the value of 'c' is cat.
+
+## From STDIN
 ```bash
 cat sample.yaml | yq w - b.c blah
 ```
 
-### Adding new fields
+## Adding new fields
 Any missing fields in the path will be created on the fly.
 
 Given a sample.yaml file of:
@@ -43,85 +53,7 @@ b:
     - new thing
 ```
 
-### Splat
-Given a sample.yaml file of:
-```yaml
----
-bob:
-  item1:
-    cats: bananas
-  item2:
-    cats: apples
-  thing:
-    cats: oranges
-```
-then
-```bash
-yq w sample.yaml bob.*.cats meow
-```
-will output:
-```yaml
----
-bob:
-  item1:
-    cats: meow
-  item2:
-    cats: meow
-  thing:
-    cats: meow
-```
-
-### Prefix Splat
-Given a sample.yaml file of:
-```yaml
----
-bob:
-  item1:
-    cats: bananas
-  item2:
-    cats: apples
-  thing:
-    cats: oranges
-```
-then
-```bash
-yq w sample.yaml bob.item*.cats meow
-```
-will output:
-```yaml
----
-bob:
-  item1:
-    cats: meow
-  item2:
-    cats: meow
-  thing:
-    cats: oranges
-```
-
-### Array Splat
-Given a sample.yaml file of:
-```yaml
----
-bob:
-- cats: bananas
-- cats: apples
-- cats: oranges
-```
-then
-```bash
-yq w sample.yaml bob[*].cats meow
-```
-will output:
-```yaml
----
-bob:
-- cats: meow
-- cats: meow
-- cats: meow
-```
-
-### Appending value to an array field
+## Appending value to an array field
 Given a sample.yaml file of:
 ```yaml
 b:
@@ -146,7 +78,8 @@ b:
 
 Note that the path is in quotes to avoid the square brackets being interpreted by your shell.
 
-### Multiple Documents - update a single document
+## Multiple Documents 
+### Update a single document
 Given a sample.yaml file of:
 ```yaml
 something: else
@@ -166,7 +99,7 @@ b:
   c: 5
 ```
 
-### Multiple Documents - update all documents
+### Update all documents
 Given a sample.yaml file of:
 ```yaml
 something: else
@@ -188,22 +121,11 @@ b:
   c: 5
 ```
 
-Note that '*' is in quotes to avoid being interpreted by your shell.
+UPDATE THIS
+UPDATE THIS 
+INCLUDE DELETE EXAMPLE
 
-### Updating files in-place
-Given a sample.yaml file of:
-```yaml
-b:
-  c: 2
-```
-then
-```bash
-yq w -i sample.yaml b.c cat
-```
-will update the sample.yaml file so that the value of 'c' is cat.
-
-
-### Updating multiple values with a script
+## Updating multiple values with a script 
 Given a sample.yaml file of:
 ```yaml
 b:
@@ -233,18 +155,3 @@ And, of course, you can pipe the instructions in using '-':
 ```bash
 cat update_instructions.yaml | yq w -s - sample.yaml
 ```
-
-### Values starting with a hyphen (or dash)
-The flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags:
-
-```
-yq w -- my.path -3
-```
-
-will output
-```yaml
-my:
-  path: -3
-```
-
-{!snippets/niche.md!}