Skip to content

Commit 5b13e2b

Browse files
bendlasbendlas
committed
prepare documentation for release
1 parent ce63e8e commit 5b13e2b

3 files changed

Lines changed: 84 additions & 26 deletions

File tree

‎CHANGES.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ From 0.2.0-alpha2 to 0.2.0-alpha3
77
- Emit empty tags for elements with no content (DXML-25)
88
- Add clojure.data.xml/element? predicate
99
- Support empty protocol function on Element deftypes (DXML-44)
10+
- Reflection cleanup (DXML-42)
1011

1112
From 0.2.0-alpha1 to 0.2.0-alpha2
1213
- qname function now returns canonical (keyword) names

‎README.md‎

Lines changed: 5 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -198,7 +198,7 @@ Generated API docs for data.xml are available [here](http://clojure.github.com/d
198198

199199
## Namespace Support
200200

201-
XML Namespaced names (QNames) are commonly 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`.
201+
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`.
202202

203203
Below is an example of parsing an XHTML document:
204204

@@ -262,19 +262,14 @@ tags with the same namespace will use one prefix:
262262

263263
"<?xml version=\"1.0\" encoding=\"UTF-8\"?><a:html xmlns:a=\"http://www.w3.org/1999/xhtml\"><a:head><a:title>Example title</a:title></a:head></a:html>"
264264

265-
Note that the Java QName does not consider namespace prefixes when
266-
checking equality. Similarly constructing QNames from string
267-
representations does not preserve prefixes. Prefixes are treated
268-
similarly in data.xml. Prefixes are currently represented as metadata
269-
on the elements. This preserves the same equality behavior that QNames
270-
have:
265+
Note that the jdk QName ignores namespace prefixes for equality, but allows to preserve them for emitting.
271266

272267
(= (parse-str "<foo:title xmlns:foo=\"http://www.w3.org/1999/xhtml2\">Example title</foo:title>")
273268
(parse-str "<bar:title xmlns:bar=\"http://www.w3.org/1999/xhtml2\">Example title</bar:title>"))
274269

275-
Removing the metadata will cause the elements to not have a prefix,
276-
which is still correct, but will cause new prefixes to be generated
277-
when the document is emitted.
270+
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.
271+
272+
(emit-str (parse-str "<foo:element xmlns:foo=\"FOO:\" />"))
278273

279274
## Location information as meta
280275

‎src/main/clojure/clojure/data/xml.clj‎

Lines changed: 78 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -38,35 +38,97 @@
3838
name/uri-file name/print-uri-file-command!
3939
process/find-xmlns process/aggregate-xmlns)
4040

