wip update docs

README.md

@@ -43,7 +43,7 @@ sudo apt install yq -y
 ```
 ### or, [Download latest binary](https://github.com/mikefarah/yq/releases/latest) or alternatively:
 ```
-GO111MODULE=on go get github.com/mikefarah/yq/v2
+GO111MODULE=on go get github.com/mikefarah/yq/v3
 ```
 
 ## Run with Docker

Upgrade Notes

@@ -1,12 +1,14 @@
 
+Major release! Upgraded underlying yaml parser, re-written majority of yq. This has brought on a number of features that have been in demand for a while (see below).
+
+This is in beta and needs some community feedback and testing :)
+
 # New Features
-  - Keeps yaml comments and formatting (string blocks are saved, number formatting is preserved, so it won't drop off trailing 0s for values like 0.10, which is important when that's a version entry )
+  - Keeps yaml comments and formatting, can specify yaml tags when updating. https://github.com/mikefarah/yq/issues/19, https://github.com/mikefarah/yq/issues/169, https://github.com/mikefarah/yq/issues/107, https://github.com/mikefarah/yq/issues/171, https://github.com/mikefarah/yq/issues/245, https://github.com/mikefarah/yq/issues/303,https://github.com/mikefarah/yq/issues/308,https://github.com/mikefarah/yq/issues/314
-  
+  - Handles anchors!  https://github.com/mikefarah/yq/issues/310, https://github.com/mikefarah/yq/issues/178
-  - Handles anchors! (doc link)
+  - Can print out matching paths and values when splatting https://github.com/mikefarah/yq/issues/20
-  - Can specify yaml tags (e.g. !!int), quoting values no longer sufficient, need to specify the tag value instead.
-  - Can print out matching paths and values when splatting (doc link)
   - JSON output works for all commands! Yaml files with multiple documents are printed out as one JSON document per line. 
-  - Deep splat (**) to match arbitrary paths, (doc link)
+  - Deep splat (**) to match arbitrary paths
 
 
 # Breaking changes
@@ -14,6 +16,24 @@
 ## Update scripts file format has changed to be more powerful. 
 Comments can be added, and delete commands have been introduced.
 
+Before:
+```yaml
+b.e[+].name: Mike Farah
+```
+
+After:
+```yaml
+- command: update 
+  path: b.e[+].thing
+  value:
+    #great 
+    things: frog # wow!
+- command: delete
+  path: b.d
+```
+
+https://github.com/mikefarah/yq/issues/305
+
 ## Reading and splatting, matching results are printed once per line.
   e.g:
 
@@ -27,7 +47,9 @@ parent:
     there2: also matches
 ```
 
+```bash
 yq r sample.yaml 'parent.*.there*'
+```
 
 old
 ```yaml
@@ -50,7 +72,3 @@ yq r --printMode pv sample.yaml 'parent.*.there*'
 parent.childB.there: matches
 parent.childB.there2: also matches
 ```
-
-# Merge command
-- New flag 'autocreates' missing entries in target by default, new flag to turn that off.
-

commands_test.go

@@ -94,6 +94,27 @@ func TestReadCmd(t *testing.T) {
 	test.AssertResult(t, "2", result.Output)
 }
 
+func TestReadWithAdvancedFilterCmd(t *testing.T) {
+	cmd := getRootCommand()
+	result := test.RunCmd(cmd, "read -v examples/sample.yaml b.e(name==sam).value")
+	if result.Error != nil {
+		t.Error(result.Error)
+	}
+	test.AssertResult(t, "4", result.Output)
+}
+
+func TestReadWithAdvancedFilterMapCmd(t *testing.T) {
+	cmd := getRootCommand()
+	result := test.RunCmd(cmd, "read -v examples/sample.yaml b.e[name==fr*]")
+	if result.Error != nil {
+		t.Error(result.Error)
+	}
+	expectedOutput := `name: fred
+value: 3
+`
+	test.AssertResult(t, expectedOutput, result.Output)
+}
+
 func TestReadWithKeyAndValueCmd(t *testing.T) {
 	cmd := getRootCommand()
 	result := test.RunCmd(cmd, "read -p pv examples/sample.yaml b.c")

docs/404.html

@@ -248,6 +248,18 @@
       
 
 
+  <li class="md-nav__item">
+    <a href="/path_expressions/" title="Path Expressions" class="md-nav__link">
+      Path Expressions
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
   <li class="md-nav__item">
     <a href="/write/" title="Write/Update" class="md-nav__link">
       Write/Update

docs/convert/index.html

@@ -252,6 +252,18 @@
       
 
 
+  <li class="md-nav__item">
+    <a href="../path_expressions/" title="Path Expressions" class="md-nav__link">
+      Path Expressions
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
   <li class="md-nav__item">
     <a href="../write/" title="Write/Update" class="md-nav__link">
       Write/Update
@@ -414,20 +426,37 @@
                   <h1>Convert</h1>
                 
                 <h3 id="yaml-to-json">Yaml to Json<a class="headerlink" href="#yaml-to-json" title="Permanent link">&para;</a></h3>
-<p>To convert output to json, use the --tojson (or -j) flag. This can only be used with the read command.</p>
+<p>To convert output to json, use the --tojson (or -j) flag. This is supported by all commands.</p>
+<p>Each matching yaml node will be converted to json and printed out on a separate line.</p>
 <p>Given a sample.yaml file of:</p>
 <pre><code class="yaml">b:
   c: 2
 </code></pre>
 
 <p>then</p>
-<pre><code class="bash">yq r -j sample.yaml b.c
+<pre><code class="bash">yq r -j sample.yaml
 </code></pre>
 
 <p>will output</p>
 <pre><code class="json">{&quot;b&quot;:{&quot;c&quot;:2}}
 </code></pre>
 
+<p>Given a sample.yaml file of:</p>
+<pre><code class="yaml">bob:
+  c: 2
+bab:
+  c: 5
+</code></pre>
+
+<p>then</p>
+<pre><code class="bash">yq r -j sample.yaml b*
+</code></pre>
+
+<p>will output</p>
+<pre><code class="json">{&quot;c&quot;:2}
+{&quot;c&quot;:5}
+</code></pre>
+
 <h3 id="json-to-yaml">Json to Yaml<a class="headerlink" href="#json-to-yaml" title="Permanent link">&para;</a></h3>
 <p>To read in json, just pass in a json file instead of yaml, it will just work :)</p>
 <p>e.g given a json file</p>

docs/create/index.html

@@ -252,6 +252,18 @@
       
 
 
+  <li class="md-nav__item">
+    <a href="../path_expressions/" title="Path Expressions" class="md-nav__link">
+      Path Expressions
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
   <li class="md-nav__item">
     <a href="../write/" title="Write/Update" class="md-nav__link">
       Write/Update
@@ -325,20 +337,6 @@
   
 </li>
       
-        <li class="md-nav__item">
-  <a href="#keys-with-dots" title="Keys with dots" class="md-nav__link">
-    Keys with dots
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#keys-and-values-with-leading-dashes" title="Keys (and values) with leading dashes" class="md-nav__link">
-    Keys (and values) with leading dashes
-  </a>
-  
-</li>
-      
       
       
       
@@ -406,20 +404,6 @@
   
 </li>
       
-        <li class="md-nav__item">
-  <a href="#keys-with-dots" title="Keys with dots" class="md-nav__link">
-    Keys with dots
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#keys-and-values-with-leading-dashes" title="Keys (and values) with leading dashes" class="md-nav__link">
-    Keys (and values) with leading dashes
-  </a>
-  
-</li>
-      
       
       
       
@@ -441,10 +425,11 @@
                 
                   <h1>Create</h1>
                 
-                <p>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.</p>
+                <pre><code>yq n &lt;path_expression&gt; &lt;new value&gt;
-<pre><code>yq n &lt;path&gt; &lt;new value&gt;
 </code></pre>
 
+<p>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.</p>
+<p>See docs for <a href="../path_expressions/">path expression</a></p>
 <h3 id="creating-a-simple-yaml-file">Creating a simple yaml file<a class="headerlink" href="#creating-a-simple-yaml-file" title="Permanent link">&para;</a></h3>
 <pre><code class="bash">yq n b.c cat
 </code></pre>
@@ -457,8 +442,11 @@
 <h3 id="creating-using-a-create-script">Creating using a create script<a class="headerlink" href="#creating-using-a-create-script" title="Permanent link">&para;</a></h3>
 <p>Create scripts follow the same format as the update scripts.</p>
 <p>Given a script create_instructions.yaml of:</p>
-<pre><code class="yaml">b.c: 3
+<pre><code class="yaml">- command: update 
-b.e[+].name: Howdy Partner
+  path: b.c
+  value:
+    #great 
+    things: frog # wow!
 </code></pre>
 
 <p>then</p>
@@ -467,39 +455,15 @@ b.e[+].name: Howdy Partner
 
 <p>will output:</p>
 <pre><code class="yaml">b:
-  c: 3
+  c:
-  e:
+    #great
-    - name: Howdy Partner
+    things: frog # wow!
 </code></pre>
 
 <p>You can also pipe the instructions in:</p>
 <pre><code class="bash">cat create_instructions.yaml | yq n -s -
 </code></pre>
                 
