std/xmltree

Source Edit

A simple XML tree generator.

Example:

import std/xmltree
var g = newElement("myTag")
g.add newText("some text")
g.add newComment("this is comment")

var h = newElement("secondTag")
h.add newEntity("some entity")

let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
let k = newXmlTree("treeTag", [g, h], att)

doAssert $k == """<treeTag key1="first value" key2="second value">
  <myTag>some text<!-- this is comment --></myTag>
  <secondTag>&some entity;</secondTag>
</treeTag>"""

See also:

• xmlparser module for high-level XML parsing
• parsexml module for low-level XML parsing
• htmlgen module for html code generator

Imports

since, macros, strtabs, strutils, sequtils

Types

XmlAttributes = StringTableRef

An alias for a string to string mapping.

Use toXmlAttributes proc to create XmlAttributes.

Source Edit

XmlNode = ref XmlNodeObj

An XML tree consisting of XML nodes.

Use newXmlTree proc for creating a new tree.

Source Edit

XmlNodeKind = enum
  xnText,                   ## a text element
  xnVerbatimText, xnElement, ## an element with 0 or more children
  xnCData,                  ## a CDATA node
  xnEntity,                 ## an entity (like ``&thing;``)
  xnComment                  ## an XML comment

Different kinds of XML nodes. Source Edit

Consts

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

Header to use for complete XML output. Source Edit

Procs

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

Converts n into its string representation.

No <$xml ...$> declaration is produced, so that the produced XML fragments are composable.

Source Edit

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

Returns the i'th child of n so that it can be modified. Source Edit

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

Returns the i'th child of n.

Example:

var f = newElement("myTag")
f.add newElement("first")
f.insert(newElement("second"), 0)
assert $f[1] == "<first />"
assert $f[0] == "<second />"

Source Edit

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

Adds the child son to father. father must be of xnElement type

See also:

• add proc
• insert proc
• insert proc
• delete proc
• delete proc
• replace proc
• replace proc

Example:

var f = newElement("myTag")
f.add newText("my text")
f.add newElement("sonTag")
f.add newEntity("my entity")
assert $f == "<myTag>my text<sonTag />&my entity;</myTag>"

Source Edit

proc add(father: XmlNode; sons: openArray[XmlNode]) {.inline, ...raises: [],
    tags: [], forbids: [].}

Adds the children sons to father. father must be of xnElement type

See also:

• add proc
• insert proc
• insert proc
• delete proc
• delete proc
• replace proc
• replace proc

Example:

var f = newElement("myTag")
f.add(@[newText("my text"), newElement("sonTag"), newEntity("my entity")])
assert $f == "<myTag>my text<sonTag />&my entity;</myTag>"

Source Edit

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

Adds the textual representation of n to string result.

Example:

var
  a = newElement("firstTag")
  b = newText("my text")
  c = newComment("my comment")
  s = ""
s.add(c)
s.add(a)
s.add(b)
assert s == "<!-- my comment --><firstTag />my text"

Source Edit

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

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

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

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

See also:

• attrs proc for XmlAttributes getter
• attrs= proc for XmlAttributes setter
• attrsLen proc for number of attributes

Example:

var j = newElement("myTag")
let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
j.attrs = att
assert j.attr("key1") == "first value"
assert j.attr("key2") == "second value"

Source Edit

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

Gets the attributes belonging to n.

Returns nil if attributes have not been initialised for this node.

See also:

• attrs= proc for XmlAttributes setter
• attrsLen proc for number of attributes
• attr proc for finding an attribute

Example:

var j = newElement("myTag")
assert j.attrs == nil
let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
j.attrs = att
assert j.attrs == att

Source Edit

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

Sets the attributes belonging to n.

See also:

• attrs proc for XmlAttributes getter
• attrsLen proc for number of attributes
• attr proc for finding an attribute

Example:

var j = newElement("myTag")
assert j.attrs == nil
let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
j.attrs = att
assert j.attrs == att

