Updated docs to explicity put array paths in quotes

This commit is contained in:
Mike Farah 2018-02-28 08:07:34 +11:00
parent 92ce195424
commit 8f15dba812
8 changed files with 42 additions and 29 deletions

View File

@ -414,13 +414,14 @@ b.e[0].name: Howdy Partner
foo.bar: 7
</code></pre>
<pre><code class="bash">yaml r sample.yaml b[foo.bar]
<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
<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>

View File

@ -492,10 +492,11 @@ e.g.: given a sample file of</p>
</code></pre>
<p>then</p>
<pre><code>yq r sample.yaml b.e[1].name
<pre><code>yq r sample.yaml 'b.e[1].name'
</code></pre>
<p>will output 'sam'</p>
<p>Note that the path is in quotes to avoid the square brackets being interpreted by your shell.</p>
<h3 id="array-splat">Array Splat<a class="headerlink" href="#array-splat" title="Permanent link">&para;</a></h3>
<p>e.g.: given a sample file of</p>
<pre><code class="yaml">b:
@ -507,7 +508,7 @@ e.g.: given a sample file of</p>
</code></pre>
<p>then</p>
<pre><code>yq r sample.yaml b.e[*].name
<pre><code>yq r sample.yaml 'b.e[*].name'
</code></pre>
<p>will output:</p>
@ -515,19 +516,21 @@ e.g.: given a sample file of</p>
- sam
</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]
<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
<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>

View File