-<h3 id="keys-with-dots">Keys with dots<a class="headerlink" href="#keys-with-dots" title="Permanent link">&para;</a></h3>
-<p>When specifying a key that has a dot use key lookup indicator.</p>
-<pre><code class="yaml">b:
-  foo.bar: 7
-</code></pre>
-
-<pre><code class="bash">yaml r sample.yaml 'b[foo.bar]'
-</code></pre>
-
-<pre><code class="bash">yaml w sample.yaml 'b[foo.bar]' 9
-</code></pre>
-
-<p>Any valid yaml key can be specified as part of a key lookup.</p>
-<p>Note that the path is in quotes to avoid the square brackets being interpreted by your shell.</p>
-<h3 id="keys-and-values-with-leading-dashes">Keys (and values) with leading dashes<a class="headerlink" href="#keys-and-values-with-leading-dashes" title="Permanent link">&para;</a></h3>
-<p>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).</p>
-<p>To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so:</p>
-<pre><code class="bash">yq n -t -- --key --value
-</code></pre>
-
-<p>Will result in</p>
-<p><code>`
---key: --value</code></p>
-                
                   
                 
               

docs/delete/index.html

@@ -94,7 +94,7 @@
     <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
     <label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
     
-      <a href="#to-stdout" tabindex="1" class="md-skip">
+      <a href="#from-stdin" tabindex="1" class="md-skip">
         Skip to content
       </a>
     
@@ -252,6 +252,18 @@
       
 
 
+  <li class="md-nav__item">
+    <a href="../path_expressions/" title="Path Expressions" class="md-nav__link">
+      Path Expressions
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
   <li class="md-nav__item">
     <a href="../write/" title="Write/Update" class="md-nav__link">
       Write/Update
@@ -299,25 +311,11 @@
     <label class="md-nav__title" for="__toc">Table of contents</label>
     <ul class="md-nav__list" data-md-scrollfix>
       
-        <li class="md-nav__item">
-  <a href="#to-stdout" title="To Stdout" class="md-nav__link">
-    To Stdout
-  </a>
-  
-</li>
-      
         <li class="md-nav__item">
   <a href="#from-stdin" title="From STDIN" class="md-nav__link">
     From STDIN
   </a>
   
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#deleting-array-elements" title="Deleting array elements" class="md-nav__link">
-    Deleting array elements
-  </a>
-  
 </li>
       
         <li class="md-nav__item">
@@ -325,27 +323,6 @@
     Deleting nodes in-place
   </a>
   
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#splat" title="Splat" class="md-nav__link">
-    Splat
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#prefix-splat" title="Prefix Splat" class="md-nav__link">
-    Prefix Splat
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#array-splat" title="Array Splat" class="md-nav__link">
-    Array Splat
-  </a>
-  
 </li>
       
         <li class="md-nav__item">
@@ -362,20 +339,6 @@
   
 </li>
       
-        <li class="md-nav__item">
-  <a href="#keys-with-dots" title="Keys with dots" class="md-nav__link">
-    Keys with dots
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#keys-and-values-with-leading-dashes" title="Keys (and values) with leading dashes" class="md-nav__link">
-    Keys (and values) with leading dashes
-  </a>
-  
-</li>
-      
       
       
       
@@ -441,25 +404,11 @@
     <label class="md-nav__title" for="__toc">Table of contents</label>
     <ul class="md-nav__list" data-md-scrollfix>
       
-        <li class="md-nav__item">
-  <a href="#to-stdout" title="To Stdout" class="md-nav__link">
-    To Stdout
-  </a>
-  
-</li>
-      
         <li class="md-nav__item">
   <a href="#from-stdin" title="From STDIN" class="md-nav__link">
     From STDIN
   </a>
   
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#deleting-array-elements" title="Deleting array elements" class="md-nav__link">
-    Deleting array elements
-  </a>
-  
 </li>
       
         <li class="md-nav__item">
@@ -467,27 +416,6 @@
     Deleting nodes in-place
   </a>
   
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#splat" title="Splat" class="md-nav__link">
-    Splat
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#prefix-splat" title="Prefix Splat" class="md-nav__link">
-    Prefix Splat
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#array-splat" title="Array Splat" class="md-nav__link">
-    Array Splat
-  </a>
-  
 </li>
       
         <li class="md-nav__item">
@@ -504,20 +432,6 @@
   
 </li>
       
-        <li class="md-nav__item">
-  <a href="#keys-with-dots" title="Keys with dots" class="md-nav__link">
-    Keys with dots
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#keys-and-values-with-leading-dashes" title="Keys (and values) with leading dashes" class="md-nav__link">
-    Keys (and values) with leading dashes
-  </a>
-  
-</li>
-      
       
       
       
@@ -539,49 +453,16 @@
                 
                   <h1>Delete</h1>
                 
-                <pre><code>yq d &lt;yaml_file&gt; &lt;path_to_delete&gt;
+                <pre><code>yq delete &lt;yaml_file|-&gt; &lt;path_expression&gt;
-</code></pre>
-
-<h3 id="to-stdout">To Stdout<a class="headerlink" href="#to-stdout" title="Permanent link">&para;</a></h3>
-<p>Given a sample.yaml file of:</p>
-<pre><code class="yaml">b:
-  c: 2
-  apples: green
-</code></pre>
-
-<p>then</p>
-<pre><code class="bash">yq d sample.yaml b.c
-</code></pre>
-
-<p>will output:</p>
-<pre><code class="yaml">b:
-  apples: green
 </code></pre>
 
+<p>The delete command will delete all the matching nodes for the path expression in the given yaml input.</p>
+<p>See docs for <a href="../path_expressions/">path expression</a> for more details.</p>
 <h3 id="from-stdin">From STDIN<a class="headerlink" href="#from-stdin" title="Permanent link">&para;</a></h3>
+<p>Use "-" (without quotes) inplace of a file name if you wish to pipe in input from STDIN.</p>
 <pre><code class="bash">cat sample.yaml | yq d - b.c
 </code></pre>
 
-<h3 id="deleting-array-elements">Deleting array elements<a class="headerlink" href="#deleting-array-elements" title="Permanent link">&para;</a></h3>
-<p>Given a sample.yaml file of:</p>
-<pre><code class="yaml">b:
-  c: 
-    - 1
-    - 2
-    - 3
-</code></pre>
-
-<p>then</p>
-<pre><code class="bash">yq d sample.yaml 'b.c[1]'
-</code></pre>
-
-<p>will output:</p>
-<pre><code class="yaml">b:
-  c:
-  - 1
-  - 3
-</code></pre>
-
 <h3 id="deleting-nodes-in-place">Deleting nodes in-place<a class="headerlink" href="#deleting-nodes-in-place" title="Permanent link">&para;</a></h3>
 <p>Given a sample.yaml file of:</p>
 <pre><code class="yaml">b:
@@ -594,91 +475,6 @@
 </code></pre>
 
 <p>will update the sample.yaml file so that the 'c' node is deleted</p>
-<h3 id="splat">Splat<a class="headerlink" href="#splat" title="Permanent link">&para;</a></h3>
-<p>Given a sample.yaml file of:</p>
-<pre><code class="yaml">---
-bob:
-  item1:
-    cats: bananas
-    dogs: woof
-  item2:
-    cats: apples
-    dogs: woof2
-  thing:
-    cats: oranges
-    dogs: woof3
-</code></pre>
-
-<p>then</p>
-<pre><code class="bash">yq d sample.yaml bob.*.cats
-</code></pre>
-
-<p>will output:</p>
-<pre><code class="yaml">---
-bob:
-  item1:
-    dogs: woof
-  item2:
-    dogs: woof2
-  thing:
-    dogs: woof3
-</code></pre>
-
-<h3 id="prefix-splat">Prefix Splat<a class="headerlink" href="#prefix-splat" title="Permanent link">&para;</a></h3>
-<p>Given a sample.yaml file of:</p>
-<pre><code class="yaml">---
-bob:
-  item1:
-    cats: bananas
-    dogs: woof
-  item2:
-    cats: apples
-    dogs: woof2
-  thing:
-    cats: oranges
-    dogs: woof3
-</code></pre>
-
-<p>then</p>
-<pre><code class="bash">yq d sample.yaml bob.item*.cats
-</code></pre>
-
-<p>will output:</p>
-<pre><code class="yaml">---
-bob:
-  item1:
-    dogs: woof
-  item2:
-    dogs: woof2
-  thing:
-    cats: oranges
-    dogs: woof3
-</code></pre>
-
-<h3 id="array-splat">Array Splat<a class="headerlink" href="#array-splat" title="Permanent link">&para;</a></h3>
-<p>Given a sample.yaml file of:</p>
-<pre><code class="yaml">---
-bob:
-- cats: bananas
-  dogs: woof
-- cats: apples
-  dogs: woof2
-- cats: oranges
-  dogs: woof3
-</code></pre>
-
-<p>then</p>
-<pre><code class="bash">yq d sample.yaml bob.[*].cats
-</code></pre>
-
-<p>will output:</p>
-<pre><code class="yaml">---
-bob:
-- dogs: woof
-- dogs: woof2
-- dogs: woof3
-</code></pre>
-
 <h3 id="multiple-documents-delete-from-single-document">Multiple Documents - delete from single document<a class="headerlink" href="#multiple-documents-delete-from-single-document" title="Permanent link">&para;</a></h3>
 <p>Given a sample.yaml file of:</p>
 <pre><code class="yaml">something: else
@@ -723,29 +519,6 @@ b:
 </code></pre>
 
 <p>Note that '*' is in quotes to avoid being interpreted by your shell.</p>
-<h3 id="keys-with-dots">Keys with dots<a class="headerlink" href="#keys-with-dots" title="Permanent link">&para;</a></h3>
-<p>When specifying a key that has a dot use key lookup indicator.</p>
-<pre><code class="yaml">b:
-  foo.bar: 7
-</code></pre>
-
-<pre><code class="bash">yaml r sample.yaml 'b[foo.bar]'
-</code></pre>
-
-<pre><code class="bash">yaml w sample.yaml 'b[foo.bar]' 9
-</code></pre>
-
-<p>Any valid yaml key can be specified as part of a key lookup.</p>
-<p>Note that the path is in quotes to avoid the square brackets being interpreted by your shell.</p>
-<h3 id="keys-and-values-with-leading-dashes">Keys (and values) with leading dashes<a class="headerlink" href="#keys-and-values-with-leading-dashes" title="Permanent link">&para;</a></h3>
-<p>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).</p>
-<p>To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so:</p>
-<pre><code class="bash">yq n -t -- --key --value
-</code></pre>
-
-<p>Will result in</p>
-<p><code>`
---key: --value</code></p>
                 
                   
                 

docs/index.html

@@ -290,6 +290,18 @@
       
 
 
+  <li class="md-nav__item">
+    <a href="path_expressions/" title="Path Expressions" class="md-nav__link">
+      Path Expressions
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
   <li class="md-nav__item">
     <a href="write/" title="Write/Update" class="md-nav__link">
       Write/Update
@@ -422,7 +434,7 @@ sudo apt install yq -y
 </code></pre>
 
 <p>or, <a href="https://github.com/mikefarah/yq/releases/latest">Download latest binary</a> or alternatively:</p>
-<pre><code>go get gopkg.in/mikefarah/yq.v2
+<pre><code>GO111MODULE=on go get github.com/mikefarah/yq/v3
 </code></pre>
 
 <p><a href="https://github.com/mikefarah/yq">View on GitHub</a></p>

docs/merge/index.html

@@ -252,6 +252,18 @@
       
 
 
+  <li class="md-nav__item">
+    <a href="../path_expressions/" title="Path Expressions" class="md-nav__link">
+      Path Expressions
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
   <li class="md-nav__item">
     <a href="../write/" title="Write/Update" class="md-nav__link">
       Write/Update
@@ -608,7 +620,6 @@ d: hi
 </code></pre>
 
 <p>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).</p>
-<p>Append cannot be used with overwrite, if both flags are given then append is ignored.</p>
 <h3 id="multiple-documents-merge-into-single-document">Multiple Documents - merge into single document<a class="headerlink" href="#multiple-documents-merge-into-single-document" title="Permanent link">&para;</a></h3>
 <p>Currently yq only has multi-document support for the <em>first</em> document being merged into. The remaining yaml files will have their first document selected.</p>
 <p>Given a data1.yaml file of:</p>

docs/path_expressions/index.html

