riveted.core

A Clojure library for the fast processing of XML with VTD-XML.

at

(at navigator xpath)(at navigator xpath prefix url)
Search for the given XPath in the navigator, returning the first matching
navigator. If used with a namespace aware navigator, also takes a namespace
prefix and URL for use in the XPath.

Examples:

  ; Returns a single navigator for the first matching element.
  (at nav "/article/title")

  ; Returns a single navigator for the first matching element providing
  ; ns-nav is namespace aware.
  (at ns-nav "//ns1:title" "ns1" "http://example.com/ns")

attr

(attr navigator attr-name)
Return the value of the named attribute for the given navigator.
Attributes can be specified with either a keyword or string name.

Examples:

  (attr (root nav) :lang)
  ;=> "en"

attr?

(attr? navigator attr-name)
Test whether the given attribute exists on the current element.
Attributes can be specified with either a keyword or string name.

Examples:

  (attr? (root nav) :lang)
  ;=> true

attribute?

(attribute? navigator)
Tests whether the given navigator is currently positioned on an attribute.

children

(children navigator)(children navigator element)
Return a lazy sequence of navigators for all child nodes of the given
navigator (optionally restricted by a given element type).

Examples:

  ; Return navigators for all children of nav.
  (children nav)

  ; Return navigators for all child p elements of nav.
  (children nav :p)

document?

(document? navigator)
Tests whether the given navigator is currently positioned the document.

element?

(element? navigator)
Tests whether the given navigator is currently positioned on an element.

first-child

(first-child navigator)(first-child navigator element)
Return a new navigator pointing to the current element's first child element
(restricted by an optional element type).

Examples:

  ; Return a new navigator pointing to the first child element of nav.
  (first-child nav)

  ; Return a new navigator pointing to the first child b element of nav.
  (first-child nav :b)

first-child!

(first-child! navigator)(first-child! navigator element)
Move the given navigator to the current element's first child element
(restricted by an optional element type), mutating it in place.

Examples:

  ; Move nav to the first child element.
  (first-child! nav)

  ; Move nav to the first child b element.
  (first-child! nav :b)

fragment

(fragment navigator)
Return a string XML fragment for all nodes under the given navigator.

Examples:

  (fragment nav)
  ;=> "<b>Some</b> XML as a raw <i>string</i>"

last-child

(last-child navigator)(last-child navigator element)
Return a new navigator pointing to the current element's last child element
(restricted by an optional element type).

Examples:

  ; Return a new navigator pointing to the last child element of nav.
  (last-child nav)

  ; Return a new navigator pointing to the last child b element of nav.
  (last-child nav :b)

last-child!

(last-child! navigator)(last-child! navigator element)
Move the given navigator to the current element's last child element
(restricted by an optional element type), mutating it in place.

Examples:

  ; Move nav to the last child element.
  (last-child! nav)

  ; Move nav to the last child b element.
  (last-child! nav :b)

navigator

(navigator xml)(navigator xml namespace-aware)
Return a VTD navigator for the given UTF-8 XML string with optional
namespace support. If called with only a string of XML, namespace support is
disabled.

Examples:

  ; Return a navigator for the given string with no namespace support.
  (navigator "<root><foo>Bar</foo></root>")

  ; Return a navigator for the given string with namespace support.
  (navigator "<root xmlns:ns=\"http://example.com/ns\"><foo>Bar</foo></root>" true)

next-sibling

(next-sibling navigator)(next-sibling navigator element)
Return a new navigator pointing to the current element's next sibling element
(restricted by an optional element type).

Examples:

  ; Return a new navigator pointing to the next sibling element of nav.
  (next-sibling nav)

  ; Return a new navigator pointing to the next sibling b element of nav.
  (next-sibling nav :b)

next-sibling!

(next-sibling! navigator)(next-sibling! navigator element)
Move the given navigator to the current element's next sibling element
(restricted by an optional element type), mutating it in place.

Examples:

  ; Move nav to the next sibling element.
  (next-sibling! nav)

  ; Move nav to the next sibling b element.
  (next-sibling! nav :b)

next-siblings

(next-siblings navigator)(next-siblings navigator element)
Return a lazy sequence of navigators representing all siblings next to the
given navigator (optionally restricted by a given element type).

Examples:

  ; Return navigators for every next sibling element to nav.
  (next-siblings nav)

  ; Return navigators for every next sibling p element to nav.
  (next-siblings nav :p)

parent

(parent navigator)
Return a new navigator pointing to the parent element of the given
navigator.

parent!

(parent! navigator)
Move the given navigator to the current element's parent element, mutating
it in place.

previous-sibling

(previous-sibling navigator)(previous-sibling navigator element)
Return a new navigator pointing to the current element's previous sibling
element (restricted by an optional element type).

Examples:

  ; Return a new navigator pointing to the previous sibling element of nav.
  (previous-sibling nav)

  ; Return a new navigator pointing to the previous sibling b element of nav.
  (previous-sibling nav :b)

previous-sibling!

(previous-sibling! navigator)(previous-sibling! navigator element)
Move the given navigator to the current element's previous sibling element
(restricted by an optional element type), mutating it in place.

Examples:

  ; Move nav to the previous sibling element.
  (previous-sibling! nav)

  ; Move nav to the previous sibling b element.
  (previous-sibling! nav :b)

previous-siblings

(previous-siblings navigator)(previous-siblings navigator element)
Return a lazy sequence of navigators representing all siblings previous to
the given navigator (optionally restricted by a given element type).

Note that this is lazily evaluated right-to-left so the final sequence will
be in reverse order to the actual nodes in the document.

Examples:

  ; Return navigators for every previous sibling element to nav.
  (previous-siblings nav)

  ; Return navigators for every previous sibling p element to nav.
  (previous-siblings nav :p)

root

(root navigator)
Return a new navigator pointing to the document root.

root!

(root! navigator)
Move the given navigator to the document root, mutating it in place.

select

(select navigator element)
Return a lazy sequence of navigators matching the given element name, * can
be used to match all elements.

Examples:

  ; Returns navigators for each element in nav.
  (select nav "*")

  ; Returns navigators for all b elements in nav.
  (select nav "b")

siblings

(siblings navigator)(siblings navigator element)
Return navigators for all siblings to the given navigator (optionally
restricted by a given element type).

Note that this is not lazy in order to preserve the correct order of nodes
and previous siblings need to be fully realised for sorting.

Examples:

  ; Return navigators for all siblings to nav.
  (siblings nav)

  ; Return navigators for all sibling p elements to nav.
  (siblings nav :p)

tag

(tag navigator)
Return the tag name for the element under the given VTD navigator as a
string. If positioned on an attribute (e.g. with an XPath like /@foo), return
the name of the attribute.

Examples:

  (tag (root nav))
  ;=> "root"

  (tag (at nav "/channel/@id"))
  ;=> "id"

text

(text navigator)
Return all descendant text content below the given navigator as one string.
This means both the value of a simple text node and also the resulting text
value of a mixed content node such as <p><b>Foo</b> bar</p>. If the navigator
is currently positioned on an attribute (e.g. by using an XPath like /@foo),
return the value of the attribute.

Examples:

  ; Returns "Foo" given nav points to <p>Foo</p>
  (text nav)

  ; Returns "Foo bar" given nav points to <p><b>Foo</b> bar</p>
  (text nav)

  ; Returns "123" given nav points to @src of <img src="123"/>
  (text nav)