@stxt-lang/core 0.6.3 → 0.7.0

package/README.md

@@ -41,7 +41,7 @@ The package ships CommonJS plus type declarations, so it works from both TypeScr
 ## Parsing
 
 ```ts
-import { Parser, ParseResult, Node } from '@stxt-lang/core';
+import { Parser, ParseResult, Node, InlineNode } from '@stxt-lang/core';
 
 const text = [
     'Article (blog.post):',
@@ -62,14 +62,50 @@ if (result.hasErrors()) {
 
 const article: Node = result.getNodes()[0];
 
-console.log(article.getName());                     // "Article"
-console.log(article.getNamespace());                // "blog.post"
-console.log(article.getChild('Title')?.getValue()); // "Getting started with STXT"
+console.log(article.getName());       // "Article"
+console.log(article.getNamespace());  // "blog.post"
+if (article instanceof InlineNode) {
+    console.log(article.getChild('Title')?.getText()); // "Getting started with STXT"
+}
 ```
 
 Use `parser.parse(text)` instead if you prefer an exception (`ParseException`) on the first error.
 
-Nodes are **frozen once parsed** — treat the tree as immutable.
+## Working with the tree
+
+`Node` is an abstract class with exactly two forms, and each one owns only what is really its own: `InlineNode` (`Name: value`) has the optional value, the children and the child lookups (`getChildren()`, `getChild(name)`, `getChildrenByName(name)`); `TextNode` (`Name >>`) has the literal text lines and nothing else. What they share lives in `Node`: name and canonical name, declared and effective namespace, source line, parent (always an `InlineNode`) and `getText()` — the value of an inline node or the joined lines of a text node. Walking a tree therefore asks for the form (`node instanceof InlineNode`), the same way the canonical tree of STXT-TREE-SPEC has `children` only for inline nodes.
+
+Trees are mutable and keep their own integrity: every node knows its parent, `addChild` links both ends and refuses a node that already has one, and `removeChild` / `detach()` undo it. Levels are derived from the chain of parents; the source line is only set by the parser.
+
+```ts
+import { InlineNode, TextNode, Node } from '@stxt-lang/core';
+
+const email = new InlineNode('Email', 'com.example.docs', 'Weekly report');
+email.addInlineNode('From', 'ana@example.com');
+const to = email.addInlineNode('To');
+to.addInlineNode('Address', 'bob@example.com');
+const body = email.addTextNode('Body', 'Hi Bob,\n\nSee attached.');
+
+body.getParent() === email;   // true
+body.getLevel();              // 1
+to.getNamespace();            // "com.example.docs", inherited
+to.getDeclaredNamespace();    // "" — it declares none
+
+// Reorganise: move "To" to the front
+to.detach();
+email.addChild(to, 0);
+
+// Edit in place
+email.setNamespace('com.example.mail');   // the whole inheriting subtree follows
+body.setText('Hi Bob,\n\nSee the new attachment.');
+
+for (const child of email.getChildren()) {
+    if (child instanceof InlineNode) { console.log(child.getValue(), child.getChildren().length); }
+    if (child instanceof TextNode)   { console.log(child.getTextLines()); }
+}
+```
+
+Overloads with two strings always take the second one as the *content* (value or text); the namespace only appears in the three-argument forms. Adding a node that already has a parent throws `NODE_ALREADY_ATTACHED`; adding an ancestor throws `NODE_CYCLE`.
 
 ## Validating against a schema
 
@@ -259,7 +295,7 @@ const doc = NodeWriter.toSTXTDocs(result.getNodes(), IndentStyle.SPACES_4);
 
 Everything importable from the package:
 
-- **Parsing** — `Node`, `Parser`, `ParseResult`, `Line`, `Constants`, `parseLine`, `StringUtils`
+- **Parsing** — `Node`, `InlineNode`, `TextNode`, `Parser`, `ParseResult`, `Line`, `Constants`, `parseLine`, `StringUtils`
 - **Exceptions** — `ParseException`, `ValidationException`
 - **Extension points** — `Observer`
 - **Schemas** — `Schema`, `SchemaValidator`, `SchemaProvider`, `NodeDefinition`, `ChildDefinition`, `transformNodeToSchema`, `transformTemplateNodeToSchema`

package/out/all.d.ts

@@ -1,4 +1,6 @@
 export { Node } from "./core/Node";
+export { InlineNode } from "./core/InlineNode";
+export { TextNode } from "./core/TextNode";
 export { Parser } from "./core/Parser";
 export { ParseResult } from "./core/ParseResult";
 export { Line } from "./core/Line";

