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

Imports

macros, strtabs

Types

PXmlNode = ref TXmlNode: an XML tree consists of PXmlNode's.
TXmlNodeKind = 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
PXmlAttributes = PStringTable: an alias for a string to string mapping

Consts

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

Procs

proc newElement(tag: string): PXmlNode {.raises: [], tags: [].}

creates a new PXmlNode of kind xnText with the given tag.

proc newText(text: string): PXmlNode {.raises: [], tags: [].}

creates a new PXmlNode of kind xnText with the text text.

proc newComment(comment: string): PXmlNode {.raises: [], tags: [].}

creates a new PXmlNode of kind xnComment with the text comment.

proc newCData(cdata: string): PXmlNode {.raises: [], tags: [].}

creates a new PXmlNode of kind xnComment with the text cdata.

proc newEntity(entity: string): PXmlNode {.raises: [], tags: [].}

creates a new PXmlNode of kind xnEntity with the text entity.

proc text(n: PXmlNode): string {.inline, raises: [], tags: [].}

gets the associated text with the node n. n can be a CDATA, Text, comment, or entity node.

proc rawText(n: PXmlNode): string {.inline, raises: [], tags: [].}

returns the underlying 'text' string by reference. This is only used for speed hacks.

proc rawTag(n: PXmlNode): string {.inline, raises: [], tags: [].}

returns the underlying 'tag' string by reference. This is only used for speed hacks.

proc innerText(n: PXmlNode): string {.raises: [], tags: [].}

gets the inner text of n. n has to be an xnElement node. Only xnText and xnEntity nodes are considered part of n's inner text, other child nodes are silently ignored.

proc tag(n: PXmlNode): string {.inline, raises: [], tags: [].}

gets the tag name of n. n has to be an xnElement node.

proc add(father, son: PXmlNode) {.inline, raises: [], tags: [].}

adds the child son to father.

proc len(n: PXmlNode): int {.inline, raises: [], tags: [].}

returns the number n's children.

proc kind(n: PXmlNode): TXmlNodeKind {.inline, raises: [], tags: [].}

returns n's kind.

proc `[]`(n: PXmlNode; i: int): PXmlNode {.inline, raises: [], tags: [].}

returns the i'th child of n.

proc attrs(n: PXmlNode): PXmlAttributes {.inline, raises: [], tags: [].}

gets the attributes belonging to n. Returns nil if attributes have not been initialised for this node.

proc attrs=(n: PXmlNode; attr: PXmlAttributes) {.inline, raises: [], tags: [].}

sets the attributes belonging to n.

proc attrsLen(n: PXmlNode): int {.inline, raises: [], tags: [].}

returns the number of n's attributes.

proc clientData(n: PXmlNode): int {.inline, raises: [], tags: [].}

gets the client data of n. The client data field is used by the HTML parser and generator.

proc clientData=(n: PXmlNode; data: int) {.inline, raises: [], tags: [].}

sets the client data of n. The client data field is used by the HTML parser and generator.

proc addEscaped(result: var string; s: string) {.raises: [], tags: [].}

same as result.add(escape(s)), but more efficient.

proc escape(s: string): string {.raises: [], tags: [].}

escapes s for inclusion into an XML document. Escapes these characters:

char	is converted to
`<`	`<`
`>`	`>`
`&`	`&`
`"`	`"`

proc add(result: var string; n: PXmlNode; indent = 0; indWidth = 2) {. raises: [], tags: [].}

adds the textual representation of n to result.

proc `$`(n: PXmlNode): string {.raises: [], tags: [].}

converts n into its string representation. No <$xml ...$> declaration is produced, so that the produced XML fragments are composable.

proc newXmlTree(tag: string; children: openArray[PXmlNode]; attributes: PXmlAttributes = nil): PXmlNode {.raises: [], tags: [].}

creates a new XML tree with tag, children and attributes

proc child(n: PXmlNode; name: string): PXmlNode {.raises: [], tags: [].}

Finds the first child element of n with a name of name. Returns nil on failure.

proc attr(n: PXmlNode; name: string): string {.raises: [], tags: [].}

Finds the first attribute of n with a name of name. Returns "" on failure.

proc findAll(n: PXmlNode; tag: string; result: var seq[PXmlNode]) {.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: PXmlNode
  tags: seq[PXmlNode] = @[]

html = buildHtml()
findAll(html, "img", tags)
for imgTag in tags:
  process(imgTag)

proc findAll(n: PXmlNode; tag: string): seq[PXmlNode] {.raises: [], tags: [].}

Shortcut version to assign in let blocks. Example:

var html: PXmlNode

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

Iterators

iterator items(n: PXmlNode): PXmlNode {.inline, raises: [], tags: [].}: iterates over any child of n.

Macros

macro `<>`(x: expr): expr {.immediate.}

Constructor macro for XML. Example usage:

<>a(href="http://nimrod-code.org", newText("Nimrod rules."))

Produces an XML tree for: