xmloxide

Eine reine Rust-Neuimplementierung von libxml2 — dem De-facto-Standard für XML/HTML-Parsing-Bibliotheken in der Open-Source-Welt.

libxml2 wurde im Dezember 2025 offiziell für ungepflegt erklärt und weist bekannte Sicherheitslücken auf. xmloxide zielt darauf ab, ein speichersicherer, leistungsstarker Ersatz zu sein, der die gleichen Konformitätstestsuiten besteht.

Funktionen

• Speichersicher — Arena-basierter Baum ohne unsafe in der öffentlichen API
• Konform — 100% Bestehensquote der W3C-XML-Konformitätstestsuite (1727/1727 anwendbare Tests)
• Fehlerbehandlung — fehlerhafte XML-Daten parsen und trotzdem einen nutzbaren Baum erzeugen, genau wie libxml2
• Mehrere Parsing-APIs — DOM-Baum, SAX2-Streaming, XmlReader-Pull, Push/inkrementell
• HTML-Parser — fehlertolerantes HTML-4.01-Parsen mit automatischem Schließen und void-Elementen
• WHATWG-HTML5-Parser — vollständiger HTML Living Standard-Tokenizer und Baumkonstruktor (8810/8810 html5lib-Tests bestanden)
• HTML5-Streaming — SAX-ähnliche Callback-API für HTML5 (html5::sax), die den Tokenizer umschließt, ohne einen DOM-Baum zu erstellen
• CSS-Selektoren — Abfrage von Elementen mit vertrauter CSS-Syntax (css::select) inklusive Kombinatoren, Pseudoklassen und schnellem #id-Lookup
• XPath 1.0+ — vollständiger Ausdrucksparser und -auswerter mit allen Kernfunktionen von XPath 1.0 sowie wichtigen XPath-2.0-Funktionen (matches(), replace(), tokenize(), upper-case(), lower-case(), abs(), min(), max() und mehr)
• Validierung — DTD-, RelaxNG-, XML-Schema-(XSD)- und ISO-Schematron-Validierung (ISO/IEC 19757-3)
• Serde-Integration — optionales serde-Feature für XML-(De-)Serialisierung von/nach Rust-Typen
• Asynchrones Parsen — optionales async-Feature zum Parsen von tokio::io::AsyncRead-Quellen
• Kanonisches XML — C14N 1.0 und Exclusive-C14N-Serialisierung
• XInclude — Dokumenteninklusionsverarbeitung
• XML-Kataloge — OASIS-XML-Kataloge zur URI-Auflösung
• xmllint-CLI — Kommandozeilenwerkzeug zum Parsen, Validieren und Abfragen von XML
• Zero-Copy wo möglich — String-Interning für schnelle Vergleiche
• Kein globaler Zustand — jedes Document ist in sich abgeschlossen und Send + Sync
• C/C++-FFI — vollständige C-API mit Header-Datei (include/xmloxide.h) zur Einbettung in C/C++-Projekte
• Minimale Abhängigkeiten — nur encoding_rs (die Bibliothek hat keine weiteren Abhängigkeiten; clap ist nur CLI-spezifisch)

Schnellstart

use xmloxide::Document;

let doc = Document::parse_str("<root><child>Hello</child></root>").unwrap();
let root = doc.root_element().unwrap();
assert_eq!(doc.node_name(root), Some("root"));
assert_eq!(doc.text_content(root), "Hello");

Serialisierung

use xmloxide::Document;
use xmloxide::serial::serialize;

let doc = Document::parse_str("<root><child>Hello</child></root>").unwrap();
let xml = serialize(&doc);
assert_eq!(xml, "<root><child>Hello</child></root>");

XPath-Abfragen

use xmloxide::Document;
use xmloxide::xpath::{evaluate, XPathValue};

let doc = Document::parse_str("<library><book><title>Rust</title></book></library>").unwrap();
let root = doc.root_element().unwrap();
let result = evaluate(&doc, root, "count(book)").unwrap();
assert_eq!(result.to_number(), 1.0);

SAX2-Streaming

use xmloxide::sax::{parse_sax, SaxHandler, DefaultHandler};
use xmloxide::parser::ParseOptions;

struct MyHandler;
impl SaxHandler for MyHandler {
    fn start_element(&mut self, name: &str, _: Option<&str>, _: Option<&str>,
                     _: &[(String, String, Option<String>, Option<String>)]) {
        println!("Element: {name}");
    }
}

