@stxt-lang/core 0.5.2 → 0.5.3

package/README.md

@@ -6,6 +6,7 @@ STXT is a plain-text format for writing structured, semantic documents: no brace
 
 - Website and language reference: <https://stxt.dev>
 - VSCode extension: [STXT - Semantic Text](https://marketplace.visualstudio.com/items?itemName=stxt-lang.stxt)
+- Java implementation: [`dev.stxt:stxt-core`](https://central.sonatype.com/artifact/dev.stxt/stxt-core) on Maven Central
 
 ## What STXT looks like
 

package/out/all.js

@@ -1,7 +1,7 @@
 "use strict";
-// Punto de entrada público del paquete (out/all.js / out/all.d.ts).
-// Todo lo que deba ser consumible por terceros (p. ej. la extensión VSCode)
-// debe re-exportarse desde aquí.
+// Public entry point of the package (out/all.js / out/all.d.ts).
+// 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.transformTemplateNodeToSchema = 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;
 var Node_1 = require("./core/Node");

package/out/core/Constants.d.ts

@@ -1,9 +1,17 @@
+/** Characters and sizes fixed by STXT-SPEC that the parser and the writer share. */
 export declare class Constants {
+    /** Character that opens a comment line. */
     static readonly COMMENT_CHAR: string;
+    /** Number of spaces that make up one indentation level. */
     static readonly TAB_SPACES: number;
+    /** Tab character, the other way of indenting one level. */
     static readonly TAB: string;
+    /** Space character. */
     static readonly SPACE: string;
+    /** Separator between the name and the value of an INLINE node. */
     static readonly SEP_NODE: string;
+    /** Marker that turns a node into a BLOCK text node. */
     static readonly SEP_TEXT_NODE: string;
+    /** Namespace of a node that declares none and inherits none. */
     static readonly EMPTY_NAMESPACE: string;
 }

package/out/core/Constants.js

@@ -1,14 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Constants = void 0;
+/** Characters and sizes fixed by STXT-SPEC that the parser and the writer share. */
 class Constants {
 }
 exports.Constants = Constants;
+/** Character that opens a comment line. */
 Constants.COMMENT_CHAR = "#";
+/** Number of spaces that make up one indentation level. */
 Constants.TAB_SPACES = 4;
+/** Tab character, the other way of indenting one level. */
 Constants.TAB = "\t";
+/** Space character. */
 Constants.SPACE = " ";
+/** Separator between the name and the value of an INLINE node. */
 Constants.SEP_NODE = ":";
+/** Marker that turns a node into a BLOCK text node. */
 Constants.SEP_TEXT_NODE = ">>";
+/** Namespace of a node that declares none and inherits none. */
 Constants.EMPTY_NAMESPACE = "";
 //# sourceMappingURL=Constants.js.map

package/out/core/Line.d.ts

@@ -1,9 +1,29 @@
+/**
+ * A source line already split into its indentation and its content, as produced by
+ * {@link parseLine}. It is what tells the {@link Parser} whether the line opens a node, continues
+ * a text block or is just a comment.
+ */
 export declare class Line {
+    /** Indentation level of the line (one level per tab or per {@link Constants.TAB_SPACES} spaces). */
     readonly level: number;
+    /** Content of the line with the indentation already removed. */
     readonly content: string;
+    /** True if the line is a comment (`#`). */
     readonly isComment: boolean;
+    /** True if the line is a text line belonging to an open BLOCK node (`>>`). */
     readonly isBlock: boolean;
+    /** Number of characters the indentation took up. */
     readonly indentLength: number;
+    /**
+     * Creates a line already split into indentation and content.
+     *
+     * @param level indentation level of the line.
+     * @param content content of the line without its indentation.
+     * @param isComment true if the line is a comment.
+     * @param isBlock true if the line belongs to an open text block.
+     * @param indentLength number of characters the indentation took up.
+     */
     constructor(level: number, content: string, isComment: boolean, isBlock: boolean, indentLength: number);
+    /** @returns true if the line has no content beyond whitespace. */
     isEmpty(): boolean;
 }

package/out/core/Line.js

@@ -1,7 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Line = void 0;
+/**
+ * A source line already split into its indentation and its content, as produced by
+ * {@link parseLine}. It is what tells the {@link Parser} whether the line opens a node, continues
+ * a text block or is just a comment.
+ */
 class Line {
+    /**
+     * Creates a line already split into indentation and content.
+     *
+     * @param level indentation level of the line.
+     * @param content content of the line without its indentation.
+     * @param isComment true if the line is a comment.
+     * @param isBlock true if the line belongs to an open text block.
+     * @param indentLength number of characters the indentation took up.
+     */
     constructor(level, content, isComment, isBlock, indentLength) {
         this.level = level;
         this.content = content;
@@ -9,6 +23,7 @@ class Line {
         this.isBlock = isBlock;
         this.indentLength = indentLength;
     }
+    /** @returns true if the line has no content beyond whitespace. */
     isEmpty() {
         return this.content.trim() === "";
     }

package/out/core/LineParser.d.ts

@@ -1,2 +1,19 @@
 import { Line } from "./Line";
+/**
+ * Splits a source line into its indentation and its content, and classifies it as a comment, a
+ * text line of an open block or a regular line.
+ *
+ * Indentation is one level per tab or per {@link Constants.TAB_SPACES} spaces; mixing both, using
+ * a number of spaces that is not a multiple of four or going more than one level deeper than the
+ * previous node are errors (spec 8.1 and 8.3).
+ *
+ * @param line source line, with its indentation.
+ * @param lastNodeBlock true if the node currently open is a BLOCK text node.
+ * @param lastLevel indentation level of the node currently open.
+ * @param numLine line number, for the error messages.
+ * @param validate false to split the line without enforcing the indentation rules.
+ * @returns the line already split into indentation and content.
+ * @throws ParseException with code `MIXED_INDENTATION`, `INVALID_NUMBER_SPACES` or
+ *         `INDENTATION_LEVEL_NOT_VALID` if the indentation is not valid.
+ */
 export declare function parseLine(line: string, lastNodeBlock: boolean, lastLevel: number, numLine: number, validate?: boolean): Line;

package/out/core/LineParser.js

@@ -5,6 +5,23 @@ const Constants_1 = require("./Constants");
 const StringUtils_1 = require("./StringUtils");
 const ParseException_1 = require("../exceptions/ParseException");
 const Line_1 = require("./Line");
+/**
+ * Splits a source line into its indentation and its content, and classifies it as a comment, a
+ * text line of an open block or a regular line.
+ *
+ * Indentation is one level per tab or per {@link Constants.TAB_SPACES} spaces; mixing both, using
+ * a number of spaces that is not a multiple of four or going more than one level deeper than the
+ * previous node are errors (spec 8.1 and 8.3).
+ *
+ * @param line source line, with its indentation.
+ * @param lastNodeBlock true if the node currently open is a BLOCK text node.
+ * @param lastLevel indentation level of the node currently open.
+ * @param numLine line number, for the error messages.
+ * @param validate false to split the line without enforcing the indentation rules.
+ * @returns the line already split into indentation and content.
+ * @throws ParseException with code `MIXED_INDENTATION`, `INVALID_NUMBER_SPACES` or
+ *         `INDENTATION_LEVEL_NOT_VALID` if the indentation is not valid.
+ */
 function parseLine(line, lastNodeBlock, lastLevel, numLine, validate = true) {
     let level = 0;
     let spaces = 0;
@@ -30,23 +47,23 @@ function parseLine(line, lastNodeBlock, lastLevel, numLine, validate = true) {
             return new Line_1.Line(level, line.substring(pointer + 1), true, false, pointer);
         }
         else {
-            // Primer carácter no espacio/tab/comentario => fin de indentación
+            // First character that is not space/tab/comment => end of indentation
             break;
         }
-        // Dentro del bloque de texto
+        // Inside the text block
         if (lastNodeBlock && level > lastLevel) {
             const text = StringUtils_1.StringUtils.rightTrim(line.substring(pointer + 1));
-            // El prefijo que cubre el nivel de bloque debe ser homogéneo (spec 10.2, regla 2);
-            // las líneas vacías se preservan siempre y quedan exentas (spec 10.3)
+            // The prefix covering the block level must be homogeneous (spec 10.2, rule 2);
+            // empty lines are always preserved and are exempt from it (spec 10.3)
             if (validate && sawSpace && sawTab && text.length > 0) {
                 throw new ParseException_1.ParseException(numLine, "MIXED_INDENTATION", `Mixed tabs and spaces in indentation`);
             }
             return new Line_1.Line(level, text, false, true, pointer);
         }
-        // Aumentamos pointer
+        // Move the pointer forward
         pointer++;
     }
-    // En este punto ya estamos fuera de bloque de texto (si existía)
+    // From here on we are outside the text block (if there was one)
     // Empty
     if (pointer === line.length) {
         if (lastNodeBlock) {
@@ -54,19 +71,19 @@ function parseLine(line, lastNodeBlock, lastLevel, numLine, validate = true) {
         }
         return new Line_1.Line(level, "", false, false, pointer);
     }
-    // Mezcla de espacios y tabuladores en la indentación (spec 8.1 y 8.3)
+    // Tabs and spaces mixed in the indentation (spec 8.1 and 8.3)
     if (validate && sawSpace && sawTab) {
         throw new ParseException_1.ParseException(numLine, "MIXED_INDENTATION", `Mixed tabs and spaces in indentation`);
     }
-    // Indentación no es múltiplo de 4 con espacios
+    // Indentation with spaces that is not a multiple of 4
     if (validate && spaces > 0) {
         throw new ParseException_1.ParseException(numLine, "INVALID_NUMBER_SPACES", `There are ${spaces} spaces before node`);
     }
-    // Validamos level
+    // Validate the level
     if (validate && level > lastLevel + 1) {
         throw new ParseException_1.ParseException(numLine, "INDENTATION_LEVEL_NOT_VALID", `Level of indent incorrect: ${level}`);
     }
-    // Caso general: devolver la línea sin la indentación consumida
+    // General case: return the line without the indentation already consumed
     return new Line_1.Line(level, line.substring(pointer).trim(), false, false, pointer);
 }
 //# sourceMappingURL=LineParser.js.map

package/out/core/NameNamespace.d.ts

@@ -1,7 +1,16 @@
+/** Result of splitting a raw node name into its resolved name and namespace. */
 export declare class NameNamespace {
     private readonly name;
     private readonly namespace;
+    /**
+     * Creates a resolved name and namespace pair.
+     *
+     * @param name name of the node without the namespace part.
+     * @param namespace resolved namespace (its own or inherited).
+     */
     constructor(name: string, namespace: string);
+    /** @returns the name of the node, without the namespace part. */
     getName(): string;
+    /** @returns the resolved namespace (its own or inherited from the parent), or the empty string if it has none. */
     getNamespace(): string;
 }

package/out/core/NameNamespace.js

@@ -1,14 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NameNamespace = void 0;
+/** Result of splitting a raw node name into its resolved name and namespace. */
 class NameNamespace {
+    /**
+     * Creates a resolved name and namespace pair.
+     *
+     * @param name name of the node without the namespace part.
+     * @param namespace resolved namespace (its own or inherited).
+     */
     constructor(name, namespace) {
         this.name = name;
         this.namespace = namespace;
     }
+    /** @returns the name of the node, without the namespace part. */
     getName() {
         return this.name;
     }
+    /** @returns the resolved namespace (its own or inherited from the parent), or the empty string if it has none. */
     getNamespace() {
         return this.namespace;
     }

package/out/core/NameNamespaceParser.d.ts

@@ -1,5 +1,16 @@
 import { NameNamespace } from "./NameNamespace";
+/** Extracts the name and the namespace `(a.b.c)` from the left-hand side of an STXT line. */
 export declare class NameNamespaceParser {
     private constructor();
+    /**
+     * Splits a raw node name into its name and its namespace.
+     *
+     * @param rawName raw name, with the namespace in parentheses if it carries one.
+     * @param inheritedNs namespace inherited from the parent, used when `rawName` brings none of its own.
+     * @param lineNumber line number, for the error messages.
+     * @param fullLine original full line, for the error messages.
+     * @returns the name and the namespace, already split apart and resolved.
+     * @throws ParseException if the name or the namespace are not well formed.
+     */
     static parse(rawName: string | null | undefined, inheritedNs: string | null | undefined, lineNumber: number, fullLine: string): NameNamespace;
 }

package/out/core/NameNamespaceParser.js

@@ -3,9 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NameNamespaceParser = void 0;
 const ParseException_1 = require("../exceptions/ParseException");
 const NameNamespace_1 = require("./NameNamespace");
+/** Extracts the name and the namespace `(a.b.c)` from the left-hand side of an STXT line. */
 class NameNamespaceParser {
     constructor() {
     }
+    /**
+     * Splits a raw node name into its name and its namespace.
+     *
+     * @param rawName raw name, with the namespace in parentheses if it carries one.
+     * @param inheritedNs namespace inherited from the parent, used when `rawName` brings none of its own.
+     * @param lineNumber line number, for the error messages.
+     * @param fullLine original full line, for the error messages.
+     * @returns the name and the namespace, already split apart and resolved.
+     * @throws ParseException if the name or the namespace are not well formed.
+     */
     static parse(rawName, inheritedNs, lineNumber, fullLine) {
         if (rawName === null || rawName === undefined) {
             throw new ParseException_1.ParseException(lineNumber, "INVALID_LINE", `Line not valid: ${fullLine}`);
@@ -15,27 +26,27 @@ class NameNamespaceParser {
         const endIndex = rawName.indexOf(")");
         let name;
         let namespace = inheritedNs ?? "";
-        // Encontrados los dos
+        // Both of them found
         if (startIndex !== -1 && endIndex !== -1) {
             if (startIndex > endIndex || endIndex !== rawName.length - 1) {
                 throw new ParseException_1.ParseException(lineNumber, "INVALID_NAMESPACE", `Line not valid: ${fullLine}`);
             }
             name = rawName.substring(0, startIndex).trim();
-            // Sin trim: la gramática (STXT-SPEC 7/16) no admite espacios dentro de '( )'
+            // No trim: the grammar (STXT-SPEC 7/16) does not allow spaces inside '( )'
             namespace = rawName.substring(startIndex + 1, endIndex);
             if (namespace.length === 0) {
                 throw new ParseException_1.ParseException(lineNumber, "INVALID_NAMESPACE", `Line not valid: ${fullLine}`);
             }
         }
-        // Ninguno de los dos
+        // Neither of them
         else if (startIndex === -1 && endIndex === -1) {
             name = rawName;
         }
-        // Solo uno de los dos
+        // Only one of the two
         else {
             throw new ParseException_1.ParseException(lineNumber, "INVALID_NAMESPACE", `Line not valid: ${fullLine}`);
         }
-        // Retorno
+        // Return
         return new NameNamespace_1.NameNamespace(name, namespace.toLowerCase());
     }
 }

package/out/core/NamespaceValidator.d.ts

@@ -1,4 +1,22 @@
+/** Validates the format of STXT `(a.b.c)` namespaces. */
 export declare class NamespaceValidator {
+    /**
+     * Format of the logical namespace.
+     *
+     * Rules:
+     * - Lower-case letters, digits and dot only.
+     * - It may optionally start with '@'.
+     * - It must be one or more domain-style labels separated by '.':
+     *   label := [a-z0-9]+
+     * valid examples: "xxx", "xxx.ddd", "zzz.ttt.ooo", "@xxx", "@xxx.ddd".
+     */
     private static readonly NAMESPACE_FORMAT;
+    /**
+     * Validates the format of a namespace.
+     *
+     * @param namespace already normalized namespace to validate; ignored when null or empty.
+     * @param lineNumber line number, for the error message.
+     * @throws ParseException with code `INVALID_NAMESPACE` if it does not match the format.
+     */
     static validateNamespaceFormat(namespace: string | null | undefined, lineNumber: number): void;
 }

package/out/core/NamespaceValidator.js

@@ -2,7 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NamespaceValidator = void 0;
 const ParseException_1 = require("../exceptions/ParseException");
+/** Validates the format of STXT `(a.b.c)` namespaces. */
 class NamespaceValidator {
+    /**
+     * Validates the format of a namespace.
+     *
+     * @param namespace already normalized namespace to validate; ignored when null or empty.
+     * @param lineNumber line number, for the error message.
+     * @throws ParseException with code `INVALID_NAMESPACE` if it does not match the format.
+     */
     static validateNamespaceFormat(namespace, lineNumber) {
         if (!namespace) {
             return;
@@ -13,5 +21,15 @@ class NamespaceValidator {
     }
 }
 exports.NamespaceValidator = NamespaceValidator;
+/**
+ * Format of the logical namespace.
+ *
+ * Rules:
+ * - Lower-case letters, digits and dot only.
+ * - It may optionally start with '@'.
+ * - It must be one or more domain-style labels separated by '.':
+ *   label := [a-z0-9]+
+ * valid examples: "xxx", "xxx.ddd", "zzz.ttt.ooo", "@xxx", "@xxx.ddd".
+ */
 NamespaceValidator.NAMESPACE_FORMAT = /^@?[a-z0-9]+(\.[a-z0-9]+)+$/;
 //# sourceMappingURL=NamespaceValidator.js.map

package/out/core/Node.d.ts

@@ -1,3 +1,9 @@
+/**
+ * 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}.
+ */
 export declare class Node {
     private static readonly VALID_NAME;
     private readonly name;
@@ -9,21 +15,70 @@ export declare class Node {
     private readonly line;
     private readonly level;
     private children;
+    /**
+     * Creates a node with its full position in the document. This is the constructor the
+     * {@link Parser} uses while parsing.
+     *
+     * @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.
+     */
     constructor(line: number, level: number, name: string, namespace: string | null | undefined, textNode: boolean, value: string | null | undefined);
+    /**
+     * Appends a text line to a BLOCK node.
+     *
+     * @param line text line to append to a BLOCK node ({@link Node.isTextNode}).
+     */
     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. */
     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>;
+    /**
+     * Appends an already closed child to this node.
+     *
+     * @param node already closed child to append at the end of this node's list of children.
+     */
     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. */
     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.
+     *
+     * @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.
+     */
     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 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.
+     */
     getChildrenByName(cname: string, namespace?: string): Node[];
+    /** @returns a readable representation of the node, for debugging and error messages. */
     toString(): string;
 }

package/out/core/Node.js

@@ -5,7 +5,25 @@ const ParseException_1 = require("../exceptions/ParseException");
 const RuntimeException_1 = require("../exceptions/RuntimeException");
 const NamespaceValidator_1 = require("./NamespaceValidator");
 const StringUtils_1 = require("./StringUtils");
+/**
+ * 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}.
+ */
 class Node {
+    /**
+     * Creates a node with its full position in the document. This is the constructor the
+     * {@link Parser} uses while parsing.
+     *
+     * @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.
+     */
     constructor(line, level, name, namespace, textNode, value) {
         this.textLines = [];
         this.children = [];
@@ -27,47 +45,76 @@ class Node {
             throw new ParseException_1.ParseException(line, "INVALID_NODE_NAME", `Node name not valid: ${name}`);
         }
     }
+    /**
+     * Appends a text line to a BLOCK node.
+     *
+     * @param line text line to append to a BLOCK node ({@link Node.isTextNode}).
+     */
     addTextLine(line) {
         this.textLines.push(line);
     }
+    /** @returns the original name of the node as it appears in the document (with spaces compacted). */
     getName() {
         return this.name;
     }
+    /** @returns the canonical name of the node, used to compare/look up by structural identity. */
     getNormalizedName() {
         return this.normalizedName;
     }
+    /** @returns the canonical name prefixed by its namespace (`namespace:name`), or just the name when there is no namespace. */
     getQualifiedName() {
         return this.namespace.length === 0
             ? this.normalizedName
             : `${this.namespace}:${this.normalizedName}`;
     }
+    /** @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() {
         return this.namespace;
     }
+    /** @returns the children of the node in order of appearance, as a read-only view. */
     getChildren() {
         return this.children;
     }
+    /**
+     * Appends an already closed child to this node.
+     *
+     * @param node already closed child to append at the end of this node's list of children.
+     */
     addChild(node) {
         this.children.push(node);
     }
+    /** @returns the inline value of the node (INLINE node), or the empty string if it is a BLOCK node. */
     getValue() {
         return this.value;
     }
+    /** @returns the text lines of a BLOCK node ({@link Node.isTextNode}), in order of appearance. */
     getTextLines() {
         return this.textLines;
     }
+    /** @returns the line number of the document where this node was opened. */
     getLine() {
         return this.line;
     }
+    /** @returns the indentation level of the node (0 for root nodes). */
     getLevel() {
         return this.level;
     }
+    /** @returns true if the node is a text block (BLOCK, `>>`); false if it is INLINE. */
     isTextNode() {
         return this.textNode;
     }
+    /** @returns the textual content of the node: the text lines joined with '\n' if it is BLOCK, or the inline value otherwise. */
     getText() {
         return this.isTextNode() ? this.textLines.join("\n") : this.value;
     }
+    /**
+     * Looks up the only direct child with that name.
+     *
+     * @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.
+     */
     getChild(cname, namespace) {
         const result = this.getChildrenByName(cname, namespace);
         if (result.length > 1) {
@@ -79,6 +126,13 @@ class Node {
         return result[0];
     }
     // Fast access methods to children
+    /**
+     * Looks up every direct child with that name.
+     *
+     * @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.
+     */
     getChildrenByName(cname, namespace) {
         const key = StringUtils_1.StringUtils.normalize(cname);
         const targetNamespace = namespace !== undefined ? namespace : this.namespace;
@@ -90,6 +144,7 @@ class Node {
         }
         return result;
     }
+    /** @returns a readable representation of the node, for debugging and error messages. */
     toString() {
         let s = "Node{";
         s += `line=${this.line}`;
@@ -111,6 +166,6 @@ class Node {
     }
 }
 exports.Node = Node;
-// STXT-SPEC 4.2: letras y dígitos Unicode (categorías L y Nd) más '-', '_' y espacio
+// STXT-SPEC 4.2: Unicode letters and digits (categories L and Nd) plus '-', '_' and space
 Node.VALID_NAME = /^[\p{L}\p{Nd}\-_ ]+$/u;
 //# sourceMappingURL=Node.js.map

package/out/core/NodeCreator.d.ts

@@ -1,3 +1,14 @@
 import { Line } from "./Line";
 import { Node } from "./Node";
+/**
+ * Builds the node a line opens, telling apart the INLINE form (`Name: value`) from the BLOCK one
+ * (`Name >>`) and resolving the namespace against the parent.
+ *
+ * @param lineIndent line already split into indentation and content.
+ * @param lineNumber line number of the document where the node opens.
+ * @param level indentation level of the node.
+ * @param parent node currently open, whose namespace is inherited, or null at root level.
+ * @returns the node the line opens, still with no children and no text lines.
+ * @throws ParseException if the line is not a valid node declaration.
+ */
 export declare function createNode(lineIndent: Line, lineNumber: number, level: number, parent: Node | null): Node;