@ -17,7 +17,7 @@
},
{
"location": "/read/",
"text": "yq r <yaml_file|json_file> <path>\n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nBasic\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyq r sample.yaml b.c\n\n\n\n\nwill output the value of '2'.\n\n\nFrom Stdin\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\ncat sample.yaml | yq r - b.c\n\n\n\n\nwill output the value of '2'.\n\n\nSplat\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\n---\nbob:\n item1:\n cats: bananas\n item2:\n cats: apples\n\n\n\n\nthen\n\n\nyq r sample.yaml bob.*.cats\n\n\n\n\nwill output\n\n\n- bananas\n- apples\n\n\n\n\nHandling '.' in the yaml key\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb.x:\n c: 2\n\n\n\n\nthen\n\n\nyq r sample.yaml \\\"b.x\\\".c\n\n\n\n\nwill output the value of '2'.\n\n\nArrays\n\u00b6\n\n\nYou can give an index to access a specific element:\ne.g.: given a sample file of\n\n\nb:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4\n\n\n\n\nthen\n\n\nyq r sample.yaml b.e[1].name\n\n\n\n\nwill output 'sam'\n\n\nArray Splat\n\u00b6\n\n\ne.g.: given a sample file of\n\n\nb:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4\n\n\n\n\nthen\n\n\nyq r sample.yaml b.e[*].name\n\n\n\n\nwill output:\n\n\n- fred\n- sam\n\n\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n foo.bar: 7\n\n\n\n\nyaml r sample.yaml b[foo.bar]\n\n\n\n\nyaml w sample.yaml b[foo.bar] 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.",
"text": "yq r <yaml_file|json_file> <path>\n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nBasic\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyq r sample.yaml b.c\n\n\n\n\nwill output the value of '2'.\n\n\nFrom Stdin\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\ncat sample.yaml | yq r - b.c\n\n\n\n\nwill output the value of '2'.\n\n\nSplat\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\n---\nbob:\n item1:\n cats: bananas\n item2:\n cats: apples\n\n\n\n\nthen\n\n\nyq r sample.yaml bob.*.cats\n\n\n\n\nwill output\n\n\n- bananas\n- apples\n\n\n\n\nHandling '.' in the yaml key\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb.x:\n c: 2\n\n\n\n\nthen\n\n\nyq r sample.yaml \\\"b.x\\\".c\n\n\n\n\nwill output the value of '2'.\n\n\nArrays\n\u00b6\n\n\nYou can give an index to access a specific element:\ne.g.: given a sample file of\n\n\nb:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4\n\n\n\n\nthen\n\n\nyq r sample.yaml 'b.e[1].name'\n\n\n\n\nwill output 'sam'\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.\n\n\nArray Splat\n\u00b6\n\n\ne.g.: given a sample file of\n\n\nb:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4\n\n\n\n\nthen\n\n\nyq r sample.yaml 'b.e[*].name'\n\n\n\n\nwill output:\n\n\n- fred\n- sam\n\n\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n foo.bar: 7\n\n\n\n\nyaml r sample.yaml 'b[foo.bar]'\n\n\n\n\nyaml w sample.yaml 'b[foo.bar]' 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.",
"title": "Read"
},
{
@ -42,22 +42,22 @@
},
{
"location": "/read/#arrays",
"text": "You can give an index to access a specific element:\ne.g.: given a sample file of b:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4 then yq r sample.yaml b.e[1].name will output 'sam'",
"text": "You can give an index to access a specific element:\ne.g.: given a sample file of b:\n e:\n - name: fred\n value: 3\n - name: sam\n 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.",
"title": "Arrays"
},
{
"location": "/read/#array-splat",
"text": "e.g.: given a sample file of b:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4 then yq r sample.yaml b.e[*].name will output: - fred\n- sam",
"text": "e.g.: given a sample file of b:\n e:\n - name: fred\n value: 3\n - name: sam\n value: 4 then yq r sample.yaml 'b.e[*].name' will output: - fred\n- sam Note that the path is in quotes to avoid the square brackets being interpreted by your shell.",
"title": "Array Splat"
},
{
"location": "/read/#keys-with-dots",
"text": "When specifying a key that has a dot use key lookup indicator. b:\n foo.bar: 7 yaml r sample.yaml b[foo.bar] yaml w sample.yaml b[foo.bar] 9 Any valid yaml key can be specified as part of a key lookup.",
"text": "When specifying a key that has a dot use key lookup indicator. b:\n foo.bar: 7 yaml r sample.yaml 'b[foo.bar]' 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.",
"title": "Keys with dots"
},
{
"location": "/write/",
"text": "yq w <yaml_file|json_file> <path> <new value>\n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nTo Stdout\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyq w sample.yaml b.c cat\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n\n\n\n\nFrom STDIN\n\u00b6\n\n\ncat sample.yaml | yq w - b.c blah\n\n\n\n\nAdding new fields\n\u00b6\n\n\nAny missing fields in the path will be created on the fly.\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyq w sample.yaml b.d[0] \"new thing\"\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n d:\n - new thing\n\n\n\n\nAppending value to an array field\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n d:\n - new thing\n - foo thing\n\n\n\n\nthen\n\n\nyq w sample.yaml b.d[+] \"bar thing\"\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n d:\n - new thing\n - foo thing\n - bar thing\n\n\n\n\nUpdating files in-place\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyq w -i sample.yaml b.c cat\n\n\n\n\nwill update the sample.yaml file so that the value of 'c' is cat.\n\n\nUpdating multiple values with a script\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n e:\n - name: Billy Bob\n\n\n\n\nand a script update_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyq w -s update_instructions.yaml sample.yaml\n\n\n\n\nwill output:\n\n\nb:\n c: 3\n e:\n - name: Howdy Partner\n\n\n\n\nAnd, of course, you can pipe the instructions in using '-':\n\n\ncat update_instructions.yaml | yq w -s - sample.yaml\n\n\n\n\nValues starting with a hyphen (or dash)\n\u00b6\n\n\nThe flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags:\n\n\nyq w -- my.path -3\n\n\n\n\nwill output\n\n\nmy:\n path: -3\n\n\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n foo.bar: 7\n\n\n\n\nyaml r sample.yaml b[foo.bar]\n\n\n\n\nyaml w sample.yaml b[foo.bar] 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.",
"text": "yq w <yaml_file|json_file> <path> <new value>\n\n\n\n\nThis command can take a json file as input too, and will output yaml unless specified to export as json (-j)\n\n\nTo Stdout\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyq w sample.yaml b.c cat\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n\n\n\n\nFrom STDIN\n\u00b6\n\n\ncat sample.yaml | yq w - b.c blah\n\n\n\n\nAdding new fields\n\u00b6\n\n\nAny missing fields in the path will be created on the fly.\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyq w sample.yaml b.d[0] \"new thing\"\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n d:\n - new thing\n\n\n\n\nAppending value to an array field\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n d:\n - new thing\n - foo thing\n\n\n\n\nthen\n\n\nyq w sample.yaml \"b.d[+]\" \"bar thing\"\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n d:\n - new thing\n - foo thing\n - bar thing\n\n\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.\n\n\nUpdating files in-place\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n\n\n\n\nthen\n\n\nyq w -i sample.yaml b.c cat\n\n\n\n\nwill update the sample.yaml file so that the value of 'c' is cat.\n\n\nUpdating multiple values with a script\n\u00b6\n\n\nGiven a sample.yaml file of:\n\n\nb:\n c: 2\n e:\n - name: Billy Bob\n\n\n\n\nand a script update_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyq w -s update_instructions.yaml sample.yaml\n\n\n\n\nwill output:\n\n\nb:\n c: 3\n e:\n - name: Howdy Partner\n\n\n\n\nAnd, of course, you can pipe the instructions in using '-':\n\n\ncat update_instructions.yaml | yq w -s - sample.yaml\n\n\n\n\nValues starting with a hyphen (or dash)\n\u00b6\n\n\nThe flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags:\n\n\nyq w -- my.path -3\n\n\n\n\nwill output\n\n\nmy:\n path: -3\n\n\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n foo.bar: 7\n\n\n\n\nyaml r sample.yaml 'b[foo.bar]'\n\n\n\n\nyaml w sample.yaml 'b[foo.bar]' 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.",
"title": "Write/Update"
},
{
@ -77,7 +77,7 @@
},
{
"location": "/write/#appending-value-to-an-array-field",
"text": "Given a sample.yaml file of: b:\n c: 2\n d:\n - new thing\n - foo thing then yq w sample.yaml b.d[+] \"bar thing\" will output: b:\n c: cat\n d:\n - new thing\n - foo thing\n - bar thing",
"text": "Given a sample.yaml file of: b:\n c: 2\n d:\n - new thing\n - foo thing then yq w sample.yaml \"b.d[+]\" \"bar thing\" will output: b:\n c: cat\n d:\n - new thing\n - foo thing\n - bar thing Note that the path is in quotes to avoid the square brackets being interpreted by your shell.",
"title": "Appending value to an array field"
},
{
@ -97,12 +97,12 @@
},
{
"location": "/write/#keys-with-dots",
"text": "When specifying a key that has a dot use key lookup indicator. b:\n foo.bar: 7 yaml r sample.yaml b[foo.bar] yaml w sample.yaml b[foo.bar] 9 Any valid yaml key can be specified as part of a key lookup.",
"text": "When specifying a key that has a dot use key lookup indicator. b:\n foo.bar: 7 yaml r sample.yaml 'b[foo.bar]' 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.",
"title": "Keys with dots"
},
{
"location": "/create/",
"text": "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.\n\n\nyq n <path> <new value>\n\n\n\n\nCreating a simple yaml file\n\u00b6\n\n\nyq n b.c cat\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n\n\n\n\nCreating using a create script\n\u00b6\n\n\nCreate scripts follow the same format as the update scripts.\n\n\nGiven a script create_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyq n -s create_instructions.yaml\n\n\n\n\nwill output:\n\n\nb:\n c: 3\n e:\n - name: Howdy Partner\n\n\n\n\nYou can also pipe the instructions in:\n\n\ncat create_instructions.yaml | yq n -s -\n\n\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n foo.bar: 7\n\n\n\n\nyaml r sample.yaml b[foo.bar]\n\n\n\n\nyaml w sample.yaml b[foo.bar] 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.",
"text": "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.\n\n\nyq n <path> <new value>\n\n\n\n\nCreating a simple yaml file\n\u00b6\n\n\nyq n b.c cat\n\n\n\n\nwill output:\n\n\nb:\n c: cat\n\n\n\n\nCreating using a create script\n\u00b6\n\n\nCreate scripts follow the same format as the update scripts.\n\n\nGiven a script create_instructions.yaml of:\n\n\nb.c: 3\nb.e[0].name: Howdy Partner\n\n\n\n\nthen\n\n\nyq n -s create_instructions.yaml\n\n\n\n\nwill output:\n\n\nb:\n c: 3\n e:\n - name: Howdy Partner\n\n\n\n\nYou can also pipe the instructions in:\n\n\ncat create_instructions.yaml | yq n -s -\n\n\n\n\nKeys with dots\n\u00b6\n\n\nWhen specifying a key that has a dot use key lookup indicator.\n\n\nb:\n foo.bar: 7\n\n\n\n\nyaml r sample.yaml 'b[foo.bar]'\n\n\n\n\nyaml w sample.yaml 'b[foo.bar]' 9\n\n\n\n\nAny valid yaml key can be specified as part of a key lookup.\n\n\nNote that the path is in quotes to avoid the square brackets being interpreted by your shell.",
"title": "Create"
},
{
@ -117,7 +117,7 @@
},
{
"location": "/create/#keys-with-dots",
"text": "When specifying a key that has a dot use key lookup indicator. b:\n foo.bar: 7 yaml r sample.yaml b[foo.bar] yaml w sample.yaml b[foo.bar] 9 Any valid yaml key can be specified as part of a key lookup.",
"text": "When specifying a key that has a dot use key lookup indicator. b:\n foo.bar: 7 yaml r sample.yaml 'b[foo.bar]' 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.",
"title": "Keys with dots"
},
{

View File

@ -4,7 +4,7 @@
<url>
<loc>/</loc>
<lastmod>2018-02-19</lastmod>
<lastmod>2018-02-28</lastmod>
<changefreq>daily</changefreq>
</url>
@ -12,7 +12,7 @@
<url>
<loc>/read/</loc>
<lastmod>2018-02-19</lastmod>
<lastmod>2018-02-28</lastmod>
<changefreq>daily</changefreq>
</url>
@ -20,7 +20,7 @@
<url>
<loc>/write/</loc>
<lastmod>2018-02-19</lastmod>
<lastmod>2018-02-28</lastmod>
<changefreq>daily</changefreq>
</url>
@ -28,7 +28,7 @@
<url>
<loc>/create/</loc>
<lastmod>2018-02-19</lastmod>
<lastmod>2018-02-28</lastmod>
<changefreq>daily</changefreq>
</url>
@ -36,7 +36,7 @@
<url>
<loc>/convert/</loc>
<lastmod>2018-02-19</lastmod>
<lastmod>2018-02-28</lastmod>
<changefreq>daily</changefreq>
</url>
@ -44,7 +44,7 @@
<url>
<loc>/merge/</loc>
<lastmod>2018-02-19</lastmod>
<lastmod>2018-02-28</lastmod>
<changefreq>daily</changefreq>
</url>

View File

@ -494,7 +494,7 @@
</code></pre>
<p>then</p>
<pre><code class="bash">yq w sample.yaml b.d[+] &quot;bar thing&quot;
<pre><code class="bash">yq w sample.yaml &quot;b.d[+]&quot; &quot;bar thing&quot;
</code></pre>
<p>will output:</p>
@ -506,6 +506,7 @@
- bar thing
</code></pre>
<p>Note that the path is in quotes to avoid the square brackets being interpreted by your shell.</p>
<h3 id="updating-files-in-place">Updating files in-place<a class="headerlink" href="#updating-files-in-place" title="Permanent link">&para;</a></h3>
<p>Given a sample.yaml file of:</p>
<pre><code class="yaml">b:
@ -561,13 +562,14 @@ b.e[0].name: Howdy Partner
foo.bar: 7
</code></pre>
<pre><code class="bash">yaml r sample.yaml b[foo.bar]
<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
<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>

View File

@ -68,10 +68,12 @@ b:
```
then
```
yq r sample.yaml b.e[1].name
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
@ -84,12 +86,13 @@ b:
```
then
```
yq r sample.yaml b.e[*].name
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/keys_with_dots.md!}

View File

@ -7,11 +7,13 @@ b:
```
```bash
yaml r sample.yaml b[foo.bar]
yaml r sample.yaml 'b[foo.bar]'
```
```bash
yaml w sample.yaml b[foo.bar] 9
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.

View File

@ -55,7 +55,7 @@ b:
```
then
```bash
yq w sample.yaml b.d[+] "bar thing"
yq w sample.yaml "b.d[+]" "bar thing"
```
will output:
```yaml
@ -67,6 +67,8 @@ b:
- bar thing
```
Note that the path is in quotes to avoid the square brackets being interpreted by your shell.
### Updating files in-place
Given a sample.yaml file of:
```yaml