Module xmltree

A simple XML tree. More efficient and simpler than the DOM.

Types

XmlNode = ref XmlNodeObj
an XML tree consists of PXmlNode's.   Source Edit
XmlNodeKind = enum
  xnText,                     ## a text element
  xnElement,                  ## an element with 0 or more children
  xnCData,                    ## a CDATA node
  xnEntity,                   ## an entity (like ``&thing;``)
  xnComment                   ## an XML comment
different kinds of PXmlNode's   Source Edit
XmlAttributes = StringTableRef
an alias for a string to string mapping   Source Edit

Consts

xmlHeader = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\x0A"
header to use for complete XML output   Source Edit

Procs

proc newElement(tag: string): XmlNode {.
raises: [], tags: []
.}
creates a new PXmlNode of kind xnText with the given tag.   Source Edit
proc newText(text: string): XmlNode {.
raises: [], tags: []
.}
creates a new PXmlNode of kind xnText with the text text.   Source Edit
proc newComment(comment: string): XmlNode {.
raises: [], tags: []
.}
creates a new PXmlNode of kind xnComment with the text comment.   Source Edit
proc newCData(cdata: string): XmlNode {.
raises: [], tags: []
.}
creates a new PXmlNode of kind xnComment with the text cdata.   Source Edit
proc newEntity(entity: string): XmlNode {.
raises: [], tags: []
.}
creates a new PXmlNode of kind xnEntity with the text entity.   Source Edit
proc text(n: XmlNode): string {.
inline, raises: [], tags: []
.}
gets the associated text with the node n. n can be a CDATA, Text, comment, or entity node.   Source Edit
proc text=(n: XmlNode; text: string) {.
inline, raises: [], tags: []
.}
sets the associated text with the node n. n can be a CDATA, Text, comment, or entity node.   Source Edit
proc rawText(n: XmlNode): string {.
inline, raises: [], tags: []
.}
returns the underlying 'text' string by reference. This is only used for speed hacks.   Source Edit
proc rawTag(n: XmlNode): string {.
inline, raises: [], tags: []
.}
returns the underlying 'tag' string by reference. This is only used for speed hacks.   Source Edit
proc innerText(n: XmlNode): string {.
raises: [], tags: []
.}
gets the inner text of n:
  • If n is xnText or xnEntity, returns its content.
  • If n is xnElement, runs recursively on each child node and concatenates the results.
  • Otherwise returns an empty string.
  Source Edit
proc tag(n: XmlNode): string {.
inline, raises: [], tags: []
.}
gets the tag name of n. n has to be an xnElement node.   Source Edit
proc tag=(n: XmlNode; tag: string) {.
inline, raises: [], tags: []
.}
sets the tag name of n. n has to be an xnElement node.   Source Edit
proc add(father, son: XmlNode) {.
inline, raises: [], tags: []
.}
adds the child son to father.   Source Edit
proc insert(father, son: XmlNode; index: int) {.
inline, raises: [], tags: []
.}
insert the child son to a given position in father.   Source Edit
proc len(n: XmlNode): int {.
inline, raises: [], tags: []
.}
returns the number n's children.   Source Edit
proc kind(n: XmlNode): XmlNodeKind {.
inline, raises: [], tags: []
.}
returns n's kind.   Source Edit
proc `[]`(n: XmlNode; i: int): XmlNode {.
inline, raises: [], tags: []
.}
returns the i'th child of n.   Source Edit
proc delete(n: XmlNode; i: Natural) {.
noSideEffect, raises: [], tags: []
.}
delete the i'th child of n.   Source Edit
proc `[]`(n: var XmlNode; i: int): var XmlNode {.
inline, raises: [], tags: []
.}
returns the i'th child of n so that it can be modified   Source Edit
proc mget(n: var XmlNode; i: int): var XmlNode {.
inline, deprecated, raises: [], tags: []
.}
returns the i'th child of n so that it can be modified. Use ```[]``` instead.   Source Edit
proc attrs(n: XmlNode): XmlAttributes {.
inline, raises: [], tags: []
.}
gets the attributes belonging to n. Returns nil if attributes have not been initialised for this node.   Source Edit
proc attrs=(n: XmlNode; attr: XmlAttributes) {.
inline, raises: [], tags: []
.}
sets the attributes belonging to n.   Source Edit
proc attrsLen(n: XmlNode): int {.
inline, raises: [], tags: []
.}
returns the number of n's attributes.   Source Edit
proc clientData(n: XmlNode): int {.
inline, raises: [], tags: []
.}
gets the client data of n. The client data field is used by the HTML parser and generator.   Source Edit
proc clientData=(n: XmlNode; data: int) {.
inline, raises: [], tags: []
.}
sets the client data of n. The client data field is used by the HTML parser and generator.   Source Edit
proc addEscaped(result: var string; s: string) {.
raises: [], tags: []
.}
same as result.add(escape(s)), but more efficient.   Source Edit
proc escape(s: string): string {.
raises: [], tags: []
.}
escapes s for inclusion into an XML document. Escapes these characters:
charis converted to
<&lt;
>&gt;
&&amp;
"&quot;
'&#x27;
/&#x2F;
  Source Edit
proc add(result: var string; n: XmlNode; indent = 0; indWidth = 2) {.
raises: [], tags: []
.}
adds the textual representation of n to result.   Source Edit
proc `$`(n: XmlNode): string {.
raises: [], tags: []
.}
converts n into its string representation. No <$xml ...$> declaration is produced, so that the produced XML fragments are composable.   Source Edit
proc newXmlTree(tag: string; children: openArray[XmlNode];
               attributes: XmlAttributes = nil): XmlNode {.
raises: [], tags: []
.}
creates a new XML tree with tag, children and attributes   Source Edit
proc child(n: XmlNode; name: string): XmlNode {.
raises: [], tags: []
.}
Finds the first child element of n with a name of name. Returns nil on failure.   Source Edit
proc attr(n: XmlNode; name: string): string {.
raises: [], tags: []
.}
Finds the first attribute of n with a name of name. Returns "" on failure.   Source Edit
proc findAll(n: XmlNode; tag: string; result: var seq[XmlNode]) {.
raises: [], tags: []
.}

Iterates over all the children of n returning those matching tag.

Found nodes satisfying the condition will be appended to the result sequence, which can't be nil or the proc will crash. Usage example:

var
  html: XmlNode
  tags: seq[XmlNode] = @[]

html = buildHtml()
findAll(html, "img", tags)
for imgTag in tags:
  process(imgTag)
  Source Edit
proc findAll(n: XmlNode; tag: string): seq[XmlNode] {.
raises: [], tags: []
.}
Shortcut version to assign in let blocks. Example:
var html: XmlNode

html = buildHtml(html)
for imgTag in html.findAll("img"):
  process(imgTag)
  Source Edit

Iterators

iterator items(n: XmlNode): XmlNode {.
inline, raises: [], tags: []
.}
iterates over any child of n.   Source Edit
iterator mitems(n: var XmlNode): var XmlNode {.
inline, raises: [], tags: []
.}
iterates over any child of n.   Source Edit

Macros

macro `<>`(x: expr): expr {.
immediate
.}
Constructor macro for XML. Example usage:
<>a(href="http://nim-lang.org", newText("Nim rules."))

Produces an XML tree for:

<a href="http://nim-lang.org">Nim rules.</a>

  Source Edit