@stxt-lang/core 0.5.2 → 0.6.0

package/out/template/MetaTemplateSchemaProvider.js

@@ -5,7 +5,16 @@ const Parser_1 = require("../core/Parser");
 const ValidationException_1 = require("../exceptions/ValidationException");
 const RuntimeException_1 = require("../exceptions/RuntimeException");
 const TemplateParser_1 = require("./TemplateParser");
+/**
+ * {@link SchemaProvider} that defines in code the meta-schema of the template language itself
+ * (`@stxt.template`), so that a loaded template can validate itself.
+ */
 class MetaTemplateSchemaProvider {
+    /**
+     * Parses the meta-template and keeps the schema it produces ready to be served.
+     *
+     * @throws ValidationException with code `META_SCHEMA_INVALID` if the meta-template does not produce exactly one document.
+     */
     constructor() {
         const parser = new Parser_1.Parser();
         const nodes = parser.parse(MetaTemplateSchemaProvider.META_TEXT);
@@ -14,11 +23,18 @@ class MetaTemplateSchemaProvider {
         }
         this.meta = (0, TemplateParser_1.transformTemplateNodeToSchema)(nodes[0]);
     }
+    /**
+     * Serves the meta-schema of the template language.
+     *
+     * @param namespace namespace whose schema is wanted; only `@stxt.template` is served.
+     * @returns the meta-schema of the template language.
+     * @throws RuntimeException with code `RESOURCE_NOT_FOUND` if any other namespace is asked for.
+     */
     getSchema(namespace) {
         if (namespace !== "@stxt.template") {
             throw new RuntimeException_1.RuntimeException("RESOURCE_NOT_FOUND", `Not found '${namespace}' in namespace: @stxt.template`);
         }
-        // meta siempre existe si el constructor terminó, pero lo dejamos equivalente al Java
+        // meta always exists once the constructor finished, but this mirrors the Java version
         if (!this.meta) {
             throw new ValidationException_1.ValidationException(0, "META_SCHEMA_NOT_AVAILABLE", "Meta schema not available");
         }

package/out/template/TemplateParser.d.ts

@@ -1,3 +1,11 @@
 import { Node } from "../core/Node";
 import { Schema } from "../schema/Schema";
+/**
+ * Turns the tree of an already parsed `@stxt.template` document into an equivalent {@link Schema}.
+ *
+ * @param node root of the already parsed `@stxt.template` document.
+ * @returns the resulting {@link Schema}.
+ * @throws ValidationException if the template is not valid, with the line already shifted to the
+ *         one of the original document.
+ */
 export declare function transformTemplateNodeToSchema(node: Node): Schema;

package/out/template/TemplateParser.js

@@ -10,29 +10,37 @@ const StringUtils_1 = require("../core/StringUtils");
 const ChildLineParser_1 = require("./ChildLineParser");
 const ParseException_1 = require("../exceptions/ParseException");
 const TypeRegistry_1 = require("../schema/TypeRegistry");
+/**
+ * Turns the tree of an already parsed `@stxt.template` document into an equivalent {@link Schema}.
+ *
+ * @param node root of the already parsed `@stxt.template` document.
+ * @returns the resulting {@link Schema}.
+ * @throws ValidationException if the template is not valid, with the line already shifted to the
+ *         one of the original document.
+ */
 function transformTemplateNodeToSchema(node) {
-    // Insertamos namespace
+    // Set the namespace
     const result = new Schema_1.Schema(node.getValue(), node.getLine(), undefined);
-    // Buscamos nodo structure
+    // Look for the structure node
     const structure = node.getChild("structure");
     if (!structure) {
         throw new ValidationException_1.ValidationException(node.getLine(), "TEMPLATE_STRUCTURE_REQUIRED", "Template must define 'Structure >>'");
     }
     const text = structure.getText();
     const offset = structure.getLine();
-    // Creamos un parser simple
+    // Build a plain parser
     const parser = new Parser_1.Parser();
-    // Parseamos para los nodos
+    // Parse to get the nodes
     try {
         const nodes = parser.parse(text);
-        // Vamos iterando todos los nodos insertando
+        // Walk every node adding it to the schema
         for (const n of nodes) {
             addToSchema(result, n);
         }
     }
     catch (e) {
-        // ValidationException extiende ParseException: comprobar primero para no degradar
-        // la severidad (la extensión pinta ValidationException como Warning)
+        // ValidationException extends ParseException: check it first so the severity is not
+        // downgraded (the extension paints ValidationException as a Warning)
         if (e instanceof ValidationException_1.ValidationException) {
             throw new ValidationException_1.ValidationException(e.line + offset, e.code, e.message);
         }
@@ -41,7 +49,7 @@ function transformTemplateNodeToSchema(node) {
         }
         throw e;
     }
-    // Buscamos descripciones
+    // Look for the descriptions
     const description = node.getChild("description");
     if (description) {
         const text = description.getText();
@@ -59,21 +67,22 @@ function transformTemplateNodeToSchema(node) {
             throw e;
         }
     }
-    // Retornamos resultado
+    // Return the result
     return result;
 }
+/** Adds to the schema the definition a node of the structure declares, along with its children. */
 function addToSchema(schema, node) {
-    // Obtenemos nombre qualificado
+    // Get the qualified name
     let namespace = node.getNamespace();
     const name = node.getName();
-    // Miramos datos
+    // Look at the data
     let cl = ChildLineParser_1.ChildLineParser.parse(node.getValue(), node.getLine());
     if (!namespace || namespace === "") {
         namespace = schema.getNamespace();
     }
     if (namespace !== schema.getNamespace()) {
-        // Un nodo externo solo puede declarar cardinalidad: ni tipo, ni valores ENUM,
-        // ni hijos (STXT-TEMPLATE-SPEC 6.4, 10 y 14.15)
+        // An external node may only declare cardinality: no type, no ENUM values
+        // and no children (STXT-TEMPLATE-SPEC 6.4, 10 and 14.15)
         const type = cl.getType();
         if (type && type.trim().length > 0) {
             throw new ValidationException_1.ValidationException(node.getLine(), "TYPE_DEFINITION_NOT_ALLOWED", "Not allowed type definition in external namespaces");
@@ -85,17 +94,17 @@ function addToSchema(schema, node) {
         if (node.getChildren().length > 0) {
             throw new ValidationException_1.ValidationException(node.getLine(), "CHILDREN_NOT_ALLOWED_IN_EXTERNAL_NAMESPACE", `Not allowed children in external namespaces (node ${node.getName()})`);
         }
-        // No hacemos nada con creación de nodos que no son de @stxt.template!!
+        // Nodes that do not belong to @stxt.template create nothing here!!
         return;
     }
-    // Miramos si es nuevo y añadimos en listado
+    // Check whether it is new and add it to the list
     let schemaNode = schema.getNodeDefinition(name);
     if (!schemaNode) {
-        // Nuevo
+        // New one
         const type = cl.getType() ?? "INLINE";
-        // En este punto el schema ya contiene tanto las definiciones previas ya cerradas
-        // como los ancestros abiertos, así que una referencia que no resuelve aquí no
-        // resuelve a nada (STXT-TEMPLATE-SPEC 6.4 y 14.11)
+        // At this point the schema already holds both the previous definitions, already closed,
+        // and the open ancestors, so a reference that does not resolve here resolves to
+        // nothing (STXT-TEMPLATE-SPEC 6.4 and 14.11)
         if (type.startsWith("@")) {
             throw new ValidationException_1.ValidationException(node.getLine(), "REFERENCE_NOT_FOUND", `Reference '${type}' does not point to a previous definition or an open ancestor`);
         }
@@ -107,16 +116,16 @@ function addToSchema(schema, node) {
         const values = cl.getValues();
         if (values) {
             if (type !== "ENUM") {
-                // Mismo código que SchemaParser: un template es azúcar equivalente a un schema
-                // (STXT-TEMPLATE-SPEC 13), así que la misma condición no debe cambiar de código
-                // según la puerta de entrada
+                // Same code as SchemaParser: a template is sugar equivalent to a schema
+                // (STXT-TEMPLATE-SPEC 13), so the same condition must not change its code
+                // depending on the entry point
                 throw new ValidationException_1.ValidationException(node.getLine(), "VALUES_ONLY_SUPPORTED_BY_ENUM", `Values only supported for type ENUM, not for type ${type}`);
             }
             for (const v of values) {
                 schemaNode.addValue(v, node.getLine());
             }
         }
-        // Un ENUM sin lista de valores es un template inválido (STXT-TEMPLATE-SPEC 9 y 13.7)
+        // An ENUM with no list of values is an invalid template (STXT-TEMPLATE-SPEC 9 and 13.7)
         if (type === "ENUM" && (!values || values.length === 0)) {
             throw new ValidationException_1.ValidationException(node.getLine(), "VALUES_EMPTY_FOR_ENUM", "ENUM Type must include values");
         }
@@ -127,7 +136,7 @@ function addToSchema(schema, node) {
             throw new ValidationException_1.ValidationException(node.getLine(), "NODE_DEFINED_MULTIPLE_TIMES", `Multiple node reference must start with @: ${node.getName()}`);
         }
         const reference = type.substring(1).trim();
-        // Referencia y tipo explícito en la misma línea (STXT-TEMPLATE-SPEC 14.13)
+        // Reference and explicit type on the same line (STXT-TEMPLATE-SPEC 14.13)
         const explicitType = referenceType(reference, node.getNormalizedName());
         if (explicitType) {
             throw new ValidationException_1.ValidationException(node.getLine(), "REFERENCE_WITH_TYPE_NOT_ALLOWED", `Reference '@${node.getName()}' can not declare a type: ${explicitType}`);
@@ -135,8 +144,8 @@ function addToSchema(schema, node) {
         if (StringUtils_1.StringUtils.normalize(reference) !== node.getNormalizedName()) {
             throw new ValidationException_1.ValidationException(node.getLine(), "NODE_REFERENCE_NOT_VALID", `Reference must be '@${node.getName()}', not '${reference}'`);
         }
-        // La referencia puede sobrescribir la cardinalidad, pero no redefinir valores
-        // ENUM ni hijos (STXT-TEMPLATE-SPEC 6.4)
+        // A reference may override the cardinality, but it may redefine neither the ENUM
+        // values nor the children (STXT-TEMPLATE-SPEC 6.4)
         const values = cl.getValues();
         if (values) {
             throw new ValidationException_1.ValidationException(node.getLine(), "VALUES_NOT_ALLOWED_IN_REFERENCE", `Reference '@${node.getName()}' can not redefine ENUM values`);
@@ -146,13 +155,13 @@ function addToSchema(schema, node) {
         }
         return; // OK Definition
     }
-    // Una vez ya existe, si tiene hijos los intentamos crear.
+    // Once it exists, try to create its children if it has any.
     const childrenNode = node.getChildren();
-    // Error de template 14.9: nodo con hijos y tipo efectivo que no admite hijos
+    // Template error 14.9: node with children and an effective type that does not admit children
     if (childrenNode.length > 0 && !TypeRegistry_1.TypeRegistry.admitsChildren(schemaNode.getType())) {
         throw new ValidationException_1.ValidationException(node.getLine(), "CHILDREN_NOT_ALLOWED_FOR_TYPE", `Type ${schemaNode.getType()} does not allow children (node ${node.getName()})`);
     }
-    // Insertamos childs
+    // Add the children
     for (const child of childrenNode) {
         cl = ChildLineParser_1.ChildLineParser.parse(child.getValue(), child.getLine());
         const childName = child.getName();
@@ -166,11 +175,11 @@ function addToSchema(schema, node) {
     }
 }
 /**
- * Distingue `@Nombre Nodo TIPO` (referencia + tipo, error 14.13) de `@Otro Nombre`
- * (referencia con nombre distinto, error 14.12). Como los nombres de nodo admiten
- * espacios, la única lectura fiable es: si el último token es un tipo conocido y lo
- * que queda delante es el nombre del propio nodo, la línea declara ambas cosas.
- * Devuelve el tipo declarado, o null si la referencia no lleva tipo.
+ * Tells `@Node Name TYPE` (reference + type, error 14.13) apart from `@Another Name`
+ * (reference with a different name, error 14.12). Since node names may contain spaces,
+ * the only reliable reading is: if the last token is a known type and what comes before
+ * it is the name of the node itself, the line is declaring both things.
+ * Returns the declared type, or null when the reference carries no type.
  */
 function referenceType(reference, normalizedName) {
     const cut = reference.lastIndexOf(" ");
@@ -184,27 +193,28 @@ function referenceType(reference, normalizedName) {
     }
     return null;
 }
+/** Attaches to the node definitions the descriptions declared in the `Description >>` block. */
 function addDescriptions(schema, nodes) {
     nodes.forEach((node) => {
-        // Obtenemos namespace
+        // Get the namespace
         let namespace = node.getNamespace();
         if (!namespace || namespace === "") {
             namespace = schema.getNamespace();
         }
-        // Validamos no external description
+        // No external descriptions
         if (namespace !== schema.getNamespace()) {
             throw new ValidationException_1.ValidationException(node.getLine(), "EXTERNAL_DESCRIPTION_NOT_ALLOWED", "Not allowed description in external namespaces");
         }
-        // Validamos sin hijos
+        // No children either
         if (node.getChildren().length > 0) {
             throw new ValidationException_1.ValidationException(node.getLine(), "CHILDREN_DESCRIPTION_NOT_ALLOWED", "Not allowed children in description");
         }
-        // Buscamos nodo de esquema
+        // Look for the node in the schema
         const nodeDef = schema.getNodeDefinition(node.getName());
         if (!nodeDef) {
             throw new ValidationException_1.ValidationException(node.getLine(), "NODE_NOT_FOUND", `Not found node with name: ${node.getName()}`);
         }
-        // No se permite más de una entrada por nodo (STXT-TEMPLATE-SPEC 12)
+        // No more than one entry per node is allowed (STXT-TEMPLATE-SPEC 12)
         if (nodeDef.getDescription() !== undefined) {
             throw new ValidationException_1.ValidationException(node.getLine(), "DESCRIPTION_ALREADY_DEFINED", `Exists a previous description for node: ${node.getName()}`);
         }

package/out/template/TemplateSchemaProviderMemory.d.ts

@@ -1,6 +1,24 @@
 import { SchemaProviderMemory } from "../schema/SchemaProviderMemory";
 import { SchemaProvider } from "../schema/SchemaProvider";
+/**
+ * In-memory {@link SchemaProvider} fed with `@stxt.template` documents: each template is turned
+ * into its equivalent {@link Schema} and registered under its own namespace.
+ */
 export declare class TemplateSchemaProviderMemory extends SchemaProviderMemory {
+    /**
+     * Creates an empty provider.
+     *
+     * @param parent provider to fall back to when a namespace is not registered here; the
+     *        template meta-schema provider when omitted.
+     */
     constructor(parent?: SchemaProvider | null | undefined);
+    /**
+     * Parses a template document, validates it against the template meta-schema and registers the
+     * schema it produces.
+     *
+     * @param template text of the `@stxt.template` document.
+     * @throws ValidationException with code `INVALID_SCHEMA` if the document does not hold exactly
+     *         one template, or if the resulting schema has no namespace.
+     */
     addTemplate(template: string): void;
 }

package/out/template/TemplateSchemaProviderMemory.js

@@ -8,25 +8,43 @@ const ValidationException_1 = require("../exceptions/ValidationException");
 const MetaTemplateSchemaProvider_1 = require("./MetaTemplateSchemaProvider");
 const SchemaProviderMemory_1 = require("../schema/SchemaProviderMemory");
 const TemplateParser_1 = require("./TemplateParser");
+/**
+ * In-memory {@link SchemaProvider} fed with `@stxt.template` documents: each template is turned
+ * into its equivalent {@link Schema} and registered under its own namespace.
+ */
 class TemplateSchemaProviderMemory extends SchemaProviderMemory_1.SchemaProviderMemory {
+    /**
+     * Creates an empty provider.
+     *
+     * @param parent provider to fall back to when a namespace is not registered here; the
+     *        template meta-schema provider when omitted.
+     */
     constructor(parent) {
         if (!parent) {
             parent = new MetaTemplateSchemaProvider_1.MetaTemplateSchemaProvider();
         }
         super(parent);
     }
+    /**
+     * Parses a template document, validates it against the template meta-schema and registers the
+     * schema it produces.
+     *
+     * @param template text of the `@stxt.template` document.
+     * @throws ValidationException with code `INVALID_SCHEMA` if the document does not hold exactly
+     *         one template, or if the resulting schema has no namespace.
+     */
     addTemplate(template) {
         const parser = new Parser_1.Parser();
         const nodes = parser.parse(template);
         if (nodes.length !== 1) {
             throw new ValidationException_1.ValidationException(0, "INVALID_SCHEMA", `There are ${nodes.length}, and expected is 1`);
         }
-        // Validamos el template contra el meta-schema de templates
+        // Validate the template against the template meta-schema
         const schemaValidator = new SchemaValidator_1.SchemaValidator(new MetaTemplateSchemaProvider_1.MetaTemplateSchemaProvider(), true);
         schemaValidator.validate(nodes[0]);
-        // Generamos schema desde el template
+        // Build the schema out of the template
         const sch = (0, TemplateParser_1.transformTemplateNodeToSchema)(nodes[0]);
-        // Check mínimo de seguridad (en Java también se controlaba el namespace esperado)
+        // Minimum safety check (Java checked the expected namespace here too)
         if (!sch.getNamespace() || sch.getNamespace().trim().length === 0) {
             throw new ValidationException_1.ValidationException(0, "INVALID_SCHEMA", "Schema namespace is empty");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stxt-lang/core",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Parser and schema validator for STXT, an indentation-based structured-text format.",
   "main": "out/all.js",
   "types": "out/all.d.ts",
@@ -11,6 +11,7 @@
     "out/all.js",
     "out/all.d.ts",
     "out/core",
+    "out/discovery",
     "out/exceptions",
     "out/processors",
     "out/runtime",