Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/clojure/data.xml
https://github.com/clojure/data.xml
Last synced: 6 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/clojure/data.xml
- Owner: clojure
- License: epl-1.0
- Created: 2011-03-11T15:05:46.000Z (almost 14 years ago)
- Default Branch: master
- Last Pushed: 2024-07-15T17:56:09.000Z (6 months ago)
- Last Synced: 2024-12-19T00:04:32.147Z (13 days ago)
- Language: Clojure
- Homepage:
- Size: 578 KB
- Stars: 232
- Watchers: 38
- Forks: 69
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# data.xml
[data.xml](https://github.com/clojure/data.xml) is a Clojure library for reading and writing XML data. This
library is the successor to
[lazy-xml](https://clojure.github.io/clojure-contrib/lazy-xml-api.html).
data.xml has the following features:
* Parses XML documents into Clojure data structures
* Emits XML from Clojure data structures
* No additional dependencies if using JDK >= 1.6
* Uses StAX internally
* lazy - should allow parsing and emitting of large XML documents
## API Reference
Generated API docs for data.xml are available [here](https://clojure.github.io/data.xml).
## Bugs
Please report bugs using JIRA [here](https://clojure.atlassian.net/browse/DXML).
## Installation
Latest stable release: `0.0.8`
Latest preview release: `0.2.0-alpha9`
(The main features of the `0.2.0` series are XML Namespace support and Clojurescript support)
* [All Released Versions](https://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.clojure%22%20AND%20a%3A%22data.xml%22)
* [Development Snapshot Versions](https://oss.sonatype.org/index.html#nexus-search;gav~org.clojure~data.xml~~~)
### Maven
For Maven projects, add the following XML in your `pom.xml`'s `` section:
For stable:
org.clojure
data.xml
0.0.8
---
For preview:
org.clojure
data.xml
0.2.0-alpha9
### Leiningen
Add the following to the `project.clj` dependencies:
For stable:
[org.clojure/data.xml "0.0.8"]
---
For preview:
[org.clojure/data.xml "0.2.0-alpha9"]
### [CLI/`deps.edn`](https://clojure.org/reference/deps_and_cli)
Add the following to the `deps.edn` dependencies:
```clojure
;; for stable version:
org.clojure/data.xml {:mvn/version "0.0.8"}
;; for preview version:
org.clojure/data.xml {:mvn/version "0.2.0-alpha9"}
```
## Examples
The examples below assume you have added a `:refer` for data.xml:
(require '[clojure.data.xml :as xml])
data.xml supports parsing and emitting XML. The parsing functions will
read XML from a
[Reader](https://docs.oracle.com/javase/8/docs/api/java/io/Reader.html)
or
[InputStream](https://docs.oracle.com/javase/8/docs/api/java/io/InputStream.html).
(let [input-xml (java.io.StringReader. "
The baz value")]
(xml/parse input-xml))
#xml/element{:tag :foo,
:content [#xml/element{:tag :bar,
:content [#xml/element{:tag :baz,
: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:
(xml/parse-str "" :coalescing false)
#xml/element{:tag :a, :content ["\nfoo bar\n" "\nbaz\n"]}
XML elements can be created using the typical defrecord constructor
functions or the element function used below or just a plain map with :tag :attrs :content keys, and written using a
[java.io.Writer](https://docs.oracle.com/javase/8/docs/api/java/io/Writer.html).:
(let [tags (xml/element :foo {:foo-attr "foo value"}
(xml/element :bar {:bar-attr "bar value"}
(xml/element :baz {} "The baz value")))]
(with-open [out-file (java.io.FileWriter. "/tmp/foo.xml")]
(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:
(= (xml/element :foo {:foo-attr "foo value"}
(xml/element :bar {:bar-attr "bar value"}
(xml/element :baz {} "The baz value")))
(xml/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:
(= (xml/element :tag {:attr "value"}
(xml/element :body {} (xml/cdata "not parsed true
XML can be "round tripped" through the library:
(let [tags (xml/element :foo {:foo-attr "foo value"}
(xml/element :bar {:bar-attr "bar value"}
(xml/element :baz {} "The baz value")))]
(with-open [out-file (java.io.FileWriter. "/tmp/foo.xml")]
(xml/emit tags out-file))
(with-open [input (java.io.FileInputStream. "/tmp/foo.xml")]
(xml/parse input)))
#xml/element{:tag :foo, :attrs {:foo-attr "foo value"}...}
There are also some string based functions that are useful for
debugging.
(let [tags (xml/element :foo {:foo-attr "foo value"}
(xml/element :bar {:bar-attr "bar value"}
(xml/element :baz {} "The baz value")))]
(= tags (xml/parse-str (xml/emit-str tags))))
true
Indentation is supported, but should be treated as a debugging feature
as it's likely to be pretty slow:
(print (xml/indent-str (xml/element :foo {:foo-attr "foo value"}
(xml/element :bar {:bar-attr "bar value"}
(xml/element :baz {} "The baz value1")
(xml/element :baz {} "The baz value2")
(xml/element :baz {} "The baz value3")))))
The baz value1
The baz value2
The baz value3
CDATA can be emitted:
(xml/emit-str (xml/element :foo {}
(xml/cdata "")))
;; newlines added for readability, not in actual output
"
]]>"
But will be read as regular character data:
(xml/parse-str (xml/emit-str (xml/element :foo {}
(xml/cdata ""))))
#xml/element{:tag :foo, :content [""]}
Comments can also be emitted:
(xml/emit-str
(xml/element :foo {}
(xml/xml-comment "Just a goes here")
(xml/element :bar {} "and another element")))
;; newlines added for readability, not in actual output
"
and another element"
But are ignored when read:
(xml/emit-str
(xml/parse-str
(xml/emit-str (xml/element :foo {}
(xml/xml-comment "Just a goes here")
(xml/element :bar {} "and another element")))))
;; newlines added for readability, not in actual output
"
and another element"
## Namespace Support
XML Namespaced names (QNames) are encoded into clojure keywords, by percent-encoding the (XML) namespace: `{http://www.w3.org/1999/xhtml}head` is encoded in data.xml as `:http%3A%2F%2Fwww.w3.org%2F1999%2Fxhtml/head`.
Below is an example of parsing an XHTML document:
(xml/parse-str "
")
#xml/element{:tag :xmlns.http%3A%2F%2Fwww.w3.org%2F1999%2Fxhtml/html}
Emitting namespaced XML is usually done by using `alias-uri` in combination with clojure's built-in `::kw-ns/shorthands`:
;; this needs to be at the top level of your code (parallel to defns)
;; or subsequent ::xh/ ... will throw "Invalid token"
(xml/alias-uri 'xh "http://www.w3.org/1999/xhtml")
(xml/emit-str {:tag ::xh/html
:content [{:tag ::xh/head} {:tag ::xh/body :content ["DOCUMENT"]}]})
DOCUMENT
To emit namespaced tags without prefixes, you can also set the default xmlns at the root (it's important that the uris match!!):
;; at top level
(xml/alias-uri 'xh "http://www.w3.org/1999/xhtml")
;; top-level element should set xmlns that matches
(xml/emit-str
(xml/element ::xh/html
{:xmlns "http://www.w3.org/1999/xhtml"}
(xml/element ::xh/head)
(xml/element ::xh/body {} "DOCUMENT")))
;; newlines and indents added for readability, not in actual output
"
DOCUMENT
"
Same example, but using the more concise hiccup style (same output):
;; at top level
(xml/alias-uri 'xh "http://www.w3.org/1999/xhtml")
(xml/emit-str
(xml/sexp-as-element
[::xh/html {:xmlns "http://www.w3.org/1999/xhtml"}
[::xh/head]
[::xh/body "DOCUMENT"]]))
It is also allowable to use `javax.xml.namespace.QName` instances, as well as strings with the informal `{ns}n` encoding.
(xml/emit-str {:tag (xml/qname "http://www.w3.org/1999/xhtml" "html")})
(xml/emit-str {:tag "{http://www.w3.org/1999/xhtml}html"})
;; newlines added for readability, not in actual output
### Namespace Prefixes
Prefixes are mostly an artifact of xml serialisation. They can be
customized by explicitly declaring them as attributes in the `xmlns`
kw-namespace:
(xml/emit-str
(xml/element (xml/qname "http://www.w3.org/1999/xhtml" "title")
{:xmlns/foo "http://www.w3.org/1999/xhtml"}
"Example title"))
;; newlines added for readability, not in actual output
"
Example title"
Not specifying a namespace prefix will results in a prefix being generated:
(xml/emit-str
(xml/element ::xh/title
{}
"Example title"))
;; newlines added for readability, not in actual output
"
Example title"
The above example auto assigns prefixes for the namespaces used. In
this case it was named `a` by the emitter. Emitting several nested
tags with the same namespace will use one prefix:
(xml/emit-str
(xml/element ::xh/html
{}
(xml/element ::xh/head
{}
(xml/element ::xh/title
{}
"Example title"))))
;; newlines and indents added for readability, not in actual output
"
Example title"
Note that the jdk QName ignores namespace prefixes for equality, but allows to preserve them for emitting.
(= (xml/parse-str "Example title")
(xml/parse-str "Example title"))
In data.xml prefix mappings are (by default) retained in metadata on a tag record. If there is no metadata, new prefixes will be generated when emitting.
(xml/emit-str (xml/parse-str ""))
## Location information as meta
By default the parser attaches location information as element meta,
`:character-offset`, `:column-number` and `:line-number` are available under
the `:clojure.data.xml/location-info` key:
(deftest test-location-meta
(let [input "\n"
location-meta (comp :clojure.data.xml/location-info meta)]
(is (= 1 (-> input xml/parse-str location-meta :line-number)))))
To elide location information, pass `:location-info false` to the parser:
(xml/parse-str your-input :location-info false)
## Clojurescript support
The Clojurescript implementation uses the same namespace as the Clojure one `clojure.data.xml`.
### Native DOM support
data.xml can directly work with native dom nodes.
- To parse into DOM objects, call parse with `:raw true`
- To use DOM objects like regular persistent maps, call `(extend-dom-as-data!)`.
This extends the native dom node prototypes to Clojurescript collection protocols, such that you can treat them as data.xml parse trees.
- To coerce to native dom use `element-node`
- To coerce to records use `element-data`
### Missing Features, Patches Welcome
#### Streaming
data.xml on Clojurescript doesn't currently support streaming, hence only the `*-str` variants of `parse`/`emit` are implemented. Those are just wrappers for browser's native xml parsing/printing.
Pull parsing doesn't seem the right solution for Clojurescript, because when code cannot block, the parser has no way of waiting on its input. For this reason, parsing in Clojurescript cannot be based around `event-seq`.
Push parsing, on the other hand should not pose a problem, because when data arrives in a callback, it can be pushed on into the parser. Fortunately, clojure already has a nice push-based pendant for lazy sequences: transducers.
#### Utilities
Some utilities, like `process/*-xmlns`, `prxml/sexp-as-*`, `indent` aren't yet implemented.
#### Immutable updates for dom types
Make `extend-dom-as-data!` also support assoc, ... on dom nodes.
#### Feel free to pick a [ticket](https://clojure.atlassian.net/browse/DXML) to work on
## License
Licensed under the [Eclipse Public License](https://opensource.org/license/epl-1-0/).
## Developer Information
* [GitHub project](https://github.com/clojure/data.xml)
* [Bug Tracker](https://clojure.atlassian.net/browse/DXML)
* [Continuous Integration](https://github.com/clojure/data.xml/actions/workflows/test.yml)
## Contributing
All contributions need to be made via patches attached to tickets in
[JIRA](https://clojure.atlassian.net/browse/DXML). Check the
[Contributing to Clojure](https://clojure.org/community/contributing) page for
more information.