parse_sax("<root><child/></root>", &ParseOptions::default(), &mut MyHandler).unwrap();

HTML-Parsing

use xmloxide::html::parse_html;

let doc = parse_html("<p>Hello <br> World").unwrap();
let root = doc.root_element().unwrap();
assert_eq!(doc.node_name(root), Some("html"));

CSS-Selektoren

use xmloxide::css::select;
use xmloxide::Document;

let doc = Document::parse_str(r#"<div><p class="intro">Hello</p><p>World</p></div>"#).unwrap();
let root = doc.root_element().unwrap();
let intros = select(&doc, root, "p.intro").unwrap();
assert_eq!(intros.len(), 1);
assert_eq!(doc.text_content(intros[0]), "Hello");

HTML5-Parsing (WHATWG)

use xmloxide::html5::parse_html5;

let doc = parse_html5("<p>Hello <b>world</b>").unwrap();
let root = doc.root_element().unwrap();
assert_eq!(doc.node_name(root), Some("html"));

Fragment-Parsing (der Algorithmus hinter innerHTML) wird ebenfalls unterstützt:

use xmloxide::html5::{parse_html5_with_options, Html5ParseOptions};

let opts = Html5ParseOptions {
    scripting: false,
    fragment_context: Some("body".to_string()),
};
let doc = parse_html5_with_options("<p>fragment</p>", &opts).unwrap();

HTML5-Streaming (SAX-ähnlich)

use xmloxide::html5::sax::{Html5SaxHandler, parse_html5_sax};

struct LinkExtractor { hrefs: Vec<String> }
impl Html5SaxHandler for LinkExtractor {
    fn start_element(&mut self, name: &str, attrs: &[(String, String)], _sc: bool) {
        if name == "a" {
            if let Some((_, href)) = attrs.iter().find(|(n, _)| n == "href") {
                self.hrefs.push(href.clone());
            }
        }
    }
}

let mut handler = LinkExtractor { hrefs: Vec::new() };
parse_html5_sax(r#"<a href="/page">Link</a>"#, &mut handler);
assert_eq!(handler.hrefs, vec!["/page"]);

Fehlerbehandlung

use xmloxide::parser::{parse_str_with_options, ParseOptions};

let opts = ParseOptions::default().recover(true);
let doc = parse_str_with_options("<root><unclosed>", &opts).unwrap();
for diag in &doc.diagnostics {
    eprintln!("{}", diag);
}

CLI-Werkzeug

# Analysieren und hübsch ausgeben
xmllint --format document.xml

# Gegen ein Schema validieren
xmllint --schema schema.xsd document.xml
xmllint --relaxng schema.rng document.xml
xmllint --schematron schema.sch document.xml
xmllint --dtdvalid schema.dtd document.xml

# XPath-Abfrage
xmllint --xpath "//title" document.xml

# Kanonisches XML
xmllint --c14n document.xml

# HTML parsen
xmllint --html page.html

Modulübersicht

Leistung

Der Parsing-Durchsatz ist vergleichbar mit libxml2 — innerhalb von 3–4% bei den meisten Dokumenten und 12 % schneller bei SVG. Die Serialisierung ist 1,5–2,4x schneller dank des arena-basierten Baumdesigns. XPath ist 1,1–2,7x schneller in allen Benchmarks.

Parsing:

Serialisierung:

XPath:

Wichtige Optimierungen: Arena-basierter Baum für schnelle Serialisierung, Byte-Level-Vorprüfungen für Zeichenvalidierung, Bulk-Text-Scanning, ASCII-Schnellpfade für Namensparsing, Zero-Copy-Elementnamen-Aufteilung, Inline-Entity-Auflösung, XPath-//-Schrittfusion mit fusionierter Achsenerweiterung, Inline-Baumzugriffe und Namens-Test-Schnellpfade für Kind-/Nachkommenachsen.

# Benchmarks ausführen (erfordert libxml2-Systembibliothek)
cargo bench --features bench-libxml2 --bench comparison_bench

Tests

• 1078 Komponententests über alle Module hinweg
• 138 FFI-Tests decken die gesamte C-API-Oberfläche ab (einschließlich SAX, Schematron und CSS)
• libxml2-Kompatibilitätssuite — 119/119 Tests bestanden (100 %) für XML-Parsing, Namensräume, Fehlererkennung und HTML-Parsing
• W3C-XML-Konformitätstestsuite — 1727/1727 anwendbare Tests bestanden (100 %)
• html5lib-Tests — 7032/7032 Tokenizer-Tests + 1778/1778 Baumkonstruktionstests (100 %)
• Integrationstests decken reale XML/HTML-Dokumente, Randfälle und Fehlerbehandlung ab

cargo test --all-features

C/C++-FFI

xmloxide bietet eine C-kompatible API zur Einbettung in C/C++-Projekte (wie Chromium, Game-Engines oder jede Codebasis, die derzeit libxml2 verwendet).

# Gemeinsame + statische Bibliotheken bauen (verwendet das beiliegende Makefile)
make

# Oder einzeln bauen:
make shared   # .so / .dylib / .dll
make static   # .a / .lib

# C-Beispiel bauen und ausführen
make example

#include "xmloxide.h"

xmloxide_document *doc = xmloxide_parse_str("<root>Hello</root>");
uint32_t root = xmloxide_doc_root_element(doc);
char *name = xmloxide_node_name(doc, root);   // "root"
char *text = xmloxide_node_text_content(doc, root); // "Hello"

xmloxide_free_string(name);
xmloxide_free_string(text);
xmloxide_free_doc(doc);

Die vollständige API — einschließlich Baum-Navigation und -Mutation, XPath-Auswertung, Serialisierung (einfach und hübsch gedruckt), HTML/HTML5-Parsing, DTD/RelaxNG/XSD/Schematron-Validierung, C14N, SAX-Streaming, XmlReader, Push-Parser und XML-Kataloge — ist in include/xmloxide.h deklariert.

Migration von libxml2

Thread-Sicherheit: Im Gegensatz zu libxml2 hat xmloxide keinen globalen Zustand. Jedes Document ist in sich abgeschlossen und Send + Sync. Die FFI-Schicht verwendet thread-lokalen Speicher für die letzte Fehlermeldung – jeder Thread hat seinen eigenen Fehlerzustand. Es werden keine Initialisierungs- oder Bereinigungsfunktionen benötigt.

Fuzzing

xmloxide enthält Fuzz-Ziele für Sicherheitstests:

# cargo-fuzz installieren (erfordert nightly)
cargo install cargo-fuzz

# Ein Fuzz-Ziel ausführen
cargo +nightly fuzz run fuzz_xml_parse
cargo +nightly fuzz run fuzz_html_parse
cargo +nightly fuzz run fuzz_html5_parse
cargo +nightly fuzz run fuzz_html5_fragment
cargo +nightly fuzz run fuzz_xpath
cargo +nightly fuzz run fuzz_roundtrip
cargo +nightly fuzz run fuzz_sax
cargo +nightly fuzz run fuzz_reader
cargo +nightly fuzz run fuzz_push
cargo +nightly fuzz run fuzz_validation
cargo +nightly fuzz run fuzz_schematron

Bauen

cargo build
cargo test
cargo clippy --all-targets --all-features -- -D warnings
cargo bench

Mindestunterstützte Rust-Version: 1.81

Einschränkungen

• Kein XML 1.1 — xmloxide implementiert nur XML 1.0 (Fünfte Edition). XML 1.1 wird selten verwendet und ist nicht geplant.
• Kein XSLT — XSLT ist eine separate Spezifikation (libxslt) und außerhalb des Rahmens.
• HTML-Parser — Es werden sowohl ein HTML-4.01-Parser (der das Verhalten von libxml2 nachbildet) als auch ein vollständiger WHATWG-HTML5-Parser bereitgestellt. Der HTML5-Parser besteht 100% der html5lib-Tests.
• Push-Parser puffert intern — die Push/inkrementelle Parser-API (PushParser) puffert derzeit alle gepushten Daten und führt die vollständige Analyse bei finish() durch, anstatt wirklich zu streamen wie libxml2s xmlParseChunk. SAX-Streaming (parse_sax für XML, html5::sax::parse_html5_sax für HTML5) steht als Alternative für die speicherbeschränkte Verarbeitung großer Dokumente zur Verfügung.
• XPath-namespace::-Achse — die namespace::-Achse gibt den Elementknoten zurück, wenn Namensräume im Gültigkeitsbereich übereinstimmen (anstatt separate Namensraumknoten zu materialisieren), und folgt damit dem gleichen Muster wie die Attributachse.

Mitwirken

Siehe CONTRIBUTING.md für Entwicklungseinrichtung und Richtlinien.

Changelog

Siehe CHANGELOG.md für den Versionsverlauf.

Lizenz

MIT