Module xmltree

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

Imports

macros, strtabs

Types

XmlNode = ref XmlNodeObj

an XML tree consists of PXmlNode's.

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

XmlAttributes = StringTableRef

an alias for a string to string mapping

Consts

xmlHeader = "<?xml version=\"1.0\" encoding=\"UTF-8\" ?>\x0D\x0A"

header to use for complete XML output

Procs

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

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

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

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

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

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

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

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

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

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

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.

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.

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

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

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

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

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.

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

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

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

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

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

adds the child son to father.

proc insert(father, son: XmlNode; index: int) {.inline, raises: [], tags: [].}

insert the child son to a given position in father.

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

returns the number n's children.

proc kind(n: XmlNode): XmlNodeKind {.inline, raises: [], tags: [].}

returns n's kind.

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

returns the i'th child of n.

proc delete(n: XmlNode; i: Natural) {.noSideEffect, raises: [], tags: [].}

delete the i'th child of n.

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

returns the i'th child of n so that it can be modified

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.

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.

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

sets the attributes belonging to n.

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

returns the number of n's attributes.

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.

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.

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
<	&lt;
>	&gt;
&	&amp;
"	&quot;
'	&#x27;
/	&#x2F;

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

adds the textual representation of n to result.

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.

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

creates a new XML tree with tag, children and attributes

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.

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

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

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)

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)

Iterators

iterator items(n: XmlNode): XmlNode {.inline, raises: [], tags: [].}

iterates over any child of n.

iterator mitems(n: var XmlNode): var XmlNode {.inline, raises: [], tags: [].}

iterates over any child of n.

Macros

macro `<>`(x: untyped): untyped

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>