package/out/all.js

@@ -3,9 +3,13 @@
 // Anything that should be consumable by third parties (e.g. the VSCode extension)
 // has to be re-exported from here.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DiscoveryError = exports.DiscoveryResult = exports.DiscoveryResolver = exports.transformTemplateNodeToSchema = exports.toCanonicalJson = exports.toCanonicalTree = exports.IndentStyle = exports.NodeWriter = exports.ConditionalValidator = exports.UnifiedSchemaProvider = exports.transformNodeToSchema = exports.ChildDefinition = exports.NodeDefinition = exports.SchemaValidator = exports.Schema = exports.ValidationException = exports.ParseException = exports.StringUtils = exports.parseLine = exports.Constants = exports.Line = exports.ParseResult = exports.Parser = exports.Node = void 0;
+exports.DiscoveryError = exports.DiscoveryResult = exports.DiscoveryResolver = exports.transformTemplateNodeToSchema = exports.toCanonicalJson = exports.toCanonicalTree = exports.IndentStyle = exports.NodeWriter = exports.ConditionalValidator = exports.UnifiedSchemaProvider = exports.transformNodeToSchema = exports.ChildDefinition = exports.NodeDefinition = exports.SchemaValidator = exports.Schema = exports.ValidationException = exports.ParseException = exports.StringUtils = exports.parseLine = exports.Constants = exports.Line = exports.ParseResult = exports.Parser = exports.TextNode = exports.InlineNode = exports.Node = void 0;
 var Node_1 = require("./core/Node");
 Object.defineProperty(exports, "Node", { enumerable: true, get: function () { return Node_1.Node; } });
+var InlineNode_1 = require("./core/InlineNode");
+Object.defineProperty(exports, "InlineNode", { enumerable: true, get: function () { return InlineNode_1.InlineNode; } });
+var TextNode_1 = require("./core/TextNode");
+Object.defineProperty(exports, "TextNode", { enumerable: true, get: function () { return TextNode_1.TextNode; } });
 var Parser_1 = require("./core/Parser");
 Object.defineProperty(exports, "Parser", { enumerable: true, get: function () { return Parser_1.Parser; } });
 var ParseResult_1 = require("./core/ParseResult");

package/out/core/InlineNode.d.ts