@@ -0,0 +1,862 @@
+
+
+
+
+<!doctype html>
+<html lang="en" class="no-js">
+  <head>
+    
+      <meta charset="utf-8">
+      <meta name="viewport" content="width=device-width,initial-scale=1">
+      <meta http-equiv="x-ua-compatible" content="ie=edge">
+      
+      
+      
+      
+        <meta name="lang:clipboard.copy" content="Copy to clipboard">
+      
+        <meta name="lang:clipboard.copied" content="Copied to clipboard">
+      
+        <meta name="lang:search.language" content="en">
+      
+        <meta name="lang:search.pipeline.stopwords" content="True">
+      
+        <meta name="lang:search.pipeline.trimmer" content="True">
+      
+        <meta name="lang:search.result.none" content="No matching documents">
+      
+        <meta name="lang:search.result.one" content="1 matching document">
+      
+        <meta name="lang:search.result.other" content="# matching documents">
+      
+        <meta name="lang:search.tokenizer" content="[\s\-]+">
+      
+      <link rel="shortcut icon" href="../assets/images/favicon.png">
+      <meta name="generator" content="mkdocs-1.0.4, mkdocs-material-4.2.0">
+    
+    
+      
+        <title>Path Expressions - Yq</title>
+      
+    
+    
+      <link rel="stylesheet" href="../assets/stylesheets/application.750b69bd.css">
+      
+      
+    
+    
+      <script src="../assets/javascripts/modernizr.74668098.js"></script>
+    
+    
+      
+        <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700|Roboto+Mono">
+        <style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style>
+      
+    
+    <link rel="stylesheet" href="../assets/fonts/material-icons.css">
+    
+    
+    
+      
+    
+    
+  </head>
+  
+    <body dir="ltr">
+  
+    <svg class="md-svg">
+      <defs>
+        
+        
+          <svg xmlns="http://www.w3.org/2000/svg" width="416" height="448"
+    viewBox="0 0 416 448" id="__github">
+  <path fill="currentColor" d="M160 304q0 10-3.125 20.5t-10.75 19-18.125
+        8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19 18.125-8.5
+        18.125 8.5 10.75 19 3.125 20.5zM320 304q0 10-3.125 20.5t-10.75
+        19-18.125 8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19
+        18.125-8.5 18.125 8.5 10.75 19 3.125 20.5zM360
+        304q0-30-17.25-51t-46.75-21q-10.25 0-48.75 5.25-17.75 2.75-39.25
+        2.75t-39.25-2.75q-38-5.25-48.75-5.25-29.5 0-46.75 21t-17.25 51q0 22 8
+        38.375t20.25 25.75 30.5 15 35 7.375 37.25 1.75h42q20.5 0
+        37.25-1.75t35-7.375 30.5-15 20.25-25.75 8-38.375zM416 260q0 51.75-15.25
+        82.75-9.5 19.25-26.375 33.25t-35.25 21.5-42.5 11.875-42.875 5.5-41.75
+        1.125q-19.5 0-35.5-0.75t-36.875-3.125-38.125-7.5-34.25-12.875-30.25-20.25-21.5-28.75q-15.5-30.75-15.5-82.75
+        0-59.25 34-99-6.75-20.5-6.75-42.5 0-29 12.75-54.5 27 0 47.5 9.875t47.25
+        30.875q36.75-8.75 77.25-8.75 37 0 70 8 26.25-20.5
+        46.75-30.25t47.25-9.75q12.75 25.5 12.75 54.5 0 21.75-6.75 42 34 40 34
+        99.5z" />
+</svg>
+        
+      </defs>
+    </svg>
+    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
+    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
+    <label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
+    
+      <a href="#simple-expressions" tabindex="1" class="md-skip">
+        Skip to content
+      </a>
+    
+    
+      <header class="md-header" data-md-component="header">
+  <nav class="md-header-nav md-grid">
+    <div class="md-flex">
+      <div class="md-flex__cell md-flex__cell--shrink">
+        <a href=".." title="Yq" class="md-header-nav__button md-logo">
+          
+            <i class="md-icon"></i>
+          
+        </a>
+      </div>
+      <div class="md-flex__cell md-flex__cell--shrink">
+        <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
+      </div>
+      <div class="md-flex__cell md-flex__cell--stretch">
+        <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
+          
+            <span class="md-header-nav__topic">
+              Yq
+            </span>
+            <span class="md-header-nav__topic">
+              Path Expressions
+            </span>
+          
+        </div>
+      </div>
+      <div class="md-flex__cell md-flex__cell--shrink">
+        
+          <label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
+          
+<div class="md-search" data-md-component="search" role="dialog">
+  <label class="md-search__overlay" for="__search"></label>
+  <div class="md-search__inner" role="search">
+    <form class="md-search__form" name="search">
+      <input type="text" class="md-search__input" name="query" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
+      <label class="md-icon md-search__icon" for="__search"></label>
+      <button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
+        &#xE5CD;
+      </button>
+    </form>
+    <div class="md-search__output">
+      <div class="md-search__scrollwrap" data-md-scrollfix>
+        <div class="md-search-result" data-md-component="result">
+          <div class="md-search-result__meta">
+            Type to start searching
+          </div>
+          <ol class="md-search-result__list"></ol>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+        
+      </div>
+      
+        <div class="md-flex__cell md-flex__cell--shrink">
+          <div class="md-header-nav__source">
+            
+
+
+  
+
+<a href="https://github.com/mikefarah/yq/" title="Go to repository" class="md-source" data-md-source="github">
+  
+    <div class="md-source__icon">
+      <svg viewBox="0 0 24 24" width="24" height="24">
+        <use xlink:href="#__github" width="24" height="24"></use>
+      </svg>
+    </div>
+  
+  <div class="md-source__repository">
+    mikefarah/yq
+  </div>
+</a>
+          </div>
+        </div>
+      
+    </div>
+  </nav>
+</header>
+    
+    <div class="md-container">
+      
+        
+      
+      
+      <main class="md-main">
+        <div class="md-main__inner md-grid" data-md-component="container">
+          
+            
+              <div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
+                <div class="md-sidebar__scrollwrap">
+                  <div class="md-sidebar__inner">
+                    <nav class="md-nav md-nav--primary" data-md-level="0">
+  <label class="md-nav__title md-nav__title--site" for="__drawer">
+    <a href=".." title="Yq" class="md-nav__button md-logo">
+      
+        <i class="md-icon"></i>
+      
+    </a>
+    Yq
+  </label>
+  
+    <div class="md-nav__source">
+      
+
+
+  
+
+<a href="https://github.com/mikefarah/yq/" title="Go to repository" class="md-source" data-md-source="github">
+  
+    <div class="md-source__icon">
+      <svg viewBox="0 0 24 24" width="24" height="24">
+        <use xlink:href="#__github" width="24" height="24"></use>
+      </svg>
+    </div>
+  
+  <div class="md-source__repository">
+    mikefarah/yq
+  </div>
+</a>
+    </div>
+  
+  <ul class="md-nav__list" data-md-scrollfix>
+    
+      
+      
+      
+
+
+  <li class="md-nav__item">
+    <a href=".." title="Install" class="md-nav__link">
+      Install
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
+  <li class="md-nav__item">
+    <a href="../read/" title="Read" class="md-nav__link">
+      Read
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+  
+
+
+  <li class="md-nav__item md-nav__item--active">
+    
+    <input class="md-toggle md-nav__toggle" data-md-toggle="toc" type="checkbox" id="__toc">
+    
+    
+      <label class="md-nav__link md-nav__link--active" for="__toc">
+        Path Expressions
+      </label>
+    
+    <a href="./" title="Path Expressions" class="md-nav__link md-nav__link--active">
+      Path Expressions
+    </a>
+    
+      
+<nav class="md-nav md-nav--secondary">
+  
+  
+  
+    <label class="md-nav__title" for="__toc">Table of contents</label>
+    <ul class="md-nav__list" data-md-scrollfix>
+      
+        <li class="md-nav__item">
+  <a href="#simple-expressions" title="Simple expressions" class="md-nav__link">
+    Simple expressions
+  </a>
+  
+    <nav class="md-nav">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#maps" title="Maps" class="md-nav__link">
+    Maps
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#arrays" title="Arrays" class="md-nav__link">
+    Arrays
+  </a>
+  
+    <nav class="md-nav">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#appending-to-arrays" title="Appending to arrays" class="md-nav__link">
+    Appending to arrays
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#splat" title="Splat" class="md-nav__link">
+    Splat
+  </a>
+  
+    <nav class="md-nav">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#maps_1" title="Maps" class="md-nav__link">
+    Maps
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#arrays_1" title="Arrays" class="md-nav__link">
+    Arrays
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#deep-splat" title="Deep Splat" class="md-nav__link">
+    Deep Splat
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#finding-parents-with-particular-children-nodes" title="Finding parents with particular children nodes" class="md-nav__link">
+    Finding parents with particular children nodes
+  </a>
+  
+    <nav class="md-nav">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#with-prefixes" title="With prefixes" class="md-nav__link">
+    With prefixes
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#special-characters" title="Special Characters" class="md-nav__link">
+    Special Characters
+  </a>
+  
+    <nav class="md-nav">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#keys-with-dots" title="Keys with dots" class="md-nav__link">
+    Keys with dots
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#keys-and-values-with-leading-dashes" title="Keys (and values) with leading dashes" class="md-nav__link">
+    Keys (and values) with leading dashes
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+      
+      
+      
+      
+    </ul>
+  
+</nav>
+    
+  </li>
+
+    
+      
+      
+      
+
+
+  <li class="md-nav__item">
+    <a href="../write/" title="Write/Update" class="md-nav__link">
+      Write/Update
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
+  <li class="md-nav__item">
+    <a href="../prefix/" title="Prefix" class="md-nav__link">
+      Prefix
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
+  <li class="md-nav__item">
+    <a href="../delete/" title="Delete" class="md-nav__link">
+      Delete
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
+  <li class="md-nav__item">
+    <a href="../create/" title="Create" class="md-nav__link">
+      Create
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
+  <li class="md-nav__item">
+    <a href="../convert/" title="Convert" class="md-nav__link">
+      Convert
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
+  <li class="md-nav__item">
+    <a href="../merge/" title="Merge" class="md-nav__link">
+      Merge
+    </a>
+  </li>
+
+    
+  </ul>
+</nav>
+                  </div>
+                </div>
+              </div>
+            
+            
+              <div class="md-sidebar md-sidebar--secondary" data-md-component="toc">
+                <div class="md-sidebar__scrollwrap">
+                  <div class="md-sidebar__inner">
+                    
+<nav class="md-nav md-nav--secondary">
+  
+  
+  
+    <label class="md-nav__title" for="__toc">Table of contents</label>
+    <ul class="md-nav__list" data-md-scrollfix>
+      
+        <li class="md-nav__item">
+  <a href="#simple-expressions" title="Simple expressions" class="md-nav__link">
+    Simple expressions
+  </a>
+  
+    <nav class="md-nav">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#maps" title="Maps" class="md-nav__link">
+    Maps
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#arrays" title="Arrays" class="md-nav__link">
+    Arrays
+  </a>
+  
+    <nav class="md-nav">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#appending-to-arrays" title="Appending to arrays" class="md-nav__link">
+    Appending to arrays
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#splat" title="Splat" class="md-nav__link">
+    Splat
+  </a>
+  
+    <nav class="md-nav">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#maps_1" title="Maps" class="md-nav__link">
+    Maps
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#arrays_1" title="Arrays" class="md-nav__link">
+    Arrays
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#deep-splat" title="Deep Splat" class="md-nav__link">
+    Deep Splat
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#finding-parents-with-particular-children-nodes" title="Finding parents with particular children nodes" class="md-nav__link">
+    Finding parents with particular children nodes
+  </a>
+  
+    <nav class="md-nav">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#with-prefixes" title="With prefixes" class="md-nav__link">
+    With prefixes
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#special-characters" title="Special Characters" class="md-nav__link">
+    Special Characters
+  </a>
+  
+    <nav class="md-nav">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#keys-with-dots" title="Keys with dots" class="md-nav__link">
+    Keys with dots
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#keys-and-values-with-leading-dashes" title="Keys (and values) with leading dashes" class="md-nav__link">
+    Keys (and values) with leading dashes
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+      
+      
+      
+      
+    </ul>
+  
+</nav>
+                  </div>
+                </div>
+              </div>
+            
+          
+          <div class="md-content">
+            <article class="md-content__inner md-typeset">
+              
+                
+                  <a href="https://github.com/mikefarah/yq/edit/master/docs/path_expressions.md" title="Edit this page" class="md-icon md-content__icon">&#xE3C9;</a>
+                
+                
+                  <h1>Path Expressions</h1>
+                
+                <p>Path expressions are used to deeply navigate and match particular yaml nodes.</p>
+<p><em>As a general rule, you should wrap paths in quotes in the CLI to prevent your interpreter from processing '*, []' and other special characters.</em></p>
+<h2 id="simple-expressions">Simple expressions<a class="headerlink" href="#simple-expressions" title="Permanent link">&para;</a></h2>
+<h3 id="maps">Maps<a class="headerlink" href="#maps" title="Permanent link">&para;</a></h3>
+<p>a.b.c</p>
+<pre><code class="yaml">a:
+  b:
+    c: thing # MATCHES
+</code></pre>
+
+<h3 id="arrays">Arrays<a class="headerlink" href="#arrays" title="Permanent link">&para;</a></h3>
+<p>a.b[1].c</p>
+<pre><code class="yaml">a:
+  b:
+  - c: thing0 
+  - c: thing1 # MATCHES
+  - c: thing2
+</code></pre>
+
+<h4 id="appending-to-arrays">Appending to arrays<a class="headerlink" href="#appending-to-arrays" title="Permanent link">&para;</a></h4>
+<p>(e.g. when using the write command)</p>
+<p>a.b[+].c</p>
+<pre><code class="yaml">a:
+  b:
+  - c: thing0 
+</code></pre>
+
+<p>Will add a new entry:</p>
+<pre><code class="yaml">a:
+  b:
+  - c: thing0 
+  - c: thing1 # NEW entry from [+] on B array.
+</code></pre>
+
+<h2 id="splat">Splat<a class="headerlink" href="#splat" title="Permanent link">&para;</a></h2>
+<h3 id="maps_1">Maps<a class="headerlink" href="#maps_1" title="Permanent link">&para;</a></h3>
+<p>a.*.c</p>
+<pre><code class="yaml">a:
+  b1:
+    c: thing # MATCHES
+  b2:
+    c: thing # MATCHES
+</code></pre>
+
+<h3 id="arrays_1">Arrays<a class="headerlink" href="#arrays_1" title="Permanent link">&para;</a></h3>
+<p>a.b[*].c</p>
+<pre><code class="yaml">a:
+  b:
+  - c: thing0 # MATCHES
+  - c: thing1 # MATCHES
+  - c: thing2 # MATCHES
+</code></pre>
+
+<h2 id="deep-splat">Deep Splat<a class="headerlink" href="#deep-splat" title="Permanent link">&para;</a></h2>
+<p>'**' will match arbitrary nodes for both maps and arrays:</p>
+<p>a.**.c</p>
+<pre><code class="yaml">a:
+  b1:
+    c: thing1 # MATCHES
+  b2:
+    c: thing2 # MATCHES
+  b3:
+    d:
+    - f:
+        c: thing3 # MATCHES
+    - f:
+        g:
+          c: thing4 # MATCHES
+</code></pre>
+
+<h2 id="finding-parents-with-particular-children-nodes">Finding parents with particular children nodes<a class="headerlink" href="#finding-parents-with-particular-children-nodes" title="Permanent link">&para;</a></h2>
+<p>a.(b.d==cat).b.c</p>
+<pre><code class="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
+</code></pre>
+
+<h3 id="with-prefixes">With prefixes<a class="headerlink" href="#with-prefixes" title="Permanent link">&para;</a></h3>
+<p>a.(b.d==cat*).c</p>
+<pre><code class="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
+</code></pre>
+
+<h2 id="special-characters">Special Characters<a class="headerlink" href="#special-characters" title="Permanent link">&para;</a></h2>
+<h3 id="keys-with-dots">Keys with dots<a class="headerlink" href="#keys-with-dots" title="Permanent link">&para;</a></h3>
+<p>When specifying a key that has a dot use key lookup indicator.</p>
+<pre><code class="yaml">b:
+  foo.bar: 7
+</code></pre>
+
+<pre><code class="bash">yaml r sample.yaml 'b[foo.bar]'
+</code></pre>
+
+<pre><code class="bash">yaml w sample.yaml 'b[foo.bar]' 9
+</code></pre>
+
+<p>Any valid yaml key can be specified as part of a key lookup.</p>
+<p>Note that the path is in quotes to avoid the square brackets being interpreted by your shell.</p>
+<h3 id="keys-and-values-with-leading-dashes">Keys (and values) with leading dashes<a class="headerlink" href="#keys-and-values-with-leading-dashes" title="Permanent link">&para;</a></h3>
+<p>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).</p>
+<p>To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so:</p>
+<pre><code class="bash">yq n -t -- --key --value
+</code></pre>
+
+<p>Will result in</p>
+<pre><code>--key: --value
+</code></pre>
+                
+                  
+                
+              
+              
+                
+
+
+              
+            </article>
+          </div>
+        </div>
+      </main>
+      
+        
+<footer class="md-footer">
+  
+    <div class="md-footer-nav">
+      <nav class="md-footer-nav__inner md-grid">
+        
+          <a href="../read/" title="Read" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
+            <div class="md-flex__cell md-flex__cell--shrink">
+              <i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
+            </div>
+            <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
+              <span class="md-flex__ellipsis">
+                <span class="md-footer-nav__direction">
+                  Previous
+                </span>
+                Read
+              </span>
+            </div>
+          </a>
+        
+        
+          <a href="../write/" title="Write/Update" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
+            <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
+              <span class="md-flex__ellipsis">
+                <span class="md-footer-nav__direction">
+                  Next
+                </span>
+                Write/Update
+              </span>
+            </div>
+            <div class="md-flex__cell md-flex__cell--shrink">
+              <i class="md-icon md-icon--arrow-forward md-footer-nav__button"></i>
+            </div>
+          </a>
+        
+      </nav>
+    </div>
+  
+  <div class="md-footer-meta md-typeset">
+    <div class="md-footer-meta__inner md-grid">
+      <div class="md-footer-copyright">
+        
+        powered by
+        <a href="https://www.mkdocs.org">MkDocs</a>
+        and
+        <a href="https://squidfunk.github.io/mkdocs-material/">
+          Material for MkDocs</a>
+      </div>
+      
+  <div class="md-footer-social">
+    <link rel="stylesheet" href="../assets/fonts/font-awesome.css">
+    
+      <a href="https://github.com/mikefarah" class="md-footer-social__link fa fa-github"></a>
+    
+      <a href="https://www.linkedin.com/in/mike-farah-b5a75b2/" class="md-footer-social__link fa fa-linkedin"></a>
+    
+  </div>
+
+    </div>
+  </div>
+</footer>
+      
+    </div>
+    
+      <script src="../assets/javascripts/application.39abc4af.js"></script>
+      
+      <script>app.initialize({version:"1.0.4",url:{base:".."}})</script>
+      
+    
+  </body>
+</html>

