Home /Modules/xml/README.md

README.md

lib/xml/README.md · 184 line(s) · markdown

<img align="right" src="https://github.com/mearvk/SLeeLa/blob/master/images/debian/debian-logo.png" width="75" height="75" alt="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), 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
FileRole
SLPackage.sleelaPackage facade (configure/name/available).
SLXmlNodeType.sleelaThe DOM nodeType vocabulary (element/text/cdata/PI/comment/document) and the predicates a walker branches on.
SLXmlAttribute.sleelaOne name="value" attribute, with namespace prefix/local resolution over a char-cell view.
SLXmlNode.sleelaThe central DOM node: children, attributes, textContent, getElementsByTagName, depth/counts.
SLXmlDocument.sleelaThe DOM Document: node factory (createElement/createTextNode/…), root management, getElementById, getElementsByTagName, serialization.
SLXmlSerializer.sleelaDOM → text, compact or pretty, with XML 1.0 §2.4 escaping.
SLXmlParser.sleelaText (as char cells) → DOM for the common subset, plus a structural well-formedness check.
SLXmlAspect.sleelaThe aspect/quality register: each aspect, its governing item, and an honest 0..10 quality.
xml-dom.sleelaThe runnable reference (class XmlDom with main).

Using it (syntax 2.5)

A caller drives one document object end to end:

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:

# 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:

The xml-dom.sleela demo shows both: it escapes "Jack & Jill <xml>" on output and parses <doc><p id="x1">hi</p></doc> back into a DOM from cells.

Node kinds (DOM nodeType)

Mirror the W3C DOM constants (SLXmlNodeType):

CodeKindCarries
1elementname, attributes, children
3textcharacter data
4cdataa literal <![CDATA[…]]> section
7processing-instruction<?target data?>
8comment<!-- … -->
9documentthe 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.

AspectGoverning itemQuality (this library)
well-formednessW3C REC-xml §2strong (8/10)
DOM tree modelW3C DOM Level 1excellent (9/10)
namespace-awarenessNamespaces in XML 1.0strong (7/10)
serializationW3C REC-xml §2.4excellent (9/10)
validity (DTD/XSD)W3C REC-xml §2 / XSDminimal (1/10) — not yet implemented
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.

RungMethodMeansChildren consulted?
1 — identitysameReference(other)the two references point at the one object in memory (native == on objects = reference identity)—
2 — same subjectsameSubject(other)distinct objects that denote the same named thing: same nature (nodeType), name, id, and (for leaves) value, compared case-sensitivelyno
3 — structureequals(other) / sameStructure(other)the whole subtrees are shaped alike: same subject, same attribute set (name+value, order-independent), same children in order, recursivelyyes

tieStrength(other) reports the rung two nodes meet on — 3 identity, 2 structure, 1 subject, 0 untied — and tieName(n) gives the word.

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.