Updated transparent-json documentation and examples per comments from…

… Saašha Metsärantala
ndw · Feb 20, 2012 · a115352 · a115352
1 parent 27a3184
commit a115352
Show file tree

Hide file tree

Showing 8 changed files with 55 additions and 19 deletions.
diff --git a/docs/src/examples/object.json b/docs/src/examples/object.json
@@ -1,15 +1,18 @@
 {
   "id": "1234",
   "": "empty string",
-  "foo$bar": "foo$bar",
+  "foo$bar": "key contains non-name char",
-  "1foo$bar": "1foo$bar",
+  "1foo$bar": "key starts with non-name-start char",
-  "x:html": "x:html",
+  "x:html": "key with colon",
   "array": [1,2,3,false,null],
   "bool": false,
   "isnull": null,
   "image": {
     "url": "http://example.com/image.jpg",
     "width": 500,
     "height": 500
-  }
+  },
+  "<crazy&key>": "sane value",
+  "\"double quotes\"": "dquoted key",
+  "'single quotes'": "squoted key"
 }
diff --git a/docs/src/examples/update-json.sh b/docs/src/examples/update-json.sh
@@ -0,0 +1,5 @@
+for flavor in "marklogic" "jsonx" "jxml" "calabash" "calabash-deprecated"
+do
+    echo "Converting JSON to $flavor..."
+    calabash -Xtransparent-json -Xjson-flavor=$flavor -oresult=../results/json-$flavor.xml json.xpl
+done
diff --git a/docs/src/extensions.xml b/docs/src/extensions.xml
@@ -263,6 +263,9 @@ supported for this format.</para>
 </varlistentry>
 </variablelist>
 
+<para>Note that key values in a JSON object are considered unordered. There's
+no way to preserve the order of keys when switching between representations.</para>
+
 <para>The transparent JSON extension can be enabled in three ways:</para>
 
 <orderedlist>
@@ -297,6 +300,10 @@ configuration option.</para>
 </listitem>
 </orderedlist>
 
+<para>The flavors are “<literal>marklogic</literal>”, “<literal>jsonx</literal>”,
+“<literal>jxml</literal>”, “<literal>calabash</literal>”, and
+“<literal>calabash-deprecated</literal>”.</para>
+
 <para>A pipeline can determine the current flavor with the
 <function>p:system-property</function> function using the argument
 <literal>cx:json-flavor</literal>.</para>

diff --git a/docs/src/results/json-calabash-deprecated.xml b/docs/src/results/json-calabash-deprecated.xml
@@ -1,10 +1,13 @@
 <json type="object">
+   <pair name="&lt;crazy&amp;key&gt;" type="string">sane value</pair>
    <pair name="" type="string">empty string</pair>
    <pair name="id" type="string">1234</pair>
-   <pair name="1foo$bar" type="string">1foo$bar</pair>
+   <pair name="'single quotes'" type="string">squoted key</pair>
-   <pair name="x:html" type="string">x:html</pair>
+   <pair name="1foo$bar" type="string">key starts with non-name-start char</pair>
+   <pair name="x:html" type="string">key with colon</pair>
    <pair name="isnull" type="null"/>
-   <pair name="foo$bar" type="string">foo$bar</pair>
+   <pair name="foo$bar" type="string">key contains non-name char</pair>
+   <pair name="&#34;double quotes&#34;" type="string">dquoted key</pair>
    <pair name="image" type="object">
       <pair name="height" type="number">500</pair>
       <pair name="width" type="number">500</pair>

diff --git a/docs/src/results/json-calabash.xml b/docs/src/results/json-calabash.xml
@@ -1,10 +1,13 @@
 <c:json xmlns:c="http://www.w3.org/ns/xproc-step" type="object">
+   <c:pair name="&lt;crazy&amp;key&gt;" type="string">sane value</c:pair>
    <c:pair name="" type="string">empty string</c:pair>
    <c:pair name="id" type="string">1234</c:pair>
-   <c:pair name="1foo$bar" type="string">1foo$bar</c:pair>
+   <c:pair name="'single quotes'" type="string">squoted key</c:pair>
-   <c:pair name="x:html" type="string">x:html</c:pair>
+   <c:pair name="1foo$bar" type="string">key starts with non-name-start char</c:pair>
+   <c:pair name="x:html" type="string">key with colon</c:pair>
    <c:pair name="isnull" type="null"/>