docs/prefix/index.html

@@ -252,6 +252,18 @@
       
 
 
+  <li class="md-nav__item">
+    <a href="../path_expressions/" title="Path Expressions" class="md-nav__link">
+      Path Expressions
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
   <li class="md-nav__item">
     <a href="../write/" title="Write/Update" class="md-nav__link">
       Write/Update
@@ -455,11 +467,11 @@
                 
                   <h1>Prefix</h1>
                 
-                <p>Paths can be prefixed using the 'prefix' command.
-The complete yaml content will be nested inside the new prefix path.</p>
                 <pre><code>yq p &lt;yaml_file&gt; &lt;path&gt;
 </code></pre>
 
+<p>Prefixes a yaml document with the given path expression. The complete yaml content will be nested inside the new prefix path.</p>
+<p>See docs for <a href="../path_expressions/">path expression</a> for more details.</p>
 <h3 id="to-stdout">To Stdout<a class="headerlink" href="#to-stdout" title="Permanent link">&para;</a></h3>
 <p>Given a data1.yaml file of:</p>
 <pre><code class="yaml">a: simple

docs/read/index.html

@@ -319,20 +319,6 @@
   
 </li>
       
-        <li class="md-nav__item">
-  <a href="#keys-with-dots" title="Keys with dots" class="md-nav__link">
-    Keys with dots
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#keys-and-values-with-leading-dashes" title="Keys (and values) with leading dashes" class="md-nav__link">
-    Keys (and values) with leading dashes
-  </a>
-  
-</li>
-      
       
       
       
@@ -349,6 +335,18 @@
       
 
 
+  <li class="md-nav__item">
+    <a href="../path_expressions/" title="Path Expressions" class="md-nav__link">
+      Path Expressions
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+
   <li class="md-nav__item">
     <a href="../write/" title="Write/Update" class="md-nav__link">
       Write/Update
@@ -490,20 +488,6 @@
   
 </li>
       
-        <li class="md-nav__item">
-  <a href="#keys-with-dots" title="Keys with dots" class="md-nav__link">
-    Keys with dots
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#keys-and-values-with-leading-dashes" title="Keys (and values) with leading dashes" class="md-nav__link">
-    Keys (and values) with leading dashes
-  </a>
-  
-</li>
-      
       
       
       
@@ -525,10 +509,11 @@
                 
                   <h1>Read</h1>
                 
-                <pre><code>yq r &lt;yaml_file|json_file&gt; &lt;path&gt;
+                <pre><code>yq r &lt;yaml_file|json_file&gt; &lt;path_expression&gt;
 </code></pre>
 
-<p>This command can take a json file as input too, and will output yaml unless specified to export as json (-j)</p>
+<p>Returns the matching nodes of the path expression for the given yaml file (or STDIN).</p>
+<p>See docs for <a href="../path_expressions/">path expression</a> for more details.</p>
 <h3 id="basic">Basic<a class="headerlink" href="#basic" title="Permanent link">&para;</a></h3>
 <p>Given a sample.yaml file of:</p>
 <pre><code class="yaml">b:
@@ -662,29 +647,6 @@ e.g.: given a sample file of</p>
 </code></pre>
 
 <p>Note that the path is in quotes to avoid the square brackets being interpreted by your shell.</p>
