Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Added examples to the README

  • Loading branch information...
commit 6c3603e8e2f7f102e73d8338f79ae2e2ae52c2e8 1 parent 9de6e83
@senior senior authored
Showing with 103 additions and 1 deletion.
  1. +103 −1 README.md
View
104 README.md
@@ -40,6 +40,108 @@ Add the following to the `project.clj` dependencies:
## Examples
+data.xml supports parsing and emitting XML. The parsing functions will
+read XML from a
+[Reader](http://docs.oracle.com/javase/6/docs/api/java/io/Reader.html)
+or
+[InputStream](http://docs.oracle.com/javase/6/docs/api/java/io/InputStream.html).
+
+ (let [input-xml (java.io.StringReader. "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
+ <foo><bar><baz>The baz value</baz></bar></foo>")]
+ (parse input-xml))
+ #clojure.data.xml.Element{:tag :foo,
+ :attrs {},
+ :content (#clojure.data.xml.Element{:tag :bar,
+ :attrs {},
+ :content (#clojure.data.xml.Element{:tag :baz,
+ :attrs {},
+ :content ("The baz value")})})}
+
+The data is returned as defrecords and can be manipulated using the
+normal clojure data structure functions.
+
+XML elements can be created using the typical defrecord constructor
+functions or the element function used below, and written using a
+[java.io.Writer](http://docs.oracle.com/javase/6/docs/api/java/io/Writer.html).:
+
+ (let [tags (element :foo {:foo-attr "foo value"}
+ (element :bar {:bar-attr "bar value"}
+ (element :baz {} "The baz value")))]
+ (with-open [out-file (java.io.FileWriter. "/tmp/foo.xml")]
+ (emit tags out-file)))
+
+ ;;-> Writes XML to /tmp/foo.xml
+
+XML can be round tripped through he library with code like:
+
+ (let [tags (element :foo {:foo-attr "foo value"}
+ (element :bar {:bar-attr "bar value"}
+ (element :baz {} "The baz value")))]
+ (with-open [out-file (java.io.FileWriter. "/tmp/foo.xml")]
+ (emit tags out-file))
+ (with-open [input (java.io.FileInputStream. "/tmp/foo.xml")]
+ (parse input)))
+
+ #clojure.data.xml.Element{:tag :foo, :attrs {:foo-attr "foo value"}...}
+
+There are also some string based functions that are useful for
+debugging.
+
+ (let [tags (element :foo {:foo-attr "foo value"}
+ (element :bar {:bar-attr "bar value"}
+ (element :baz {} "The baz value")))]
+ (= tags (parse-str (emit-str tags))))
+
+ ;;-> true
+
+Indentation is supported, but should be treated as a debugging feature
+as it's likely to be pretty slow:
+
+ (print (indent-str (element :foo {:foo-attr "foo value"}
+ (element :bar {:bar-attr "bar value"}
+ (element :baz {} "The baz value1")
+ (element :baz {} "The baz value2")
+ (element :baz {} "The baz value3")))))
+
+ <?xml version="1.0" encoding="UTF-8"?>
+ <foo foo-attr="foo value">
+ <bar bar-attr="bar value">
+ <baz>The baz value1</baz>
+ <baz>The baz value2</baz>
+ <baz>The baz value3</baz>
+ </bar>
+ </foo>
+
+CDATA can be emitted:
+
+ (emit-str (element :foo {}
+ (cdata "<non><escaped><info><here>")))
+ "<?xml version=\"1.0\" encoding=\"UTF-8\"?><foo><![CDATA[<non><escaped><info><here>]]></foo>"
+
+But will be read as regular character data:
+
+ (parse-str (emit-str (element :foo {}
+ (cdata "<non><escaped><info><here>"))))
+ #clojure.data.xml.Element{:tag :foo, :attrs {}, :content ("<non><escaped><info><here>")}
+
+Comments can also be emitted:
+
+ (emit-str (element :foo {}
+ (xml-comment "Just a <comment> goes here")
+ (element :bar {} "and another element")))
+
+ "<?xml version=\"1.0\" encoding=\"UTF-8\"?><foo><!--Just a
+ <comment> goes here--><bar>and another element</bar></foo>"
+
+But are ignored when read:
+ (emit-str
+ (parse-str
+ (emit-str (element :foo {}
+ (xml-comment "Just a <comment> goes here")
+ (element :bar {} "and another element")))))
+
+"<?xml version=\"1.0\" encoding=\"UTF-8\"?><foo><bar>and another element</bar></foo>"
+
## License
-Licensed under the [Eclipse Public License](http://www.opensource.org/licenses/eclipse-1.0.php).
+Licensed under the [Eclipse Public License](http://www.opensource.org/licenses/eclipse-1.0.php).
Please sign in to comment.
Something went wrong with that request. Please try again.