Liking cljdoc? Tell your friends :D

data.xml

data.xml is a Clojure library for reading and writing XML data. This library is the successor to lazy-xml. data.xml has the following features:

Parses XML documents into Clojure data structures
Emits XML from Clojure data structures
No additional dependencies if using 1.6
Uses StAX internally
lazy - should allow parsing and emitting of large XML documents

JDK 1.5

This library uses the pull parser that ships with JDK 1.6. If you running on JDK 1.6+, you do not need any additional dependencies. If you are using JDK 1.5, you will need to include a dependency on StAX. More information on this is available here

Bugs

Please report bugs using JIRA here.

Installation

Latest stable release: 0.0.7

Maven

For Maven projects, add the following XML in your pom.xml's <dependencies> section:

<dependency>
  <groupId>org.clojure</groupId>
  <artifactId>data.xml</artifactId>
  <version>0.0.7</version>
 </dependency>

Leiningen

Add the following to the project.clj dependencies:

[org.clojure/data.xml "0.0.7"]

Examples

The examples below assume you have added a use for data.xml:

(use 'clojure.data.xml)

data.xml supports parsing and emitting XML. The parsing functions will read XML from a Reader or InputStream.

(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. Additional parsing options can be passed via key pairs:

(parse-str "<a><![CDATA[\nfoo bar\n]]><![CDATA[\nbaz\n]]></a>" :coalescing false)
#clojure.data.xml.Element{:tag :a, :attrs {}, :content ("\nfoo bar\n" "\nbaz\n")}

XML elements can be created using the typical defrecord constructor functions or the element function used below, and written using a java.io.Writer.:

(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

The same can also be expressed using a more Hiccup-like style of defining the elements using sexp-as-element:

(= (element :foo {:foo-attr "foo value"}
     (element :bar {:bar-attr "bar value"}
       (element :baz {} "The baz value")))
   (sexp-as-element
      [:foo {:foo-attr "foo value"}
       [:bar {:bar-attr "bar value"}
        [:baz {} "The baz value"]]]))
;;-> true

Comments and CDATA can also be emitted as an S-expression with the special tag names :-cdata and :-comment:

(= (element :tag {:attr "value"}
     (element :body {} (cdata "not parsed <stuff")))
   (sexp-as-element [:tag {:attr "value"} [:body {} [:-cdata "not parsed <stuff"]]]
;;-> true

XML can be "round tripped" through the library:

(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>"

Generated API docs for data.xml are available here.

cljdoc is a website building & hosting documentation for Clojure/Script libraries

Keyboard shortcuts Report a problem cljdoc on GitHub

× close