eximia.core — org.clojars.lowecg/eximia 0.1.4

A fast and small XML processor for Clojure. With XML namespace support and secure defaults.

Reads and writes a format similar but not identical to clojure.xml and data.xml:

• Elements as maps with :tag, :attrs and :content keys
  • The :tag is represented as a javax.xml.namespace.QName to support XML namespaces.
  • :attrs is a map from QNames to strings, to support XML namespaces for the attribute names as well
  • :content is a seq of elements and character data
• Character data as strings
  • By default, adjacent character sections (including CDATA) are joined together to one string when reading.

There are also options and utility functions to convert QNames to keywords when reading and from keywords to QNames when writing (:tag-fn and :key-fn, qname->keyword etc.).

CDATA blocks can also be read and written as [[CData]] records, processing instructions as [[ProcessingInstruction]]s and comments as [[Comment]]s.

end-fragment clj

(end-fragment xml-stream-writer)

End the document for fragments. Does not close out.

input-factory clj

(input-factory opts)

Create an XMLInputFactory. The opts map keys and values are the XMLInputFactory properties but :validating, :namespace-aware, :coalescing, :replacing-entity-references, :supporting-external-entities, :support-dtd, :reporter and :allocator can be used instead of the XMLInputFactory constants or the raw "javax.xml.stream.*" strings.

:support-dtd and :supporting-external-entities default to false to prevent XXE attacks.

Note that XMLInputFactory instances can be very expensive to create but are reusable. So call this as rarely as possible, probably only in the application startup phase.

keyword->qname clj

(keyword->qname kw)

Convert the keyword kw to a QName, with the keyword namespace as the prefix (and NULL_NS_URI as the ns-uri).

local-name clj

(local-name qname)

Get the local name string of a QName, similar to [[clojure.core/name]].

ns-uri clj

(ns-uri qname)

Get the namespace URI string of a QName.

output-factory clj

(output-factory opts)

Create an XMLOutputFactory. The opts map keys and values are the XMLOutputFactory properties but :repairing-namespaces can also be used instead of XMLOutputFactory/IS_REPAIRING_NAMESPACES or "javax.xml.stream.isRepairingNamespaces".

Note that XMLOutputFactory instances can be very expensive to create but are reusable. So call this as rarely as possible, probably only in the application startup phase.

prefix clj

(prefix qname)

Get the namespace prefix string of a QName, similar to [[clojure.core/namespace]].

qname clj

(qname local-name)

(qname ns-uri local-name)

(qname ns-uri local-name prefix)

Create a QName from a local name and optional namespace URI and prefix.

qname->keyword clj

(qname->keyword qname)

Convert the QName qname to a keyword, with the prefix as the keyword namespace.

qname->unq-keyword clj

(qname->unq-keyword qname)

Convert the QName qname to an unqualified keyword.

read clj

(read input)

(read input opts)

Read XML from input, which should be an InputStream or a Reader (or any ToStreamReader). Does not close input.

The optional opts map can have the following keys:

Key	Description	Value	Default
:tag-fn	Function to apply to tag QNames	An IFn	identity
:key-fn	Function to apply to attribute key QNames	An IFn	identity
:wrap-cdata	Return CDATA contents wrapped in [[CData]] instead of just the string.	boolean	false
:preserve	Return [[ProcessingInstruction]]s and [[Comment]]s instead of skipping them.	A subset of #{:processing-instruction, :comment}	#{}
:xml-input-factory	The XMLInputFactory to use. See also input-factory.	An XMLInputFactory	A (input-factory {:coalescing true}) cached internally in Eximia
:consume-eagerly?	A test function on whether to eagerly consume a tag. Eager elements are given to the :eager-consumer function rather than added to the current document	An IFn	false
:eager-consumer	Function to process an element eagerly	An IFn	n/a

read-str clj

(read-str input)

(read-str input opts)

Like read, but with a string as the input.

start-fragment clj

(start-fragment root out)

(start-fragment root out opts)

Start a document for writing subsequent fragments, under root as XML to out, which should be an OutputStream or a Writer (or any ToStreamWriter).

Returns the XMLStreamWriter which should be used in subsequent calls to write-fragment and end

The optional opts as for write.

ToStreamReader clj protocol

Conversions to XMLStreamReader

-stream-reader clj

(-stream-reader self factory)

Wrap self into a XMLStreamReader, using the XMLInputFactory factory.

ToStreamWriter clj protocol

Conversions to XMLStreamWriter

-stream-writer clj

(-stream-writer self factory)

Wrap self into a XMLStreamWriter, using the XMLOutputFactory factory.

write clj

(write tree out)

(write tree out opts)

Write tree as XML to out, which should be an OutputStream or a Writer (or any ToStreamWriter). Does not close out.

The optional opts map can have the following keys:

Key	Description	Value	Default
:tag-fn	Function to convert tag names into QNames	An IFn	identity
:key-fn	Function to convert attribute keys QNames	An IFn	identity
:xml-version	The XML standard to use	"1.0" or "1.1"	"1.0"
:xml-output-factory	The XMLOutputFactory to use. See also output-factory.	An XMLOutputFactory	A (output-factory {:repairing-namespaces true}) cached internally in Eximia

write-fragment clj

(write-fragment fragment xml-stream-writer opts)

Add the XML fragment to xml-stream-writer

write-str clj

(write-str tree)

(write-str tree opts)

Like write, but returns a string instead of writing to a provided destination.

WriteXML clj protocol

Emitting an XML fragment

-write clj

(-write self out opts)

Write the XML fragment for self into the XMLStreamWriter out and write options opts.