-<h3 id="keys-with-dots">Keys with dots<a class="headerlink" href="#keys-with-dots" title="Permanent link">&para;</a></h3>
-<p>When specifying a key that has a dot use key lookup indicator.</p>
-<pre><code class="yaml">b:
-  foo.bar: 7
-</code></pre>
-
-<pre><code class="bash">yaml r sample.yaml 'b[foo.bar]'
-</code></pre>
-
-<pre><code class="bash">yaml w sample.yaml 'b[foo.bar]' 9
-</code></pre>
-
-<p>Any valid yaml key can be specified as part of a key lookup.</p>
-<p>Note that the path is in quotes to avoid the square brackets being interpreted by your shell.</p>
-<h3 id="keys-and-values-with-leading-dashes">Keys (and values) with leading dashes<a class="headerlink" href="#keys-and-values-with-leading-dashes" title="Permanent link">&para;</a></h3>
-<p>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).</p>
-<p>To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so:</p>
-<pre><code class="bash">yq n -t -- --key --value
-</code></pre>
-
-<p>Will result in</p>
-<p><code>`
---key: --value</code></p>
                 
                   
                 
@@ -720,13 +682,13 @@ e.g.: given a sample file of</p>
           </a>
         
         
-          <a href="../write/" title="Write/Update" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
+          <a href="../path_expressions/" title="Path Expressions" class="md-flex md-footer-nav__link md-footer-nav__link--next" rel="next">
             <div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
               <span class="md-flex__ellipsis">
                 <span class="md-footer-nav__direction">
                   Next
                 </span>
-                Write/Update
+                Path Expressions
               </span>
             </div>
             <div class="md-flex__cell md-flex__cell--shrink">

docs/sitemap.xml

@@ -2,42 +2,47 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
      <loc>None</loc>
-     <lastmod>2019-05-16</lastmod>
+     <lastmod>2020-01-13</lastmod>
      <changefreq>daily</changefreq>
     </url>
     <url>
      <loc>None</loc>
-     <lastmod>2019-05-16</lastmod>
+     <lastmod>2020-01-13</lastmod>
      <changefreq>daily</changefreq>
     </url>
     <url>
      <loc>None</loc>
-     <lastmod>2019-05-16</lastmod>
+     <lastmod>2020-01-13</lastmod>
      <changefreq>daily</changefreq>
     </url>
     <url>
      <loc>None</loc>
-     <lastmod>2019-05-16</lastmod>
+     <lastmod>2020-01-13</lastmod>
      <changefreq>daily</changefreq>
     </url>
     <url>
      <loc>None</loc>
-     <lastmod>2019-05-16</lastmod>
+     <lastmod>2020-01-13</lastmod>
      <changefreq>daily</changefreq>
     </url>
     <url>
      <loc>None</loc>
-     <lastmod>2019-05-16</lastmod>
+     <lastmod>2020-01-13</lastmod>
      <changefreq>daily</changefreq>
     </url>
     <url>
      <loc>None</loc>
-     <lastmod>2019-05-16</lastmod>
+     <lastmod>2020-01-13</lastmod>
      <changefreq>daily</changefreq>
     </url>
     <url>
      <loc>None</loc>
-     <lastmod>2019-05-16</lastmod>
+     <lastmod>2020-01-13</lastmod>
+     <changefreq>daily</changefreq>
+    </url>
+    <url>
+     <loc>None</loc>
+     <lastmod>2020-01-13</lastmod>
      <changefreq>daily</changefreq>
     </url>
 </urlset>

docs/snippets/niche/index.html

@@ -1,447 +0,0 @@
-
-
-
-
-<!doctype html>
-<html lang="en" class="no-js">
-  <head>
-    
-      <meta charset="utf-8">
-      <meta name="viewport" content="width=device-width,initial-scale=1">
-      <meta http-equiv="x-ua-compatible" content="ie=edge">
-      
-      
-      
-      
-        <meta name="lang:clipboard.copy" content="Copy to clipboard">
-      
-        <meta name="lang:clipboard.copied" content="Copied to clipboard">
-      
-        <meta name="lang:search.language" content="en">
-      
-        <meta name="lang:search.pipeline.stopwords" content="True">
-      
-        <meta name="lang:search.pipeline.trimmer" content="True">
-      
-        <meta name="lang:search.result.none" content="No matching documents">
-      
-        <meta name="lang:search.result.one" content="1 matching document">
-      
-        <meta name="lang:search.result.other" content="# matching documents">
-      
-        <meta name="lang:search.tokenizer" content="[\s\-]+">
-      
-      <link rel="shortcut icon" href="../../assets/images/favicon.png">
-      <meta name="generator" content="mkdocs-1.0.4, mkdocs-material-4.2.0">
-    
-    
-      
-        <title>Niche - Yq</title>
-      
-    
-    
-      <link rel="stylesheet" href="../../assets/stylesheets/application.750b69bd.css">
-      
-      
-    
-    
-      <script src="../../assets/javascripts/modernizr.74668098.js"></script>
-    
-    
-      
-        <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
-        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700|Roboto+Mono">
-        <style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style>
-      
-    
-    <link rel="stylesheet" href="../../assets/fonts/material-icons.css">
-    
-    
-    
-      
-    
-    
-  </head>
-  
-    <body dir="ltr">
-  
-    <svg class="md-svg">
-      <defs>
-        
-        
-          <svg xmlns="http://www.w3.org/2000/svg" width="416" height="448"
-    viewBox="0 0 416 448" id="__github">
-  <path fill="currentColor" d="M160 304q0 10-3.125 20.5t-10.75 19-18.125
-        8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19 18.125-8.5
-        18.125 8.5 10.75 19 3.125 20.5zM320 304q0 10-3.125 20.5t-10.75
-        19-18.125 8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19
-        18.125-8.5 18.125 8.5 10.75 19 3.125 20.5zM360
-        304q0-30-17.25-51t-46.75-21q-10.25 0-48.75 5.25-17.75 2.75-39.25
-        2.75t-39.25-2.75q-38-5.25-48.75-5.25-29.5 0-46.75 21t-17.25 51q0 22 8
-        38.375t20.25 25.75 30.5 15 35 7.375 37.25 1.75h42q20.5 0
-        37.25-1.75t35-7.375 30.5-15 20.25-25.75 8-38.375zM416 260q0 51.75-15.25
-        82.75-9.5 19.25-26.375 33.25t-35.25 21.5-42.5 11.875-42.875 5.5-41.75
-        1.125q-19.5 0-35.5-0.75t-36.875-3.125-38.125-7.5-34.25-12.875-30.25-20.25-21.5-28.75q-15.5-30.75-15.5-82.75
-        0-59.25 34-99-6.75-20.5-6.75-42.5 0-29 12.75-54.5 27 0 47.5 9.875t47.25
-        30.875q36.75-8.75 77.25-8.75 37 0 70 8 26.25-20.5
-        46.75-30.25t47.25-9.75q12.75 25.5 12.75 54.5 0 21.75-6.75 42 34 40 34
-        99.5z" />
-</svg>
-        
-      </defs>
-    </svg>
-    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
-    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
-    <label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
-    
-      <a href="#keys-with-dots" tabindex="1" class="md-skip">
-        Skip to content
-      </a>
-    
-    
-      <header class="md-header" data-md-component="header">
-  <nav class="md-header-nav md-grid">
-    <div class="md-flex">
-      <div class="md-flex__cell md-flex__cell--shrink">
-        <a href="../.." title="Yq" class="md-header-nav__button md-logo">
-          
-            <i class="md-icon"></i>
-          
-        </a>
-      </div>
-      <div class="md-flex__cell md-flex__cell--shrink">
-        <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
-      </div>
-      <div class="md-flex__cell md-flex__cell--stretch">
-        <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
-          
-            <span class="md-header-nav__topic">
-              Yq
-            </span>
-            <span class="md-header-nav__topic">
-              Niche
-            </span>
-          
-        </div>
-      </div>
-      <div class="md-flex__cell md-flex__cell--shrink">
-        
-          <label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
-          
-<div class="md-search" data-md-component="search" role="dialog">
-  <label class="md-search__overlay" for="__search"></label>
-  <div class="md-search__inner" role="search">
-    <form class="md-search__form" name="search">
-      <input type="text" class="md-search__input" name="query" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
-      <label class="md-icon md-search__icon" for="__search"></label>
-      <button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
-        &#xE5CD;
-      </button>
-    </form>
-    <div class="md-search__output">
-      <div class="md-search__scrollwrap" data-md-scrollfix>
-        <div class="md-search-result" data-md-component="result">
-          <div class="md-search-result__meta">
-            Type to start searching
-          </div>
-          <ol class="md-search-result__list"></ol>
-        </div>
-      </div>
-    </div>
-  </div>
-</div>
-        
-      </div>
-      
-        <div class="md-flex__cell md-flex__cell--shrink">
-          <div class="md-header-nav__source">
-            
-
-
-  
-
-<a href="https://github.com/mikefarah/yq/" title="Go to repository" class="md-source" data-md-source="github">
-  
-    <div class="md-source__icon">
-      <svg viewBox="0 0 24 24" width="24" height="24">
-        <use xlink:href="#__github" width="24" height="24"></use>
-      </svg>
-    </div>
-  
-  <div class="md-source__repository">
-    mikefarah/yq
-  </div>
-</a>
-          </div>
-        </div>
-      
-    </div>
-  </nav>
-</header>
-    
-    <div class="md-container">
-      
-        
-      
-      
-      <main class="md-main">
-        <div class="md-main__inner md-grid" data-md-component="container">
-          
-            
-              <div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
-                <div class="md-sidebar__scrollwrap">
-                  <div class="md-sidebar__inner">
-                    <nav class="md-nav md-nav--primary" data-md-level="0">
-  <label class="md-nav__title md-nav__title--site" for="__drawer">
-    <a href="../.." title="Yq" class="md-nav__button md-logo">
-      
-        <i class="md-icon"></i>
-      
-    </a>
-    Yq
-  </label>
-  
-    <div class="md-nav__source">
-      
-
-
-  
-
-<a href="https://github.com/mikefarah/yq/" title="Go to repository" class="md-source" data-md-source="github">
-  
-    <div class="md-source__icon">
-      <svg viewBox="0 0 24 24" width="24" height="24">
-        <use xlink:href="#__github" width="24" height="24"></use>
-      </svg>
-    </div>
-  
-  <div class="md-source__repository">
-    mikefarah/yq
-  </div>
-</a>
-    </div>
-  
-  <ul class="md-nav__list" data-md-scrollfix>
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../.." title="Install" class="md-nav__link">
-      Install
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../read/" title="Read" class="md-nav__link">
-      Read
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../write/" title="Write/Update" class="md-nav__link">
-      Write/Update
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../prefix/" title="Prefix" class="md-nav__link">
-      Prefix
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../delete/" title="Delete" class="md-nav__link">
-      Delete
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../create/" title="Create" class="md-nav__link">
-      Create
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../convert/" title="Convert" class="md-nav__link">
-      Convert
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../merge/" title="Merge" class="md-nav__link">
-      Merge
-    </a>
-  </li>
-
-    
-  </ul>
-</nav>
-                  </div>
-                </div>
-              </div>
-            
-            
-              <div class="md-sidebar md-sidebar--secondary" data-md-component="toc">
-                <div class="md-sidebar__scrollwrap">
-                  <div class="md-sidebar__inner">
-                    
-<nav class="md-nav md-nav--secondary">
-  
-  
-  
-    <label class="md-nav__title" for="__toc">Table of contents</label>
-    <ul class="md-nav__list" data-md-scrollfix>
-      
-        <li class="md-nav__item">
-  <a href="#keys-with-dots" title="Keys with dots" class="md-nav__link">
-    Keys with dots
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#keys-and-values-with-leading-dashes" title="Keys (and values) with leading dashes" class="md-nav__link">
-    Keys (and values) with leading dashes
-  </a>
-  
-</li>
-      
-      
-      
-      
-      
-    </ul>
-  
-</nav>
-                  </div>
-                </div>
-              </div>
-            
-          
-          <div class="md-content">
-            <article class="md-content__inner md-typeset">
-              
-                
-                  <a href="https://github.com/mikefarah/yq/edit/master/docs/snippets/niche.md" title="Edit this page" class="md-icon md-content__icon">&#xE3C9;</a>
-                
-                
-                  <h1>Niche</h1>
-                
-                <h3 id="keys-with-dots">Keys with dots<a class="headerlink" href="#keys-with-dots" title="Permanent link">&para;</a></h3>
-<p>When specifying a key that has a dot use key lookup indicator.</p>
-<pre><code class="yaml">b:
-  foo.bar: 7
-</code></pre>
-
-<pre><code class="bash">yaml r sample.yaml 'b[foo.bar]'
-</code></pre>
-
-<pre><code class="bash">yaml w sample.yaml 'b[foo.bar]' 9
-</code></pre>
-
-<p>Any valid yaml key can be specified as part of a key lookup.</p>
-<p>Note that the path is in quotes to avoid the square brackets being interpreted by your shell.</p>
-<h3 id="keys-and-values-with-leading-dashes">Keys (and values) with leading dashes<a class="headerlink" href="#keys-and-values-with-leading-dashes" title="Permanent link">&para;</a></h3>
-<p>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).</p>
-<p>To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so:</p>
-<pre><code class="bash">yq n -t -- --key --value
-</code></pre>
-
-<p>Will result in</p>
-<pre><code>--key: --value
-</code></pre>
-                
-                  
-                
-              
-              
-                
-
-
-              
-            </article>
-          </div>
-        </div>
-      </main>
-      
-        
-<footer class="md-footer">
-  
-  <div class="md-footer-meta md-typeset">
-    <div class="md-footer-meta__inner md-grid">
-      <div class="md-footer-copyright">
-        
-        powered by
-        <a href="https://www.mkdocs.org">MkDocs</a>
-        and
-        <a href="https://squidfunk.github.io/mkdocs-material/">
-          Material for MkDocs</a>
-      </div>
-      
-  <div class="md-footer-social">
-    <link rel="stylesheet" href="../../assets/fonts/font-awesome.css">
-    
-      <a href="https://github.com/mikefarah" class="md-footer-social__link fa fa-github"></a>
-    
-      <a href="https://www.linkedin.com/in/mike-farah-b5a75b2/" class="md-footer-social__link fa fa-linkedin"></a>
-    
-  </div>
-
-    </div>
-  </div>
-</footer>
-      
-    </div>
-    
-      <script src="../../assets/javascripts/application.39abc4af.js"></script>
-      
-      <script>app.initialize({version:"1.0.4",url:{base:"../.."}})</script>
-      
-    
-  </body>
-</html>

docs/snippets/works_with_json/index.html

@@ -1,385 +0,0 @@
-
-
-
-
-<!doctype html>
-<html lang="en" class="no-js">
-  <head>
-    
-      <meta charset="utf-8">
-      <meta name="viewport" content="width=device-width,initial-scale=1">
-      <meta http-equiv="x-ua-compatible" content="ie=edge">
-      
-      
-      
-      
-        <meta name="lang:clipboard.copy" content="Copy to clipboard">
-      
-        <meta name="lang:clipboard.copied" content="Copied to clipboard">
-      
-        <meta name="lang:search.language" content="en">
-      
-        <meta name="lang:search.pipeline.stopwords" content="True">
-      
-        <meta name="lang:search.pipeline.trimmer" content="True">
-      
-        <meta name="lang:search.result.none" content="No matching documents">
-      
-        <meta name="lang:search.result.one" content="1 matching document">
-      
-        <meta name="lang:search.result.other" content="# matching documents">
-      
-        <meta name="lang:search.tokenizer" content="[\s\-]+">
-      
-      <link rel="shortcut icon" href="../../assets/images/favicon.png">
-      <meta name="generator" content="mkdocs-1.0.4, mkdocs-material-4.2.0">
-    
-    
-      
-        <title>Works with json - Yq</title>
-      
-    
-    
-      <link rel="stylesheet" href="../../assets/stylesheets/application.750b69bd.css">
-      
-      
-    
-    
-      <script src="../../assets/javascripts/modernizr.74668098.js"></script>
-    
-    
-      
-        <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
-        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700|Roboto+Mono">
-        <style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style>
-      
-    
-    <link rel="stylesheet" href="../../assets/fonts/material-icons.css">
-    
-    
-    
-      
-    
-    
-  </head>
-  
-    <body dir="ltr">
-  
-    <svg class="md-svg">
-      <defs>
-        
-        
-          <svg xmlns="http://www.w3.org/2000/svg" width="416" height="448"
-    viewBox="0 0 416 448" id="__github">
-  <path fill="currentColor" d="M160 304q0 10-3.125 20.5t-10.75 19-18.125
-        8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19 18.125-8.5
-        18.125 8.5 10.75 19 3.125 20.5zM320 304q0 10-3.125 20.5t-10.75
-        19-18.125 8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19
-        18.125-8.5 18.125 8.5 10.75 19 3.125 20.5zM360
-        304q0-30-17.25-51t-46.75-21q-10.25 0-48.75 5.25-17.75 2.75-39.25
-        2.75t-39.25-2.75q-38-5.25-48.75-5.25-29.5 0-46.75 21t-17.25 51q0 22 8
-        38.375t20.25 25.75 30.5 15 35 7.375 37.25 1.75h42q20.5 0
-        37.25-1.75t35-7.375 30.5-15 20.25-25.75 8-38.375zM416 260q0 51.75-15.25
-        82.75-9.5 19.25-26.375 33.25t-35.25 21.5-42.5 11.875-42.875 5.5-41.75
-        1.125q-19.5 0-35.5-0.75t-36.875-3.125-38.125-7.5-34.25-12.875-30.25-20.25-21.5-28.75q-15.5-30.75-15.5-82.75
-        0-59.25 34-99-6.75-20.5-6.75-42.5 0-29 12.75-54.5 27 0 47.5 9.875t47.25
-        30.875q36.75-8.75 77.25-8.75 37 0 70 8 26.25-20.5
-        46.75-30.25t47.25-9.75q12.75 25.5 12.75 54.5 0 21.75-6.75 42 34 40 34
-        99.5z" />
-</svg>
-        
-      </defs>
-    </svg>
-    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
-    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
-    <label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
-    
-    
-      <header class="md-header" data-md-component="header">
-  <nav class="md-header-nav md-grid">
-    <div class="md-flex">
-      <div class="md-flex__cell md-flex__cell--shrink">
-        <a href="../.." title="Yq" class="md-header-nav__button md-logo">
-          
-            <i class="md-icon"></i>
-          
-        </a>
-      </div>
-      <div class="md-flex__cell md-flex__cell--shrink">
-        <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
-      </div>
-      <div class="md-flex__cell md-flex__cell--stretch">
-        <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
-          
-            <span class="md-header-nav__topic">
-              Yq
-            </span>
-            <span class="md-header-nav__topic">
-              Works with json
-            </span>
-          
-        </div>
-      </div>
-      <div class="md-flex__cell md-flex__cell--shrink">
-        
-          <label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
-          
-<div class="md-search" data-md-component="search" role="dialog">
-  <label class="md-search__overlay" for="__search"></label>
-  <div class="md-search__inner" role="search">
-    <form class="md-search__form" name="search">
-      <input type="text" class="md-search__input" name="query" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
-      <label class="md-icon md-search__icon" for="__search"></label>
-      <button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
-        &#xE5CD;
-      </button>
-    </form>
-    <div class="md-search__output">
-      <div class="md-search__scrollwrap" data-md-scrollfix>
-        <div class="md-search-result" data-md-component="result">
-          <div class="md-search-result__meta">
-            Type to start searching
-          </div>
-          <ol class="md-search-result__list"></ol>
-        </div>
-      </div>
-    </div>
-  </div>
-</div>
-        
-      </div>
-      
-        <div class="md-flex__cell md-flex__cell--shrink">
-          <div class="md-header-nav__source">
-            
-
-
-  
-
-<a href="https://github.com/mikefarah/yq/" title="Go to repository" class="md-source" data-md-source="github">
-  
-    <div class="md-source__icon">
-      <svg viewBox="0 0 24 24" width="24" height="24">
-        <use xlink:href="#__github" width="24" height="24"></use>
-      </svg>
-    </div>
-  
-  <div class="md-source__repository">
-    mikefarah/yq
-  </div>
-</a>
-          </div>
-        </div>
-      
-    </div>
-  </nav>
-</header>
-    
-    <div class="md-container">
-      
-        
-      
-      
-      <main class="md-main">
-        <div class="md-main__inner md-grid" data-md-component="container">
-          
-            
-              <div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
-                <div class="md-sidebar__scrollwrap">
-                  <div class="md-sidebar__inner">
-                    <nav class="md-nav md-nav--primary" data-md-level="0">
-  <label class="md-nav__title md-nav__title--site" for="__drawer">
-    <a href="../.." title="Yq" class="md-nav__button md-logo">
-      
-        <i class="md-icon"></i>
-      
-    </a>
-    Yq
-  </label>
-  
-    <div class="md-nav__source">
-      
-
-
-  
-
-<a href="https://github.com/mikefarah/yq/" title="Go to repository" class="md-source" data-md-source="github">
-  
-    <div class="md-source__icon">
-      <svg viewBox="0 0 24 24" width="24" height="24">
-        <use xlink:href="#__github" width="24" height="24"></use>
-      </svg>
-    </div>
-  
-  <div class="md-source__repository">
-    mikefarah/yq
-  </div>
-</a>
-    </div>
-  
-  <ul class="md-nav__list" data-md-scrollfix>
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../.." title="Install" class="md-nav__link">
-      Install
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../read/" title="Read" class="md-nav__link">
-      Read
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../write/" title="Write/Update" class="md-nav__link">
-      Write/Update
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../prefix/" title="Prefix" class="md-nav__link">
-      Prefix
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../delete/" title="Delete" class="md-nav__link">
-      Delete
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../create/" title="Create" class="md-nav__link">
-      Create
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../convert/" title="Convert" class="md-nav__link">
-      Convert
-    </a>
-  </li>
-
-    
-      
-      
-      
-
-
-  <li class="md-nav__item">
-    <a href="../../merge/" title="Merge" class="md-nav__link">
-      Merge
-    </a>
-  </li>
-
-    
-  </ul>
-</nav>
-                  </div>
-                </div>
-              </div>
-            
-            
-          
-          <div class="md-content">
-            <article class="md-content__inner md-typeset">
-              
-                
-                  <a href="https://github.com/mikefarah/yq/edit/master/docs/snippets/works_with_json.md" title="Edit this page" class="md-icon md-content__icon">&#xE3C9;</a>
-                
-                
-                  <h1>Works with json</h1>
-                
-                <p>This command can take a json file as input too, and will output yaml unless specified to export as json (-j)</p>
-                
-                  
-                
-              
-              
-                
-
-
-              
-            </article>
-          </div>
-        </div>
-      </main>
-      
-        
-<footer class="md-footer">
-  
-  <div class="md-footer-meta md-typeset">
-    <div class="md-footer-meta__inner md-grid">
-      <div class="md-footer-copyright">
-        
-        powered by
-        <a href="https://www.mkdocs.org">MkDocs</a>
-        and
-        <a href="https://squidfunk.github.io/mkdocs-material/">
-          Material for MkDocs</a>
-      </div>
-      
-  <div class="md-footer-social">
-    <link rel="stylesheet" href="../../assets/fonts/font-awesome.css">
-    
-      <a href="https://github.com/mikefarah" class="md-footer-social__link fa fa-github"></a>
-    
-      <a href="https://www.linkedin.com/in/mike-farah-b5a75b2/" class="md-footer-social__link fa fa-linkedin"></a>
-    
-  </div>
-
-    </div>
-  </div>
-</footer>
-      
-    </div>
-    
-      <script src="../../assets/javascripts/application.39abc4af.js"></script>
-      
-      <script>app.initialize({version:"1.0.4",url:{base:"../.."}})</script>
-      
-    
-  </body>
-</html>

docs/write/index.html

@@ -252,6 +252,18 @@
       
 
 
+  <li class="md-nav__item">
+    <a href="../path_expressions/" title="Path Expressions" class="md-nav__link">
+      Path Expressions
+    </a>
+  </li>
+
+    
+      
+      
+      
+
+  
 
 
   <li class="md-nav__item md-nav__item--active">
@@ -359,20 +371,6 @@
   
 </li>
       
-        <li class="md-nav__item">
-  <a href="#keys-with-dots" title="Keys with dots" class="md-nav__link">
-    Keys with dots
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#keys-and-values-with-leading-dashes" title="Keys (and values) with leading dashes" class="md-nav__link">
-    Keys (and values) with leading dashes
-  </a>
-  
-</li>
-      
       
       
       
@@ -546,20 +544,6 @@
   
 </li>
       
-        <li class="md-nav__item">
-  <a href="#keys-with-dots" title="Keys with dots" class="md-nav__link">
-    Keys with dots
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#keys-and-values-with-leading-dashes" title="Keys (and values) with leading dashes" class="md-nav__link">
-    Keys (and values) with leading dashes
-  </a>
-  
-</li>
-      
       
       
       
@@ -581,9 +565,11 @@
                 
                   <h1>Write/Update</h1>
                 
-                <pre><code>yq w &lt;yaml_file&gt; &lt;path&gt; &lt;new value&gt;
+                <pre><code>yq w &lt;yaml_file&gt; &lt;path_expression&gt; &lt;new value&gt;
 </code></pre>
 
+<p>Updates all the matching nodes of path expression to the supplied value.</p>
+<p>See docs for <a href="../path_expressions/">path expression</a> for more details.</p>
 <h3 id="to-stdout">To Stdout<a class="headerlink" href="#to-stdout" title="Permanent link">&para;</a></h3>
 <p>Given a sample.yaml file of:</p>
 <pre><code class="yaml">b:
@@ -809,30 +795,6 @@ b.e[+].name: Howdy Partner
   path: -3
 </code></pre>
                 
-<h3 id="keys-with-dots">Keys with dots<a class="headerlink" href="#keys-with-dots" title="Permanent link">&para;</a></h3>
-<p>When specifying a key that has a dot use key lookup indicator.</p>
-<pre><code class="yaml">b:
-  foo.bar: 7
-</code></pre>
-
-<pre><code class="bash">yaml r sample.yaml 'b[foo.bar]'
-</code></pre>
-
-<pre><code class="bash">yaml w sample.yaml 'b[foo.bar]' 9
-</code></pre>
-
-<p>Any valid yaml key can be specified as part of a key lookup.</p>
-<p>Note that the path is in quotes to avoid the square brackets being interpreted by your shell.</p>
-<h3 id="keys-and-values-with-leading-dashes">Keys (and values) with leading dashes<a class="headerlink" href="#keys-and-values-with-leading-dashes" title="Permanent link">&para;</a></h3>
-<p>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).</p>
-<p>To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so:</p>
-<pre><code class="bash">yq n -t -- --key --value
-</code></pre>
-
-<p>Will result in</p>
-<p><code>`
---key: --value</code></p>
-                
                   
                 
               