@@ -0,0 +1,126 @@
+import { Node } from "./Node";
+import { TextNode } from "./TextNode";
+/**
+ * INLINE node of the STXT tree (`Name: value`): an optional inline value and an ordered list of
+ * children. It is the only form that has children — and so the only one with child lookups
+ * ({@link InlineNode.getChild}, {@link InlineNode.getChildrenByName}) — and the only one that can
+ * create them ({@link InlineNode.addInlineNode}, {@link InlineNode.addTextNode}).
+ *
+ * Overloads with two strings always take the second one as the *content* (the value); the
+ * namespace only exists in the three-argument forms.
+ */
+export declare class InlineNode extends Node {
+    private value;
+    private readonly children;
+    /**
+     * Creates an inline node with no value, no declared namespace and no known source line.
+     *
+     * @param name name of the node.
+     */
+    constructor(name: string);
+    /**
+     * Creates an inline node with a value, no declared namespace and no known source line.
+     *
+     * @param name name of the node.
+     * @param value inline value, or null/undefined for none.
+     */
+    constructor(name: string, value: string | null | undefined);
+    /**
+     * Creates an inline node with a declared namespace and a value; the source line is optional.
+     * This is the form the {@link Parser} uses.
+     *
+     * @param name name of the node.
+     * @param namespace namespace the node declares, or null/undefined/empty for none.
+     * @param value inline value, or null/undefined for none.
+     * @param line source line, or {@link Node.NO_LINE} (the default).
+     * @throws ParseException if the name or the namespace are not valid.
+     */
+    constructor(name: string, namespace: string | null | undefined, value: string | null | undefined, line?: number);
+    /** @returns the inline value of the node, trimmed; the empty string if it has none. */
+    getValue(): string;
+    /**
+     * Sets the inline value of the node.
+     *
+     * @param value new value, or null/undefined for none. It is trimmed.
+     */
+    setValue(value: string | null | undefined): void;
+    getText(): string;
+    isTextNode(): boolean;
+    /** @returns the children of the node in order of appearance, as a read-only view. */
+    getChildren(): ReadonlyArray<Node>;
+    /**
+     * Adds a child, linking both ends: afterwards `child.getParent()` is this node. It is appended
+     * at the end unless a position is given.
+     *
+     * @param child node to add; it must not have a parent yet.
+     * @param index position where to insert it (0 = first); at the end when omitted.
+     * @throws RuntimeException with code `NODE_ALREADY_ATTACHED` if the child already has a parent
+     *         (detach it first), or `NODE_CYCLE` if it is this node or one of its ancestors.
+     * @throws RangeError if the index is out of range.
+     */
+    addChild(child: Node, index?: number): void;
+    /**
+     * Removes a direct child, unlinking both ends: afterwards `child.getParent()` is null and the
+     * child is a root on its own.
+     *
+     * @param child the child to remove.
+     * @returns true if it was a direct child of this node and has been removed; false otherwise.
+     */
+    removeChild(child: Node): boolean;
+    /**
+     * Looks up the only direct child with that name.
+     *
+     * @param cname name of the child to look for.
+     * @param namespace effective namespace to search in; this node's own effective namespace when omitted.
+     * @returns the only direct child with that name, or null if there is none.
+     * @throws RuntimeException with code `AMBIGUOUS_CHILD` if there is more than one; use {@link InlineNode.getChildrenByName} then.
+     */
+    getChild(cname: string, namespace?: string): Node | null;
+    /**
+     * Looks up every direct child with that name.
+     *
+     * @param cname name of the child to look for.
+     * @param namespace effective namespace to search in; this node's own effective namespace when omitted.
+     * @returns every direct child with that name in that namespace, in order of appearance.
+     */
+    getChildrenByName(cname: string, namespace?: string): Node[];
+    /**
+     * Creates an inline child and appends it. With two strings the second one is the value; the
+     * namespace only exists in the three-argument form.
+     *
+     * @param name name of the child.
+     * @returns the child created, already attached to this node.
+     */
+    addInlineNode(name: string): InlineNode;
+    /**
+     * @param name name of the child.
+     * @param value inline value, or null/undefined for none.
+     */
+    addInlineNode(name: string, value: string | null | undefined): InlineNode;
+    /**
+     * @param name name of the child.
+     * @param namespace namespace the child declares, or null/undefined/empty to inherit this node's.
+     * @param value inline value, or null/undefined for none.
+     */
+    addInlineNode(name: string, namespace: string | null | undefined, value: string | null | undefined): InlineNode;
+    /**
+     * Creates a text child and appends it. With two strings the second one is the text; the
+     * namespace only exists in the three-argument form.
+     *
+     * @param name name of the child.
+     * @returns the child created, already attached to this node.
+     */
+    addTextNode(name: string): TextNode;
+    /**
+     * @param name name of the child.
+     * @param text text of the child (split into lines at every line break), or its lines.
+     */
+    addTextNode(name: string, text: string | ReadonlyArray<string> | null | undefined): TextNode;
+    /**
+     * @param name name of the child.
+     * @param namespace namespace the child declares, or null/undefined/empty to inherit this node's.
+     * @param text text of the child (split into lines at every line break), or its lines.
+     */
+    addTextNode(name: string, namespace: string | null | undefined, text: string | ReadonlyArray<string> | null | undefined): TextNode;
+    protected describe(): string;
+}