Source Edit

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

Returns the number of n's attributes.

See also:

• attrs proc for XmlAttributes getter
• attrs= proc for XmlAttributes setter
• attr proc for finding an attribute

Example:

var j = newElement("myTag")
assert j.attrsLen == 0
let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
j.attrs = att
assert j.attrsLen == 2

Source Edit

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

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

Example:

var f = newElement("myTag")
f.add newElement("firstSon")
f.add newElement("secondSon")
f.add newElement("thirdSon")
assert $(f.child("secondSon")) == "<secondSon />"

Source Edit

proc clear(n: var XmlNode) {....raises: [], tags: [], forbids: [].}

Recursively clears all children of an XmlNode.

Example:

var g = newElement("myTag")
g.add newText("some text")
g.add newComment("this is comment")

var h = newElement("secondTag")
h.add newEntity("some entity")

let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
var k = newXmlTree("treeTag", [g, h], att)

doAssert $k == """<treeTag key1="first value" key2="second value">
  <myTag>some text<!-- this is comment --></myTag>
  <secondTag>&some entity;</secondTag>
</treeTag>"""

clear(k)
doAssert $k == """<treeTag key1="first value" key2="second value" />"""

Source Edit

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

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: [],
    forbids: [].}

Sets the client data of n.

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

Source Edit

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

Deletes the i'th child of n.

See also:

• delete proc
• add proc
• add proc
• insert proc
• insert proc
• replace proc
• replace proc

Example:

var f = newElement("myTag")
f.add newElement("first")
f.insert(newElement("second"), 0)
f.delete(0)
assert $f == """<myTag>
  <first />
</myTag>"""

Source Edit

proc delete(n: XmlNode; slice: Slice[int]) {....raises: [], tags: [], forbids: [].}

Deletes the items n[slice] of n.

See also:

• delete proc
• add proc
• add proc
• insert proc
• insert proc
• replace proc
• replace proc

Example:

var f = newElement("myTag")
f.add newElement("first")
f.insert([newElement("second"), newElement("third")], 0)
f.delete(0..1)
assert $f == """<myTag>
  <first />
</myTag>"""

Source Edit

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

Escapes s for inclusion into an XML document.

Escapes these characters:

char	is converted to
<	&lt;
>	&gt;
&	&amp;
"	&quot;
'	&apos;

You can also use addEscaped proc.

Source Edit

proc findAll(n: XmlNode; tag: string; caseInsensitive = false): seq[XmlNode] {.
    ...raises: [], tags: [], forbids: [].}

A shortcut version to assign in let blocks.

Example:

var
  b = newElement("good")
  c = newElement("bad")
  d = newElement("BAD")
  e = newElement("GOOD")
b.add newText("b text")
c.add newText("c text")
d.add newText("d text")
e.add newText("e text")
let a = newXmlTree("father", [b, c, d, e])
assert $(a.findAll("good")) == "@[<good>b text</good>]"
assert $(a.findAll("BAD")) == "@[<BAD>d text</BAD>]"
assert $(a.findAll("good", caseInsensitive = true)) == "@[<good>b text</good>, <GOOD>e text</GOOD>]"
assert $(a.findAll("BAD", caseInsensitive = true)) == "@[<bad>c text</bad>, <BAD>d text</BAD>]"

Source Edit

proc findAll(n: XmlNode; tag: string; result: var seq[XmlNode];
             caseInsensitive = false) {....raises: [], tags: [], forbids: [].}

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

Found nodes satisfying the condition will be appended to the result sequence.

Example:

var
  b = newElement("good")
  c = newElement("bad")
  d = newElement("BAD")
  e = newElement("GOOD")
