std/data/xml

Standard Library documentation

XML parsing and DOM manipulation for ZuzuScript.

Back to Stdlib View Source

Module

Name
std/data/xml
Area
Standard Library
Source
modules/std/data/xml.zzm

NAME

std/data/xml - XML parsing and DOM manipulation for ZuzuScript.

SYNOPSIS

  from std/data/xml import XML;

  let doc := XML.parse(
    "<root><item id='a'>first</item></root>"
  );

  let root := doc.documentElement();
  let item := root.firstChild();

  item.setAttribute("status", "active");
  root.appendChild( doc.createComment("done") );

  let text := doc.toXML(true);

IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and Electron. It is partially supported by zuzu-js in the browser: core XML and ZPath pipeline coverage passes, but file-backed load/dump coverage is unsupported because browser filesystem capability is unavailable.

DESCRIPTION

This module provides in-memory XML parsing and DOM tree operations, backed by XML::LibXML.

It supports in-memory parsing plus explicit file load/dump operations using std/io Path objects.

EXPORTS

  • XML

    Static DOM entry point.

    • XML.parse(String xml) -> XMLDocument

      Parse XML text and return a document object.

    • XML.load(Path path) -> XMLDocument

      Read XML text from a std/io Path and parse it. Throws an exception if passed a plain string.

    • XML.dump(Path path, XMLDocument|XMLNode value, Bool pretty?) -> Path

      Serialize value and write XML to path. Throws an exception if passed a plain string.

  • XMLDocument

    Document-level methods:

    • documentElement()
    • createElement(name)
    • createTextNode(text)
    • createComment(text)
    • findnodes(xpath)
    • findvalue(xpath)
    • querySelector(selector)
    • querySelectorAll(selector)
    • toXML(pretty?)
    • to_String
  • XMLNode

    Node-level traversal:

    • nodeName(), nodeType(), nodeValue(), textContent()
    • uniqueKey() and unique_id()
    • localName(), namespaceURI()
    • nodeKind()
    • firstChild(), lastChild(), nextSibling()
    • previousSibling(), parentNode(), ownerDocument()
    • childNodes()
    • children(), hasChildNodes(), normalize()
    • isSameNode(other), isEqualNode(other), contains(other)

    Node mutation:

    • setNodeValue(value), setTextContent(value)
    • appendChild(node), prependChild(node)
    • insertBefore(newNode, refNode)
    • replaceChild(newNode, oldNode)
    • removeChild(childNode), remove()
    • cloneNode(deep?)
    • visitEach(lambda), findFirst(lambda)

    XPath query:

    • findnodes(xpath)
    • findvalue(xpath)
    • querySelector(selector)
    • querySelectorAll(selector)
  • DOMNode, DOMElement, DOMComment, DOMText, DOMDocument

    Specific subclasses of XMLNode are returned automatically when possible. For example, documentElement() returns DOMElement, and createComment() returns DOMComment.

    Extra methods include:

    • DOMElement.tagName(), DOMElement.id(), DOMElement.setId(value)
    • DOMElement.getElementsByTagName(name)
    • DOMComment.data(), DOMComment.setData(value)
    • DOMText.data(), DOMText.setData(value)

    Document-level extras:

    • createCDATASection(text)
    • getElementsByTagName(name)
    • getElementById(id)
    • visitEach(lambda), findFirst(lambda)

    Element attribute helpers:

    • getAttribute(name), setAttribute(name, value)
    • hasAttribute(name), removeAttribute(name)
    • attributeNames()
    • attributes()

    Serialization:

    • toXML(pretty?)
    • to_String

NOTES

XPath operations use XML::LibXML semantics.

Methods that are meaningful only for element nodes (for example, setAttribute) throw a runtime error when called on unsupported node types.

DOM COMPATIBILITY GAPS

For users coming from browser DOM APIs, these are the biggest rough edges today:

  • Querying is XPath-first, not selector-first

    findnodes and findvalue are still available and querySelector/querySelectorAll now provide CSS-style selector queries.

  • Partial node-type coverage

    Only document, element, text, and comment nodes have dedicated classes. Other node types (for example processing instructions) are surfaced as generic DOMNode values without type-specific helpers.

  • Missing namespace convenience methods

    There are no direct wrappers for methods like getAttributeNS, setAttributeNS, lookupNamespaceURI, or getElementsByTagNameNS.

  • No browser-style collection wrappers

    childNodes, children, and getElementsByTagName return plain arrays rather than DOM-like NodeList/HTMLCollection-style objects. That means there are no collection helper methods like item().

  • API naming differences from browser DOM

    The module exposes methods like toXML, setTextContent, attributeNames, visitEach, and findFirst, which are practical but are not the same method names that browser users expect.

  • No parser configuration surface in XML.parse

    Parsing is currently XML.parse(String) only, with no exposed options for recovery mode, entity handling, whitespace policy, or security hardening toggles.

If the goal is easy transfer from browser DOM experience, the highest impact improvements would be: namespace helpers and a browser-like collection API layer.

COPYRIGHT AND LICENCE

std/data/xml is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.