-   <c:pair name="foo$bar" type="string">foo$bar</c:pair>
+   <c:pair name="foo$bar" type="string">key contains non-name char</c:pair>
+   <c:pair name="&#34;double quotes&#34;" type="string">dquoted key</c:pair>
    <c:pair name="image" type="object">
       <c:pair name="height" type="number">500</c:pair>
       <c:pair name="width" type="number">500</c:pair>

diff --git a/docs/src/results/json-jsonx.xml b/docs/src/results/json-jsonx.xml
@@ -1,10 +1,13 @@
 <j:object xmlns:j="http://www.ibm.com/xmlns/prod/2009/jsonx">
+   <j:string name="&lt;crazy&amp;key&gt;">sane value</j:string>
    <j:string name="">empty string</j:string>
    <j:string name="id">1234</j:string>
-   <j:string name="1foo$bar">1foo$bar</j:string>
+   <j:string name="'single quotes'">squoted key</j:string>
-   <j:string name="x:html">x:html</j:string>
+   <j:string name="1foo$bar">key starts with non-name-start char</j:string>
+   <j:string name="x:html">key with colon</j:string>
    <j:null name="isnull"/>
-   <j:string name="foo$bar">foo$bar</j:string>
+   <j:string name="foo$bar">key contains non-name char</j:string>
+   <j:string name="&#34;double quotes&#34;">dquoted key</j:string>
    <j:object name="image">
       <j:number name="height">500</j:number>
       <j:number name="width">500</j:number>

diff --git a/docs/src/results/json-jxml.xml b/docs/src/results/json-jxml.xml
@@ -1,21 +1,30 @@
 <j:object xmlns:j="http://www.xmlsh.org/jxml">
+   <j:member name="&lt;crazy&amp;key&gt;">
+      <j:string>sane value</j:string>
+   </j:member>
    <j:member name="">
       <j:string>empty string</j:string>
    </j:member>
    <j:member name="id">
       <j:string>1234</j:string>
    </j:member>
+   <j:member name="'single quotes'">
+      <j:string>squoted key</j:string>
+   </j:member>
    <j:member name="1foo$bar">
-      <j:string>1foo$bar</j:string>
+      <j:string>key starts with non-name-start char</j:string>
    </j:member>
    <j:member name="x:html">
-      <j:string>x:html</j:string>
+      <j:string>key with colon</j:string>
    </j:member>
    <j:member name="isnull">
       <j:null/>
    </j:member>
    <j:member name="foo$bar">
-      <j:string>foo$bar</j:string>
+      <j:string>key contains non-name char</j:string>
+   </j:member>
+   <j:member name="&#34;double quotes&#34;">
+      <j:string>dquoted key</j:string>
    </j:member>
    <j:member name="image">
       <j:object>

diff --git a/docs/src/results/json-marklogic.xml b/docs/src/results/json-marklogic.xml
@@ -1,10 +1,13 @@
 <j:json xmlns:j="http://marklogic.com/json" type="object">
+   <j:_003ccrazy_0026key_003e type="string">sane value</j:_003ccrazy_0026key_003e>
    <j:_ type="string">empty string</j:_>
    <j:id type="string">1234</j:id>
-   <j:_0031foo_0024bar type="string">1foo$bar</j:_0031foo_0024bar>
+   <j:_0027single_0020quotes_0027 type="string">squoted key</j:_0027single_0020quotes_0027>
-   <j:x_003ahtml type="string">x:html</j:x_003ahtml>
+   <j:_0031foo_0024bar type="string">key starts with non-name-start char</j:_0031foo_0024bar>
+   <j:x_003ahtml type="string">key with colon</j:x_003ahtml>
    <j:isnull type="null"/>
-   <j:foo_0024bar type="string">foo$bar</j:foo_0024bar>
+   <j:foo_0024bar type="string">key contains non-name char</j:foo_0024bar>
+   <j:_0022double_0020quotes_0022 type="string">dquoted key</j:_0022double_0020quotes_0022>
    <j:image type="object">
       <j:height type="number">500</j:height>
       <j:width type="number">500</j:width>