@stxt-lang/core 0.14.0 → 0.15.0

package/README.md

@@ -5,7 +5,7 @@ Parser and schema validator for **STXT**, an indentation-based structured-text f
 STXT is a plain-text format for writing structured, semantic documents: no braces, no closing tags, just indentation. It is designed to be equally readable by humans and by machines, and it comes with an optional schema layer so documents can be validated.
 
 - Website and language reference: <https://stxt.dev>
-- VSCode extension: [STXT - Semantic Text](https://marketplace.visualstudio.com/items?itemName=stxt-lang.stxt)
+- VSCode extension: [STXT Language](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
 - Python implementation: [`stxt`](https://pypi.org/project/stxt/) on PyPI
 
@@ -334,6 +334,10 @@ if (errors.length === 0) {
 }
 ```
 
+`Formatter.format` takes the same limits as the parser as an optional third argument —
+`Formatter.format(source, IndentStyle.TABS, { maxInputSize: -1 })` — since formatting parses
+the document with them (STXT-SPEC §11.2).
+
 ## API surface
 
 Everything importable from the package:

package/out/core/LineParser.js

@@ -64,7 +64,7 @@ function parseLine(line, lastNodeBlock, lastLevel, numLine, validate = true) {
         if (lastNodeBlock && level > lastLevel) {
             const text = StringUtils_1.StringUtils.rightTrim(line.substring(pointer + 1));
             // 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)
+            // empty lines are never an error and are exempt from it (spec 10.3)
             if (validate && sawSpace && sawTab && text.length > 0) {
                 throw new ParseException_1.ParseException(numLine, "INDENTATION_MIXED", `Mixed tabs and spaces in indentation`);
             }

package/out/core/Parser.js

@@ -257,6 +257,13 @@ class Parser {
     closeToLevel(stack, targetLevel, result) {
         while (stack.length > targetLevel) {
             const completed = stack.pop();
+            // A closing block node drops its final empty lines (STXT-SPEC §10.3): they are not
+            // content, only visual separation or an editor's final line breaks. The validators
+            // and observers below already see the trimmed node; onTextLine did fire for these
+            // lines while the block was open, as process observation of the source.
+            if (completed instanceof TextNode_1.TextNode) {
+                completed.removeTrailingEmptyLines();
+            }
             // Hand it over to the validators
             this.validators.forEach(validator => {
                 try {

package/out/core/TextNode.d.ts

@@ -56,6 +56,13 @@ export declare class TextNode extends Node {
     addTextLine(line: string): void;
     /** Removes every text line. */
     clearText(): void;
+    /**
+     * Removes the final empty lines (`""` elements at the end of the lines). The {@link Parser}
+     * calls it when the block closes (STXT-SPEC §10.3: the final empty lines of a block are not
+     * content); it is public because a programmatically built node may want the same
+     * normalization before writing.
+     */
+    removeTrailingEmptyLines(): void;
     getText(): string;
     isTextNode(): boolean;
     private static splitLines;

package/out/core/TextNode.js

@@ -61,6 +61,17 @@ class TextNode extends Node_1.Node {
     clearText() {
         this.lines.length = 0;
     }
+    /**
+     * Removes the final empty lines (`""` elements at the end of the lines). The {@link Parser}
+     * calls it when the block closes (STXT-SPEC §10.3: the final empty lines of a block are not
+     * content); it is public because a programmatically built node may want the same
+     * normalization before writing.
+     */
+    removeTrailingEmptyLines() {
+        while (this.lines.length > 0 && this.lines[this.lines.length - 1] === "") {
+            this.lines.pop();
+        }
+    }
     getText() {
         return this.lines.join("\n");
     }

package/out/runtime/Formatter.d.ts

@@ -1,3 +1,4 @@
+import { ParserOptions } from "../core/Parser";
 import { ParseException } from "../exceptions/ParseException";
 import { IndentStyle } from "./NodeWriter";
 /** The outcome of {@link Formatter.format}. */
@@ -32,10 +33,10 @@ export interface FormatResult {
  * - A **text line of a block** gets the indentation of the block (its level plus one) in the
  *   requested style, followed by its content; any indentation the line had beyond the block's
  *   is content (STXT-SPEC §10.2, relative indentation is preserved) and is kept exactly. A
- *   blank line of the block is `""` in the content whatever it looks like in the source
- *   (STXT-SPEC §10.3), so it is written with the indentation of the block too: the block reads
- *   as one piece and, at the end of the file, the line is not lost — an empty last line would
- *   be indistinguishable from the final line ending.
+ *   blank line that precedes more block text is `""` in the content whatever it looks like in
+ *   the source (STXT-SPEC §10.3), so it is written with the indentation of the block too: the
+ *   block reads as one piece. The final blank lines of a block are not content (STXT-SPEC
+ *   §10.3: the parser drops them when the block closes) and fall under the next rule.
  * - Every **other line** — a comment, a blank line outside a block, or a line the parse tree
  *   does not describe because of a syntax error — is kept as the author wrote it, except that
  *   its trailing blanks are removed and the whole indentation units at its start are converted
@@ -58,9 +59,13 @@ export declare class Formatter {
      *
      * @param text the document.
      * @param style indentation style to format with; tabs by default.
+     * @param options limits for the internal parser (STXT-SPEC 11.2); every omitted one keeps
+     *                its recommended default, and -1 disables one. A limit exceeded shows up in
+     *                the errors like any other syntax error, and the lines the aborted parse
+     *                never described are converted as "other lines" (indentation units only).
      * @returns the formatted text and the syntax errors found; see {@link FormatResult}.
      */
-    static format(text: string, style?: IndentStyle): FormatResult;
+    static format(text: string, style?: IndentStyle, options?: ParserOptions): FormatResult;
     /**
      * Formats one source line.
      *

package/out/runtime/Formatter.js

@@ -23,10 +23,10 @@ const NodeWriter_1 = require("./NodeWriter");
  * - A **text line of a block** gets the indentation of the block (its level plus one) in the
  *   requested style, followed by its content; any indentation the line had beyond the block's
  *   is content (STXT-SPEC §10.2, relative indentation is preserved) and is kept exactly. A
- *   blank line of the block is `""` in the content whatever it looks like in the source
- *   (STXT-SPEC §10.3), so it is written with the indentation of the block too: the block reads
- *   as one piece and, at the end of the file, the line is not lost — an empty last line would
- *   be indistinguishable from the final line ending.
+ *   blank line that precedes more block text is `""` in the content whatever it looks like in
+ *   the source (STXT-SPEC §10.3), so it is written with the indentation of the block too: the
+ *   block reads as one piece. The final blank lines of a block are not content (STXT-SPEC
+ *   §10.3: the parser drops them when the block closes) and fall under the next rule.
  * - Every **other line** — a comment, a blank line outside a block, or a line the parse tree
  *   does not describe because of a syntax error — is kept as the author wrote it, except that
  *   its trailing blanks are removed and the whole indentation units at its start are converted
@@ -49,15 +49,19 @@ class Formatter {
      *
      * @param text the document.
      * @param style indentation style to format with; tabs by default.
+     * @param options limits for the internal parser (STXT-SPEC 11.2); every omitted one keeps
+     *                its recommended default, and -1 disables one. A limit exceeded shows up in
+     *                the errors like any other syntax error, and the lines the aborted parse
+     *                never described are converted as "other lines" (indentation units only).
      * @returns the formatted text and the syntax errors found; see {@link FormatResult}.
      */
-    static format(text, style = NodeWriter_1.IndentStyle.TABS) {
+    static format(text, style = NodeWriter_1.IndentStyle.TABS, options) {
         // STXT-TREE-SPEC 12.1: an initial BOM is not kept
         if (text.startsWith("\uFEFF")) {
             text = text.substring(1);
         }
         const sourceLines = new SourceLines();
-        const parser = new Parser_1.Parser();
+        const parser = new Parser_1.Parser(options);
         parser.registerObserver(sourceLines);
         const result = parser.parseResult(text);
         const eol = text.includes("\r\n") ? "\r\n" : "\n";
@@ -81,8 +85,11 @@ class Formatter {
         if (node) {
             return Formatter.renderNode(node, line, style);
         }
+        // A final empty line of a block is not content (STXT-SPEC §10.3): the parser removed it
+        // from the node when the block closed, so its index falls beyond the logical lines. It
+        // is kept as any other line: blank, unindented.
         const text = sourceLines.textAt(lineNumber);
-        if (text) {
+        if (text && text.index < text.node.getTextLines().length) {
             return Formatter.indent(text.node.getLevel() + 1, style) + text.line.content;
         }
         return Formatter.convertUnits(StringUtils_1.StringUtils.rightTrim(line), style);
@@ -168,7 +175,10 @@ class SourceLines {
         // Comment lines need no bookkeeping: every line that opens no node is treated alike.
     }
     onTextLine(node, lineNumber, lineString, line) {
-        this.textByLine.set(lineNumber, { node, line });
+        // The line was just appended: its 0-based index in the block is the current last. After
+        // the block closes and drops its final empty lines (STXT-SPEC §10.3), an index beyond
+        // getTextLines() marks the line as a final empty line, not content.
+        this.textByLine.set(lineNumber, { node, line, index: node.getTextLines().length - 1 });
     }
     /**
      * @param lineNumber line number, 1-indexed.
@@ -179,8 +189,9 @@ class SourceLines {
     }
     /**
      * @param lineNumber line number, 1-indexed.
-     * @returns the block node this line is text of and the line already split into indentation
-     *          and content, or undefined if the line is not text of a block.
+     * @returns the block node this line is text of, the line already split into indentation and
+     *          content, and its 0-based index in the block; or undefined if the line is not text
+     *          of a block.
      */
     textAt(lineNumber) {
         return this.textByLine.get(lineNumber);

package/out/runtime/NodeWriter.js

@@ -59,9 +59,17 @@ class NodeWriter {
         }
         if (n instanceof TextNode_1.TextNode) {
             out.push(" >>\n");
-            for (const line of n.getTextLines()) {
+            // Final empty lines are not emitted (STXT-TREE-SPEC 11.1 rule 6): parsing never
+            // produces them (STXT-SPEC 10.3), and on a programmatically built node they would
+            // not survive the round trip.
+            const lines = n.getTextLines();
+            let last = lines.length;
+            while (last > 0 && lines[last - 1] === "") {
+                last--;
+            }
+            for (let i = 0; i < last; i++) {
                 NodeWriter.indent(out, depth + 1, style);
-                out.push(line, "\n");
+                out.push(lines[i], "\n");
             }
         }
         else if (n instanceof InlineNode_1.InlineNode) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stxt-lang/core",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Parser and schema validator for STXT, an indentation-based structured-text format.",
   "main": "out/all.js",
   "types": "out/all.d.ts",
@@ -34,7 +34,6 @@
   },
   "keywords": [
     "stxt",
-    "semantic text",
     "parser",
     "schema",
     "validation",