@@ -852,7 +814,7 @@ b.e[+].name: Howdy Partner
     <div class="md-footer-nav">
       <nav class="md-footer-nav__inner md-grid">
         
-          <a href="../read/" title="Read" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
+          <a href="../path_expressions/" title="Path Expressions" class="md-flex md-footer-nav__link md-footer-nav__link--prev" rel="prev">
             <div class="md-flex__cell md-flex__cell--shrink">
               <i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
             </div>
@@ -861,7 +823,7 @@ b.e[+].name: Howdy Partner
                 <span class="md-footer-nav__direction">
                   Previous
                 </span>
-                Read
+                Path Expressions
               </span>
             </div>
           </a>

examples/instruction_sample.yaml

@@ -3,8 +3,5 @@
   value:
     #great 
     things: frog # wow!
-- command: update
-  path: b.e[+].name
-  value: Mike Farah
 - command: delete
   path: b.d

examples/sample.yaml

@@ -1,9 +1,13 @@
-a: true
+bob:
-b:
+  item:
-  c: 2
+    cats: bananas
-  d: [3, 4, 5]
+  something:
-  e:
+    cats: lemons
-    - name: fred
+  itemThing:
-      value: 3
+    cats: bananas
-    - name: sam
+  item2:
-      value: 4
+    cats: apples
+  thing:
+    cats: oranges
+my:
+  path: -3