package/out/core/InlineNode.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InlineNode = void 0;
+const Node_1 = require("./Node");
+const TextNode_1 = require("./TextNode");
+const RuntimeException_1 = require("../exceptions/RuntimeException");
+const StringUtils_1 = require("./StringUtils");
+/**
+ * INLINE node of the STXT tree (`Name: value`): an optional inline value and an ordered list of
+ * children. It is the only form that has children — and so the only one with child lookups
+ * ({@link InlineNode.getChild}, {@link InlineNode.getChildrenByName}) — and the only one that can
+ * create them ({@link InlineNode.addInlineNode}, {@link InlineNode.addTextNode}).
+ *
+ * Overloads with two strings always take the second one as the *content* (the value); the
+ * namespace only exists in the three-argument forms.
+ */
+class InlineNode extends Node_1.Node {
+    constructor(name, ...rest) {
+        // With two strings the second one is the value; the namespace only exists with three or more
+        const [namespace, value, line] = rest.length <= 1
+            ? [null, rest[0], Node_1.Node.NO_LINE]
+            : [rest[0], rest[1], rest[2] ?? Node_1.Node.NO_LINE];
+        super(name, namespace, line);
+        this.children = [];
+        this.setValue(value);
+    }
+    // ----------------------------------------------------------------
+    // Value
+    // ----------------------------------------------------------------
+    /** @returns the inline value of the node, trimmed; the empty string if it has none. */
+    getValue() {
+        return this.value;
+    }
+    /**
+     * Sets the inline value of the node.
+     *
+     * @param value new value, or null/undefined for none. It is trimmed.
+     */
+    setValue(value) {
+        this.value = (value ?? "").trim();
+    }
+    getText() {
+        return this.value;
+    }
+    isTextNode() {
+        return false;
+    }
+    // ----------------------------------------------------------------
+    // Children
+    // ----------------------------------------------------------------
+    /** @returns the children of the node in order of appearance, as a read-only view. */
+    getChildren() {
+        return this.children;
+    }
+    /**
+     * Adds a child, linking both ends: afterwards `child.getParent()` is this node. It is appended
+     * at the end unless a position is given.
+     *
+     * @param child node to add; it must not have a parent yet.
+     * @param index position where to insert it (0 = first); at the end when omitted.
+     * @throws RuntimeException with code `NODE_ALREADY_ATTACHED` if the child already has a parent
+     *         (detach it first), or `NODE_CYCLE` if it is this node or one of its ancestors.
+     * @throws RangeError if the index is out of range.
+     */
+    addChild(child, index) {
+        if (child.getParent() !== null) {
+            throw new RuntimeException_1.RuntimeException("NODE_ALREADY_ATTACHED", `Node '${child.getName()}' already has a parent: detach it first`);
+        }
+        for (let p = this; p !== null; p = p.getParent()) {
+            if (p === child) {
+                throw new RuntimeException_1.RuntimeException("NODE_CYCLE", `Node '${child.getName()}' cannot be a child of itself or of one of its descendants`);
+            }
+        }
+        const at = index ?? this.children.length;
+        if (!Number.isInteger(at) || at < 0 || at > this.children.length) {
+            throw new RangeError(`Index ${index} out of range [0, ${this.children.length}]`);
+        }
+        this.children.splice(at, 0, child);
+        child._setParent(this);
+    }
+    /**
+     * Removes a direct child, unlinking both ends: afterwards `child.getParent()` is null and the
+     * child is a root on its own.
+     *
+     * @param child the child to remove.
+     * @returns true if it was a direct child of this node and has been removed; false otherwise.
+     */
+    removeChild(child) {
+        if (child.getParent() !== this) {
+            return false;
+        }
+        // Identity, not equality: two children may look alike
+        const i = this.children.indexOf(child);
+        if (i === -1) {
+            return false;
+        }
+        this.children.splice(i, 1);
+        child._setParent(null);
+        return true;
+    }
+    /**
+     * Looks up the only direct child with that name.
+     *
+     * @param cname name of the child to look for.
+     * @param namespace effective namespace to search in; this node's own effective namespace when omitted.
+     * @returns the only direct child with that name, or null if there is none.
+     * @throws RuntimeException with code `AMBIGUOUS_CHILD` if there is more than one; use {@link InlineNode.getChildrenByName} then.
+     */
+    getChild(cname, namespace) {
+        const result = this.getChildrenByName(cname, namespace);
+        if (result.length > 1) {
+            throw new RuntimeException_1.RuntimeException("AMBIGUOUS_CHILD", "More than 1 child. Use getChildrenByName");
+        }
+        return result.length === 0 ? null : result[0];
+    }
+    /**
+     * Looks up every direct child with that name.
+     *
+     * @param cname name of the child to look for.
+     * @param namespace effective namespace to search in; this node's own effective namespace when omitted.
+     * @returns every direct child with that name in that namespace, in order of appearance.
+     */
+    getChildrenByName(cname, namespace) {
+        const key = StringUtils_1.StringUtils.normalize(cname);
+        const targetNamespace = namespace !== undefined ? namespace : this.getNamespace();
+        return this.children.filter(child => child.getCanonicalName() === key && child.getNamespace() === targetNamespace);
+    }
+    addInlineNode(name, ...rest) {
+        const child = rest.length <= 1
+            ? new InlineNode(name, rest[0])
+            : new InlineNode(name, rest[0], rest[1]);
+        this.addChild(child);
+        return child;
+    }
+    addTextNode(name, ...rest) {
+        const child = rest.length <= 1
+            ? new TextNode_1.TextNode(name, rest[0])
+            : new TextNode_1.TextNode(name, rest[0], rest[1]);
+        this.addChild(child);
+        return child;
+    }
+    describe() {
+        let s = "";
+        if (this.value.length > 0) {
+            s += `, value='${this.value}'`;
+        }
+        s += `, children=${this.children.length}`;
+        return s;
+    }
+}
+exports.InlineNode = InlineNode;
+//# sourceMappingURL=InlineNode.js.map

