SLeeLa # SLeeLa XML (DOM) **Status: SLeeLa-side XML Document Object Model.** This directory is the language-facing XML layer: a DOM tree (`SLXmlDocument` → `SLXmlNode` → `SLXmlAttribute`) with the familiar Node/Element/Document operations, a text-to-DOM reader (`SLXmlParser`), a DOM-to-text writer (`SLXmlSerializer`), and a conformance register (`SLXmlAspect`) that rates the **quality of each XML aspect** this library addresses. It is governed by the real instruments it names: XML 1.0 ([W3C REC-xml, Fifth Edition](https://www.w3.org/TR/xml/)), the DOM Node/Element interface, and Namespaces in XML 1.0. Values in the metadata records are faithful to those origins. Content was rephrased for compliance with licensing restrictions. ## The DOM shape ``` SLXmlDocument the document: declaration + the single root element, │ the node factory, and document-level queries ├─ root : SLXmlNode the document element │ ├─ children : SLXmlNode[] ordered child nodes (DOM Node) │ └─ attrs : SLXmlAttribute[] named attributes (DOM Element) └─ writer : SLXmlSerializer DOM → well-formed XML text ``` | File | Role | | --- | --- | | `SLPackage.sleela` | Package facade (`configure`/`name`/`available`). | | `SLXmlNodeType.sleela` | The DOM `nodeType` vocabulary (element/text/cdata/PI/comment/document) and the predicates a walker branches on. | | `SLXmlAttribute.sleela` | One `name="value"` attribute, with namespace prefix/local resolution over a char-cell view. | | `SLXmlNode.sleela` | The central DOM node: children, attributes, `textContent`, `getElementsByTagName`, depth/counts. | | `SLXmlDocument.sleela` | The DOM `Document`: node factory (`createElement`/`createTextNode`/…), root management, `getElementById`, `getElementsByTagName`, serialization. | | `SLXmlSerializer.sleela` | DOM → text, compact or pretty, with XML 1.0 §2.4 escaping. | | `SLXmlParser.sleela` | Text (as char cells) → DOM for the common subset, plus a structural well-formedness check. | | `SLXmlAspect.sleela` | The aspect/quality register: each aspect, its governing item, and an honest 0..10 quality. | | `xml-dom.sleela` | The runnable reference (`class XmlDom` with `main`). | ## Using it (syntax 2.5) A caller drives **one document object** end to end: ```java SLXmlDocument doc = new SLXmlDocument(); doc.create(); SLXmlNode catalog = doc.newRoot("catalog"); // the document element SLXmlNode item = doc.createElement("item"); item.setAttribute("id", "a1"); item.setAttribute("origin", "United States"); // an Item's origin item.addElement("name").addText("Liberty Bell"); catalog.appendChild(item); print(doc.toPrettyXml()); // declaration + tree SLXmlNode items = doc.getElementsByTagName("item"); // a NodeList-like node print(items.childCount()); // 1 SLXmlNode byId = doc.getElementById("a1"); // DOM-style lookup print(byId.textContent()); // "Liberty Bell" ``` Run the executable reference: ```sh # from the repository root, with the SHA-256 manifest selected SLEELA_SHA256_MANIFEST="$(pwd)/security/sha256-manifest.json" \ ./impl/build/sleela run lib/xml/xml-dom.sleela ``` ## Character data, escaping, and the opaque String SLeeLa's built-in `String` is **opaque**: it supports `+` and `==` but no in-language slicing (this is the same contract `lib/text/SLString` documents). Real character-level work is therefore done over an explicit **char-cell `String[]`** — one glyph per cell — the sanctioned mechanism across the standard library. Consequences for XML, handled honestly rather than faked: - **Serialization** of content containing `&`, `<`, `>`, or `"` needs a char-cell view so the writer can escape it (`&`, `<`, `>`, `"`). Attach it with `node.addTextCells(value, cells)` / `node.setAttributeCells(name, value, cells)`. Content known free of those characters uses plain `addText` / `setAttribute` and serializes verbatim. - **Parsing** reads a char-cell view: `parser.parseCells(cells)` and `parser.isWellFormedCells(cells)`. A caller supplies the cells at the boundary (from a known decomposition or the runtime's bridged `chars()`). The `xml-dom.sleela` demo shows both: it escapes `"Jack & Jill "` on output and parses `

hi