mkdocs.yml

@@ -5,6 +5,7 @@ theme: 'material'
 pages:
     - Install: index.md
     - Read: read.md
+    - Path Expressions: path_expressions.md
     - Write/Update: write.md
     - Prefix: prefix.md
     - Delete: delete.md

mkdocs/convert.md

@@ -1,5 +1,7 @@
-### Yaml to Json
+## Yaml to Json
-To convert output to json, use the --tojson (or -j) flag. This can only be used with the read command.
+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.
 
-```
+See docs for [path expression](path_expressions.md)
-yq n <path> <new value>
-```
 
-### 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
+- command: update 
-b.e[+].name: Howdy Partner
+  path: b.c
+  value:
+    #great 
+    things: frog # wow!
 ```
 then
 
@@ -30,9 +35,9 @@ yq n -s create_instructions.yaml
 will output:
 ```yaml
 b:
-  c: 3
+  c:
-  e:
+    #great
-    - name: Howdy Partner
+    things: frog # wow!
 ```
 
 You can also pipe the instructions in:
@@ -40,5 +45,3 @@ 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
+## Deleting in-place
-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
 ```bash
 yq d -i sample.yaml b.c
 ```
 will update the sample.yaml file so that the 'c' node is deleted
 
 
-### Splat
+## Multiple Documents
-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
-```
 
-### Prefix Splat
+### Delete from single document
-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
 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
+## 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
 ```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
+Prefixes a yaml document with the given path expression. The complete yaml content will be nested inside the new prefix path.
-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]
-```
 
-### 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
+## Updating files in-place
-Given a data1.yaml file of:
-```yaml
-a: simple
-b: [1, 2]
-```
-then
 ```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
+## Multiple Documents
-Given a sample.yaml file of:
+### Reading from a single document
-```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
 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:
@@ -106,45 +67,3 @@ will output:
 - 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
+## Appending value to an array field
-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
 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
+## Updating multiple values with a script 
-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
 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!}

pkg/yqlib/data_navigator.go

