<< lib/xml/SLXmlNode.sleela SLeeLa Standard Library Definition. Definition: Defines SLXmlNode -- the central DOM node. An element node owns an ordered list of child nodes and a list of attributes; text/CDATA/comment/PI nodes carry character data. This is the mutable tree a document, parser, and serializer all operate on. >> #sleela 2.5 material; < Family: xml. The DOM node. Every node has a kind (one of the SLXmlNodeType > < codes), a name (the tag name for an element; a conventional name such as > < "#text" / "#comment" for leaf kinds), and character data (used by text, CDATA, > < comment, and PI kinds). Element nodes additionally own ordered children and > < named attributes, both held in growable VM-managed arrays. > < > < The DOM operations mirror the W3C Node / Element interface, in SLeeLa spelling: > < appendChild, childCount, childAt, setAttribute, getAttribute, hasAttribute, > < getElementsByTagName (collected into a caller-provided result list), textContent, > < firstChild / lastChild, and removeChild. > class SLXmlNode { < ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- > << Eleven catalogued attributes with getter/setter pairs, so a GUI, loader, or catalog can read and (where appropriate) override this record. Values are faithful to the subject's real origin where publicly known. >> String metaVersion = "1.0.0"; int metaId = 7923; String metaAuthor = "Kiro Agent"; String metaDate = "2026-10-28"; String metaCopyright = "SLeeLa project"; String metaTrademark = "none"; String metaCorporation = "none"; < metaOrigin: National | | International | Galactic > String metaOrigin = "International"; String metaBirthDate = "2026-10-28"; < metaScienceRating: maturity/robustness on a 1..10 scale > int metaScienceRating = 9; < metaNationalSchedule: a real, citable instrument. > String metaNationalSchedule = "W3C DOM Level 1 Node/Element interface"; String getMetaVersion() { return metaVersion; } void setMetaVersion(String v) { metaVersion = v; } int getMetaId() { return metaId; } void setMetaId(int v) { metaId = v; } String getAuthor() { return metaAuthor; } void setAuthor(String v) { metaAuthor = v; } String getDate() { return metaDate; } void setDate(String v) { metaDate = v; } String getCopyright() { return metaCopyright; } void setCopyright(String v) { metaCopyright = v; } String getTrademark() { return metaTrademark; } void setTrademark(String v) { metaTrademark = v; } String getCorporation() { return metaCorporation; } void setCorporation(String v) { metaCorporation = v; } String getOrigin() { return metaOrigin; } void setOrigin(String v) { metaOrigin = v; } String getBirthDate() { return metaBirthDate; } void setBirthDate(String v) { metaBirthDate = v; } int getScienceRating() { return metaScienceRating; } void setScienceRating(int v) { metaScienceRating = v; } String getNationalSchedule() { return metaNationalSchedule; } void setNationalSchedule(String v) { metaNationalSchedule = v; } < ---- node identity ---- > < nodeType: one of the SLXmlNodeType codes (1 element, 3 text, ...). > int kind; < For an element: the tag name. For leaves: a conventional "#text" etc. > String nodeName; < Character data for text/CDATA/comment/PI leaves (unescaped). "" otherwise. > String data; << Optional char-cell view of `data` (one glyph per cell). The built-in String is opaque, so the serializer can only escape special characters when a cell view is supplied. Content set with a plain value (no cells) is emitted verbatim (use it for content known free of & < > "). >> String[] dataCellView; boolean dataHasCells = false; << ---- tree storage (element nodes) ---- The backing stores are GROWABLE VM-managed object arrays: they start empty and grow by arrayPush (the idiom lib/collections/SLList uses for String[], here applied to class-typed arrays). This keeps a node's footprint proportional to its actual children/attributes rather than pre-allocating a large fixed capacity for every node -- important when a document holds many nodes. The logical counts childN/attrN track how many slots are in use (capacity may exceed them after a removal, and is then reused). >> SLXmlNode[] children = new SLXmlNode[0]; int childN = 0; SLXmlAttribute[] attrs = new SLXmlAttribute[0]; int attrN = 0; < Ensure the backing stores exist (defensive; the field initializers already > < allocate them, so this is a no-op for a normally `new`-ed node). > void ensureStores() { if (children == null) { children = new SLXmlNode[0]; } if (attrs == null) { attrs = new SLXmlAttribute[0]; } } < ---- construction ---- > < Make this an element node named `tag`. > void asElement(String tag) { ensureStores(); kind = 1; nodeName = tag; data = ""; } < Make this a text node holding `value`. > void asText(String value) { ensureStores(); kind = 3; nodeName = "#text"; data = value; } < Make this a CDATA section holding `value`. > void asCData(String value) { ensureStores(); kind = 4; nodeName = "#cdata-section"; data = value; } < Make this a processing instruction with target `target` and data `value`. > void asProcessingInstruction(String target, String value) { ensureStores(); kind = 7; nodeName = target; data = value; } < Make this a comment holding `value`. > void asComment(String value) { ensureStores(); kind = 8; nodeName = "#comment"; data = value; } < Attach a char-cell view of this node's data so the serializer can escape it. > void setDataCells(String[] cells) { dataCellView = cells; dataHasCells = true; } boolean hasDataCells() { return dataHasCells; } String[] dataCells() { return dataCellView; } < ---- identity accessors ---- > int nodeType() { return kind; } String name() { return nodeName; } String nodeValue() { return data; } void setNodeValue(String v) { data = v; } boolean isElement() { return kind == 1; } boolean isText() { return kind == 3; } boolean isCharacterData() { return kind == 3 || kind == 4; } < ---- children (DOM Node) ---- > < Append a child node and return it (DOM appendChild returns the child). > < Reuses a freed slot when capacity exceeds the live count; else grows. > SLXmlNode appendChild(SLXmlNode child) { ensureStores(); if (childN < arrayLength(children)) { children[childN] = child; } else { arrayPush(children, child); } childN = childN + 1; return child; } int childCount() { return childN; } < The child at `index`, or null when out of range. > SLXmlNode childAt(int index) { if (index < 0 || index >= childN) { return null; } return children[index]; } SLXmlNode firstChild() { return childAt(0); } SLXmlNode lastChild() { return childAt(childN - 1); } < Remove the child at `index`, preserving the order of the rest. > < Returns the removed node, or null when the index is invalid. > SLXmlNode removeChild(int index) { if (index < 0 || index >= childN) { return null; } SLXmlNode gone = children[index]; int i = index; while (i + 1 < childN) { children[i] = children[i + 1]; i = i + 1; } childN = childN - 1; return gone; } < Convenience: create, append, and return a child element. > SLXmlNode addElement(String tag) { SLXmlNode e = new SLXmlNode(); e.asElement(tag); return appendChild(e); } < Convenience: append a text node with `value` (emitted verbatim). > SLXmlNode addText(String value) { SLXmlNode t = new SLXmlNode(); t.asText(value); return appendChild(t); } < Convenience: append a text node whose `cells` are the glyphs of its value, > < so the serializer escapes & < > correctly. `value` is the rejoined text. > SLXmlNode addTextCells(String value, String[] cells) { SLXmlNode t = new SLXmlNode(); t.asText(value); t.setDataCells(cells); return appendChild(t); } < Convenience: append a comment node. > SLXmlNode addComment(String value) { SLXmlNode c = new SLXmlNode(); c.asComment(value); return appendChild(c); } < ---- attributes (DOM Element) ---- > int attributeCount() { return attrN; } < Index of the attribute whose qualified name equals `qn`, or -1. > int attributeIndex(String qn) { ensureStores(); for (int i = 0; i < attrN; i = i + 1) { SLXmlAttribute a = attrs[i]; if (a != null && a.getName() == qn) { return i; } } return -1; } boolean hasAttribute(String qn) { return attributeIndex(qn) >= 0; } < The value of attribute `qn`, or null when it is absent. > String getAttribute(String qn) { int i = attributeIndex(qn); if (i < 0) { return null; } SLXmlAttribute a = attrs[i]; return a.getValue(); } < Set attribute `qn` to `value`, replacing an existing one or appending a new. > void setAttribute(String qn, String value) { ensureStores(); int i = attributeIndex(qn); if (i >= 0) { SLXmlAttribute existing = attrs[i]; existing.setValue(value); return; } SLXmlAttribute a = new SLXmlAttribute(); a.set(qn, value); if (attrN < arrayLength(attrs)) { attrs[attrN] = a; } else { arrayPush(attrs, a); } attrN = attrN + 1; } < Set attribute `qn` to a value whose `cells` are its glyphs, so the serializer > < escapes & < > " correctly. `value` is the rejoined text. > void setAttributeCells(String qn, String value, String[] cells) { setAttribute(qn, value); int i = attributeIndex(qn); if (i >= 0) { SLXmlAttribute a = attrs[i]; a.setValueCells(cells); } } < The attribute object at `index`, or null when out of range. > SLXmlAttribute attributeAt(int index) { if (index < 0 || index >= attrN) { return null; } return attrs[index]; } < Remove attribute `qn`; return true when one was removed. > boolean removeAttribute(String qn) { int idx = attributeIndex(qn); if (idx < 0) { return false; } int i = idx; while (i + 1 < attrN) { attrs[i] = attrs[i + 1]; i = i + 1; } attrN = attrN - 1; return true; } < ---- queries (DOM Element) ---- > < The concatenated character data of this node and all its descendants, > < i.e. DOM textContent. Element structure contributes no characters. > String textContent() { if (kind == 3 || kind == 4) { return data; } String acc = ""; for (int i = 0; i < childN; i = i + 1) { SLXmlNode c = children[i]; if (c != null) { acc = acc + c.textContent(); } } return acc; } < The first direct child element with tag name `tag`, or null. > SLXmlNode firstElementByTag(String tag) { for (int i = 0; i < childN; i = i + 1) { SLXmlNode c = children[i]; if (c != null && c.isElement() && c.name() == tag) { return c; } } return null; } < DOM getElementsByTagName: append every descendant element whose tag is > < `tag` (document order) into the caller-provided result node, which is used > < purely as an ordered collection via appendChild. "*" matches every element. > void collectByTag(String tag, SLXmlNode result) { for (int i = 0; i < childN; i = i + 1) { SLXmlNode c = children[i]; if (c == null) { continue; } if (c.isElement()) { if (tag == "*" || c.name() == tag) { result.appendChild(c); } c.collectByTag(tag, result); } } } < Count descendant elements (not counting this node). > int descendantElementCount() { int n = 0; for (int i = 0; i < childN; i = i + 1) { SLXmlNode c = children[i]; if (c != null && c.isElement()) { n = n + 1 + c.descendantElementCount(); } } return n; } < Depth of the deepest element subtree rooted here (a leaf element is 1). > int depth() { int best = 0; for (int i = 0; i < childN; i = i + 1) { SLXmlNode c = children[i]; if (c != null && c.isElement()) { int d = c.depth(); if (d > best) { best = d; } } } return best + 1; } << ==================================================================== EQUALITY -- a three-rung "tie of trust" ==================================================================== Comparison of two nodes is answered on an escalating ladder, each rung a stronger tie than the last. The binary question stays simple: two nodes are either the SAME POINTER, the SAME SUBJECT, or the SAME STRUCTURE -- and nothing more exotic than that. Tier 1 IDENTITY the two references point at the one object in memory. This is the native == on objects (reference identity, confirmed by the runtime). Strongest and cheapest; if it holds, no further work is done. Tier 2 SAME SUBJECT "callingly the same object": distinct objects that denote the same named thing, decided by carefully comparing the defining attributes -- nature (kind), name, id, and value, each case-sensitively (XML names are case-sensitive, so "Item" and "item" differ). This rung ignores children: it is identity of the node AS A SUBJECT, not of its subtree. Tier 3 STRUCTURE the final tie in trust: the two whole subtrees are shaped alike -- same kind, same name, the same set of attributes (name+value, order-independent), and the same children compared in document order, recursively. Charge / idempotency guarantees (the "physical idempotency of charge based on the nature of tie"): every rung is - reflexive x.equals(x) is always true at every tier; - symmetric a.equals(b) == b.equals(a); - deterministic/stable a comparison of two unchanged trees always yields the same answer (no hidden state, no clock, no allocation that could perturb the result) -- re-asking is idempotent. The default equals() is the structural tie (Tier 3), the strongest sense in which two independently-built XML trees can be "equal". >> < The "id" attribute of this node ("" when absent or not an element). Used as > < part of the subject identity of an element. > String subjectId() { if (kind != 1) { return ""; } String got = getAttribute("id"); if (got == null) { return ""; } return got; } << ---- Tier 1: IDENTITY ---- Same object in memory. Native == on objects is reference identity. >> boolean sameReference(SLXmlNode other) { return this == other; } << ---- Tier 2: SAME SUBJECT ---- Distinct nodes that denote the same named thing. Compares nature (kind), name, id, and leaf value, each case-sensitively. Children are NOT consulted. Reflexive (a node shares every attribute with itself) and symmetric (every test is a symmetric == of two values). >> boolean sameSubject(SLXmlNode other) { if (other == null) { return false; } < Tier 1 subsumes Tier 2: the one object is trivially its own subject. > if (this == other) { return true; } if (kind != other.nodeType()) { return false; } if (!strEq(nodeName, other.name())) { return false; } if (!strEq(subjectId(), other.subjectId())) { return false; } < Leaf kinds (text/cdata/comment/PI) are defined by their data. > if (kind == 3 || kind == 4 || kind == 8 || kind == 7) { return strEq(data, other.nodeValue()); } < Elements and the document node need no data comparison at this tier. > return true; } << ---- Tier 3: STRUCTURE (the default equals) ---- The whole subtree is shaped alike. Escalates through the ladder: a Tier 1 hit returns immediately; otherwise the node must be the SAME SUBJECT and then its attributes (as a set) and its children (in order) must match recursively. This is the strongest tie and the meaning of equals(). >> boolean equals(SLXmlNode other) { if (other == null) { return false; } < Tier 1: identity short-circuit (also guarantees reflexivity). > if (this == other) { return true; } < Tier 2: the nodes must denote the same subject before structure matters. > if (!sameSubject(other)) { return false; } < Attributes must match as a set (order-independent, both directions). > if (!attributesEqual(other)) { return false; } < Children must match in document order, recursively. > if (childN != other.childCount()) { return false; } for (int i = 0; i < childN; i = i + 1) { SLXmlNode mine = children[i]; SLXmlNode theirs = other.childAt(i); if (mine == null) { if (theirs != null) { return false; } } else { if (!mine.equals(theirs)) { return false; } } } return true; } < Convenience alias reading as "the same structure". > boolean sameStructure(SLXmlNode other) { return equals(other); } << Attribute-set equality: every attribute of this node has an equal-valued namesake on `other`, AND the counts match -- so neither side carries an extra attribute. Order-independent, and symmetric by construction (equal counts + one-way containment implies two-way containment). >> boolean attributesEqual(SLXmlNode other) { if (attrN != other.attributeCount()) { return false; } for (int i = 0; i < attrN; i = i + 1) { SLXmlAttribute a = attrs[i]; if (a == null) { return false; } String theirs = other.getAttribute(a.getName()); if (theirs == null) { return false; } if (!strEq(a.getValue(), theirs)) { return false; } } return true; } << ---- the decided tie ---- Report which rung of the ladder two nodes meet on -- the single "nature of the tie". Higher is a stronger trust. Deterministic for unchanged trees. 3 = identity (same reference) 2 = same structure (deep-equal subtrees, distinct objects) 1 = same subject (same named thing, differing subtree) 0 = untied (different subjects) >> int tieStrength(SLXmlNode other) { if (other == null) { return 0; } if (this == other) { return 3; } if (equals(other)) { return 2; } if (sameSubject(other)) { return 1; } return 0; } < A human word for a tie strength. > String tieName(int strength) { if (strength == 3) { return "identity"; } if (strength == 2) { return "structure"; } if (strength == 1) { return "subject"; } return "untied"; } << Null-safe, case-sensitive string equality. Two nulls are equal; a null and a non-null are not. XML is case-sensitive, so == (which is exact) is the right primitive and no case folding is applied. >> boolean strEq(String a, String b) { if (a == null) { return b == null; } if (b == null) { return false; } return a == b; } }