Quick Save

Author: rsdoiel

docs/jsonjoin.html

@@ -22,31 +22,52 @@
 <section>
 <h1>USAGE</h1>
 
-<h2>jsonjoin [OPTIONS] JSON_FILE_1 JSON_FILE_2</h2>
+<h2>jsonjoin [OPTIONS] JSON_FILE_1 [JSON_FILE_2 &hellip;]</h2>
 
 <h2>SYSNOPSIS</h2>
 
-<p>jsonjoin is a command line tool that takes two (or more) JSON object
-documents and combines into a new JSON object document based on
-the options chosen.</p>
+<p>jsonjoin is a command line tool that takes one (or more) JSON objects files
+and joins them to a root JSON object read from standard input (or
+file identified by -input option).  By default the resulting
+joined JSON object is written to standard out.</p>
+
+<p>The default behavior for jsonjoin is to create key/value pairs
+based on the joined JSON document names and their contents.
+This can be thought of as a branching behavior. Each additional
+file becomes a branch and its key/value pairs become leafs.
+The root JSON object is assumed to come from standard input
+but can be designated by the -input option or created by the
+-create option. Each additional file specified as a command line
+argument is then treated as a new branch.</p>
+
+<p>In addition to the branching behavior you can join JSON objects in a
+flat manner.  The flat joining process can be ether non-distructive
+adding new key/value pairs (-update option) or distructive
+overwriting key/value pairs (-overwrite option).</p>
+
+<p>Note: jsonjoin doesn&rsquo;t support a JSON array as the root JSON object.</p>
 
 <h2>OPTIONS</h2>
 
-<pre><code>-h  display help
+<pre><code>-create create an empty root object, {}
+-h  display help
 -help   display help
+-i  input filename (for root object)
+-input  input filename (for root object)
 -l  display license
 -license    display license
 -o  output filename
 -output output filename
--overwrite  copy all key/values from second object into the first
--update copy unique key/values from second object into the first
+-overwrite  copy all key/values into root object
+-update copy new key/values pairs into root object
 -v  display version
 -version    display version
 </code></pre>
 
 <h2>EXAMPLES</h2>
 
-<h3>Joining two JSON objects (maps)</h3>
+<p>Consider two JSON objects one in person.json and another
+in profile.json.</p>
 
 <p>person.json containes</p>
 
@@ -59,22 +80,44 @@ <h3>Joining two JSON objects (maps)</h3>
      &quot;email&quot;: &quot;[email protected]&quot; }
 </code></pre>
 
-<p>A simple join of person.json with profile.json</p>
+<p>A simple join of person.json with profile.json (note the
+-create option)</p>
+
+<pre><code class="language-shell">   jsonjoin -create person.json profile.json
+</code></pre>
+
+<p>would yeild and object like</p>
+
+<pre><code class="language-json">   {
+     &quot;person&quot;:  { &quot;name&quot;: &quot;Doe, Jane&quot;, &quot;email&quot;:&quot;[email protected]&quot;, 
+	 			&quot;age&quot;: 42},
+     &quot;profile&quot;: { &quot;name&quot;: &quot;Doe, Jane&quot;, &quot;bio&quot;: &quot;World renowned geophysist.&quot;, 
+                  &quot;email&quot;: &quot;[email protected]&quot; }
+   }
+</code></pre>
+
+<p>Likewise if you want to treat person.json as the root object and add
+profile.json as a branch try</p>
+
+<pre><code class="language-shell">   cat person.json | jsonjoin profile.json
+</code></pre>
+
+<p>or</p>
 
-<pre><code class="language-shell">   jsonjoin person.json profile.json
+<pre><code class="language-shell">   jsonjoin -i person.json profile.json
 </code></pre>
 
-<p>would yeild</p>
+<p>this yields an object like</p>
 
 <pre><code class="language-json">   {
-     &quot;person&quot;:  { &quot;name&quot;: &quot;Doe, Jane&quot;, &quot;email&quot;:&quot;[email protected]&quot;, &quot;age&quot;: 42},
+     &quot;name&quot;: &quot;Doe, Jane&quot;, &quot;email&quot;:&quot;[email protected]&quot;, &quot;age&quot;: 42,
      &quot;profile&quot;: { &quot;name&quot;: &quot;Doe, Jane&quot;, &quot;bio&quot;: &quot;World renowned geophysist.&quot;, 
                   &quot;email&quot;: &quot;[email protected]&quot; }
    }
 </code></pre>
 
 <p>You can modify this behavor with -update or -overwrite. Both options are
-order dependant (e.g. not associative, A update B does
+order dependant (i.e. not associative, A update B does
 not necessarily equal B update A).</p>
 
 <ul>
@@ -84,7 +127,7 @@ <h3>Joining two JSON objects (maps)</h3>
 
 <p>Running</p>
 
-<pre><code class="language-shell">    jsonjoin -update person.json profile.json
+<pre><code class="language-shell">    jsonjoin -create -update person.json profile.json
 </code></pre>
 
 <p>would yield</p>
@@ -95,7 +138,7 @@ <h3>Joining two JSON objects (maps)</h3>
 
 <p>Running</p>
 
-<pre><code class="language-shell">    jsonjoin -update profile.json person.json
+<pre><code class="language-shell">    jsonjoin -create -update profile.json person.json
 </code></pre>
 
 <p>would yield</p>
@@ -107,7 +150,7 @@ <h3>Joining two JSON objects (maps)</h3>
 
 <p>Running</p>
 
-<pre><code class="language-shell">    jsonjoin -overwrite person.json profile.json
+<pre><code class="language-shell">    jsonjoin -create -overwrite person.json profile.json
 </code></pre>
 
 <p>would yield</p>
@@ -116,7 +159,7 @@ <h3>Joining two JSON objects (maps)</h3>
      &quot;bio&quot;: &quot;World renowned geophysist.&quot; }
 </code></pre>
 
-<p>jsonjoin v0.0.12</p>
+<p>jsonjoin v0.0.13</p>
 
 </section>