@@ -69,7 +69,7 @@ func (n *navigator) recurse(value *yaml.Node, head string, tail []string, pathSt
 		return n.recurseMap(value, head, tail, pathStack)
 	case yaml.SequenceNode:
 		log.Debug("its a sequence of %v things!", len(value.Content))
-		if head == "*" || head == "**" {
+		if n.navigationStrategy.GetPathParser().IsPathExpression(head) {
 			return n.splatArray(value, head, tail, pathStack)
 		} else if head == "+" {
 			return n.appendArray(value, head, tail, pathStack)
@@ -96,7 +96,7 @@ func (n *navigator) recurseMap(value *yaml.Node, head string, tail []string, pat
 		newPathStack := append(pathStack, contents[indexInMap].Value)
 		log.Debug("appended %v", contents[indexInMap].Value)
 		n.navigationStrategy.DebugVisitedNodes()
-		log.Debug("should I traverse? %v, %v", head, pathStackToString(newPathStack))
+		log.Debug("should I traverse? head: %v, path: %v", head, pathStackToString(newPathStack))
 		DebugNode(value)
 		if n.navigationStrategy.ShouldTraverse(NewNodeContext(contents[indexInMap+1], head, tail, newPathStack), contents[indexInMap].Value) {
 			log.Debug("recurseMap: Going to traverse")
@@ -116,7 +116,7 @@ func (n *navigator) recurseMap(value *yaml.Node, head string, tail []string, pat
 		return errorVisiting
 	}
 
-	if traversedEntry || head == "*" || head == "**" || !n.navigationStrategy.AutoCreateMap(NewNodeContext(value, head, tail, pathStack)) {
+	if traversedEntry || n.navigationStrategy.GetPathParser().IsPathExpression(head) || !n.navigationStrategy.AutoCreateMap(NewNodeContext(value, head, tail, pathStack)) {
 		return nil
 	}
 
@@ -214,11 +214,15 @@ func (n *navigator) splatArray(value *yaml.Node, head string, tail []string, pat
 		log.Debug("processing")
 		DebugNode(childValue)
 		childValue = n.getOrReplace(childValue, guessKind(head, tail, childValue.Kind))
-		var err = n.doTraverse(childValue, head, tail, append(pathStack, index))
+
+		newPathStack := append(pathStack, index)
+		if n.navigationStrategy.ShouldTraverse(NewNodeContext(childValue, head, tail, newPathStack), childValue.Value) {
+			var err = n.doTraverse(childValue, head, tail, newPathStack)
 			if err != nil {
 				return err
 			}
 		}
+	}
 	return nil
 }
 

pkg/yqlib/delete_navigation_strategy.go

@@ -10,6 +10,7 @@ func DeleteNavigationStrategy(pathElementToDelete string) NavigationStrategy {
 	parser := NewPathParser()
 	return &NavigationStrategyImpl{
 		visitedNodes: []*NodeContext{},
+		pathParser:   parser,
 		followAlias: func(nodeContext NodeContext) bool {
 			return false
 		},

pkg/yqlib/filter_matching_node_navigation_strategy.go

@@ -0,0 +1,21 @@
+package yqlib
+
+func FilterMatchingNodesNavigationStrategy(value string) NavigationStrategy {
+	return &NavigationStrategyImpl{
+		visitedNodes: []*NodeContext{},
+		pathParser:   NewPathParser(),
+		followAlias: func(nodeContext NodeContext) bool {
+			return true
+		},
+		autoCreateMap: func(nodeContext NodeContext) bool {
+			return false
+		},
+		visit: func(nodeContext NodeContext) error {
+			return nil
+		},
+		shouldVisitExtraFn: func(nodeContext NodeContext) bool {
+			log.Debug("does %v match %v ? %v", nodeContext.Node.Value, value, nodeContext.Node.Value == value)
+			return matchesString(value, nodeContext.Node.Value)
+		},
+	}
+}

pkg/yqlib/lib.go

@@ -74,7 +74,8 @@ func guessKind(head string, tail []string, guess yaml.Kind) yaml.Kind {
 	if tail[0] == "+" || errorParsingInt == nil {
 		return yaml.SequenceNode
 	}
-	if (tail[0] == "*" || tail[0] == "**" || head == "**") && (guess == yaml.SequenceNode || guess == yaml.MappingNode) {
+	pathParser := NewPathParser()
+	if (pathParser.IsPathExpression(tail[0]) || head == "**") && (guess == yaml.SequenceNode || guess == yaml.MappingNode) {
 		return guess
 	}
 	if guess == yaml.AliasNode {
@@ -108,10 +109,10 @@ func NewYqLib() YqLib {
 
 func (l *lib) Get(rootNode *yaml.Node, path string) ([]*NodeContext, error) {
 	var paths = l.parser.ParsePath(path)
-	NavigationStrategy := ReadNavigationStrategy()
+	navigationStrategy := ReadNavigationStrategy()
-	navigator := NewDataNavigator(NavigationStrategy)
+	navigator := NewDataNavigator(navigationStrategy)
 	error := navigator.Traverse(rootNode, paths)
-	return NavigationStrategy.GetVisitedNodes(), error
+	return navigationStrategy.GetVisitedNodes(), error
 
 }
 

pkg/yqlib/navigation_strategy.go

@@ -36,13 +36,20 @@ type NavigationStrategy interface {
 	ShouldTraverse(nodeContext NodeContext, nodeKey string) bool
 	GetVisitedNodes() []*NodeContext
 	DebugVisitedNodes()
+	GetPathParser() PathParser
 }
 
 type NavigationStrategyImpl struct {
 	followAlias        func(nodeContext NodeContext) bool
 	autoCreateMap      func(nodeContext NodeContext) bool
 	visit              func(nodeContext NodeContext) error
+	shouldVisitExtraFn func(nodeContext NodeContext) bool
 	visitedNodes       []*NodeContext
+	pathParser         PathParser
+}
+
+func (ns *NavigationStrategyImpl) GetPathParser() PathParser {
+	return ns.pathParser
 }
 
 func (ns *NavigationStrategyImpl) GetVisitedNodes() []*NodeContext {
@@ -67,10 +74,8 @@ func (ns *NavigationStrategyImpl) ShouldTraverse(nodeContext NodeContext, nodeKe
 		return false
 	}
 
-	parser := NewPathParser()
-
 	return (nodeKey == "<<" && ns.FollowAlias(nodeContext)) || (nodeKey != "<<" &&
-		parser.MatchesNextPathElement(nodeContext, nodeKey))
+		ns.pathParser.MatchesNextPathElement(nodeContext, nodeKey))
 }
 
 func (ns *NavigationStrategyImpl) shouldVisit(nodeContext NodeContext) bool {
@@ -87,11 +92,10 @@ func (ns *NavigationStrategyImpl) shouldVisit(nodeContext NodeContext) bool {
 
 	nodeKey := fmt.Sprintf("%v", pathStack[len(pathStack)-1])
 	log.Debug("nodeKey: %v, nodeContext.Head: %v", nodeKey, nodeContext.Head)
-	parser := NewPathParser()
 
 	// only visit aliases if its an exact match
-	return (nodeKey == "<<" && nodeContext.Head == "<<") || (nodeKey != "<<" &&
+	return ((nodeKey == "<<" && nodeContext.Head == "<<") || (nodeKey != "<<" &&
-		parser.MatchesNextPathElement(nodeContext, nodeKey))
+		ns.pathParser.MatchesNextPathElement(nodeContext, nodeKey))) && (ns.shouldVisitExtraFn == nil || ns.shouldVisitExtraFn(nodeContext))
 }
 
 func (ns *NavigationStrategyImpl) Visit(nodeContext NodeContext) error {

pkg/yqlib/path_parser.go

@@ -8,6 +8,7 @@ import (
 type PathParser interface {
 	ParsePath(path string) []string
 	MatchesNextPathElement(nodeContext NodeContext, nodeKey string) bool
+	IsPathExpression(pathElement string) bool
 }
 
 type pathParser struct{}
@@ -16,6 +17,19 @@ func NewPathParser() PathParser {
 	return &pathParser{}
 }
 
+func matchesString(expression string, value string) bool {
+	var prefixMatch = strings.TrimSuffix(expression, "*")
+	if prefixMatch != expression {
+		log.Debug("prefix match, %v", strings.HasPrefix(value, prefixMatch))
+		return strings.HasPrefix(value, prefixMatch)
+	}
+	return value == expression
+}
+
+func (p *pathParser) IsPathExpression(pathElement string) bool {
+	return pathElement == "*" || pathElement == "**" || strings.Contains(pathElement, "==")
+}
+
 /**
  * node: node that we may traverse/visit
  * head: path element expression to match against
@@ -28,6 +42,26 @@ func (p *pathParser) MatchesNextPathElement(nodeContext NodeContext, nodeKey str
 	if head == "**" || head == "*" {
 		return true
 	}
+	if strings.Contains(head, "==") {
+		log.Debug("ooh deep recursion time")
+		result := strings.SplitN(head, "==", 2)
+		path := strings.TrimSpace(result[0])
+		value := strings.TrimSpace(result[1])
+		log.Debug("path %v", path)
+		log.Debug("value %v", value)
+		DebugNode(nodeContext.Node)
+		navigationStrategy := FilterMatchingNodesNavigationStrategy(value)
+
+		navigator := NewDataNavigator(navigationStrategy)
+		err := navigator.Traverse(nodeContext.Node, p.ParsePath(path))
+		if err != nil {
+			log.Error(err.Error())
+		}
+		//crap handle error
+		log.Debug("done deep recursing, found %v matches", len(navigationStrategy.GetVisitedNodes()))
+		return len(navigationStrategy.GetVisitedNodes()) > 0
+	}
+
 	if head == "+" {
 		log.Debug("head is +, nodeKey is %v", nodeKey)
 		var _, err = strconv.ParseInt(nodeKey, 10, 64) // nolint
@@ -35,12 +69,8 @@ func (p *pathParser) MatchesNextPathElement(nodeContext NodeContext, nodeKey str
 			return true
 		}
 	}
-	var prefixMatch = strings.TrimSuffix(head, "*")
+
-	if prefixMatch != head {
+	return matchesString(head, nodeKey)
-		log.Debug("prefix match, %v", strings.HasPrefix(nodeKey, prefixMatch))
-		return strings.HasPrefix(nodeKey, prefixMatch)
-	}
-	return nodeKey == head
 }
 
 func (p *pathParser) ParsePath(path string) []string {
@@ -66,9 +96,12 @@ func (p *pathParser) nextYamlPath(path string) (pathElement string, remaining st
 	case '"':
 		// e.g "a.b".blah.cat -> we need to return "a.b" and "blah.cat"
 		return p.search(path[1:], []uint8{'"'}, true)
+	case '(':
+		// e.g "a.b".blah.cat -> we need to return "a.b" and "blah.cat"
+		return p.search(path[1:], []uint8{')'}, true)
 	default:
 		// e.g "a.blah.cat" -> return "a" and "blah.cat"
-		return p.search(path[0:], []uint8{'.', '['}, false)
+		return p.search(path[0:], []uint8{'.', '[', '"', '('}, false)
 	}
 }
 

pkg/yqlib/read_navigation_strategy.go

@@ -3,6 +3,7 @@ package yqlib
 func ReadNavigationStrategy() NavigationStrategy {
 	return &NavigationStrategyImpl{
 		visitedNodes: []*NodeContext{},
+		pathParser:   NewPathParser(),
 		followAlias: func(nodeContext NodeContext) bool {
 			return true
 		},

pkg/yqlib/update_navigation_strategy.go

@@ -3,6 +3,7 @@ package yqlib
 func UpdateNavigationStrategy(updateCommand UpdateCommand, autoCreate bool) NavigationStrategy {
 	return &NavigationStrategyImpl{
 		visitedNodes: []*NodeContext{},
+		pathParser:   NewPathParser(),
 		followAlias: func(nodeContext NodeContext) bool {
 			return false
 		},

scripts/publish.sh

@@ -32,5 +32,5 @@ upload() {
     done < <(find ./build -mindepth 1 -maxdepth 1 -print0)
 }
 
-release
+# release
 upload

scripts/xcompile.sh

@@ -3,7 +3,7 @@
 # This assumes that gonative and gox is installed as per the 'one time setup' instructions
 # at https://github.com/inconshreveable/gonative
 
-gox -ldflags "${LDFLAGS}" -output="build/{{.Dir}}_{{.OS}}_{{.Arch}}"
+gox -ldflags "${LDFLAGS}" -output="build/yq_{{.OS}}_{{.Arch}}"
 # include non-default linux builds too
-gox -ldflags "${LDFLAGS}" -os=linux  -output="build/{{.Dir}}_{{.OS}}_{{.Arch}}"
+gox -ldflags "${LDFLAGS}" -os=linux  -output="build/yq_{{.OS}}_{{.Arch}}"
 

yq.go

@@ -92,17 +92,18 @@ func newCommandCLI() *cobra.Command {
 
 func createReadCmd() *cobra.Command {
 	var cmdRead = &cobra.Command{
-		Use:     "read [yaml_file] [path]",
+		Use:     "read [yaml_file] [path_expression]",
 		Aliases: []string{"r"},
-		Short:   "yq r [--doc/-d index] sample.yaml a.b.c",
+		Short:   "yq r [--doc/-d index] sample.yaml 'a.b.c'",
 		Example: `
-yq read things.yaml a.b.c
+yq read things.yaml 'a.b.c'
-yq r - a.b.c (reads from stdin)
+yq r - 'a.b.c' # reads from stdin
-yq r things.yaml a.*.c
+yq r things.yaml 'a.*.c'
-yq r things.yaml a.**.c
+yq r things.yaml 'a.**.c' # deep splat
+yq r things.yaml 'a.(child.subchild==co*).c'
 yq r -d1 things.yaml 'a.array[0].blah'
 yq r things.yaml 'a.array[*].blah'
-yq r -- things.yaml --key-starting-with-dashes.blah
+yq r -- things.yaml '--key-starting-with-dashes.blah'
       `,
 		Long: "Outputs the value of the given path in the yaml file to STDOUT",
 		RunE: readProperty,
@@ -114,23 +115,24 @@ yq r -- things.yaml --key-starting-with-dashes.blah
 
 func createWriteCmd() *cobra.Command {
 	var cmdWrite = &cobra.Command{
-		Use:     "write [yaml_file] [path] [value]",
+		Use:     "write [yaml_file] [path_expression] [value]",
 		Aliases: []string{"w"},
-		Short:   "yq w [--inplace/-i] [--script/-s script_file] [--doc/-d index] sample.yaml a.b.c newValue",
+		Short:   "yq w [--inplace/-i] [--script/-s script_file] [--doc/-d index] sample.yaml 'a.b.c' newValue",
 		Example: `
-yq write things.yaml a.b.c true
+yq write things.yaml 'a.b.c' true
 yq write things.yaml 'a.*.c' true
 yq write things.yaml 'a.**' true
-yq write things.yaml a.b.c --tag '!!str' true
+yq write things.yaml 'a.(child.subchild==co*).c' true
-yq write things.yaml a.b.c --tag '!!float' 3
+yq write things.yaml 'a.b.c' --tag '!!str' true # force 'true' to be interpreted as a string instead of bool
-yq write --inplace -- things.yaml a.b.c --cat
+yq write things.yaml 'a.b.c' --tag '!!float' 3
-yq w -i things.yaml a.b.c cat
+yq write --inplace -- things.yaml 'a.b.c' '--cat' # need to use '--' to stop processing arguments as flags
+yq w -i things.yaml 'a.b.c' cat
 yq w --script update_script.yaml things.yaml
 yq w -i -s update_script.yaml things.yaml
-yq w --doc 2 things.yaml 'a.b.d[+]' foo
+yq w things.yaml 'a.b.d[+]' foo # appends a new node to the 'd' array
-yq w -d2 things.yaml 'a.b.d[+]' foo
+yq w --doc 2 things.yaml 'a.b.d[+]' foo # updates the 3rd document of the yaml file
       `,
-		Long: `Updates the yaml file w.r.t the given path and value.
+		Long: `Updates the matching nodes of path expression to the specified value
 Outputs to STDOUT unless the inplace flag is used, in which case the file is updated instead.
 
 Append value to array adds the value to the end of array.
@@ -162,12 +164,12 @@ func createPrefixCmd() *cobra.Command {
 		Aliases: []string{"p"},
 		Short:   "yq p [--inplace/-i] [--doc/-d index] sample.yaml a.b.c",
 		Example: `
-yq prefix things.yaml a.b.c
+yq prefix things.yaml 'a.b.c'
-yq prefix --inplace things.yaml a.b.c
+yq prefix --inplace things.yaml 'a.b.c'
-yq prefix --inplace -- things.yaml --key-starting-with-dash
+yq prefix --inplace -- things.yaml '--key-starting-with-dash' # need to use '--' to stop processing arguments as flags
-yq p -i things.yaml a.b.c
+yq p -i things.yaml 'a.b.c'
-yq p --doc 2 things.yaml a.b.d
+yq p --doc 2 things.yaml 'a.b.d'
-yq p -d2 things.yaml a.b.d
+yq p -d2 things.yaml 'a.b.d'
       `,
 		Long: `Prefixes w.r.t to the yaml file at the given path.
 Outputs to STDOUT unless the inplace flag is used, in which case the file is updated instead.
@@ -181,19 +183,19 @@ Outputs to STDOUT unless the inplace flag is used, in which case the file is upd
 
 func createDeleteCmd() *cobra.Command {
 	var cmdDelete = &cobra.Command{
-		Use:     "delete [yaml_file] [path]",
+		Use:     "delete [yaml_file] [path_expression]",
 		Aliases: []string{"d"},
 		Short:   "yq d [--inplace/-i] [--doc/-d index] sample.yaml a.b.c",
 		Example: `
-yq delete things.yaml a.b.c
+yq delete things.yaml 'a.b.c'
-yq delete things.yaml a.*.c
+yq delete things.yaml 'a.*.c'
-yq delete things.yaml a.**
+yq delete things.yaml 'a.(child.subchild==co*).c'
-yq delete --inplace things.yaml a.b.c
+yq delete things.yaml 'a.**'
-yq delete --inplace -- things.yaml --key-starting-with-dash
+yq delete --inplace things.yaml 'a.b.c'
-yq d -i things.yaml a.b.c
+yq delete --inplace -- things.yaml '--key-starting-with-dash' # need to use '--' to stop processing arguments as flags
-yq d things.yaml a.b.c
+yq d -i things.yaml 'a.b.c'
 	`,
-		Long: `Deletes the given path from the YAML file.
+		Long: `Deletes the nodes matching the given path expression from the YAML file.
 Outputs to STDOUT unless the inplace flag is used, in which case the file is updated instead.
 `,
 		RunE: deleteProperty,
@@ -209,10 +211,10 @@ func createNewCmd() *cobra.Command {
 		Aliases: []string{"n"},
 		Short:   "yq n [--script/-s script_file] a.b.c newValue",
 		Example: `
-yq new a.b.c cat
+yq new 'a.b.c' cat
-yq n a.b.c cat
+yq n 'a.b.c' --tag '!!str' true # force 'true' to be interpreted as a string instead of bool
-yq n a.b[+] --tag '!!str' true
+yq n 'a.b[+]' cat
-yq n -- --key-starting-with-dash cat
+yq n -- '--key-starting-with-dash' cat # need to use '--' to stop processing arguments as flags
 yq n --script create_script.yaml
       `,
 		Long: `Creates a new yaml w.r.t the given path and value.