ddn-data-xml 1.1.3

ddn-data-xml

An idiomatic XML library for the D programming language.

It provides a DOM-like tree model, multiple parsing styles (DOM / SAX / streaming reader), serialization, querying, canonicalization, inclusion (XInclude/XPointer), and validation utilities.

Optionally, a project logo is available at files/ddn-data-xml-512x512.png.

Part of the DDN (D Developer Network) ecosystem: Organisation https://codeberg.org/ddn · Kanban https://codeberg.org/ddn/-/projects/30288 · Core https://codeberg.org/ddn/ddn · Docs https://ddn.ovh

Table of contents

• Features
• Install
• Quick start
• Demos / CLI tools
• Standards coverage
• Testing
• Repository notes
• Contributing
• License

Features

• Parsing
• DOM parsing via ddn.data.xml.parse (parseDocument, parseFragment)
• SAX-like push parsing via ddn.data.xml.sax (parseSax)
• Streaming pull reader via ddn.data.xml.stream (XmlReader)
• DOM-like tree model via ddn.data.xml.dom (XmlDocument, XmlElement, XmlNode, ...)
• Serialization / writing via ddn.data.xml.write (writeXml, toXmlString, XmlWriteOptions)
• Querying via ddn.data.xml.query (XmlPath)
• XPath / XPointer / XInclude (seeGUIDE.md)
• Validation
• Native validators: XSD (ddn.data.xml.xsd) and Relax NG (ddn.data.xml.relaxng)
• CLI-backed helpers (used heavily by tests): ddn.data.xml.validate
• Canonicalization (C14N) via ddn.data.xml.c14n (canonicalize)
• XML Catalog support (for hermetic tests and offline resources)

The umbrella import ddn.data.xml re-exports the commonly used entry points.

Install

Add the package as a dependency:

`dub.sdl`:

dependency "ddn-data-xml" version="*"

`dub.json`:

{
  "dependencies": {
    "ddn-data-xml": "*"
  }
}

If you want reproducible builds, replace * with a tagged version once the package is published.

Then import:

import ddn.data.xml;

Quick start

Parse a document (DOM)

import ddn.data.xml.parse : parseDocument;

auto doc = parseDocument("<root><child id='1'>t</child></root>");
assert(doc.documentElement().lexicalName == "root");

Build + serialize a document

import ddn.data.xml.dom.document : XmlDocument;
import ddn.data.xml.write : toXmlString, XmlWriteOptions;

auto doc = new XmlDocument();
auto root = doc.createRootElement("root");
root.addChildElement("child").withAttribute("id", "1").addText("t");

XmlWriteOptions opt;
opt.pretty = true;

auto xml = toXmlString(doc, opt);

Streaming reader (pull)

import ddn.data.xml.stream : XmlEventType, XmlReader;

auto r = new XmlReader("<a><b/>t</a>");
while (!r.empty)
{
  if (r.front.type == XmlEventType.TEXT)
    assert(r.front.text == "t");
  r.popFront();
}

Canonicalize for stable comparisons

import ddn.data.xml.c14n : canonicalize;
import ddn.data.xml.parse : parseDocument;
import std.algorithm.searching : canFind;

auto doc = parseDocument("<root b='2' a='1'/>" );
assert(canonicalize(doc).canFind("<root a=\"1\" b=\"2\"></root>") );

For a longer, tutorial-style walkthrough, see GUIDE.md.

Demos / CLI tools

This repository includes runnable demos under demo/.

Each demo file contains an embedded dub.sdl header, so you can run them directly with dub run --single:

dub run --single demo/data/xml/parser.d
dub run --single demo/data/xml/dom.d
dub run --single demo/data/xml/reader.d

Most demos are configured to write executables into bin/ (see the embedded targetPath).

Notable demo entry points:

• demo/data/xml/parser.d — DOM + SAX parsing
• demo/data/xml/dom.d — DOM construction and traversal
• demo/data/xml/reader.d — streaming reader
• demo/data/xml/writer.d — serialization
• demo/data/xml/c14n.d — canonicalization
• demo/data/xml/validation.d — validation demos
• demo/data/xml/xinclude.d, demo/data/xml/xpointer.d, demo/data/xml/xpath.d

Standards coverage

Coverage is tracked explicitly and kept consistent across docs:

• XML-Standards.md — authoritative list of tracked standards/specs
• XML-Standards-Coverage.md — coverage table with notes and estimated completeness
• LIBXML2-COMPARE.md — libxml2-oriented comparisons/breakdown

Testing

Run the test suite:

dub test

External prerequisites

Unit/integration tests use external libxml2 CLI tools as an oracle for correctness. The machine running dub test must have these tools on PATH:

• xmllint
• xmlcatalog

Tests spawn these tools (via std.process) to validate well-formedness, run schema checks (XSD/RelaxNG), and compare canonicalized output (for example against xmllint --c14n) where applicable.

If these tools are missing, tests fail with a clear message indicating the missing prerequisite.

XML Catalogs (hermetic tests)

Where tests rely on external DTD/XSD/RNG resources, they should be made hermetic via XML Catalogs. Typical approaches include:

• Setting the XML_CATALOG_FILES environment variable for the dub test process, and/or
• Passing --catalogs to xmllint invocations within tests.

Contributing

• Please read CODE_STYLE.md (and Idiomatic-D.md for library conventions).
• If you change standards coverage, keep XML-Standards.md and XML-Standards-Coverage.md in sync.
• Contributions should include tests where practical.

License

BSD 3-Clause. See LICENSE.