core.base.xml

The core.base.xml module provides a tiny DOM-style XML toolkit that works inside Xmake’s sandbox. It focuses on predictable data structures, JSON-like usability, and optional streaming so you can parse large XML documents without building the entire tree.

Node Structure

XML nodes are plain Lua tables. All constructors (xml.new, xml.text, xml.comment, etc.) return values shaped like:

{
    name     = "element-name" | nil, -- only for element nodes
    kind     = "element" | "text" | "comment" | "cdata" | "doctype" | "document",
    attrs    = { key = value, ... } or nil,
    text     = string or nil,
    children = { child1, child2, ... } or nil,
    prolog   = { comment/doctype nodes before root } or nil
}

Because these are regular tables, mutating them updates the DOM in place and the changes show up automatically when you call xml.encode or xml.savefile.

Quick Start

import("core.base.xml")

local doc = assert(xml.decode([[
<?xml version="1.0"?>
<root id="1">
  <item id="foo">hello</item>
</root>
]]))

local item = assert(xml.find(doc, "//item[@id='foo']"))
item.attrs.lang = "en"             -- mutate attrs directly
item.children = {xml.text("world")} -- replace existing text node
table.insert(doc.children, xml.comment("generated by xmake"))

local pretty = assert(xml.encode(doc, {pretty = true}))
assert(xml.savefile("out.xml", doc, {pretty = true}))

Streaming Example

local found
xml.scan(plist_text, function(node)
    if node.name == "key" and xml.text_of(node) == "NSPrincipalClass" then
        found = node
        return false -- early terminate
    end
end)

xml.scan walks nodes as they are completed; returning false stops the scan immediately. This is ideal for large files (e.g. Info.plist) when you only need a few entries.

Options Summary

API Reference

xml.new(opt)

Create a custom node. opt may contain name, kind, attrs, children, and text. Usually you call the dedicated helpers below instead of xml.new directly.

Element/Text Helpers

local textnode    = xml.text("hello")
local empty       = xml.empty("br", {class = "line"})
local comment     = xml.comment("generated by xmake")
local cdata_node  = xml.cdata("if (value < 1) {...}")
local doctype     = xml.doctype('plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"')

All helpers return node tables that you can insert into children.

xml.decode(data, opt)

Parse an XML string into a node tree. Returns the single root element when there is exactly one element, or all top-level nodes when multiple elements exist. On failure returns nil, err.

Supports:

• Comments, CDATA, DOCTYPE (stored in root.prolog when present).
• Unquoted attributes such as <item flag=true path=/tmp/file>.
• XPath-friendly structure (name, attrs, children).
• trim_text and keep_whitespace_nodes options described above.

xml.encode(node, opt)

Serialize a node tree back into XML. Set {pretty = true, indent = 2} for multi-line output or pass a custom indentchar.

xml.loadfile(path, opt) / xml.savefile(path, node, opt)

Convenience wrappers that call io.readfile/io.writefile and reuse the decode/encode options.

xml.text_of(node)

Concatenate all direct text children and return the combined string. Useful for quickly reading <string>...</string> values.

xml.find(node, path)

XPath-like lookup supporting:

• / child axis, // descendant axis.
• Wildcards (*) and node tests (text(), comment(), cdata(), doctype()).
• Attribute predicates ([@id='foo'], [@enabled]), text predicates ([text()='value']), positional indexes ([2]).

Returns the first node that matches or nil if nothing is found.

xml.scan(data, callback, opt)

Streaming parser. Calls callback(node) for each completed node; returning false stops the scan early. Accepts the same options as xml.decode (trim_text, keep_whitespace_nodes). Nodes produced by xml.scan share the same structure as xml.decode.

Attribute Parsing Notes

• Both quoted and unquoted values are supported (a="1 2", b='foo', c=bare).
• Attribute names may include colons, dashes, or underscores.
• Entity references inside attribute values are decoded (& → &).

Example: Parsing and Updating an Info.plist

import("core.base.xml")

local plist = assert(xml.loadfile("Info.plist"))
local dict = assert(xml.find(plist, "plist/dict"))
local version_key

for i = 1, #dict.children, 2 do
    local key = dict.children[i]
    local value = dict.children[i + 1]
    if key and value and xml.text_of(key) == "CFBundleShortVersionString" then
        version_key = value
        break
    end
end

if version_key then
    version_key.children = {xml.text("2.0")}
    assert(xml.savefile("Info.plist", plist, {pretty = true}))
end

This example demonstrates decoding, querying via DOM traversal, mutating nodes, and writing the file back with pretty formatting.