package/out/core/Node.d.ts

@@ -1,83 +1,101 @@
+import type { InlineNode } from "./InlineNode";
 /**
- * Node of the STXT tree. Mutable while parsing ({@link Node.addChild}/{@link Node.addTextLine}
- * are public); once the document is closed it must be treated as read-only. It represents both
- * INLINE nodes (with {@link Node.getValue}) and BLOCK text nodes (with {@link Node.getTextLines}),
- * as told apart by {@link Node.isTextNode}.
+ * Node of the STXT tree: what INLINE nodes ({@link InlineNode}) and BLOCK text nodes
+ * ({@link TextNode}) have in common. Those two are the only forms, and each one owns what is
+ * really its own — only an `InlineNode` has a value and children (and so the child lookups); only
+ * a `TextNode` has text lines. Code that walks a tree asks for the form
+ * (`node instanceof InlineNode`), the same way the canonical tree of STXT-TREE-SPEC has
+ * `children` only for inline nodes.
+ *
+ * Nodes are mutable, and the tree keeps its own integrity: a node knows its
+ * {@link Node.getParent | parent} (always an `InlineNode`), {@link InlineNode.addChild} links
+ * both ends and refuses a node that already has a parent, and {@link InlineNode.removeChild} /
+ * {@link Node.detach} undo it. The {@link Node.getLevel | level} is derived from the chain of
+ * parents, never stored.
+ *
+ * The namespace a node *declares* ({@link Node.getDeclaredNamespace}) and the one that *applies*
+ * to it ({@link Node.getNamespace}) are different things: the effective namespace is the declared
+ * one or, failing that, the parent's effective namespace (STXT-SPEC: namespaces are inherited
+ * vertically). Changing the declared namespace of a node therefore changes the effective
+ * namespace of the whole subtree that inherited it, and so does moving a subtree.
+ *
+ * The source line ({@link Node.getLine}) is optional: the parser sets it, code that builds trees
+ * usually does not ({@link Node.NO_LINE}).
  */
