Merge #83 (stage 4b): adoption agency algorithm

This commit is contained in:
Mihaela Mihaljevic 2026-06-09 05:46:13 +02:00
commit 2af445dd09
5 changed files with 224 additions and 7 deletions

View File

@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- HTML5 adoption agency algorithm and active formatting elements (#83, stage 4): misnested formatting tags are now recovered exactly as the HTML standard prescribes. Overlapping tags nest (`<b><i></b></i>` -> `<b><i></i></b>`), content after an out-of-order close is re-wrapped by reconstructing the active formatting elements (`<b><i></b>X</i>` -> `<b><i></i></b><i>X</i>`), and a block inside a formatting element reparents through the furthest-block path, including the canonical `<p>1<b>2<i>3</b>4</i>5</p>` -> `<p>1<b>2<i>3</i></b><i>4</i>5</p>`.
- HTML5 SVG element-name case adjustment (#83, stage 3): an SVG element written in mixed case (which the tokenizer lowercases) is restored to its canonical camel case in the tree, so `<foreignObject>`, `<linearGradient>`, `<clipPath>`, and the rest carry their correct SVG names. Applies only in the SVG namespace; same-named HTML elements keep their lowercased name.
- HTML5 foreign content (#83, stage 2): an `<svg>` or `<math>` element and all of its descendants now carry the SVG (`http://www.w3.org/2000/svg`) or MathML (`http://www.w3.org/1998/Math/MathML`) namespace on their `QualifiedName`, so foreign elements are distinguishable from same-named HTML; ordinary HTML content (including content after a closed `<svg>`) stays in no namespace. (SVG/MathML element- and attribute-name case adjustment, and HTML integration points, are a later refinement.)
- HTML5 table tree construction (#83, stage 1): a `<table>` written without its section and row wrappers now nests correctly. A `<tr>` directly inside a `<table>` gets an implied `<tbody>`, a `<td>`/`<th>` gets an implied `<tr>` (and section), consecutive rows share one implied `<tbody>`, and an explicit `<thead>`/`<tbody>`/`<tfoot>` is not duplicated, all inside an open table only.

View File

@ -89,7 +89,7 @@ flowchart TB
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 **727 tests in 114 suites** (`swift test`).
currently runs **733 tests in 115 suites** (`swift test`).
### Shipped (libxml2-aligned surface)

View File

@ -0,0 +1,156 @@
extension HTMLDocument {
/// The formatting elements tracked on the active-formatting list and recovered
/// by the adoption agency.
private static let formatting: Set<String> = [
"a", "b", "big", "code", "em", "font", "i", "nobr", "s", "small", "strike", "strong", "tt", "u",
]
/// The "special" category: an element of this kind, open below a formatting
/// element, is the furthest block that triggers reparenting.
private static let special: Set<String> = [
"address", "applet", "area", "article", "aside", "blockquote", "body", "br", "button", "caption",
"center", "col", "colgroup", "dd", "details", "dir", "div", "dl", "dt", "embed", "fieldset",
"figcaption", "figure", "footer", "form", "frame", "frameset", "h1", "h2", "h3", "h4", "h5", "h6",
"header", "hgroup", "hr", "html", "iframe", "img", "input", "li", "listing", "main", "marquee",
"menu", "nav", "object", "ol", "p", "plaintext", "pre", "section", "select", "summary", "table",
"tbody", "td", "textarea", "tfoot", "th", "thead", "title", "tr", "ul", "wbr", "xmp",
]
/// The elements that bound "element in scope" lookups.
private static let scopeBoundaries: Set<String> = [
"applet", "caption", "html", "table", "td", "th", "marquee", "object",
]
func isFormatting(_ name: String) -> Bool {
Self.formatting.contains(name)
}
private func openIndex(_ node: PureXML.Model.TreeNode) -> Int? {
openBody.firstIndex { $0 === node }
}
private func formattingIndex(_ node: PureXML.Model.TreeNode) -> Int? {
activeFormatting.firstIndex { $0 === node }
}
/// Whether `target` is in scope: reachable up the open stack without crossing a
/// scope boundary.
private func hasInScope(_ target: PureXML.Model.TreeNode) -> Bool {
for node in openBody.reversed() {
if node === target { return true }
if Self.scopeBoundaries.contains(tagName(node)) { return false }
}
return false
}
/// The HTML5 "reconstruct the active formatting elements" step: re-open any
/// formatting elements that were closed out of order, so content after them is
/// re-wrapped (the `<b><i></b>X</i>` -> `<b><i></i></b><i>X</i>` behavior).
func reconstructActiveFormatting() {
guard var index = activeFormatting.indices.last else { return }
if activeFormatting[index] == nil || isOpen(activeFormatting[index]) { return }
while index > 0 {
index -= 1
if activeFormatting[index] == nil || isOpen(activeFormatting[index]) {
index += 1
break
}
}
while index < activeFormatting.count {
if let template = activeFormatting[index] {
let clone = template.shallowCopy()
openBody.last?.append(clone)
openBody.append(clone)
activeFormatting[index] = clone
}
index += 1
}
}
private func isOpen(_ node: PureXML.Model.TreeNode?) -> Bool {
guard let node else { return false }
return openBody.contains { $0 === node }
}
/// The HTML5 adoption agency algorithm: recovers a misnested formatting element
/// end tag, reparenting the intervening block (the "furthest block") and
/// cloning the formatting element around it.
func adoptionAgency(_ subject: String) {
if let current = openBody.last, current !== bodyRoot, tagName(current) == subject, formattingIndex(current) == nil {
openBody.removeLast()
return
}
var outer = 0
while outer < 8 {
outer += 1
guard let formattingIndexInList = lastFormatting(tag: subject), let formattingElement = activeFormatting[formattingIndexInList] else {
bodyClose(subject)
return
}
guard let formattingOpenIndex = openIndex(formattingElement) else {
activeFormatting.remove(at: formattingIndexInList)
return
}
if !hasInScope(formattingElement) { return }
guard let furthestBlockIndex = openBody[(formattingOpenIndex + 1)...].firstIndex(where: { Self.special.contains(tagName($0)) }) else {
openBody.removeLast(openBody.count - formattingOpenIndex)
activeFormatting.remove(at: formattingIndexInList)
return
}
reparent(formattingElement: formattingElement, formattingIndexInList: formattingIndexInList, furthestBlockIndex: furthestBlockIndex)
}
}
private func lastFormatting(tag: String) -> Int? {
for index in activeFormatting.indices.reversed() {
guard let entry = activeFormatting[index] else { return nil } // a marker bounds the search
if tagName(entry) == tag { return index }
}
return nil
}
/// Steps 8-19 of the algorithm: walk the open elements between the formatting
/// element and the furthest block, cloning formatting nodes, then clone the
/// formatting element around the furthest block's content.
private func reparent(formattingElement: PureXML.Model.TreeNode, formattingIndexInList: Int, furthestBlockIndex: Int) {
let furthestBlock = openBody[furthestBlockIndex]
guard let formattingOpenIndex = openIndex(formattingElement), formattingOpenIndex >= 1 else { return }
let commonAncestor = openBody[formattingOpenIndex - 1]
var bookmark = formattingIndexInList
var lastNode = furthestBlock
var nodeIndex = furthestBlockIndex
var inner = 0
while inner < 3 {
inner += 1
nodeIndex -= 1
let node = openBody[nodeIndex]
if node === formattingElement { break }
guard let activeIndex = formattingIndex(node) else {
openBody.remove(at: nodeIndex)
continue
}
let clone = node.shallowCopy()
activeFormatting[activeIndex] = clone
openBody[nodeIndex] = clone
if lastNode === furthestBlock { bookmark = activeIndex + 1 }
clone.append(lastNode)
lastNode = clone
}
commonAncestor.append(lastNode)
let formattingClone = formattingElement.shallowCopy()
for child in furthestBlock.children {
formattingClone.append(child)
}
furthestBlock.append(formattingClone)
if let removeIndex = formattingIndex(formattingElement) {
activeFormatting.remove(at: removeIndex)
if removeIndex < bookmark { bookmark -= 1 }
}
activeFormatting.insert(formattingClone, at: min(bookmark, activeFormatting.count))
if let removeOpen = openIndex(formattingElement) { openBody.remove(at: removeOpen) }
// The clone becomes a child of the furthest block, so it sits immediately
// above it on the open-elements stack; inserting below would re-find the
// same furthest block and loop.
if let blockIndex = openIndex(furthestBlock) { openBody.insert(formattingClone, at: blockIndex + 1) }
}
}

View File

@ -28,8 +28,9 @@ private enum InsertionMode {
/// Builds a full HTML document from tokens by driving the HTML5 insertion modes,
/// materializing the implied `html`/`head`/`body` and routing head-only elements
/// into the head. File-scope and private.
private final class HTMLDocument {
/// into the head. The adoption agency lives in a sibling file, so this type is
/// internal (its members stay private except the live-body state it shares).
final class HTMLDocument {
typealias Token = PureXML.HTML.Token
typealias Node = PureXML.Model.Node
typealias Attribute = PureXML.Model.Attribute
@ -50,8 +51,11 @@ private final class HTMLDocument {
/// of currently-open elements into that tree, with the body element at the
/// bottom. This lets the adoption agency reparent already-built subtrees, which
/// a pop-on-close model cannot.
private let bodyRoot = PureXML.Model.TreeNode.element("body")
private lazy var openBody: [PureXML.Model.TreeNode] = [bodyRoot]
let bodyRoot = PureXML.Model.TreeNode.element("body")
lazy var openBody: [PureXML.Model.TreeNode] = [bodyRoot]
/// The active formatting elements (the HTML5 list), with nil entries acting as
/// scope markers. Drives reconstruction and the adoption agency.
var activeFormatting: [PureXML.Model.TreeNode?] = []
func build(_ tokens: [Token]) -> Node {
for token in tokens {
@ -159,10 +163,15 @@ private final class HTMLDocument {
private func processInBody(_ token: Token) {
switch token {
case let .startTag(name, attributes, selfClosing):
reconstructActiveFormatting()
bodyOpen(name, attributes, selfClosing: selfClosing)
noteOpenedFormatting(name, selfClosing: selfClosing)
case let .endTag(name) where isFormatting(name):
adoptionAgency(name)
case let .endTag(name) where name != "body" && name != "html":
bodyClose(name)
case let .text(value):
reconstructActiveFormatting()
bodyInsert(.text(value))
case let .comment(value):
bodyInsert(.comment(value))
@ -171,11 +180,18 @@ private final class HTMLDocument {
}
}
/// After opening a start tag, records it on the active-formatting list when it
/// is a formatting element (so misnesting can be recovered later).
private func noteOpenedFormatting(_ name: String, selfClosing: Bool) {
guard isFormatting(name), !selfClosing, !PureXML.HTML.Elements.void.contains(name), let opened = openBody.last else { return }
activeFormatting.append(opened)
}
// MARK: Body building (live mutable tree)
/// The lowercased tag name of an open element, for case-insensitive stack
/// matching (an SVG element's canonical camel case folds back to the token).
private func tagName(_ node: PureXML.Model.TreeNode) -> String {
func tagName(_ node: PureXML.Model.TreeNode) -> String {
node.name?.localName.lowercased() ?? ""
}
@ -194,7 +210,7 @@ private final class HTMLDocument {
}
}
private func bodyClose(_ name: String) {
func bodyClose(_ name: String) {
guard let index = openBody.lastIndex(where: { tagName($0) == name }), index >= 1 else { return }
openBody.removeLast(openBody.count - index)
}

View File

@ -0,0 +1,44 @@
@testable import PureXML
import Testing
@Suite("HTML5 adoption agency (misnested formatting elements)")
struct HTMLAdoptionTests {
private func body(_ html: String) -> String {
let full = PureXML.HTML.serialize(PureXML.HTML.parseDocument(html))
let wrapper = "<html><head></head><body>"
guard full.hasPrefix(wrapper), full.hasSuffix("</body></html>") else { return full }
return String(full.dropFirst(wrapper.count).dropLast("</body></html>".count))
}
@Test("Overlapping formatting tags are nested")
func test_overlapping() {
#expect(body("<b><i></b></i>") == "<b><i></i></b>")
}
@Test("Content after a misnested close is re-wrapped (reconstruction)")
func test_reconstruction() {
#expect(body("<b><i></b>X</i>") == "<b><i></i></b><i>X</i>")
}
@Test("A block inside a formatting element triggers the furthest-block path")
func test_furthestBlock() {
#expect(body("<b>1<p>2</b>3</p>") == "<b>1</b><p><b>2</b>3</p>")
}
@Test("Nested anchors and formatting close cleanly")
func test_nestedFormatting() {
#expect(body("<a><b></a>") == "<a><b></b></a>")
}
@Test("The canonical adoption-agency example reparents correctly")
func test_canonicalExample() {
// The well-known html5lib case for the adoption agency algorithm.
#expect(body("<p>1<b>2<i>3</b>4</i>5</p>") == "<p>1<b>2<i>3</i></b><i>4</i>5</p>")
}
@Test("Well-nested formatting is unchanged")
func test_wellNested() {
#expect(body("<b><i>x</i></b>") == "<b><i>x</i></b>")
#expect(body("<p><b>bold</b> and <i>italic</i></p>") == "<p><b>bold</b> and <i>italic</i></p>")
}
}