@stxt-lang/core 0.5.1 → 0.5.3

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;

package/out/core/NodeCreator.js

@@ -5,6 +5,17 @@ const NameNamespaceParser_1 = require("./NameNamespaceParser");
 const Node_1 = require("./Node");
 const ParseException_1 = require("../exceptions/ParseException");
 const Constants_1 = require("./Constants");
+/**
+ * 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.
+ */
 function createNode(lineIndent, lineNumber, level, parent) {
     const line = lineIndent.content;
     let name;
@@ -38,15 +49,15 @@ function createNode(lineIndent, lineNumber, level, parent) {
     if (textNode && value.trim().length > 0) {
         throw new ParseException_1.ParseException(lineNumber, "INLINE_VALUE_NOT_VALID", `Line not valid: ${line}`);
     }
-    // Namespace por defecto: heredado del padre
+    // Default namespace: inherited from the parent
     const nameNamespace = NameNamespaceParser_1.NameNamespaceParser.parse(name, parent ? parent.getNamespace() : null, lineNumber, line);
     name = nameNamespace.getName();
     const namespace = nameNamespace.getNamespace();
-    // Validamos nombre
+    // Validate the name
     if (name.length === 0) {
         throw new ParseException_1.ParseException(lineNumber, "INVALID_LINE", `Line not valid: ${line}`);
     }
-    // Creamos nodo
+    // Create the node
     return new Node_1.Node(lineNumber, level, name, namespace, textNode, value);
 }
 //# sourceMappingURL=NodeCreator.js.map

package/out/core/ParseResult.d.ts

@@ -1,12 +1,38 @@
 import { Node } from "./Node";
 import { ParseException } from "../exceptions/ParseException";
+/**
+ * Result of a parse in multi-error mode: it collects the root nodes obtained and every error
+ * found (both syntax and validation ones), without bailing out on the first one.
+ *
+ * See {@link Parser.parseResult}. For the traditional fail-fast mode use {@link Parser.parse},
+ * which internally uses this result and throws the first error.
+ */
 export declare class ParseResult {
     private readonly nodes;
     private readonly errors;
+    /**
+     * Creates a result, empty by default.
+     *
+     * @param nodes root nodes to start from.
+     * @param errors errors to start from.
+     */
     constructor(nodes?: Node[], errors?: ParseException[]);
+    /** @returns the root nodes collected so far. */
     getNodes(): Node[];
+    /** @returns the syntax or validation errors collected so far, in order of appearance. */
     getErrors(): ParseException[];
+    /** @returns true if at least one error has been collected. */
     hasErrors(): boolean;
+    /**
+     * Adds an error found while parsing.
+     *
+     * @param error error found while parsing, without aborting the traversal.
+     */
     addError(error: ParseException): void;
+    /**
+     * Adds a root node to the result.
+     *
+     * @param node already closed root node to add to the result.
+     */
     addNode(node: Node): void;
 }

package/out/core/ParseResult.js

@@ -1,23 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ParseResult = void 0;
+/**
+ * Result of a parse in multi-error mode: it collects the root nodes obtained and every error
+ * found (both syntax and validation ones), without bailing out on the first one.
+ *
+ * See {@link Parser.parseResult}. For the traditional fail-fast mode use {@link Parser.parse},
+ * which internally uses this result and throws the first error.
+ */
 class ParseResult {
+    /**
+     * Creates a result, empty by default.
+     *
+     * @param nodes root nodes to start from.
+     * @param errors errors to start from.
+     */
     constructor(nodes = [], errors = []) {
         this.nodes = nodes;
         this.errors = errors;
     }
+    /** @returns the root nodes collected so far. */
     getNodes() {
         return this.nodes;
     }
+    /** @returns the syntax or validation errors collected so far, in order of appearance. */
     getErrors() {
         return this.errors;
     }
+    /** @returns true if at least one error has been collected. */
     hasErrors() {
         return this.errors.length > 0;
     }
+    /**
+     * Adds an error found while parsing.
+     *
+     * @param error error found while parsing, without aborting the traversal.
+     */
     addError(error) {
         this.errors.push(error);
     }
+    /**
+     * Adds a root node to the result.
+     *
+     * @param node already closed root node to add to the result.
+     */
     addNode(node) {
         this.nodes.push(node);
     }

package/out/core/Parser.d.ts

@@ -2,12 +2,43 @@ import { Node } from "./Node";
 import { Observer } from "../processors/Observer";
 import { Validator } from "../processors/Validator";
 import { ParseResult } from "./ParseResult";
+/**
+ * Line-by-line STXT parsing engine. It knows nothing about schemas: semantic validation is
+ * plugged in through {@link Parser.registerValidator} and {@link Parser.registerObserver}.
+ * See {@link UnifiedSchemaProvider} for the usual way of building the validators to register.
+ */
 export declare class Parser {
     private observers;
     private validators;
+    /**
+     * Registers an observer, notified when each node is opened and closed.
+     *
+     * @param observer the {@link Observer} to register, notified while parsing.
+     */
     registerObserver(observer: Observer): void;
+    /**
+     * Registers a validator, invoked when each node is closed.
+     *
+     * @param validator the {@link Validator} to register, invoked when each node is closed during parsing.
+     */
     registerValidator(validator: Validator): void;
+    /**
+     * Traditional fail-fast mode: throws the first error found (either syntax or validation).
+     * Internally it reuses the same traversal as {@link Parser.parseResult}, and throws the first
+     * error it collected.
+     *
+     * @param content the whole STXT document to parse.
+     * @returns the root nodes of the document.
+     * @throws ParseException the first error found, be it syntax or validation.
+     */
     parse(content: string): Node[];
+    /**
+     * Multi-error mode: parses the whole content collecting every error found (both syntax and
+     * validation) without bailing out on the first one. See {@link ParseResult}.
+     *
+     * @param content the whole STXT document to parse.
+     * @returns the collected result, with the root nodes obtained and every error found.
+     */
     parseResult(content: string): ParseResult;
     private processLine;
     private handleError;

package/out/core/Parser.js

@@ -5,17 +5,41 @@ const LineParser_1 = require("./LineParser");
 const NodeCreator_1 = require("./NodeCreator");
 const ParseResult_1 = require("./ParseResult");
 const ParseException_1 = require("../exceptions/ParseException");
+/**
+ * Line-by-line STXT parsing engine. It knows nothing about schemas: semantic validation is
+ * plugged in through {@link Parser.registerValidator} and {@link Parser.registerObserver}.
+ * See {@link UnifiedSchemaProvider} for the usual way of building the validators to register.
+ */
 class Parser {
     constructor() {
         this.observers = [];
         this.validators = [];
     }
+    /**
+     * Registers an observer, notified when each node is opened and closed.
+     *
+     * @param observer the {@link Observer} to register, notified while parsing.
+     */
     registerObserver(observer) {
         this.observers.push(observer);
     }
+    /**
+     * Registers a validator, invoked when each node is closed.
+     *
+     * @param validator the {@link Validator} to register, invoked when each node is closed during parsing.
+     */
     registerValidator(validator) {
         this.validators.push(validator);
     }
+    /**
+     * Traditional fail-fast mode: throws the first error found (either syntax or validation).
+     * Internally it reuses the same traversal as {@link Parser.parseResult}, and throws the first
+     * error it collected.
+     *
+     * @param content the whole STXT document to parse.
+     * @returns the root nodes of the document.
+     * @throws ParseException the first error found, be it syntax or validation.
+     */
     parse(content) {
         const result = this.parseResult(content);
         if (result.hasErrors()) {
@@ -24,6 +48,13 @@ class Parser {
         }
         return result.getNodes();
     }
+    /**
+     * Multi-error mode: parses the whole content collecting every error found (both syntax and
+     * validation) without bailing out on the first one. See {@link ParseResult}.
+     *
+     * @param content the whole STXT document to parse.
+     * @returns the collected result, with the root nodes obtained and every error found.
+     */
     parseResult(content) {
         content = this.removeUTF8BOM(content);
         const result = new ParseResult_1.ParseResult();
@@ -31,8 +62,8 @@ class Parser {
         const documents = [];
         let lineNumber = 0;
         const lines = content.split(/\r?\n/);
-        // El salto de línea final es terminador de la última línea, no una línea
-        // vacía adicional (evita añadir una línea espuria a un bloque >> en EOF, spec 10.3)
+        // The final line break terminates the last line, it is not an extra empty line
+        // (this avoids adding a spurious line to a >> block at EOF, spec 10.3)
         if (lines.length > 0 && lines[lines.length - 1] === "") {
             lines.pop();
         }
@@ -40,13 +71,13 @@ class Parser {
             lineNumber++;
             this.processLine(line, lineNumber, stack, documents, result);
         }
-        // Cerrar todos los nodos pendientes al EOF
+        // Close every node still open at EOF
         this.closeToLevel(stack, documents, 0, result);
-        // Agregar nodos al resultado
+        // Add the nodes to the result
         for (const doc of documents) {
             result.addNode(doc);
         }
-        // Retorno resultado
+        // Return the result
         return result;
     }
     processLine(lineString, lineNumber, stack, documents, result) {
@@ -54,40 +85,40 @@ class Parser {
             const lastNode = stack.length === 0 ? null : stack[stack.length - 1];
             const lastLevel = lastNode ? lastNode.getLevel() : 0;
             const lastNodeText = lastNode ? lastNode.isTextNode() : false;
-            // Parseamos línea
+            // Parse the line
             const line = (0, LineParser_1.parseLine)(lineString, lastNodeText, lastLevel, lineNumber);
             if (line.isComment) {
-                // Pasamos a observers
+                // Hand it over to the observers
                 this.observers.forEach(observer => {
                     observer.onComment(lineNumber, lineString);
                 });
                 return;
             }
             const currentLevel = line.level;
-            // Si estamos dentro de un nodo texto, y el nivel indica que sigue siendo texto,
-            // añadimos línea de texto y no creamos nodo.
+            // When we are inside a text node and the level says it is still text,
+            // append the text line instead of creating a node.
             if (line.isBlock) {
                 lastNode.addTextLine(line.content);
-                // Notificar a observers sobre la línea de texto
+                // Notify the observers about the text line
                 this.observers.forEach(observer => {
                     observer.onTextLine(lastNode, lineNumber, lineString, line);
                 });
                 return;
             }
-            // Si es línea vacía no hacemos nada
+            // Empty lines are ignored
             if (line.isEmpty()) {
                 return;
             }
-            // Cerramos nodos hasta el nivel actual (esto "finaliza" y adjunta al padre/documentos)
+            // Close the nodes down to the current level (this "finishes" them and attaches them to the parent/documents)
             this.closeToLevel(stack, documents, currentLevel, result);
-            // Creamos el nuevo nodo y lo dejamos "abierto" en la pila (NO lo adjuntamos aún)
+            // Create the new node and leave it "open" on the stack (do NOT attach it yet)
             const parent = stack.length === 0 ? null : stack[stack.length - 1];
             const node = (0, NodeCreator_1.createNode)(line, lineNumber, currentLevel, parent);
-            // Pasamos a observers
+            // Hand it over to the observers
             this.observers.forEach(observer => {
                 observer.onCreate(node, lineString);
             });
-            // Añadimos a stack
+            // Push it onto the stack
             stack.push(node);
         }
         catch (e) {
@@ -99,18 +130,18 @@ class Parser {
             result.addError(e);
         }
         else if (e instanceof Error) {
-            // Convertir errores genéricos a ParseException
+            // Turn generic errors into a ParseException
             result.addError(new ParseException_1.ParseException(line, errorCode, e.message));
         }
         else {
-            // Error desconocido
+            // Unknown error
             result.addError(new ParseException_1.ParseException(line, unknownErrorCode, String(e)));
         }
     }
     closeToLevel(stack, documents, targetLevel, result) {
         while (stack.length > targetLevel) {
             const completed = stack.pop();
-            // Pasamos validators
+            // Hand it over to the validators
             this.validators.forEach(validator => {
                 try {
                     const errors = validator.validate(completed);
@@ -128,7 +159,7 @@ class Parser {
             else {
                 stack[stack.length - 1].addChild(completed);
             }
-            // Pasamos a observers
+            // Hand it over to the observers
             this.observers.forEach(observer => {
                 observer.onFinish(completed);
             });

package/out/core/StringUtils.d.ts

@@ -1,8 +1,39 @@
+/** String normalization helpers used for names, namespaces and values. */
 export declare class StringUtils {
     private constructor();
+    /**
+     * Removes the trailing whitespace of a string.
+     *
+     * @param s string to strip the trailing spaces from.
+     * @returns the string without trailing whitespace; null/undefined is treated as the empty string.
+     */
     static rightTrim(s: string | null | undefined): string;
+    /**
+     * Removes every whitespace character of a string.
+     *
+     * @param input string to remove the spaces from.
+     * @returns the string without any whitespace at all.
+     */
     static cleanSpaces(input: string): string;
+    /**
+     * Lower-cases a string.
+     *
+     * @param input string to lower-case.
+     * @returns the lower-cased string; null/undefined is treated as the empty string.
+     */
     static lowerCase(input: string | null | undefined): string;
+    /**
+     * Trims a string and collapses its inner whitespace.
+     *
+     * @param s string to compact.
+     * @returns the string with the outer spaces trimmed and the inner ones collapsed into a single one; null/undefined is treated as the empty string.
+     */
     static compactSpaces(s: string | null | undefined): string;
+    /**
+     * Builds the canonical name of a node, as defined by STXT-SPEC 4.3.
+     *
+     * @param input string to normalize.
+     * @returns the canonical name of a node: NFC + lower case, with separators collapsed into '-'; null/undefined is treated as the empty string.
+     */
     static normalize(input: string | null | undefined): string;
 }