Skip to content
Browse files

Fixed formatting in the README.

  • Loading branch information...
1 parent 3de0de6 commit 59ef5c000f0ecab63813cee74d6208e92b58f62f @bramstein committed
Showing with 87 additions and 76 deletions.
  1. +87 −76 README.md
View
163 README.md
@@ -10,7 +10,7 @@ XSLTJSON supports several different JSON output formats, from a compact output f
There are three options in using XSLTJSON. You can call the stylesheet from the command line, programmatically, or import it in your own stylesheets.
-The stylesheet example below would transform any node matching `my-node` to JSON . If you import XSLTJSON in your stylesheet, you have to add the JSON namespace `xmlns:json="http://json.org/"` to your stylesheet because all functions and templates are in that namespace. The `json:generate()` function takes a XML node as input, generates a JSON representation of that node and returns it as an `xs:string` . This is the only function you should call from your stylesheet.
+The stylesheet example below would transform any node matching `my-node` to JSON. If you import XSLTJSON in your stylesheet, you have to add the JSON namespace `xmlns:json="http://json.org/"` to your stylesheet because all functions and templates are in that namespace. The `json:generate()` function takes a XML node as input, generates a JSON representation of that node and returns it as an `xs:string`. This is the only function you should call from your stylesheet.
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="2.0"
@@ -23,7 +23,7 @@ The stylesheet example below would transform any node matching `my-node` to JSON
</xsl:template>
</xsl:stylesheet>
-If your stylesheet's sole purpose is to transform XML to JSON , it would be easier to use the `xml-to-json.xsl` stylesheet directly from the command line. The following line shows how to do that using [Java](http://java.sun.com/) and [Saxon](http://www.saxonica.com/) .
+If your stylesheet's sole purpose is to transform XML to JSON, it would be easier to use the `xml-to-json.xsl` stylesheet directly from the command line. The following line shows how to do that using [Java](http://java.sun.com/) and [Saxon](http://www.saxonica.com/).
java net.sf.saxon.Transform source.xml xml-to-json.xsl
@@ -31,26 +31,27 @@ You can also call the stylesheet programmatically, but this depends heavily on y
### Parameters
-There are five Boolean parameters to control the stylesheet, and all are turned off by default (set to `false()` .) You can control them from the command line, from your program or from another stylesheet. Four of the parameters are used to control the output format and are discussed in more detail in the section on [output formats](output-formats) .
-* `use-badgerfish` — Use the [BadgerFish](http://badgerfish.ning.com/) convention to output JSON *without* XML namespaces.
+There are five Boolean parameters to control the stylesheet, and all are turned off by default (set to `false()`.) You can control them from the command line, from your program or from another stylesheet. Four of the parameters are used to control the output format and are discussed in more detail in the section on [output formats](output-formats).
+
+* `use-badgerfish` — Use the [BadgerFish](http://badgerfish.ning.com/) convention to output JSON *without* XML namespaces.
* `use-rabbitfish` — Output basic JSON with an `@` to mark XML attributes.
-* `use-rayfish` — Use the [Rayfish](http://onperl.org/blog/onperl/page/rayfish) convention to output JSON *without* XML namespaces.
+* `use-rayfish` — Use the [Rayfish](http://onperl.org/blog/onperl/page/rayfish) convention to output JSON *without* XML namespaces.
* `use-namespaces` — Output XML namespaces according to the BadgerFish convention.
-* `debug` — Enable or disable the output of the temporary XML tree used to generate JSON . Note that turning this on invalidates the JSON output.
-* `jsonp` — Enable [JSONP](http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/) ; prepend the JSON output with the given string. Defaults to an empty string.
+* `debug` — Enable or disable the output of the temporary XML tree used to generate JSON. Note that turning this on invalidates the JSON output.
+* `jsonp` — Enable [JSONP](http://bob.pythonmac.org/archives/2005/12/05/remote-json-jsonp/); prepend the JSON output with the given string. Defaults to an empty string.
* `skip-root` — Enable or disable skipping the root element and returning only the child elements of the root. Disabled by default.
For example; to transform `source.xml` to BadgerFish JSON with Saxon, you would invoke the following on the command line:
java net.sf.saxon.Transform source.xml xml-to-json.xsl use-badgerfish=true()
-For other options consult the [Saxon manual](http://www.saxonica.com/documentation/index/intro.html) , or your XSLT processor's documentation.
+For other options consult the [Saxon manual](http://www.saxonica.com/documentation/index/intro.html), or your XSLT processor's documentation.
If you import the stylesheet in your own stylesheet you can override the default parameters by redefining them. So if you want to output JSON using the BadgerFish convention, you should add the following parameter definition to your stylesheet.
<xsl:param name="use-badgerfish" as="xs:boolean" select="true()"/>
-You can force the creation of an array by adding the `force-array` parameter to your XML . So instead of creating two nested objects, the following example will create an object containing an array.
+You can force the creation of an array by adding the `force-array` parameter to your XML. So instead of creating two nested objects, the following example will create an object containing an array.
<list json:force-array="true" xmlns:json="http://json.org/">
<item>one</item>
@@ -62,129 +63,139 @@ The `force-array` attribute will not be copied to the output JSON .
### Output formats
-There are four output formats in XSLTJSON, which one to use depends on your target application. If you want the most compact JSON , use the basic output. If you want to transform XML to JSON and JSON back to XML , use the [BadgerFish](http://badgerfish.ning.com/) output. If you want something in between, you could use the RabbitFish output; which is similar to the basic version, but does distinguish between elements and attributes. If you're dealing with a lot of data centric XML, you could use the highly structured Rayfish output. All four output formats ignore XML namespaces unless the `use-namespaces` parameter is set to `true()` , in which case namespaces are created according to the BadgerFish convention.
+There are four output formats in XSLTJSON, which one to use depends on your target application. If you want the most compact JSON, use the basic output. If you want to transform XML to JSON and JSON back to XML, use the [BadgerFish](http://badgerfish.ning.com/) output. If you want something in between, you could use the RabbitFish output; which is similar to the basic version, but does distinguish between elements and attributes. If you're dealing with a lot of data centric XML, you could use the highly structured Rayfish output. All four output formats ignore XML namespaces unless the `use-namespaces` parameter is set to `true()`, in which case namespaces are created according to the BadgerFish convention.
-Each format has a list of rules by which XML is transformed to JSON . The examples for these rules are all but one taken from the [BadgerFish convention website](http://badgerfish.ning.com/) to make comparing them easier.
+Each format has a list of rules by which XML is transformed to JSON. The examples for these rules are all but one taken from the [BadgerFish convention website](http://badgerfish.ning.com/) to make comparing them easier.
#### Basic output (default)
The purpose of the basic output is to generate the most compact JSON possible. This is useful if you do not require round-trips between XML and JSON or if you need to send a large amount of data over a network. It borrows the `$` syntax for text elements from the BadgerFish convention but attempts to avoid needless text-only JSON properties. It also does not distinguish between elements and attributes. The rules are:
-* Element names become object properties.
-* Text content of elements goes directly in the value of an object.
+* Element names become object properties.
+* Text content of elements goes directly in the value of an object.
+
+ <alice>bob</alice>
+
+ becomes
- <alice>bob</alice>
+ { "alice": "bob" }
-becomes
+* Nested elements become nested properties.
- { "alice": "bob" }
-* Nested elements become nested properties.
+ <alice><bob>charlie</bob><david>edgar</david></alice>
- <alice><bob>charlie</bob><david>edgar</david></alice>
+ becomes
-becomes
+ { "alice": { "bob": "charlie", "david": "edgar" } }
- { "alice": { "bob": "charlie", "david": "edgar" } }
-* Multiple elements with the same name and at the same level become array elements.
+* Multiple elements with the same name and at the same level become array elements.
- <alice><bob>charlie</bob><bob>david</bob></alice>
+ <alice><bob>charlie</bob><bob>david</bob></alice>
-becomes
+ becomes
- { "alice": { "bob": [ "charlie", "david" ] } }
-* Mixed content (element and text nodes) at the same level become array elements.
+ { "alice": { "bob": [ "charlie", "david" ] } }
- <alice>bob<charlie>david</charlie>edgar</alice>
+* Mixed content (element and text nodes) at the same level become array elements.
-becomes
+ <alice>bob<charlie>david</charlie>edgar</alice>
- { "alice": [ "bob", { "charlie": "david" }, "edgar" ] }
-* Attributes go in properties.
+ becomes
- <alice charlie="david">bob</alice>
+ { "alice": [ "bob", { "charlie": "david" }, "edgar" ] }
-becomes
+* Attributes go in properties.
- { "alice": { "charlie": "david", "$": "bob" } }
+ <alice charlie="david">bob</alice>
+
+ becomes
+
+ { "alice": { "charlie": "david", "$": "bob" } }
#### BadgerFish convention (use-badgerfish)
The BadgerFish convention was invented by [David Sklar](http://www.sklar.com/) ; more detailed information can be found on his [BadgerFish website](http://badgerfish.ning.com/). I have taken some liberties in supporting BadgerFish, for example the treatment of mixed content nodes (nodes with both text and element nodes as children) which was not covered in the convention (except for a mention in the to-do list) but is supported by XSLTJSON. The other change is that namespaces are optional instead of mandatory (which is also mentioned in the to-do list.) The rules are:
-* Element names become object properties.
-* Text content of elements goes in the `$` property of an object.
+* Element names become object properties.
+* Text content of elements goes in the `$` property of an object.
+
+ <alice>bob</alice>
- <alice>bob</alice>
+ becomes
-becomes
+ { "alice": { "$": "bob" } }
- { "alice": { "$": "bob" } }
-* Nested elements become nested properties.
+* Nested elements become nested properties.
- <alice><bob>charlie</bob><david>edgar</david></alice>
+ <alice><bob>charlie</bob><david>edgar</david></alice>
-becomes
+ becomes
- { "alice": {"bob": { "$": "charlie" }, "david": { "$": "edgar" } } }
-* Multiple elements with the same name and at the same level become array elements.
+ { "alice": {"bob": { "$": "charlie" }, "david": { "$": "edgar" } } }
- <alice><bob>charlie</bob><bob>david</bob></alice>
+* Multiple elements with the same name and at the same level become array elements.
-becomes
+ <alice><bob>charlie</bob><bob>david</bob></alice>
- { "alice": { "bob": [ { "$": "charlie" }, { "$": "david" } ] } }
-* Mixed content (element and text nodes) at the same level become array elements.
+ becomes
- <alice>bob<charlie>david</charlie>edgar</alice>
+ { "alice": { "bob": [ { "$": "charlie" }, { "$": "david" } ] } }
-becomes
+* Mixed content (element and text nodes) at the same level become array elements.
- { "alice": [ { "$": "bob" }, { "charlie": { "$": "david" } }, { "$": "edgar" } ] }
-* Attributes go in properties whose name begin with `@` .
+ <alice>bob<charlie>david</charlie>edgar</alice>
- <alice charlie="david">bob</alice>
+ becomes
-becomes
+ { "alice": [ { "$": "bob" }, { "charlie": { "$": "david" } }, { "$": "edgar" } ] }
- { "alice": { "@charlie": "david", "$": "bob" } }
+* Attributes go in properties whose name begin with `@` .
+
+ <alice charlie="david">bob</alice>
+
+ becomes
+
+ { "alice": { "@charlie": "david", "$": "bob" } }
#### RabbitFish (use-rabbitfish)
-RabbitFish is identical to the basic output format except that it uses Rule 6 “Attributes go in properties whose name begin with `@` ” from the BadgerFish convention in order to distinguish between elements and attributes.
+RabbitFish is identical to the basic output format except that it uses Rule 6 “Attributes go in properties whose name begin with `@`” from the BadgerFish convention in order to distinguish between elements and attributes.
#### Rayfish (use-rayfish)
The [Rayfish convention](http://onperl.org/blog/onperl/page/rayfish) was invented by [Micheal Matthew](http://onperl.org/) and aims to create highly structured JSON which is easy to parse and extract information from due to its regularity. This makes it an excellent choice for data centric XML documents. The downside is that it does not support mixed content (elements and text nodes at the same level) and is slightly more verbose than the other output formats. The rules are:
-* Elements are transformed into an object with three properties: `#name` , `#text` and `#children` . The name property contains the name of the element, the text property contains the text contents of the element and the children property contains an array of the child elements.
+* Elements are transformed into an object with three properties: `#name`, `#text` and `#children`. The name property contains the name of the element, the text property contains the text contents of the element and the children property contains an array of the child elements.
+
+ <alice/>
+
+ becomes
- <alice/>
+ { "#name": "alice", "#text": null, "#children": [ ] }
-becomes
+* Nested elements become members of the `#children` property of the parent element.
- { "#name": "alice", "#text": null, "#children": [ ] }
-* Nested elements become members of the `#children` property of the parent element.
+ <alice><bob>charlie</bob><david>edgar</david></alice>
- <alice><bob>charlie</bob><david>edgar</david></alice>
+ becomes
-becomes
+ { "#name": "alice", "#text": null, "#children": [
+ { "#name": "bob", "#text": "charlie", "#children": [ ] },
+ { "#name": "david", "#text": "edgar", "#children": [ ] }
+ ]}
- { "#name": "alice", "#text": null, "#children": [
- { "#name": "bob", "#text": "charlie", "#children": [ ] },
- { "#name": "david", "#text": "edgar", "#children": [ ] }
- ]}
-* Attributes go into an object in the `#children` property and begin with `@` .
+* Attributes go into an object in the `#children` property and begin with `@` .
- <alice charlie="david">bob</alice>
+ <alice charlie="david">bob</alice>
-becomes
+ becomes
- { "#name": "alice", "#text": "bob", "#children": [
- { "#name": "@charlie",
- "#text": "david",
- "#children": [ ]
- }
- ]}
+ { "#name": "alice", "#text": "bob", "#children": [
+ { "#name": "@charlie",
+ "#text": "david",
+ "#children": [ ]
+ }
+ ]}
#### Namespaces (use-namespaces)
@@ -196,11 +207,11 @@ The [XSLTJSON Lite stylesheet](xml-to-jsonml.xsl) transforms arbitrary XML to th
## Requirements
-XSLTJSON requires an XSLT 2.0 processor. An excellent option is [Saxon](http://www.saxonica.com/) , which was used to test and develop XSLTJSON.
+XSLTJSON requires an XSLT 2.0 processor. An excellent option is [Saxon](http://www.saxonica.com/), which was used to test and develop XSLTJSON.
## XSLT 2.0?
-Don't have an XSLT 2.0 processor? Check out [Alan Lewis](http://alanlewis.typepad.com/)'s excellent [XML 2 JSON project](xml-2-json.xsl) , [Micheal Matthew's Rayfish project](http://onperl.org/blog/onperl/page/rayfish) , [xml2json](http://code.google.com/p/xml2json-xslt/), or a modified [xml2json version by Martynas Jusevičius](http://www.xml.lt/Blog/2009/01/21/XML+to+JSON). You can also use [XSLTJSON Lite](xsltjson-lite) to transform XML to JSONML.
+Don't have an XSLT 2.0 processor? Check out [Alan Lewis](http://alanlewis.typepad.com/)'s excellent [XML 2 JSON project](xml-2-json.xsl), [Micheal Matthew's Rayfish project](http://onperl.org/blog/onperl/page/rayfish), [xml2json](http://code.google.com/p/xml2json-xslt/), or a modified [xml2json version by Martynas Jusevičius](http://www.xml.lt/Blog/2009/01/21/XML+to+JSON). You can also use [XSLTJSON Lite](xsltjson-lite) to transform XML to JSONML.
## Credits

0 comments on commit 59ef5c0

Please sign in to comment.
Something went wrong with that request. Please try again.