libxml_rs/xml/namespaces/
mod.rs

1//! Namespace handling (§23, §85 Phase 2/3).
2//!
3//! Default namespace, prefixed namespace, namespace undeclaration, attribute
4//! namespaces, duplicate declarations, shadowing, prefix reuse, conflicting
5//! prefixes, orphaned namespace pointers, namespace reconciliation.
6//!
7//! Phase 0: scaffolded. Implementation begins in Phase 2/3.
8//!
9//! # Upstream contract
10//!
11//! Mirrors upstream namespaces.c (SRC-LIBXML2-2.15.0-NAMESPACES-C, oracle
12//! tree `oracle/historical/src/libxml2-2.15.0/namespaces.c`): xmlNewNs,
13//! xmlSetNs, xmlSearchNs, xmlSearchNsByHref, xmlGetNsList,
14//! xmlReconciliateNs, xmlCopyNamespace, xmlCopyNamespaceList,
15//! xmlFreeNamespace, xmlFreeNamespaceList, xmlNewGlobalNs.
16//!
17//! # Conceptual behavior
18//!
19//! Default namespace, prefixed namespace, namespace undeclaration, attribute
20//! namespaces, duplicate declarations, shadowing, prefix reuse, conflicting
21//! prefixes, orphaned namespace pointers and namespace reconciliation.
22//! Namespace nodes live on node->nsDef chains and are resolved by walking the
23//! element scope upward — the same model the parser and XPath rely on.
24//!
25//! # Ownership & safety invariants
26//!
27//! Ownership: an xmlNs created by xmlNewNs is owned by the node nsDef list
28//! and freed with the node (xmlFreeNs only for unlinked standalone ns);
29//! node->ns is a borrowed pointer. SAFETY: upstream xmlNs nodes have NO
30//! parent pointer (QUIRK-0002 / LORE-0006) — the model must not invent one.
31//!
32//! # Historical quirks & epochs
33//!
34//! The no-parent namespace node is a long-standing upstream divergence fixed
35//! only in the c14n birth commit 044fc6b7 (2002, issue #61290); downstream
36//! XPath namespace-axis consumers depend on it. Epoch: unchanged across
37//! 2.7.8 to 2.15.3 (stable case in the historical matrix).
38//!
39//! # Deliberate oddities
40//!
41//! The deliberately odd part is the nsDef-first resolution order used by
42//! xmlSAX2AttributeNs (R-000147): scan the element-local declarations, then
43//! fall back to the parent scope — the new element is not yet linked to its
44//! parent when attributes are processed.
45//!
46//! # Proving courts
47//!
48//! Exercised by the TREE-NS-* and XPATH-NS-* court families (QUIRK-0002),
49//! TREE-001 (nsDef duplicates, empty-value xmlns, default-ns handling),
50//! READER-001 (attribute namespace accessors) and `cargo test --lib`.
51//!
52//! # Tempting simplifications that would break parity
53//!
54//! A tempting simplification is giving namespace nodes a parent pointer for
55//! convenience — it would break XPath 1.0 namespace-axis semantics and the
56//! TREE-NS-* courts. Do not deduplicate nsDef entries: upstream registers
57//! each declaration once and TREE-001 fingerprints the exact chains.
libxml_rs/xml/namespaces/mod.rs

libxml_rs/xml/namespaces/
mod.rs