-export declare class Node {
-    private readonly name;
-    private readonly normalizedName;
-    private readonly namespace;
-    private readonly textNode;
-    private readonly value;
-    private textLines;
-    private readonly line;
-    private readonly level;
-    private children;
+export declare abstract class Node {
+    /** Value of {@link Node.getLine} when the node has no known position in a document. */
+    static readonly NO_LINE = -1;
+    private name;
+    private canonicalName;
+    private declaredNamespace;
+    private line;
+    private parent;
     /**
-     * Creates a node with its full position in the document. This is the constructor the
-     * {@link Parser} uses while parsing.
+     * Common initialisation, for the two concrete forms.
      *
-     * @param line line number of the document where the node opens.
-     * @param level indentation level of the node (0 for root nodes).
      * @param name name of the node.
-     * @param namespace namespace of the node, or null/undefined if it has none.
-     * @param textNode true if it is a text block node (BLOCK); false if it is INLINE.
-     * @param value inline value of the node (INLINE node), ignored when it is BLOCK.
-     * @throws ParseException if the name or the namespace are not valid.
+     * @param namespace namespace the node declares, or null/undefined/empty if it declares none.
+     * @param line source line, or {@link Node.NO_LINE}.
+     * @throws ParseException with code `INVALID_NODE_NAME` if the name is not a valid STXT node
+     *         name, or if the namespace does not have a valid format.
      */
-    constructor(line: number, level: number, name: string, namespace: string | null | undefined, textNode: boolean, value: string | null | undefined);
+    protected constructor(name: string, namespace: string | null | undefined, line: number);
+    /** @returns the original name of the node as it appears in the document (with spaces compacted). */
+    getName(): string;
     /**
-     * Appends a text line to a BLOCK node.
+     * Renames the node. The canonical name is recomputed.
      *
-     * @param line text line to append to a BLOCK node ({@link Node.isTextNode}).
+     * @param name new name of the node.
+     * @throws ParseException with code `INVALID_NODE_NAME` if it is not a valid STXT node name.
+     */
+    setName(name: string): void;
+    /** @returns the canonical name of the node (STXT-SPEC §4.3), used to compare/look up by structural identity. */
+    getCanonicalName(): string;
+    /**
+     * @returns the canonical name of the node.
+     * @deprecated since 0.7.0, use {@link Node.getCanonicalName}; "canonical name" is the term of
+     *             the specifications. To be removed in a later version.
      */
-    addTextLine(line: string): void;
-    /** @returns the original name of the node as it appears in the document (with spaces compacted). */
-    getName(): string;
-    /** @returns the canonical name of the node, used to compare/look up by structural identity. */
     getNormalizedName(): string;
-    /** @returns the canonical name prefixed by its namespace (`namespace:name`), or just the name when there is no namespace. */
+    /** @returns the canonical name prefixed by the effective namespace (`namespace:name`), or just the canonical name when there is no namespace. */
     getQualifiedName(): string;
-    /** @returns the effective namespace of the node (its own or inherited from the parent), lower-cased, or the empty string if it has none. */
-    getNamespace(): string;
-    /** @returns the children of the node in order of appearance, as a read-only view. */
-    getChildren(): ReadonlyArray<Node>;
+    /** @returns the namespace this node declares itself, lower-cased, or the empty string if it declares none (and so inherits the parent's). */
+    getDeclaredNamespace(): string;
     /**
-     * Appends an already closed child to this node.
+     * Sets the namespace this node declares. The empty string (or null/undefined) means "none":
+     * the node then inherits the effective namespace of its parent.
      *
-     * @param node already closed child to append at the end of this node's list of children.
+     * @param namespace namespace to declare, or null/undefined/empty for none.
+     * @throws ParseException if the namespace does not have a valid format (STXT-SPEC §7).
      */
-    addChild(node: Node): void;
-    /** @returns the inline value of the node (INLINE node), or the empty string if it is a BLOCK node. */
-    getValue(): string;
-    /** @returns the text lines of a BLOCK node ({@link Node.isTextNode}), in order of appearance. */
-    getTextLines(): ReadonlyArray<string>;
-    /** @returns the line number of the document where this node was opened. */
+    setNamespace(namespace: string | null | undefined): void;
+    /** @returns the effective namespace of the node: the one it declares or, failing that, the effective namespace of its parent; the empty string if there is none. */
+    getNamespace(): string;
+    /** @returns the line number of the document where this node was opened, or {@link Node.NO_LINE} if unknown. */
     getLine(): number;
-    /** @returns the indentation level of the node (0 for root nodes). */
-    getLevel(): number;
-    /** @returns true if the node is a text block (BLOCK, `>>`); false if it is INLINE. */
-    isTextNode(): boolean;
-    /** @returns the textual content of the node: the text lines joined with '\n' if it is BLOCK, or the inline value otherwise. */
-    getText(): string;
     /**
-     * Looks up the only direct child with that name.
+     * Sets the source line of the node.
      *
-     * @param cname name of the child to look for.
-     * @param namespace namespace to search in; this node's own namespace when omitted.
-     * @returns the only direct child with that name, or null if there is none.
-     * @throws RuntimeException with code `AMBIGUOUS_CHILD` if there is more than one; use {@link Node.getChildrenByName} then.
+     * @param line line number, or {@link Node.NO_LINE} if unknown.
      */
-    getChild(cname: string, namespace?: string): Node | null;
+    setLine(line: number): void;
+    /** @returns the depth of the node in its tree: 0 for a root node, 1 for its children, and so on. */
+    getLevel(): number;
+    /** @returns the parent of this node, or null if it is a root node. */
+    getParent(): InlineNode | null;
     /**
-     * Looks up every direct child with that name.
+     * Removes this node from its parent, if it has one. Afterwards the node is a root, and its
+     * effective namespace is the one it declares.
      *
-     * @param cname name of the child to look for.
-     * @param namespace namespace to search in; this node's own namespace when omitted.
-     * @returns every direct child with that name in the given namespace, in order of appearance.
+     * @returns true if the node had a parent and was detached; false if it was already a root.
      */
-    getChildrenByName(cname: string, namespace?: string): Node[];
+    detach(): boolean;
+    /** @returns true if the node is a text block (BLOCK, `>>`); false if it is INLINE. */
+    abstract isTextNode(): boolean;
+    /** @returns the textual content of the node: the text lines joined with '\n' if it is BLOCK, or the inline value otherwise. */
+    abstract getText(): string;
     /** @returns a readable representation of the node, for debugging and error messages. */
     toString(): string;
+    /** Form-specific part of {@link Node.toString}. */
+    protected abstract describe(): string;
 }