b.add newText("b text")
c.add newText("c text")
d.add newText("d text")
e.add newText("e text")
let a = newXmlTree("father", [b, c, d, e])
var s = newSeq[XmlNode]()
a.findAll("good", s)
assert $s == "@[<good>b text</good>]"
s.setLen(0)
a.findAll("good", s, caseInsensitive = true)
assert $s == "@[<good>b text</good>, <GOOD>e text</GOOD>]"
s.setLen(0)
a.findAll("BAD", s)
assert $s == "@[<BAD>d text</BAD>]"
s.setLen(0)
a.findAll("BAD", s, caseInsensitive = true)
assert $s == "@[<bad>c text</bad>, <BAD>d text</BAD>]"

Source Edit

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

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.

See also:

• text proc

Example:

var f = newElement("myTag")
f.add newText("my text")
f.add newComment("my comment")
f.add newEntity("my entity")
assert $f == "<myTag>my text<!-- my comment -->&my entity;</myTag>"
assert innerText(f) == "my textmy entity"

Source Edit

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

Inserts the child son to a given position in father.

father must be of xnElement kind.

See also:

• insert proc
• add proc
• add proc
• delete proc
• delete proc
• replace proc
• replace proc

Example:

var f = newElement("myTag")
f.add newElement("first")
f.insert(newElement("second"), 0)
assert $f == """<myTag>
  <second />
  <first />
</myTag>"""

Source Edit

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

Inserts the children openArray`sons` to a given position in father.

father must be of xnElement kind.

See also:

• insert proc
• add proc
• add proc
• delete proc
• delete proc
• replace proc
• replace proc

Example:

var f = newElement("myTag")
f.add newElement("first")
f.insert([newElement("second"), newElement("third")], 0)
assert $f == """<myTag>
  <second />
  <third />
  <first />
</myTag>"""

Source Edit

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

Returns n's kind.

Example:

var a = newElement("firstTag")
assert a.kind == xnElement
var b = newText("my text")
assert b.kind == xnText

Source Edit

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

Returns the number of n's children.

Example:

var f = newElement("myTag")
f.add newElement("first")
f.insert(newElement("second"), 0)
assert len(f) == 2

Source Edit

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

Creates a new XmlNode of kind xnCData with the text cdata.

Example:

var d = newCData("my cdata")
assert d.kind == xnCData
assert $d == "<![CDATA[my cdata]]>"

Source Edit

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

Creates a new XmlNode of kind xnComment with the text comment.

Example:

var c = newComment("my comment")
assert c.kind == xnComment
assert $c == "<!-- my comment -->"

Source Edit

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

Creates a new XmlNode of kind xnElement with the given tag.

See also:

• newXmlTree proc
• <> macro

Example:

var a = newElement("firstTag")
a.add newElement("childTag")
assert a.kind == xnElement
assert $a == """<firstTag>
  <childTag />
</firstTag>"""

Source Edit

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

Creates a new XmlNode of kind xnEntity with the text entity.

Example:

var e = newEntity("my entity")
assert e.kind == xnEntity
assert $e == "&my entity;"

Source Edit

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

Creates a new XmlNode of kind xnText with the text text.

Example:

var b = newText("my text")
assert b.kind == xnText
assert $b == "my text"

Source Edit

proc newVerbatimText(text: sink string): XmlNode {....raises: [], tags: [],
    forbids: [].}

Creates a new XmlNode of kind xnVerbatimText with the text text. Since: Version 1.3. Source Edit

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

Creates a new XML tree with tag, children and attributes.

See also:

• newElement proc
• <> macro

Example:

var g = newElement("myTag")
g.add newText("some text")
g.add newComment("this is comment")
var h = newElement("secondTag")
h.add newEntity("some entity")
let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
let k = newXmlTree("treeTag", [g, h], att)

doAssert $k == """<treeTag key1="first value" key2="second value">
  <myTag>some text<!-- this is comment --></myTag>
  <secondTag>&some entity;</secondTag>
</treeTag>"""

Source Edit

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

Returns the underlying 'tag' string by reference.

This is only used for speed hacks.