` back into a DOM from cells. ## Node kinds (DOM `nodeType`) Mirror the W3C DOM constants (`SLXmlNodeType`): | Code | Kind | Carries | | --- | --- | --- | | `1` | element | name, attributes, children | | `3` | text | character data | | `4` | cdata | a literal `` section | | `7` | processing-instruction | `` | | `8` | comment | `` | | `9` | document | the single root element | ## The aspect / quality register `SLXmlAspect` catalogues the aspects an XML processor is judged by and reports an **honest** 0..10 quality for how fully *this* library addresses each — an unimplemented aspect scores low, never an inflated value. | Aspect | Governing item | Quality (this library) | | --- | --- | --- | | well-formedness | W3C REC-xml §2 | strong (8/10) | | DOM tree model | W3C DOM Level 1 | excellent (9/10) | | namespace-awareness | Namespaces in XML 1.0 | strong (7/10) | | serialization | W3C REC-xml §2.4 | excellent (9/10) | | validity (DTD/XSD) | W3C REC-xml §2 / XSD | minimal (1/10) — not yet implemented | ```java SLXmlAspect a = new SLXmlAspect(); print(a.nameOf(1) + " " + a.qualityOf(1) + "/10 " + a.bandOf(a.qualityOf(1))); print("overall quality x10: " + a.overallQualityX10()); // 68 = 6.8 / 10 ``` ## Equality — a three-rung "tie of trust" Comparing two nodes is answered on an escalating ladder; each rung is a stronger tie than the last, and the binary question stays simple — two nodes are either the **same pointer**, the **same subject**, or the **same structure**. | Rung | Method | Means | Children consulted? | | --- | --- | --- | --- | | **1 — identity** | `sameReference(other)` | the two references point at the one object in memory (native `==` on objects = reference identity) | — | | **2 — same subject** | `sameSubject(other)` | distinct objects that denote the same named thing: same **nature** (`nodeType`), **name**, **id**, and (for leaves) **value**, compared case-sensitively | no | | **3 — structure** | `equals(other)` / `sameStructure(other)` | the whole subtrees are shaped alike: same subject, same attribute **set** (name+value, order-independent), same children **in order**, recursively | yes | `tieStrength(other)` reports the rung two nodes meet on — `3` identity, `2` structure, `1` subject, `0` untied — and `tieName(n)` gives the word. ```java SLXmlNode a = doc.getElementById("x"); SLXmlNode b = other.getElementById("x"); a.sameReference(b); // Tier 1: same object in memory? a.sameSubject(b); // Tier 2: same named thing (ignoring subtree)? a.equals(b); // Tier 3: structurally deep-equal? (the default sense) a.tieName(a.tieStrength(b)); // "identity" | "structure" | "subject" | "untied" ``` The default `equals()` is the structural tie — the strongest sense in which two **independently built** XML trees can be equal. `SLXmlAttribute.equals` (name + value) and `SLXmlDocument.equals` (defers to the root elements' structural equality) follow the same ladder. **Charge / idempotency guarantees.** Every rung is **reflexive** (`x.equals(x)` is always true), **symmetric** (`a.equals(b) == b.equals(a)`), and **deterministic/stable** — comparing two unchanged trees always yields the same answer, with no hidden state, clock, or allocation that could perturb it, so re-asking is idempotent. String comparison is null-safe and case-sensitive (XML names are case-sensitive; no case folding is applied). The `xml-dom.sleela` demo exercises all four outcomes and verifies the three guarantees. ## Implementation boundary This layer models, builds, queries, serializes, and reparses XML in the common subset. It does **not** implement DTD/XSD validity, general (non-predefined) entity expansion, or namespace binding resolution beyond prefix/local splitting; those aspects report their honest standing through `SLXmlAspect` rather than pretending to a capability the code does not have — the same "never fake a result" contract the `lib/codecs` and `lib/compression` families carry. ## Metadata Class metapattern Every class here carries the descriptive-metadata block required across SLeeLa (see `.kiro/steering/metadata-class-standard.md`): eleven catalogued attributes with get/set pairs, under the verbatim greppable header. `SLXmlAspect` is an executive-grade class and carries the full record (identity + legality via `metaNationalSchedule` + fiduciary + jurisdictional `metaOrigin`). The XML standards are stewarded by the W3C, an international consortium (host institutions include MIT in the United States, ERCIM in Europe, Keio in Japan, and Beihang in China), so `metaOrigin` is `International`.