XML module – DOM parsing, manipulation, serialisation and XPath queries.

Backed by pugixml. Provides two core types:

• XmlDocument: An XML document that owns the DOM tree.
• XmlNode: A lightweight handle to a single element within a document.

Availability

This module is a typed facade over an optional pugixml backend. In builds without XML support, require("@eryx/xml") fails immediately with a clear capability error.

Quick start

local xml = require("xml")
local doc = xml.parse('<root><item id="1">Hello</item></root>')
local root = doc:root()
print(root.name)                    --> "root"
print(root:child("item"):text())    --> "Hello"
print(root:child("item"):attr("id")) --> "1"

-- XPath
for _, node in doc:xpath("//item[@id]") do
    print(node.name, node:attr("id"))
end

Summary

Classes

Functions

API Reference

Classes

XmlNode

A lightweight handle to a single node in an XML DOM tree.

Nodes remain valid as long as their owning XmlDocument is alive. Reading .name, .type, or .value uses __index and does not require a method call.

Properties

name: string

The element/PI tag name, or "" for text/comment nodes.

type: NodeType

The node type (see NodeType).

value: string

Shorthand for the first PCDATA/CDATA child's content (like Text()).

XmlNode:text

Returns the concatenated text content of this element (first PCDATA/CDATA child).

XmlNode:text() → string

XmlNode:setText

Sets the text content of this element (creates a PCDATA child if needed).

XmlNode:setText(value: string) → ()

XmlNode:children

Returns a list of element children. If name is given, only children with that tag name are included.

XmlNode:children(name: string?) → { XmlNode }

XmlNode:child

Returns the first child element with the given tag name, or nil if not found.

XmlNode:child(name: string) → XmlNode?

XmlNode:appendChild

Appends a new child element with the given tag name.

XmlNode:appendChild(name: string) → XmlNode

XmlNode:prependChild

Prepends a new child element with the given tag name.

XmlNode:prependChild(name: string) → XmlNode

XmlNode:removeChild

Removes a child by tag name or by XmlNode reference.

XmlNode:removeChild(child: string | XmlNode) → ()

XmlNode:parent

Returns the parent node, or nil for the document root.

XmlNode:parent() → XmlNode?

XmlNode:nextSibling

Returns the next sibling element. If name is given, skips siblings until one with a matching tag name is found.

XmlNode:nextSibling(name: string?) → XmlNode?

XmlNode:prevSibling

Returns the previous sibling element.

XmlNode:prevSibling(name: string?) → XmlNode?

XmlNode:attr

Returns the value of the attribute name, or nil.

XmlNode:attr(name: string) → string?

XmlNode:setAttr

Sets (or creates) the attribute name to value.

XmlNode:setAttr(name: string, value: string) → ()

XmlNode:removeAttr

Removes the attribute with the given name.

XmlNode:removeAttr(name: string) → ()

XmlNode:attrs

Returns all attributes as a { [name] = value } dictionary.

XmlNode:attrs() → { [string]: string }

XmlNode:xpath

Evaluates an XPath expression relative to this node and returns all matching nodes.

XmlNode:xpath(query: string) → { XmlNode }

XmlNode:xpathOne

Evaluates an XPath expression and returns the first match, or nil. ]]

XmlNode:xpathOne(query: string) → XmlNode?

XmlNode:xpathValue

Evaluates an XPath expression that returns a scalar value (string, number, or boolean) rather than a node set.

XmlNode:xpathValue(query: string) → string | number | boolean | nil

XmlNode:path

Returns the absolute path of this node from the document root. Uses delimiter (default "/") to separate path segments.

XmlNode:path(delimiter: string?) → string

XmlNode:setName

Changes this element's tag name.

XmlNode:setName(name: string) → ()

XmlNode:__tostring

XmlNode.__tostring(self: XmlNode) → string

XmlDocument

An XML document that owns a DOM tree.

The document is the entry point for parsing and serialisation. It exposes XPath queries directly so you don't always need to grab the root element first.

Properties

XmlDocument:root

Returns the document element (the single top-level element).

XmlDocument:root() → XmlNode?

XmlDocument:save

Serialises the entire document to a string.

XmlDocument:save(indent: string?, flags: string?) → string

Parameters

indent: string?

Indentation string (default "\t").

flags: string?

"raw" | "no_declaration" | nil (default includes a declaration and pretty-prints).

XmlDocument:saveFile

Writes the document to a file on disk.

XmlDocument:saveFile(path: PathLike, indent: string?, flags: string?) → ()

XmlDocument:xpath

Evaluates an XPath expression on the whole document and returns all matching nodes.

XmlDocument:xpath(query: string) → { XmlNode }

XmlDocument:xpathOne

Evaluates an XPath expression and returns the first match, or nil.

XmlDocument:xpathOne(query: string) → XmlNode?

XmlDocument:appendChild

Appends a top-level child element (useful when building documents from scratch with xml.document()).

XmlDocument:appendChild(name: string) → XmlNode

XmlDocument:__tostring

XmlDocument.__tostring(self: XmlDocument) → string

Functions

xml.parse

Parses an XML string and returns a new document.

xml.parse(source: string) → XmlDocument

xml.load

Loads and parses an XML file from disk.

xml.load(path: PathLike) → XmlDocument

xml.document

Creates a new, empty XML document. Use AppendChild() to add a root element and build the tree programmatically.

xml.document() → XmlDocument

Types

NodeType

Node type string

type NodeType = "element" | "pcdata" | "cdata" | "comment" | "pi" | "declaration" | "doctype" | "document" | "null"