API for clojure.data.xml - data.xml 0.2.0-SNAPSHOT (in development)

by Chris Houser

Full namespace name: clojure.data.xml

Overview

Functions to parse XML into lazy sequences and lazy trees and
emit these as text.

Public Variables and Functions



aggregate-xmlns

function
Usage: (aggregate-xmlns xml)
Put all occurring xmlns into the root

    
    
    Source
  


alias-uri

function
Usage: (alias-uri & {:as alias-nss})
Define a Clojure namespace aliases for xmlns uris.

This sets up the current namespace for reading qnames denoted with
Clojure's ::alias/keywords reader feature.


## Example
(alias-uri :D "DAV:")
                         ; similar in effect to
;; (require '[xmlns.DAV%3A :as D])
                         ; but required namespace is auto-created
                         ; henceforth, shorthand keywords can be used
{:tag ::D/propfind}
                         ; ::D/propfind will be expanded to :xmlns.DAV%3A/propfind
                         ; in the current namespace by the reader

## Clojurescript support
Currently, namespaces can't be auto-created in Clojurescript.
Dummy files for aliased uris have to exist. Have a look at `uri-file` and `print-uri-file-command!` to create those.

    
    
    Source
  


cdata

function
Usage: (cdata content)
Create a CData node

    
    
    Source
  


element

function
Usage: (element tag)
       (element tag attrs)
       (element tag attrs & content)
Create an xml Element from content varargs

    
    
    Source
  


element*

function
Usage: (element* tag attrs content meta)
       (element* tag attrs content)
Create an xml element from a content collection and optional metadata

    
    
    Source
  


element-nss

function
Usage: (element-nss {:keys [attrs], :as element})
Get xmlns environment from element

    
    
    Source
  


emit

function
Usage: (emit e writer & {:as opts})
Prints the given Element tree as XML text to stream.
Options:
 :encoding <str>          Character encoding to use
 :doctype  <str>          Document type (DOCTYPE) declaration to use

    
    
    Source
  


emit-str

function
Usage: (emit-str e & opts)
Emits the Element to String and returns it.
Options:
 :encoding <str>          Character encoding to use
 :doctype  <str>          Document type (DOCTYPE) declaration to use

    
    
    Source
  


event-seq

function
Usage: (event-seq source {:keys [include-node? location-info coalescing supporting-external-entities allocator namespace-aware replacing-entity-references validating reporter resolver support-dtd], :or {include-node? #{:characters :element}, location-info true, coalescing true, supporting-external-entities false}})
Parses an XML input source into a lazy sequence of pull events.

Input source can be a java.io.InputStream or java.io.Reader

Options:

  :include-node? can be a subset of #{:element :characters :comment} default #{:element :characters}
  :location-info pass false to skip generating location meta data

See http://docs.oracle.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html
for documentation on options:

  {:allocator                      XMLInputFactory/ALLOCATOR
   :coalescing                     XMLInputFactory/IS_COALESCING
   :namespace-aware                XMLInputFactory/IS_NAMESPACE_AWARE
   :replacing-entity-references    XMLInputFactory/IS_REPLACING_ENTITY_REFERENCES
   :supporting-external-entities   XMLInputFactory/IS_SUPPORTING_EXTERNAL_ENTITIES
   :validating                     XMLInputFactory/IS_VALIDATING
   :reporter                       XMLInputFactory/REPORTER
   :resolver                       XMLInputFactory/RESOLVER
   :support-dtd                    XMLInputFactory/SUPPORT_DTD}

    
    
    Source
  


find-xmlns

function
Usage: (find-xmlns xml)
Find all xmlns occuring in a root

    
    
    Source
  


indent

function
Usage: (indent e writer & opts)
Emits the XML and indents the result.  WARNING: this is slow
it will emit the XML and read it in again to indent it.  Intended for
debugging/testing only.

    
    
    Source
  


indent-str

function
Usage: (indent-str e & opts)
Emits the XML and indents the result.  Writes the results to a String and returns it

    
    
    Source
  


parse

function
Usage: (parse source & {:keys [include-node? location-info coalescing supporting-external-entities allocator namespace-aware replacing-entity-references validating reporter resolver support-dtd], :or {include-node? #{:characters :element}, location-info true, coalescing true, supporting-external-entities false}})
Parses an XML input source into a a tree of Element records.
The element tree is realized lazily, so huge XML files can be streamed through a depth-first tree walk.

Input source can be a java.io.InputStream or java.io.Reader

Options:

  :include-node? can be a subset of #{:element :characters :comment} default #{:element :characters}
  :location-info pass false to skip generating location meta data

See http://docs.oracle.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html
for documentation on options:

  {:allocator                      XMLInputFactory/ALLOCATOR
   :coalescing                     XMLInputFactory/IS_COALESCING
   :namespace-aware                XMLInputFactory/IS_NAMESPACE_AWARE
   :replacing-entity-references    XMLInputFactory/IS_REPLACING_ENTITY_REFERENCES
   :supporting-external-entities   XMLInputFactory/IS_SUPPORTING_EXTERNAL_ENTITIES
   :validating                     XMLInputFactory/IS_VALIDATING
   :reporter                       XMLInputFactory/REPORTER
   :resolver                       XMLInputFactory/RESOLVER
   :support-dtd                    XMLInputFactory/SUPPORT_DTD}

    
    
    Source
  


parse-str

function
Usage: (parse-str string & {:keys [include-node? location-info coalescing supporting-external-entities allocator namespace-aware replacing-entity-references validating reporter resolver support-dtd], :or {include-node? #{:characters :element}, location-info true, coalescing true, supporting-external-entities false}})
Parses an XML String into a a tree of Element records.

Options:

  :include-node? can be a subset of #{:element :characters :comment} default #{:element :characters}
  :location-info pass false to skip generating location meta data

See http://docs.oracle.com/javase/6/docs/api/javax/xml/stream/XMLInputFactory.html
for documentation on options:

  {:allocator                      XMLInputFactory/ALLOCATOR
   :coalescing                     XMLInputFactory/IS_COALESCING
   :namespace-aware                XMLInputFactory/IS_NAMESPACE_AWARE
   :replacing-entity-references    XMLInputFactory/IS_REPLACING_ENTITY_REFERENCES
   :supporting-external-entities   XMLInputFactory/IS_SUPPORTING_EXTERNAL_ENTITIES
   :validating                     XMLInputFactory/IS_VALIDATING
   :reporter                       XMLInputFactory/REPORTER
   :resolver                       XMLInputFactory/RESOLVER
   :support-dtd                    XMLInputFactory/SUPPORT_DTD}

    
    
    Source
  


print-uri-file-command!

function
Usage: (print-uri-file-command! uri)
Shell command to create a dummy file for xmlns. Execute from a source root.

    
    
    Source
  


qname-local

function
Usage: (qname-local v)
Get the name for this qname

    
    
    Source
  


qname-uri

function
Usage: (qname-uri v)
Get the namespace uri for this qname

    
    
    Source
  


sexp-as-element

function
Usage: (sexp-as-element sexp)
Convert a single sexp into an Element

    
    
    Source
  


sexps-as-fragment

function
Usage: (sexps-as-fragment)
       (sexps-as-fragment sexp)
       (sexps-as-fragment sexp & sexps)
Convert a compact prxml/hiccup-style data structure into the more formal
tag/attrs/content format. A seq of elements will be returned, which may
not be suitable for immediate use as there is no root element. See also
sexp-as-element.

The format is [:tag-name attr-map? content*]. Each vector opens a new tag;
seqs do not open new tags, and are just used for inserting groups of elements
into the parent tag. A bare keyword not in a vector creates an empty element.

To provide XML conversion for your own data types, extend the AsElements
protocol to them.

    
    
    Source
  


uri-file

function
Usage: (uri-file uri)
Dummy file name for :require'ing xmlns uri

    
    
    Source
  


xml-comment

function
Usage: (xml-comment content)
Create a Comment node

    
    
    Source
  

clojure.data.xml.event

Data type for xml pull events

Types



CDataEvent

record

    Fields: [str]
Protocols:
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map


CharsEvent

record

    Fields: [str]
Protocols:
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map


CommentEvent

record

    Fields: [str]
Protocols:
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map


EmptyElementEvent

record

    Fields: [tag attrs nss location-info]
Protocols:
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map


EndElementEvent

type

    Fields: []
Protocols:
Interfaces:


QNameEvent

record

    Fields: [qn]
Protocols:
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map


StartElementEvent

record

    Fields: [tag attrs nss location-info]
Protocols:
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map

Public Variables and Functions



->CDataEvent

function
Usage: (->CDataEvent str)
Positional factory function for class clojure.data.xml.event.CDataEvent.

    
    
    Source
  


->CharsEvent

function
Usage: (->CharsEvent str)
Positional factory function for class clojure.data.xml.event.CharsEvent.

    
    
    Source
  


->CommentEvent

function
Usage: (->CommentEvent str)
Positional factory function for class clojure.data.xml.event.CommentEvent.

    
    
    Source
  


->EmptyElementEvent

function
Usage: (->EmptyElementEvent tag attrs nss location-info)
Positional factory function for class clojure.data.xml.event.EmptyElementEvent.

    
    
    Source
  


->QNameEvent

function
Usage: (->QNameEvent qn)
Positional factory function for class clojure.data.xml.event.QNameEvent.

    
    
    Source
  


->StartElementEvent

function
Usage: (->StartElementEvent tag attrs nss location-info)
Positional factory function for class clojure.data.xml.event.StartElementEvent.

    
    
    Source
  


element-nss

function
Usage: (element-nss {:keys [attrs], :as element})
Get xmlns environment from element

    
    
    Source
  


map->CDataEvent

function
Usage: (map->CDataEvent m#)
Factory function for class clojure.data.xml.event.CDataEvent, taking a map of keywords to field values.

    
    
    Source
  


map->CharsEvent

function
Usage: (map->CharsEvent m#)
Factory function for class clojure.data.xml.event.CharsEvent, taking a map of keywords to field values.

    
    
    Source
  


map->CommentEvent

function
Usage: (map->CommentEvent m#)
Factory function for class clojure.data.xml.event.CommentEvent, taking a map of keywords to field values.

    
    
    Source
  


map->EmptyElementEvent

function
Usage: (map->EmptyElementEvent m#)
Factory function for class clojure.data.xml.event.EmptyElementEvent, taking a map of keywords to field values.

    
    
    Source
  


map->QNameEvent

function
Usage: (map->QNameEvent m#)
Factory function for class clojure.data.xml.event.QNameEvent, taking a map of keywords to field values.

    
    
    Source
  


map->StartElementEvent

function
Usage: (map->StartElementEvent m#)
Factory function for class clojure.data.xml.event.StartElementEvent, taking a map of keywords to field values.

    
    
    Source
  

clojure.data.xml.impl

Shared private code for data.xml namespaces

Public Variables and Functions



compile-if

macro
Usage: (compile-if exp then else)
Evaluate `exp` and if it returns logical true and doesn't error, expand to
`then`.  Else expand to `else`.

see clojure.core.reducers

    
    
    Source
  


export-api

macro
Usage: (export-api & names)
This creates vars, that take their (local) name, value and metadata from another var

    
    
    Source
  


extend-protocol-fns

macro
Usage: (extend-protocol-fns proto & types+mmaps)
Helper to many types to a protocol with a method map, similar to extend

    
    
    Source
  


static-case

macro
Usage: (static-case val & cases)
Variant of case where keys are evaluated at compile-time

    
    
    Source
  

clojure.data.xml.jvm.emit

JVM implementation of the emitter details

Public Variables and Functions



write-document

function
Usage: (write-document swriter events opts)
Writes the given event seq as XML text to writer.
Options:
 :encoding <str>          Character encoding to use
 :doctype  <str>          Document type (DOCTYPE) declaration to use

    
    
    Source
  

clojure.data.xml.jvm.parse





Public Variables and Functions



pull-seq

function
Usage: (pull-seq sreader {:keys [include-node? location-info skip-whitespace], :as opts} ns-envs)
Creates a seq of events.  The XMLStreamConstants/SPACE clause below doesn't seem to
be triggered by the JDK StAX parser, but is by others.  Leaving in to be more complete.

    
    
    Source
  

clojure.data.xml.name





Public Variables and Functions



*gen-prefix-counter*

dynamic var

    
Thread local counter for a single document

    
    
    Source
  


alias-uri

function
Usage: (alias-uri & {:as alias-nss})
Define a Clojure namespace aliases for xmlns uris.

This sets up the current namespace for reading qnames denoted with
Clojure's ::alias/keywords reader feature.


## Example
(alias-uri :D "DAV:")
                         ; similar in effect to
;; (require '[xmlns.DAV%3A :as D])
                         ; but required namespace is auto-created
                         ; henceforth, shorthand keywords can be used
{:tag ::D/propfind}
                         ; ::D/propfind will be expanded to :xmlns.DAV%3A/propfind
                         ; in the current namespace by the reader

## Clojurescript support
Currently, namespaces can't be auto-created in Clojurescript.
Dummy files for aliased uris have to exist. Have a look at `uri-file` and `print-uri-file-command!` to create those.

    
    
    Source
  


gen-prefix

function
Usage: (gen-prefix)
       (gen-prefix n)
Generates an xml prefix.
Zero-arity can only be called, when *gen-prefix-counter* is bound and will increment it.

    
    
    Source
  


print-uri-file-command!

function
Usage: (print-uri-file-command! uri)
Shell command to create a dummy file for xmlns. Execute from a source root.

    
    
    Source
  


qname-local

function
Usage: (qname-local v)
Get the name for this qname

    
    
    Source
  


qname-uri

function
Usage: (qname-uri v)
Get the namespace uri for this qname

    
    
    Source
  


separate-xmlns

function
Usage: (separate-xmlns attrs cont)
Call cont with two args: attributes and xmlns attributes

    
    
    Source
  


uri-file

function
Usage: (uri-file uri)
Dummy file name for :require'ing xmlns uri

    
    
    Source
  


xmlns-attr?

function
Usage: (xmlns-attr? qn)
Is this qname an xmlns declaration?

    
    
    Source
  

clojure.data.xml.node

Data types for xml nodes: Element, CData and Comment

Types



CData

record

    Fields: [content]
Protocols:
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map


Comment

record

    Fields: [content]
Protocols:
Interfaces: clojure.lang.IHashEq, clojure.lang.IKeywordLookup, clojure.lang.ILookup, clojure.lang.IObj, clojure.lang.IPersistentMap, java.io.Serializable, java.util.Map


Element

type

    Fields: [tag attrs content meta]
Protocols:
Interfaces: clojure.lang.IHashEq, clojure.lang.IObj, clojure.lang.IPersistentMap, clojure.lang.MapEquivalence, java.io.Serializable, java.lang.Iterable, java.util.Map


ElementIterator

type

    Fields: [el fields]
Protocols:
Interfaces: java.util.Iterator

Public Variables and Functions



->CData

function
Usage: (->CData content)
Positional factory function for class clojure.data.xml.node.CData.

    
    
    Source
  


->Comment

function
Usage: (->Comment content)
Positional factory function for class clojure.data.xml.node.Comment.

    
    
    Source
  


->Element

function
Usage: (->Element tag attrs content meta)
Positional factory function for class clojure.data.xml.node.Element.

    
    
    Source
  


->ElementIterator

function
Usage: (->ElementIterator el fields)
Positional factory function for class clojure.data.xml.node.ElementIterator.

    
    
    Source
  


cdata

function
Usage: (cdata content)
Create a CData node

    
    
    Source
  


element

function
Usage: (element tag)
       (element tag attrs)
       (element tag attrs & content)
Create an xml Element from content varargs

    
    
    Source
  


element*

function
Usage: (element* tag attrs content meta)
       (element* tag attrs content)
Create an xml element from a content collection and optional metadata

    
    
    Source
  


map->CData

function
Usage: (map->CData m#)
Factory function for class clojure.data.xml.node.CData, taking a map of keywords to field values.

    
    
    Source
  


map->Comment

function
Usage: (map->Comment m#)
Factory function for class clojure.data.xml.node.Comment, taking a map of keywords to field values.

    
    
    Source
  


xml-comment

function
Usage: (xml-comment content)
Create a Comment node

    
    
    Source
  

clojure.data.xml.process





Public Variables and Functions



aggregate-xmlns

function
Usage: (aggregate-xmlns xml)
Put all occurring xmlns into the root

    
    
    Source
  


find-xmlns

function
Usage: (find-xmlns xml)
Find all xmlns occuring in a root

    
    
    Source
  

clojure.data.xml.protocols





Protocols



AsElements

Protocol

    Known implementations: clojure.lang.IPersistentVector, clojure.lang.ISeq, clojure.lang.Keyword, java.lang.String, nil, Object
    

as-elements

function
Usage: (as-elements expr)
Return a seq of elements represented by an expression.

      
      
      
    
Source


AsQName

Protocol

    Known implementations: clojure.lang.Keyword, java.lang.String, javax.xml.namespace.QName
    

qname-local

function
Usage: (qname-local qname)
Get the name for this qname

      
      
      
    

qname-uri

function
Usage: (qname-uri qname)
Get the namespace uri for this qname

      
      
      
    
Source


AsXmlString

Protocol

    Known implementations: array-of-bytes, clojure.lang.BigInt, clojure.lang.Ratio, java.lang.Boolean, java.lang.Byte, java.lang.Character, java.lang.Double, java.lang.Float, java.lang.Integer, java.lang.Long, java.lang.Short, java.lang.String, java.math.BigDecimal, java.math.BigInteger, java.net.URI, java.net.URL, java.time.Instant, java.util.Date, nil
    

xml-str

function
Usage: (xml-str node)
Serialize atribute value or content node

      
      
      
    
Source


EventGeneration

Protocol
Protocol for generating new events based on element type
Known implementations: array-of-bytes, clojure.data.xml.event.CDataEvent, clojure.data.xml.event.CDataEvent, clojure.data.xml.event.CharsEvent, clojure.data.xml.event.CharsEvent, clojure.data.xml.event.CommentEvent, clojure.data.xml.event.CommentEvent, clojure.data.xml.event.EmptyElementEvent, clojure.data.xml.event.EmptyElementEvent, clojure.data.xml.event.EndElementEvent, clojure.data.xml.event.EndElementEvent, clojure.data.xml.event.StartElementEvent, clojure.data.xml.event.StartElementEvent, clojure.data.xml.node.CData, clojure.data.xml.node.Comment, clojure.data.xml.node.Element, clojure.lang.IPersistentMap, clojure.lang.Keyword, clojure.lang.Sequential, java.lang.Boolean, java.lang.Number, java.lang.String, java.net.URI, java.net.URL, java.time.Instant, java.util.Date, javax.xml.namespace.QName, nil

gen-event

function
Usage: (gen-event item)
Function to generate an event for e.

      
      
      
    

next-events

function
Usage: (next-events item next-items)
Returns the next set of events that should occur after e.  next-events are the
events that should be generated after this one is complete.

      
      
      
    
Source

clojure.data.xml.prxml





Public Variables and Functions



sexp-as-element

function
Usage: (sexp-as-element sexp)
Convert a single sexp into an Element

    
    
    Source
  


sexps-as-fragment

function
Usage: (sexps-as-fragment)
       (sexps-as-fragment sexp)
       (sexps-as-fragment sexp & sexps)
Convert a compact prxml/hiccup-style data structure into the more formal
tag/attrs/content format. A seq of elements will be returned, which may
not be suitable for immediate use as there is no root element. See also
sexp-as-element.

The format is [:tag-name attr-map? content*]. Each vector opens a new tag;
seqs do not open new tags, and are just used for inserting groups of elements
into the parent tag. A bare keyword not in a vector creates an empty element.

To provide XML conversion for your own data types, extend the AsElements
protocol to them.

    
    
    Source
  

clojure.data.xml.pu-map

Provides a bidirectional mapping for keeping track of prefix->uri mappings in xml namespaces.

This has the semantics of a basic key -> multiple values map + two special features, both of which are dictated by the xml standard:

- instead of a special dissoc, there is assoc to empty string or nil
- there are two fixed, unique mappings:
  - "xml" <-> ["http://www.w3.org/2000/xmlns/"]
  - "xmlns" <-> ["http://www.w3.org/XML/1998/namespace"]

Public Variables and Functions



merge

function
Usage: (merge pu {:keys [:p->u]})
Merge two pu-maps, left to right

    
    
    Source
  


merge-prefix-map

function
Usage: (merge-prefix-map pu pm)
Merge a prefix map into pu-map

    
    
    Source
  


reduce-diff

function
Usage: (reduce-diff f s {ppu :p->u} {pu :p->u})
A high-performance diffing operation, that reduces f over changed and removed prefixes

    
    
    Source
  

clojure.data.xml.tree





Public Variables and Functions



event-tree

function
Usage: (event-tree events)
Returns a lazy tree of Element objects for the given seq of Event
objects. See source-seq and parse.

    
    
    Source
  


flatten-elements

function
Usage: (flatten-elements elements)
Flatten a collection of elements to an event seq

    
    
    Source
  


seq-tree

function
Usage: (seq-tree parent exit? node coll)
Takes a seq of events that logically represents
a tree by each event being one of: enter-sub-tree event,
exit-sub-tree event, or node event.

Returns a lazy sequence whose first element is a sequence of
sub-trees and whose remaining elements are events that are not
siblings or descendants of the initial event.

The given exit? function must return true for any exit-sub-tree
event.  parent must be a function of two arguments: the first is an
event, the second a sequence of nodes or subtrees that are children
of the event.  parent must return nil or false if the event is not
an enter-sub-tree event.  Any other return value will become
a sub-tree of the output tree and should normally contain in some
way the children passed as the second arg.  The node function is
called with a single event arg on every event that is neither parent
nor exit, and its return value will become a node of the output tree.

(seq-tree #(when (= %1 :<) (vector %2)) #{:>} str
          [1 2 :< 3 :< 4 :> :> 5 :> 6])
;=> (("1" "2" [("3" [("4")])] "5") 6)

    
    
    Source
  
Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.