# Module xmltree

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 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
  --- | ---
  `<` | `&lt;`
  `>` | `&gt;`
  `&` | `&amp;`
  `"` | `&quot;`

    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.

# 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", "Nimrod rules.")

  Produces an XML tree for:

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

Generated: 2013-05-21 09:55:18 UTC