Source Edit

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

Returns the underlying 'text' string by reference.

This is only used for speed hacks.

Source Edit

proc replace(n: XmlNode; i: Natural; replacement: openArray[XmlNode]) {.
    ...raises: [], tags: [], forbids: [].}

Replaces the i'th child of n with replacement openArray.

n must be of xnElement kind.

See also:

• replace proc
• add proc
• add proc
• delete proc
• delete proc
• insert proc
• insert proc

Example:

var f = newElement("myTag")
f.add newElement("first")
f.insert(newElement("second"), 0)
f.replace(0, @[newElement("third"), newElement("fourth")])
assert $f == """<myTag>
  <third />
  <fourth />
  <first />
</myTag>"""

Source Edit

proc replace(n: XmlNode; slice: Slice[int]; replacement: openArray[XmlNode]) {.
    ...raises: [], tags: [], forbids: [].}

Deletes the items n[slice] of n.

n must be of xnElement kind.

See also:

• replace proc
• add proc
• add proc
• delete proc
• delete proc
• insert proc
• insert proc

Example:

var f = newElement("myTag")
f.add newElement("first")
f.insert([newElement("second"), newElement("fifth")], 0)
f.replace(0..1, @[newElement("third"), newElement("fourth")])
assert $f == """<myTag>
  <third />
  <fourth />
  <first />
</myTag>"""

Source Edit

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

Gets the tag name of n.

n has to be an xnElement node.

See also:

• text proc for text getter
• text= proc for text setter
• tag= proc for tag setter
• innerText proc

Example:

var a = newElement("firstTag")
a.add newElement("childTag")
assert $a == """<firstTag>
  <childTag />
</firstTag>"""
assert a.tag == "firstTag"

Source Edit

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

Sets the tag name of n.

n has to be an xnElement node.

See also:

• text proc for text getter
• text= proc for text setter
• tag proc for tag getter

Example:

var a = newElement("firstTag")
a.add newElement("childTag")
assert $a == """<firstTag>
  <childTag />
</firstTag>"""
a.tag = "newTag"
assert $a == """<newTag>
  <childTag />
</newTag>"""

Source Edit

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

Gets the associated text with the node n.

n can be a CDATA, Text, comment, or entity node.

See also:

• text= proc for text setter
• tag proc for tag getter
• tag= proc for tag setter
• innerText proc

Example:

var c = newComment("my comment")
assert $c == "<!-- my comment -->"
assert c.text == "my comment"

Source Edit

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

Sets the associated text with the node n.

n can be a CDATA, Text, comment, or entity node.

See also:

• text proc for text getter
• tag proc for tag getter
• tag= proc for tag setter

Example:

var e = newEntity("my entity")
assert $e == "&my entity;"
e.text = "a new entity text"
assert $e == "&a new entity text;"

Source Edit

proc toXmlAttributes(keyValuePairs: varargs[tuple[key, val: string]]): XmlAttributes {.
    ...raises: [], tags: [], forbids: [].}

Converts {key: value} pairs into XmlAttributes.

Example:

let att = {"key1": "first value", "key2": "second value"}.toXmlAttributes
var j = newElement("myTag")
j.attrs = att

doAssert $j == """<myTag key1="first value" key2="second value" />"""

Source Edit

Iterators

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

Iterates over all direct children of n.

Example:

var g = newElement("myTag")
g.add newText("some text")
g.add newComment("this is comment")

var h = newElement("secondTag")
h.add newEntity("some entity")
g.add h

assert $g == "<myTag>some text<!-- this is comment --><secondTag>&some entity;</secondTag></myTag>"

# for x in g: # the same as `for x in items(g):`
#   echo x

# some text
# <!-- this is comment -->
# <secondTag>&some entity;<![CDATA[some cdata]]></secondTag>

Source Edit

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

Iterates over all direct children of n so that they can be modified. Source Edit

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>

Source Edit