# 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`.