Added doco regarding values starting with hyphens

Author: Mike Farah

docs/convert/index.html

@@ -323,7 +323,7 @@
 
                   <h1>Convert</h1>
 
-                <h3 id="yaml-to-json">Yaml to Json</h3>
+                <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 be used with any command.</p>
 <p>Given a sample.yaml file of:</p>
 <pre><code class="yaml">b:
@@ -338,7 +338,7 @@ <h3 id="yaml-to-json">Yaml to Json</h3>
 <pre><code class="json">{&quot;b&quot;:{&quot;c&quot;:2}}
 </code></pre>
 
-<h3 id="json-to-yaml">Json to Yaml</h3>
+<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>
 <pre><code class="json">{&quot;a&quot;:&quot;Easy! as one two three&quot;,&quot;b&quot;:{&quot;c&quot;:2,&quot;d&quot;:[3,4]}}

docs/create/index.html

@@ -327,7 +327,7 @@ <h1>Create</h1>
 <pre><code>yaml n &lt;path&gt; &lt;new value&gt;
 </code></pre>
 
-<h3 id="creating-a-simple-yaml-file">Creating a simple yaml file</h3>
+<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">yaml n b.c cat
 </code></pre>
 
@@ -336,7 +336,7 @@ <h3 id="creating-a-simple-yaml-file">Creating a simple yaml file</h3>
   c: cat
 </code></pre>
 
-<h3 id="creating-using-a-create-script">Creating using a create script</h3>
+<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

docs/index.html

@@ -327,11 +327,11 @@
 
 
 
-                <h1 id="yaml">yaml</h1>
+                <h1 id="yaml">yaml<a class="headerlink" href="#yaml" title="Permanent link">&para;</a></h1>
 <p>yaml is a lightweight and portable command-line YAML processor</p>
 <p>The aim of the project is to be the <a href="https://github.com/stedolan/jq">jq</a> or sed of yaml files.</p>
-<h3 id="download-latest-binary"><a href="https://github.com/mikefarah/yaml/releases/latest">download latest binary</a></h3>
-<h3 id="get-the-source">get the source</h3>
+<h3 id="download-latest-binary"><a href="https://github.com/mikefarah/yaml/releases/latest">download latest binary</a><a class="headerlink" href="#download-latest-binary" title="Permanent link">&para;</a></h3>
+<h3 id="get-the-source">get the source<a class="headerlink" href="#get-the-source" title="Permanent link">&para;</a></h3>
 <pre><code class="bash">go get github.com/mikefarah/yaml
 </code></pre>
 

docs/mkdocs/search_index.json

@@ -57,7 +57,7 @@
         }, 
         {
             "location": "/write/", 
-            "text": "yaml w \nyaml_file|json_file\n \npath\n \nnew value\n\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\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyaml 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\n\ncat sample.yaml | yaml w - b.c blah\n\n\n\n\nAdding new fields\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\nyaml w sample.yaml b.d[0] \nnew thing\n\n\n\n\n\nwill output:\n\n\nb:\n  c: cat\n  d:\n    - new thing\n\n\n\n\nUpdating files in-place\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyaml 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\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\nyaml 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 | yaml w -s - sample.yaml", 
+            "text": "yaml w \nyaml_file|json_file\n \npath\n \nnew value\n\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\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyaml 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\n\ncat sample.yaml | yaml w - b.c blah\n\n\n\n\nAdding new fields\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\nyaml w sample.yaml b.d[0] \nnew thing\n\n\n\n\n\nwill output:\n\n\nb:\n  c: cat\n  d:\n    - new thing\n\n\n\n\nUpdating files in-place\n\n\nGiven a sample.yaml file of:\n\n\nb:\n  c: 2\n\n\n\n\nthen\n\n\nyaml 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\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\nyaml 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 | yaml w -s - sample.yaml\n\n\n\n\nValues starting with a hyphen (or dash)\n\n\nThis needs a bit of trickery so that it won't try to parse the value as a CLI option. Specifically you will need to wrap the value with a single and double quotes:\n\n\nyaml w my.path '\n-Dvalue\n'\n\n\n\n\nwill output\n\n\nmy:\n  path: -Dvalue", 
             "title": "Write/Update"
         }, 
         {
@@ -85,6 +85,11 @@
             "text": "Given a sample.yaml file of:  b:\n  c: 2\n  e:\n    - name: Billy Bob  and a script update_instructions.yaml of:  b.c: 3\nb.e[0].name: Howdy Partner  then  yaml w -s update_instructions.yaml sample.yaml  will output:  b:\n  c: 3\n  e:\n    - name: Howdy Partner  And, of course, you can pipe the instructions in using '-':  cat update_instructions.yaml | yaml w -s - sample.yaml", 
             "title": "Updating multiple values with a script"
         }, 
