Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 203 lines (140 sloc) 7.513 kB
08c493f @senior Added readme
senior authored
1 # data.xml
2
ca7f807 @senior README formatting changes
senior authored
3 [data.xml](https://github.com/clojure/data.xml) is a Clojure library for reading and writing XML data. This
08c493f @senior Added readme
senior authored
4 library is the successor to
5 [lazy-xml](http://clojure.github.com/clojure-contrib/lazy-xml-api.html).
6 data.xml has the following features:
7
8 * Parses XML documents into Clojure data structures
9 * Emits XML from Clojure data structures
10 * No additional dependencies if using 1.6
11 * Uses StAX internally
12 * lazy - should allow parsing and emitting of large XML documents
13
ca7f807 @senior README formatting changes
senior authored
14 ## JDK 1.5
15
16 This library uses the pull parser that ships with JDK 1.6. If you running on JDK 1.6+, you do not need any
17 additional dependencies. If you are using JDK 1.5, you will need to include a dependency on StAX. More
18 information on this is available [here](https://github.com/clojure/data.xml/blob/jdk16-pull-parser/jdk_15_readme.txt)
19
08c493f @senior Added readme
senior authored
20 ## Bugs
21
ca7f807 @senior README formatting changes
senior authored
22 Please report bugs using JIRA [here](http://dev.clojure.org/jira/browse/DXML).
08c493f @senior Added readme
senior authored
23
2c1c598 @senior Updated README to contrib standard
senior authored
24 ## Installation
08c493f @senior Added readme
senior authored
25
320eda8 @puredanger Updated latest version
puredanger authored
26 Latest stable release: 0.0.8
08c493f @senior Added readme
senior authored
27
2c1c598 @senior Updated README to contrib standard
senior authored
28 * [All Released Versions](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.clojure%22%20AND%20a%3A%22data.xml%22)
29
30 * [Development Snapshot Versions](https://oss.sonatype.org/index.html#nexus-search;gav~org.clojure~data.xml~~~)
08c493f @senior Added readme
senior authored
31
32 ### Maven
33 For Maven projects, add the following XML in your `pom.xml`'s `<dependencies>` section:
34
35 <dependency>
e719b58 @ataggart Fix formatting of examples.
ataggart authored
36 <groupId>org.clojure</groupId>
37 <artifactId>data.xml</artifactId>
320eda8 @puredanger Updated latest version
puredanger authored
38 <version>0.0.8</version>
08c493f @senior Added readme
senior authored
39 </dependency>
40
41 ### Leiningen
42 Add the following to the `project.clj` dependencies:
43
320eda8 @puredanger Updated latest version
puredanger authored
44 [org.clojure/data.xml "0.0.8"]
08c493f @senior Added readme
senior authored
45
46 ## Examples
47
ca91651 @senior Added a statement to the README on getting your ns setup for data.xml
senior authored
48 The examples below assume you have added a `use` for data.xml:
49
e719b58 @ataggart Fix formatting of examples.
ataggart authored
50 (use 'clojure.data.xml)
ca91651 @senior Added a statement to the README on getting your ns setup for data.xml
senior authored
51
6c3603e @senior Added examples to the README
senior authored
52 data.xml supports parsing and emitting XML. The parsing functions will
53 read XML from a
54 [Reader](http://docs.oracle.com/javase/6/docs/api/java/io/Reader.html)
55 or
56 [InputStream](http://docs.oracle.com/javase/6/docs/api/java/io/InputStream.html).
57
e719b58 @ataggart Fix formatting of examples.
ataggart authored
58 (let [input-xml (java.io.StringReader. "<?xml version=\"1.0\" encoding=\"UTF-8\"?>
59 <foo><bar><baz>The baz value</baz></bar></foo>")]
60 (parse input-xml))
61
62 #clojure.data.xml.Element{:tag :foo,
63 :attrs {},
64 :content (#clojure.data.xml.Element{:tag :bar,
65 :attrs {},
66 :content (#clojure.data.xml.Element{:tag :baz,
67 :attrs {},
68 :content ("The baz value")})})}
6c3603e @senior Added examples to the README
senior authored
69
70 The data is returned as defrecords and can be manipulated using the
5671774 @senior Added some comments/docs on the keyword input parsing parameters
senior authored
71 normal clojure data structure functions. Additional parsing options
72 can be passed via key pairs:
6c3603e @senior Added examples to the README
senior authored
73
5671774 @senior Added some comments/docs on the keyword input parsing parameters
senior authored
74 (parse-str "<a><![CDATA[\nfoo bar\n]]><![CDATA[\nbaz\n]]></a>" :coalescing false)
75 #clojure.data.xml.Element{:tag :a, :attrs {}, :content ("\nfoo bar\n" "\nbaz\n")}
76
6c3603e @senior Added examples to the README
senior authored
77 XML elements can be created using the typical defrecord constructor
78 functions or the element function used below, and written using a
79 [java.io.Writer](http://docs.oracle.com/javase/6/docs/api/java/io/Writer.html).:
80
e719b58 @ataggart Fix formatting of examples.
ataggart authored
81 (let [tags (element :foo {:foo-attr "foo value"}
82 (element :bar {:bar-attr "bar value"}
83 (element :baz {} "The baz value")))]
84 (with-open [out-file (java.io.FileWriter. "/tmp/foo.xml")]
85 (emit tags out-file)))
6c3603e @senior Added examples to the README
senior authored
86
e719b58 @ataggart Fix formatting of examples.
ataggart authored
87 ;;-> Writes XML to /tmp/foo.xml
6c3603e @senior Added examples to the README
senior authored
88
715e506 @senior Add an example for sexp-as-element
senior authored
89 The same can also be expressed using a more Hiccup-like style of defining the elements using sexp-as-element:
90
91 (= (element :foo {:foo-attr "foo value"}
92 (element :bar {:bar-attr "bar value"}
93 (element :baz {} "The baz value")))
94 (sexp-as-element
95 [:foo {:foo-attr "foo value"}
96 [:bar {:bar-attr "bar value"}
97 [:baz {} "The baz value"]]]))
98 ;;-> true
99
df7324d @senior Update README.md
senior authored
100 Comments and CDATA can also be emitted as an S-expression with the special tag names :-cdata and :-comment:
8c74d87 @senior Updated readme to include S-expression comment/cdata example
senior authored
101
102 (= (element :tag {:attr "value"}
103 (element :body {} (cdata "not parsed <stuff")))
104 (sexp-as-element [:tag {:attr "value"} [:body {} [:-cdata "not parsed <stuff"]]]
105 ;;-> true
106
ca7f807 @senior README formatting changes
senior authored
107 XML can be "round tripped" through the library:
6c3603e @senior Added examples to the README
senior authored
108
e719b58 @ataggart Fix formatting of examples.
ataggart authored
109 (let [tags (element :foo {:foo-attr "foo value"}
110 (element :bar {:bar-attr "bar value"}
111 (element :baz {} "The baz value")))]
112 (with-open [out-file (java.io.FileWriter. "/tmp/foo.xml")]
113 (emit tags out-file))
114 (with-open [input (java.io.FileInputStream. "/tmp/foo.xml")]
115 (parse input)))
6c3603e @senior Added examples to the README
senior authored
116
e719b58 @ataggart Fix formatting of examples.
ataggart authored
117 #clojure.data.xml.Element{:tag :foo, :attrs {:foo-attr "foo value"}...}
6c3603e @senior Added examples to the README
senior authored
118
119 There are also some string based functions that are useful for
120 debugging.
121
e719b58 @ataggart Fix formatting of examples.
ataggart authored
122 (let [tags (element :foo {:foo-attr "foo value"}
123 (element :bar {:bar-attr "bar value"}
124 (element :baz {} "The baz value")))]
125 (= tags (parse-str (emit-str tags))))
126
127 true
6c3603e @senior Added examples to the README
senior authored
128
129 Indentation is supported, but should be treated as a debugging feature
130 as it's likely to be pretty slow:
131
e719b58 @ataggart Fix formatting of examples.
ataggart authored
132 (print (indent-str (element :foo {:foo-attr "foo value"}
133 (element :bar {:bar-attr "bar value"}
134 (element :baz {} "The baz value1")
135 (element :baz {} "The baz value2")
136 (element :baz {} "The baz value3")))))
137
138 <?xml version="1.0" encoding="UTF-8"?>
139 <foo foo-attr="foo value">
140 <bar bar-attr="bar value">
141 <baz>The baz value1</baz>
142 <baz>The baz value2</baz>
143 <baz>The baz value3</baz>
144 </bar>
145 </foo>
6c3603e @senior Added examples to the README
senior authored
146
147 CDATA can be emitted:
148
e719b58 @ataggart Fix formatting of examples.
ataggart authored
149 (emit-str (element :foo {}
150 (cdata "<non><escaped><info><here>")))
151
152 "<?xml version=\"1.0\" encoding=\"UTF-8\"?><foo><![CDATA[<non><escaped><info><here>]]></foo>"
6c3603e @senior Added examples to the README
senior authored
153
154 But will be read as regular character data:
155
e719b58 @ataggart Fix formatting of examples.
ataggart authored
156 (parse-str (emit-str (element :foo {}
157 (cdata "<non><escaped><info><here>"))))
158
159 #clojure.data.xml.Element{:tag :foo, :attrs {}, :content ("<non><escaped><info><here>")}
6c3603e @senior Added examples to the README
senior authored
160
161 Comments can also be emitted:
162
e719b58 @ataggart Fix formatting of examples.
ataggart authored
163 (emit-str (element :foo {}
164 (xml-comment "Just a <comment> goes here")
165 (element :bar {} "and another element")))
6c3603e @senior Added examples to the README
senior authored
166
e719b58 @ataggart Fix formatting of examples.
ataggart authored
167 "<?xml version=\"1.0\" encoding=\"UTF-8\"?><foo><!--Just a <comment> goes here--><bar>and another element</bar></foo>"
6c3603e @senior Added examples to the README
senior authored
168
169 But are ignored when read:
170
e719b58 @ataggart Fix formatting of examples.
ataggart authored
171 (emit-str
172 (parse-str
173 (emit-str (element :foo {}
174 (xml-comment "Just a <comment> goes here")
175 (element :bar {} "and another element")))))
ca7f807 @senior README formatting changes
senior authored
176
e719b58 @ataggart Fix formatting of examples.
ataggart authored
177 "<?xml version=\"1.0\" encoding=\"UTF-8\"?><foo><bar>and another element</bar></foo>"
6c3603e @senior Added examples to the README
senior authored
178
2c1c598 @senior Updated README to contrib standard
senior authored
179 Generated API docs for data.xml are available [here](http://clojure.github.com/data.xml).
180
08c493f @senior Added readme
senior authored
181 ## License
182
6c3603e @senior Added examples to the README
senior authored
183 Licensed under the [Eclipse Public License](http://www.opensource.org/licenses/eclipse-1.0.php).
2c1c598 @senior Updated README to contrib standard
senior authored
184
185 ## Developer Information
186
187 * [GitHub project](https://github.com/clojure/data.xml)
188
189 * [Bug Tracker](http://dev.clojure.org/jira/browse/DXML)
190
191 * [Continuous Integration](http://build.clojure.org/job/data.xml/)
192
193 * [Compatibility Test Matrix](http://build.clojure.org/job/data.xml-test-matrix/)
194
195 ## Contributing
196
197 All contributions need to be made via patches attached to tickets in
198 [JIRA](http://dev.clojure.org/jira/browse/DXML). Check the
199 [Contributing to Clojure](http://clojure.org/contributing) page for
200 more information.
201
202
Something went wrong with that request. Please try again.