libxml_rs/xml/
mod.rs

1//! libxml2 implementation — native Rust (§1, §3, §31).
2//!
3//! This module contains the complete native-Rust implementation of libxml2's
4//! observable behavior: parser, SAX, tree, entities, namespaces, DTD,
5//! validation, reader, writer, encoding, I/O, catalog, URI, XPath, XPointer,
6//! XInclude, RELAX NG, schemas, Schematron, C14N, HTML, regex, automata,
7//! dictionary, hash, list, debug, globals, threads, errors, memory.
8//!
9//! # Phase 0 status
10//!
11//! All sub-modules are scaffolded. Implementation proceeds in phases per §85:
12//! - Phase 2: Tree and ownership
13//! - Phase 3: XML parsing + SAX
14//! - Phase 4: I/O, encoding, URI, catalog, serialization, HTML
15//! - Phase 5: XPath/XPointer/XInclude
16//! - Phase 6: Validation family
17//! - Phase 7: Remaining libxml2 surfaces
18//!
19//! See `atlas/PARITY_MATRIX.md` for current status.
20//!
21//! # Upstream contract
22//!
23//! Parity target is the system libxml2 2.15.3 oracle (`21503-GITv2.15.3`) and
24//! libxslt 1.1.45; upstream source trees are `oracle/historical/src/libxml2-2.15.0/*.c`
25//! (parser.c, SAX2.c, tree.c, entities.c, namespaces.c, valid.c, error.c,
26//! globals.c, dict.c, xmlmemory.c, xmlstring.c, ...), resolved via `SRC-LIBXML2-GIT`
27//! in `archaeology/libxml2-git`. The crate is a C-ABI drop-in reimplementation of
28//! the upstream library, not a binding: every exported symbol and data global
29//! must match the oracle DSO (R-000136: 881 libxml2 + 201 libxslt exports).
30//!
31//! # Conceptual behavior
32//!
33//! Each submodule reimplements one upstream subsystem as native Rust: the parser
34//! is a state machine over a tokenizer, SAX dispatch mirrors SAX2.c, the tree
35//! reproduces libxml2 pointer topology, validation follows valid.c, and the
36//! remaining modules (entities, namespaces, DTD, errors, globals, memory,
37//! strings, schemas, RELAX NG, Schematron) mirror their upstream .c files.
38//! Observable behavior (stdout, stderr, exit codes, tree structure, ABI layout)
39//! is the compatibility contract.
40//!
41//! # Ownership & safety invariants
42//!
43//! Ownership follows the upstream C contract (atlas/OWNERSHIP_ATLAS.md):
44//! documents own their subtrees (caller frees with `xmlFreeDoc`), node
45//! parent/doc/ns pointers are borrowed, strings returned by `xmlGetProp` are
46//! caller-freed with `xmlFree`, and every xml* allocator result is freed by its
47//! matching xmlFree. SAFETY: the crate is a memory-safe Rust reimplementation
48//! of an unsafe C library; invariants that upstream enforces by convention are
49//! enforced here by the Rust type system plus audited unsafe blocks.
50//!
51//! # Historical quirks & epochs
52//!
53//! Current behavior is pinned to the 2.15.3 epoch but carries history:
54//! E-001 (xpath node-set newlines, 2.9.10, commit da35eeae), E-002 (parser
55//! second diagnostic dropped in 2.12.x, commit c6083a32), E-004 (TEXT compact
56//! at 2.13.0, commit 8d04f0ee), E-005 (xmllint exit codes reworked at 2.13.0),
57//! E-006 (valid no-DTD exit 0 at 2.15.0), E-007 (HTML single-line at 2.15.0),
58//! E-008 (libxslt transform output stable since 2009 or earlier). QUIRK-0001:
59//! default parser limits since 2.9.0 (commit 52d8ade7); QUIRK-0002: namespace
60//! nodes have no parent (upstream fix 044fc6b7). Security epochs: SEC-0006
61//! CVE-2014-3660 amplification guard (fix be2a7eda, regression fix 72a46a51).
62//! See atlas/SEMANTIC_EPOCHS.md, atlas/QUIRKS.md, atlas/SECURITY_HISTORY.md.
63//!
64//! # Deliberate oddities
65//!
66//! Odd-but-faithful behaviors are preserved on purpose: hybrid-epoch
67//! diagnostics (R-000121 reports the entity-in-attribute fatal error once with
68//! the 2.13+ exit code 4), exported deprecated init/cleanup entry points as
69//! intentional no-ops (R-000138), and the documented safe divergences
70//! SD-001..SD-004 in atlas/SECURITY_HISTORY.md where emulating a vulnerability
71//! would be unsafe.
72//!
73//! # Proving courts
74//!
75//! Exercised by the data-ABI family probes (TREE-001, ERROR-001, READER-001,
76//! WRITER-001, CALLBACK-001, DATA-GLOBALS-001, SECURITY-LIMITS, ENCODING-001),
77//! the CLI courts (CLI-XMLLINT-*, CLI-XSLTPROC-*, CLI-XMLCATALOG-*), the PARSER,
78//! DTD, RELAXNG, XSD, SCHEMATRON, TREE-STRUCTURE and OWNERSHIP court families,
79//! and `cargo test --lib` (counts generated into atlas/TEST_COUNTS.json by
80//! tools/evidence/test_counts.py). Receipts under courts/receipts/phase-11.
81//!
82//! # Tempting simplifications that would break parity
83//!
84//! A naive Rust-native API rewrite would break the C-ABI drop-in surface
85//! (R-000136). Do not drop exported data globals (R-000135), do not simplify
86//! error routing to a single stderr write (R-000161: a counting handler sees
87//! 6 xmlFormatError fragments per raise), and never replace the epoch-pinned
88//! behaviors with cleaner semantics — byte-identical output against the oracle
89//! is the acceptance test.
90
91pub mod automata;
92pub mod c14n;
93pub mod catalog;
94pub mod chvalid;
95pub mod debug;
96pub mod dictionary;
97pub mod dtd;
98pub mod encoding;
99pub mod entities;
100pub mod errors;
101pub mod globals;
102pub mod hash;
103pub mod html;
104pub mod io;
105pub mod list;
106pub mod memory;
107pub mod namespaces;
108pub mod parser;
109pub mod reader;
110pub mod regex;
111pub mod relaxng;
112pub mod save;
113pub mod sax;
114pub mod schemas;
115pub mod schematron;
116pub mod string;
117pub mod threads;
118pub mod tree;
119/// Unicode character-class tables (upstream libxml2 chvalid data globals,
120/// extracted verbatim from `codegen/ranges.inc`).
121pub mod unicode_tables;
122pub mod uri;
123pub mod validation;
124pub mod writer;
125pub mod xinclude;
126pub mod xpath;
127pub mod xpointer;
libxml_rs/xml/mod.rs

libxml_rs/xml/
mod.rs
