Home /Modules/xml/SLXmlNode.sleela

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;
  }
}