41+
(def ^:private ^:const parser-opts-arg
42+
'{:keys [include-node? location-info
43+
coalescing supporting-external-entities
44+
allocator namespace-aware replacing-entity-references
45+
validating reporter resolver support-dtd]
46+
:or {include-node? #{:element :characters}
47+
location-info true
48+
coalescing true
49+
supporting-external-entities false}})
50+
4151
(defn event-seq
42-
"Parses the XML InputSource source using a pull-parser. Returns
43-
a lazy sequence of Event records. Accepts key pairs
44-
with XMLInputFactory options, see http://docs.oracle.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html
45-
and xml-input-factory-props for more information.
46-
Defaults coalescing true and supporting-external-entities false.
47-
:include-node? can be a set of #{:start-element :end-element :characters :comment}"
48-
[source {:as props}]
52+
"Parses an XML input source into a lazy sequence of pull events.
53+
54+
Input source can be a java.io.InputStream or java.io.Reader
55+
56+
Options:
57+
58+
:include-node? can be a subset of #{:element :characters :comment} default #{:element :characters}
59+
:location-info pass false to skip generating location meta data
60+
61+
See http://docs.oracle.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html
62+
for documentation on options:
63+
64+
{:allocator XMLInputFactory/ALLOCATOR
65+
:coalescing XMLInputFactory/IS_COALESCING
66+
:namespace-aware XMLInputFactory/IS_NAMESPACE_AWARE
67+
:replacing-entity-references XMLInputFactory/IS_REPLACING_ENTITY_REFERENCES
68+
:supporting-external-entities XMLInputFactory/IS_SUPPORTING_EXTERNAL_ENTITIES
69+
:validating XMLInputFactory/IS_VALIDATING
70+
:reporter XMLInputFactory/REPORTER
71+
:resolver XMLInputFactory/RESOLVER
72+
:support-dtd XMLInputFactory/SUPPORT_DTD}"
73+
{:arglists (list ['source parser-opts-arg])}
74+
[source opts]
4975
(let [props* (merge {:include-node? #{:element :characters}
5076
:coalescing true
5177
:supporting-external-entities false
5278
:location-info true}
53-
props)]
79+
opts)]
5480
(pull-seq (make-stream-reader props* source)
5581
props*
5682
nil)))
5783

5884
(defn parse
59-
"Parses the source, which can be an
60-
InputStream or Reader, and returns a lazy tree of Element records. Accepts key pairs
61-
with XMLInputFactory options, see http://docs.oracle.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html
62-
and xml-input-factory-props for more information. Defaults coalescing true."
63-
[source & opts]
85+
"Parses an XML input source into a a tree of Element records.
86+
The element tree is realized lazily, so huge XML files can be streamed through a depth-first tree walk.
87+
88+
Input source can be a java.io.InputStream or java.io.Reader
89+
90+
Options:
91+
92+
:include-node? can be a subset of #{:element :characters :comment} default #{:element :characters}
93+
:location-info pass false to skip generating location meta data
94+
95+
See http://docs.oracle.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html
96+
for documentation on options:
97+
98+
{:allocator XMLInputFactory/ALLOCATOR
99+
:coalescing XMLInputFactory/IS_COALESCING
100+
:namespace-aware XMLInputFactory/IS_NAMESPACE_AWARE
101+
:replacing-entity-references XMLInputFactory/IS_REPLACING_ENTITY_REFERENCES
102+
:supporting-external-entities XMLInputFactory/IS_SUPPORTING_EXTERNAL_ENTITIES
103+
:validating XMLInputFactory/IS_VALIDATING
104+
:reporter XMLInputFactory/REPORTER
105+
:resolver XMLInputFactory/RESOLVER
106+
:support-dtd XMLInputFactory/SUPPORT_DTD}"
107+
{:arglists (list ['source '& parser-opts-arg])}
108+
[source & {:as opts}]
64109
(event-tree (event-seq source opts)))
65110

66111
(defn parse-str
67-
"Parses the passed in string to Clojure data structures. Accepts key pairs
68-
with XMLInputFactory options, see http://docs.oracle.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html
69-
and xml-input-factory-props for more information. Defaults coalescing true."
112+
"Parses an XML String into a a tree of Element records.
113+
114+
Options:
115+
116+
:include-node? can be a subset of #{:element :characters :comment} default #{:element :characters}
117+
:location-info pass false to skip generating location meta data
118+
119+
See http://docs.oracle.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html
120+
for documentation on options:
121+
122+
{:allocator XMLInputFactory/ALLOCATOR
123+
:coalescing XMLInputFactory/IS_COALESCING
124+
:namespace-aware XMLInputFactory/IS_NAMESPACE_AWARE
125+
:replacing-entity-references XMLInputFactory/IS_REPLACING_ENTITY_REFERENCES
126+
:supporting-external-entities XMLInputFactory/IS_SUPPORTING_EXTERNAL_ENTITIES
127+
:validating XMLInputFactory/IS_VALIDATING
128+
:reporter XMLInputFactory/REPORTER
129+
:resolver XMLInputFactory/RESOLVER
130+
:support-dtd XMLInputFactory/SUPPORT_DTD}"
131+
{:arglists (list ['string '& parser-opts-arg])}
70132
[s & opts]
71133
(apply parse (string-source s) opts))
72134

0 commit comments

Comments
 (0)