Added examples to the README

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).