feat(xinclude): range inclusion via XPointer range model (#87)

This commit is contained in:
Mihaela Mihaljevic 2026-06-09 04:19:38 +02:00
parent 3bd810dc2c
commit ecb9b8c881
4 changed files with 27 additions and 10 deletions

View File

@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- XInclude range inclusion (#87), completing the XInclude audit. An `xi:include` whose `xpointer` selects a range (`xpointer(range(...))`, `range-to`, or `string-range`) now includes that range's content: when no node-selecting scheme matches, the processor falls back to the XPointer range model and substitutes each range's spanned nodes (or the matched text for a `string-range`).
- XPointer `range()` model (#88), completing the XPath/XPointer audit. `PureXML.XPointer.evaluateRanges(_:over:)` (and `Pointer.evaluateRanges(over:)`) evaluate the range forms inside an `xpointer()`/`xpath1()` scheme: `range(expr)` (the covering range of each location), `start/range-to(end)` (one range spanning from the first location of `start` to the first of `end`, the sibling run when they share a parent), and `string-range(location, "search"[, offset[, length]])` (a character range per occurrence, with the XPointer offset/length adjustment). Each `Range` materializes to the whole `nodes` it spans and the `text` it covers, and `xmlns()` bindings apply to the range parts that follow, so this also unblocks XInclude range inclusion (#87).
- C14N node-subset canonicalization and Canonical XML 2.0 parameters (#85), completing the canonicalization audit. `Canonicalizer.canonicalize(_ subtree: TreeNode)` canonicalizes a fragment in place: the apex element renders the namespace context in scope from its omitted ancestors and inherits their `xml:base`/`xml:lang`/`xml:space` when it does not set them, so a signed fragment is independent of where it sat. `canonicalize(_:including:)` canonicalizes a node-set selected by a `TreeNode` predicate (XPath/position-based selection): an excluded element's tags are omitted but its selected descendants are kept and re-declare their in-scope namespaces. `Options.prefixRewrite = .sequential` rewrites every prefix to a canonical `n0`/`n1`/... in document order (eliminating the default namespace and placing declarations at first use), and `Options.qnameAwareLabels` extends that rewrite into QName-valued attributes and elements, so documents differing only in prefix spelling canonicalize to identical bytes.
- Serialization `textEscaping` round-trip option (#91), completing the serialization audit. `Options.textEscaping` defaults to `.standard` (escape only `&`, `<`, `>`); `.roundTrip` also escapes a carriage return as `&#xD;` in text and CDATA-as-text output, so a literal `\r` survives the parser's end-of-line normalization and the document round-trips byte for byte. (The CDATA-section vs escaped-text toggle, `cdataAsText`, was already present.)

View File

@ -77,21 +77,19 @@ flowchart TB
classDef epic fill:#f2e5ff,stroke:#af52de,color:#111827
classDef todo fill:#f2f4f7,stroke:#8e8e93,color:#111827
Epic71["#71 Beyond-parity libxml2 audit"]:::epic
AuditDone["Closed in main: DTD #72 #73, XSD #75 #76 #77 #78, parsing #95 #96 #98 #100, regex #89, catalog #86, XSLT #81 #82, RELAX NG #79, Schematron #80, DOM #90, serialization #91, C14N #85, XPath/XPointer #88"]:::done
AuditDone["Closed in main: DTD #72 #73, XSD #75 #76 #77 #78, parsing #95 #96 #98 #100, regex #89, catalog #86, XSLT #81 #82, RELAX NG #79, Schematron #80, DOM #90, serialization #91, C14N #85, XPath/XPointer #88, XInclude #87"]:::done
Epic74["#74 Parser-breadth sub-epic: standalone/decl #95, XML 1.1 #96, reader #98, recovery #100 done; encodings #97 #99 open"]:::epic
Partial["Partial in main: XInclude #87"]:::todo
Open["Open: HTML5 #83 #84, encoding tables #97 #99, validator decomposition #101"]:::todo
Epic71 --> AuditDone
AuditDone --> Epic74
Epic74 --> Partial
Partial --> Open
Epic74 --> Open
```
## Status
PureXML is a working, dependency-free XML library today: parse, emit, validate,
query, and stream documents on macOS, Linux, Windows, and WASM. The test suite
currently runs **697 tests in 111 suites** (`swift test`).
currently runs **699 tests in 111 suites** (`swift test`).
### Shipped (libxml2-aligned surface)

View File

@ -67,11 +67,13 @@ private struct XIncludeRun {
}
private func selectedNodes(from parsed: Node, xpointer: String?) -> [Node] {
if let xpointer {
let selections = (try? PureXML.XPointer.evaluate(xpointer, over: parsed)) ?? []
return selections.map(Self.node)
}
return [documentElement(of: parsed) ?? parsed]
guard let xpointer else { return [documentElement(of: parsed) ?? parsed] }
let selections = (try? PureXML.XPointer.evaluate(xpointer, over: parsed)) ?? []
if !selections.isEmpty { return selections.map(Self.node) }
// No node-selecting scheme matched: fall back to the XPointer range model
// (range()/range-to()/string-range()) and include each range's content.
let ranges = (try? PureXML.XPointer.evaluateRanges(xpointer, over: parsed)) ?? []
return ranges.flatMap(\.nodes)
}
private func documentElement(of parsed: Node) -> Node? {

View File

@ -48,6 +48,22 @@ struct XIncludeTests {
#expect(result == "<doc xmlns:xi=\"http://www.w3.org/2001/XInclude\"><item>two</item></doc>")
}
@Test("xi:include with an xpointer range() includes the covering range")
func test_includeRange() throws {
let xml = "<doc xmlns:xi=\"http://www.w3.org/2001/XInclude\">"
+ "<xi:include href=\"frag.xml\" xpointer=\"xpointer(range(//item[2]))\"/></doc>"
let result = try process(xml) { _ in "<list><item>one</item><item>two</item></list>" }
#expect(result == "<doc xmlns:xi=\"http://www.w3.org/2001/XInclude\"><item>two</item></doc>")
}
@Test("xi:include with a string-range xpointer includes the matched text")
func test_includeStringRange() throws {
let xml = "<doc xmlns:xi=\"http://www.w3.org/2001/XInclude\">"
+ "<xi:include href=\"frag.xml\" xpointer=\"xpointer(string-range(//item, 'wo'))\"/></doc>"
let result = try process(xml) { _ in "<list><item>one</item><item>two</item></list>" }
#expect(result == "<doc xmlns:xi=\"http://www.w3.org/2001/XInclude\">wo</doc>")
}
@Test("href resolves against an xml:base on an ancestor")
func test_xmlBase() throws {
let xml = "<doc xmlns:xi=\"http://www.w3.org/2001/XInclude\" xml:base=\"sub/\">"