+        {
+            "location": "/write/#values-starting-with-a-hyphen-or-dash", 
+            "text": "This needs a bit of trickery so that it won't try to parse the value as a CLI option. Specifically you will need to wrap the value with a single and double quotes:  yaml w my.path ' -Dvalue '  will output  my:\n  path: -Dvalue", 
+            "title": "Values starting with a hyphen (or dash)"
+        }, 
         {
             "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\nyaml n \npath\n \nnew value\n\n\n\n\n\nCreating a simple yaml file\n\n\nyaml 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\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\nyaml 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 | yaml n -s -", 

docs/read/index.html

@@ -383,7 +383,7 @@ <h1>Read</h1>
 </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>
-<h3 id="basic">Basic</h3>
+<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:
   c: 2
@@ -394,13 +394,13 @@ <h3 id="basic">Basic</h3>
 </code></pre>
 
 <p>will output the value of '2'.</p>
-<h3 id="from-stdin">From Stdin</h3>
+<h3 id="from-stdin">From Stdin<a class="headerlink" href="#from-stdin" title="Permanent link">&para;</a></h3>
 <p>Given a sample.yaml file of:</p>
 <pre><code class="bash">cat sample.yaml | yaml r - b.c
 </code></pre>
 
 <p>will output the value of '2'.</p>
-<h3 id="splat">Splat</h3>
+<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:
@@ -419,7 +419,7 @@ <h3 id="splat">Splat</h3>
 - apples
 </code></pre>
 
-<h3 id="handling-in-the-yaml-key">Handling '.' in the yaml key</h3>
+<h3 id="handling-in-the-yaml-key">Handling '.' in the yaml key<a class="headerlink" href="#handling-in-the-yaml-key" title="Permanent link">&para;</a></h3>
 <p>Given a sample.yaml file of:</p>
 <pre><code class="yaml">b.x:
   c: 2
@@ -430,7 +430,7 @@ <h3 id="handling-in-the-yaml-key">Handling '.' in the yaml key</h3>
 </code></pre>
 
 <p>will output the value of '2'.</p>
-<h3 id="arrays">Arrays</h3>
+<h3 id="arrays">Arrays<a class="headerlink" href="#arrays" title="Permanent link">&para;</a></h3>
 <p>You can give an index to access a specific element:
 e.g.: given a sample file of</p>
 <pre><code class="yaml">b:
@@ -446,7 +446,7 @@ <h3 id="arrays">Arrays</h3>
 </code></pre>
 
 <p>will output 'sam'</p>
-<h3 id="array-splat">Array Splat</h3>
+<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:
   e:

docs/sitemap.xml

@@ -4,39 +4,39 @@
 
     <url>
      <loc>/</loc>
-     <lastmod>2017-04-19</lastmod>
+     <lastmod>2017-05-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
 
 
     <url>
      <loc>/read/</loc>
-     <lastmod>2017-04-19</lastmod>
+     <lastmod>2017-05-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
 
 
     <url>
      <loc>/write/</loc>
-     <lastmod>2017-04-19</lastmod>
+     <lastmod>2017-05-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
 
 
     <url>
      <loc>/create/</loc>
-     <lastmod>2017-04-19</lastmod>
+     <lastmod>2017-05-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 
 
 
     <url>
      <loc>/convert/</loc>
-     <lastmod>2017-04-19</lastmod>
+     <lastmod>2017-05-03</lastmod>
      <changefreq>daily</changefreq>
     </url>
 

docs/write/index.html

@@ -262,6 +262,13 @@
 
 </li>
 
+        <li class="md-nav__item">
+  <a href="#values-starting-with-a-hyphen-or-dash" title="Values starting with a hyphen (or dash)" class="md-nav__link">
+    Values starting with a hyphen (or dash)
+  </a>
+  
+</li>
+      
 
 
     </ul>
@@ -348,6 +355,13 @@
 
 </li>
 
+        <li class="md-nav__item">
+  <a href="#values-starting-with-a-hyphen-or-dash" title="Values starting with a hyphen (or dash)" class="md-nav__link">
+    Values starting with a hyphen (or dash)
+  </a>
+  
+</li>
+      
 
 
     </ul>
@@ -369,7 +383,7 @@ <h1>Write/Update</h1>
 </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>
-<h3 id="to-stdout">To Stdout</h3>
+<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
@@ -384,11 +398,11 @@ <h3 id="to-stdout">To Stdout</h3>
   c: cat
 </code></pre>
 
-<h3 id="from-stdin">From STDIN</h3>
+<h3 id="from-stdin">From STDIN<a class="headerlink" href="#from-stdin" title="Permanent link">&para;</a></h3>
 <pre><code class="bash">cat sample.yaml | yaml w - b.c blah
 </code></pre>
 
-<h3 id="adding-new-fields">Adding new fields</h3>
+<h3 id="adding-new-fields">Adding new fields<a class="headerlink" href="#adding-new-fields" title="Permanent link">&para;</a></h3>
 <p>Any missing fields in the path will be created on the fly.</p>
 <p>Given a sample.yaml file of:</p>
 <pre><code class="yaml">b:
@@ -406,7 +420,7 @@ <h3 id="adding-new-fields">Adding new fields</h3>
     - new thing
 </code></pre>
 
-<h3 id="updating-files-in-place">Updating files in-place</h3>
+<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:
   c: 2
@@ -417,7 +431,7 @@ <h3 id="updating-files-in-place">Updating files in-place</h3>
 </code></pre>
 
 <p>will update the sample.yaml file so that the value of 'c' is cat.</p>
-<h3 id="updating-multiple-values-with-a-script">Updating multiple values with a script</h3>
+<h3 id="updating-multiple-values-with-a-script">Updating multiple values with a script<a class="headerlink" href="#updating-multiple-values-with-a-script" title="Permanent link">&para;</a></h3>
 <p>Given a sample.yaml file of:</p>
 <pre><code class="yaml">b:
   c: 2
@@ -444,6 +458,16 @@ <h3 id="updating-multiple-values-with-a-script">Updating multiple values with a
 <p>And, of course, you can pipe the instructions in using '-':</p>
 <pre><code class="bash">cat update_instructions.yaml | yaml w -s - sample.yaml
 </code></pre>
+
+<h3 id="values-starting-with-a-hyphen-or-dash">Values starting with a hyphen (or dash)<a class="headerlink" href="#values-starting-with-a-hyphen-or-dash" title="Permanent link">&para;</a></h3>
+<p>This needs a bit of trickery so that it won't try to parse the value as a CLI option. Specifically you will need to wrap the value with a single and double quotes:</p>
+<pre><code>yaml w my.path '&quot;-Dvalue&quot;'
+</code></pre>
+
+<p>will output</p>
+<pre><code class="yaml">my:
+  path: -Dvalue
+</code></pre>
 
 
 

mkdocs/write.md

@@ -86,4 +86,17 @@ b:
 And, of course, you can pipe the instructions in using '-':
 ```bash
 cat update_instructions.yaml | yaml w -s - sample.yaml
-```
+```
+
+### Values starting with a hyphen (or dash)
+This needs a bit of trickery so that it won't try to parse the value as a CLI option. Specifically you will need to wrap the value with a single and double quotes:
+
+```
+yaml w my.path '"-Dvalue"'
+```
+
+will output
+```yaml
+my:
+  path: -Dvalue
+```