SLXmlNode.sleela
lib/xml/SLXmlNode.sleela · 491 line(s) · sleela
<< 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 | <nation> | 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;
}
}