Permalink
Browse files

Added in some documentation for the json.xqy module.

  • Loading branch information...
1 parent 51780d2 commit d28bee313cd87d79de8827c7992dcb1f8d05171d @ryangrimm committed Jun 28, 2011
Showing with 143 additions and 43 deletions.
  1. +5 −1 README.markdown
  2. +138 −42 data/lib/json.xqy
View
@@ -62,9 +62,13 @@ change the URL structure or add in more rules if need be there.
### Files relevant to the end user
- data/lib/rewriter.xqy - A URL rewriter for the REST calls
- config/endpoints.xqy - Configuration for the REST endpoints
- - data/lib/json.xqy - Has two public functions:
+ - data/lib/json.xqy - Library module for handling JSON, see comments inside file for details on each function
- jsonToXML - parses a JSON string into XML that can be stored in MarkLogic
- xmlToJSON - parses the generated XML into a JSON string
+ - document - constructs a JSON document
+ - object - constructs a JSON object
+ - array - constructs a JSON array
+ - null - constructs a JSON null
- data/lib/json-query.xqy - Tinkering with ways to query the stored JSON
## REST Capabilities
View
@@ -19,6 +19,23 @@ xquery version "1.0-ml";
module namespace json="http://marklogic.com/json";
declare default function namespace "http://www.w3.org/2005/xpath-functions";
+(:
+ Converts a JSON string into an XML document that is highly indexable by
+ MarkLogic. The XML that is generated is intended to be treated like a black
+ box. In other words, it isn't something that you're encouraged to use
+ directly at this time. However, for those that are brave it is fairly
+ resonable to understand.
+
+ $json - A JSON string. This string can contain a number, a string, a
+ boolean value, an array or an object.
+
+ Examples:
+ json:jsonToXML('3.14159')
+ json:jsonToXML('"Hello World')
+ json:jsonToXML('true')
+ json:jsonToXML('[1, 2, 3, 4]')
+ json:jsonToXML('{"foo": "bar"}')
+:)
declare function json:jsonToXML(
$json as xs:string
) as element(json)
@@ -32,6 +49,50 @@ declare function json:jsonToXML(
return <json>{ $value/(@type, @boolean), $value/node() }</json>
};
+(:
+ Converts an specially formatted XML document into a JSON string. It is HIGHLY
+ important to understand that this function does not accept arbitrary XML.
+ It is designed to accept the XML that is generated by the functions in this
+ module.
+
+ $element - A XML element that has been generated by the functions in this module
+
+ Examples:
+ json:xmlToJSON(json:array((1, 2, 3, 4))) -> "[1, 2, 3, 4]"
+:)
+declare function json:xmlToJSON(
+ $element as element()
+) as xs:string
+{
+ fn:string-join(json:processElement($element), "")
+};
+
+(:
+ Constructs a JSON document for storage in MarkLogic.
+
+ $value - A JSON item (see below for a description of what a JSON item can be).
+
+ Examples:
+ json:document(3.14159)
+ json:document("Hello World")
+ json:document(true())
+ json:document(json:array((1, 2, 3, 4)))
+ json:document(json:object(("foo", "bar")))
+
+
+ A word on JSON items.
+ The various functions in this module that accept JSON items (json:document,
+ json:object and json:array) examine the type of the passed in item and
+ convert it to the appropriate JSON type.
+
+ Here's how the casting works, most are obvious:
+ • XQuery string -> JSON string
+ • XQuery boolean -> JSON boolean
+ • XQuery integer or decimal -> JSON number
+ • Every other XQuery type -> JSON string
+
+ A JSON item may also be the result return value of json:array or json:object.
+:)
declare function json:document(
$value as item()
) as element(json)
@@ -41,25 +102,21 @@ declare function json:document(
}</json>
};
-declare function json:o(
-) as element(item)
-{
- json:object(())
-};
+(:
+ Constructs a JSON object in an XML format for use in json:document,
+ json:array or json:xmlToJSON. The return value is not a string but a JSON
+ item. For more information on JSON items, see the note in json:document.
-declare function json:object(
-) as element(item)
-{
- json:object(())
-};
+ There are also a convenience function json:o.
-declare function json:o(
- $keyValues as item()*
-) as element(item)
-{
- json:object($keyValues)
-};
+ $keyValues - A sequence of alternating object keys and values. The keys
+ must be strings and the values can be JSON items. Keys must be unique.
+ Examples:
+ json:object(("foo", "bar")) -> {"foo": "bar"}
+ json:object(("foo", json:array((1, 2, 3, 4)))) - > {"foo": [1, 2, 3, 4]}
+ json:object(("foo", true(), "bar", false())) -> {"foo": true, "bar": false}
+:)
declare function json:object(
$keyValues as item()*
) as element(item)
@@ -87,25 +144,39 @@ declare function json:object(
}</item>
};
-declare function json:a(
+declare function json:o(
+ $keyValues as item()*
) as element(item)
{
- json:array(())
+ json:object($keyValues)
};
-declare function json:array(
+declare function json:object(
) as element(item)
{
- json:array(())
+ json:object(())
};
-declare function json:a(
- $items as item()*
+declare function json:o(
) as element(item)
{
- json:array($items)
+ json:object(())
};
+(:
+ Constructs a JSON array in an XML format for use in json:document,
+ json:object or json:xmlToJSON. The return value is not a string but a JSON
+ item. For more information on JSON items, see the note in json:document.
+
+ There are also a convenience function json:a.
+
+ $items - A sequence of JSON items to include in the array.
+
+ Examples:
+ json:array((1, 2, 3, 4)) -> [1, 2, 3, 4]
+ json:array((true(), false(), "foo")) -> [true, false, "foo"]
+ json:array((json:object(("foo", "bar")), json:object(("baz", "yaz")))) -> [{"foo": "bar"}, {"baz": "yaz"}]
+:)
declare function json:array(
$items as item()*
) as element(item)
@@ -116,12 +187,44 @@ declare function json:array(
}</item>
};
+declare function json:a(
+ $items as item()*
+) as element(item)
+{
+ json:array($items)
+};
+
+declare function json:array(
+) as element(item)
+{
+ json:array(())
+};
+
+declare function json:a(
+) as element(item)
+{
+ json:array(())
+};
+
+(:
+ Because XQuery doesn't have a stict null value, this function allows us to
+ construct a JSON null. This can be useful if you need objects or arrays
+ with null values.
+
+ Examples:
+ json:array((1, 2, json:null(), 4)) -> [1, 2, null, 4]
+ json:object(("foo", json:null())) -> {"foo": null}
+:)
declare function json:null(
) as element(item)
{
<item type="null"/>
};
+
+(:
+ Private functions
+:)
declare private function json:untypedToJSONType(
$value as item()?
) as element(item)
@@ -144,6 +247,18 @@ declare private function json:untypedToJSONType(
}</item>
};
+declare private function json:processElement(
+ $element as element()
+) as xs:string*
+{
+ if($element/@type = "object") then json:outputObject($element)
+ else if($element/@type = "array") then json:outputArray($element)
+ else if($element/@type = "null") then "null"
+ else if(fn:exists($element/@boolean)) then xs:string($element/@boolean)
+ else if($element/@type = "number") then xs:string($element)
+ else ('"', json:escapeJSONString($element), '"')
+};
+
declare private function json:parseValue(
$tokens as element(token)*,
$position as xs:integer
@@ -342,25 +457,6 @@ declare private function json:createToken(
-declare function json:xmlToJSON(
- $element as element()
-) as xs:string
-{
- fn:string-join(json:processElement($element), "")
-};
-
-declare private function json:processElement(
- $element as element()
-) as xs:string*
-{
- if($element/@type = "object") then json:outputObject($element)
- else if($element/@type = "array") then json:outputArray($element)
- else if($element/@type = "null") then "null"
- else if(fn:exists($element/@boolean)) then xs:string($element/@boolean)
- else if($element/@type = "number") then xs:string($element)
- else ('"', json:escapeJSONString($element), '"')
-};
-
declare private function json:outputObject(
$element as element()
) as xs:string*

0 comments on commit d28bee3

Please sign in to comment.