parser-lr 0.4.1 → 0.5.0

package/dist/lib-cjs/transform/grammar-fixture.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fixtureGrammarPath = fixtureGrammarPath;
+exports.findChildrenBySymbol = findChildrenBySymbol;
+exports.findChildBySymbol = findChildBySymbol;
+exports.parseFixture = parseFixture;
+exports.discoverFixtures = discoverFixtures;
+exports.runFixtureCase = runFixtureCase;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const parse_context_js_1 = require("../parse-context.js");
+/**
+ * Returns the `.grammar` file for one fixture directory.
+ *
+ * Fixture grammars are named after their directory (for example
+ * `bare-terminal/bare-terminal.grammar`). The meta-grammar keeps the reserved
+ * name `grammar.grammar` at the repo root only.
+ *
+ * @param fixtureDir - Directory containing a fixture grammar and input files.
+ */
+function fixtureGrammarPath(fixtureDir) {
+    const grammarPath = (0, node_path_1.join)(fixtureDir, `${(0, node_path_1.basename)(fixtureDir)}.grammar`);
+    return (0, node_fs_1.existsSync)(grammarPath) ? grammarPath : null;
+}
+/**
+ * Returns child AST nodes matching a symbol name.
+ *
+ * @param node - Parent AST node.
+ * @param symbol - Child symbol to find.
+ */
+function findChildrenBySymbol(node, symbol) {
+    return node.children.filter((child) => child.symbol === symbol);
+}
+/**
+ * Returns the first child AST node matching a symbol name.
+ *
+ * @param node - Parent AST node.
+ * @param symbol - Child symbol to find.
+ */
+function findChildBySymbol(node, symbol) {
+    return node.children.find((child) => child.symbol === symbol) ?? null;
+}
+/**
+ * Parses one fixture grammar and input file into an AST.
+ *
+ * @param fixtureDir - Directory containing a named fixture grammar and an input file.
+ * @param inputFileName - Input file name within the fixture directory.
+ */
+function parseFixture(fixtureDir, inputFileName = 'input.txt') {
+    const grammarPath = fixtureGrammarPath(fixtureDir);
+    if (grammarPath === null) {
+        throw new Error(`fixture grammar not found in ${fixtureDir}`);
+    }
+    const grammarSource = (0, node_fs_1.readFileSync)(grammarPath, 'utf8');
+    const input = (0, node_fs_1.readFileSync)((0, node_path_1.join)(fixtureDir, inputFileName), 'utf8').trimEnd();
+    const context = parse_context_js_1.ParseContext.fromGrammar(grammarSource, 'lr1');
+    return context.parseSource(input);
+}
+/**
+ * Discovers fixture directories containing a named `.grammar` file under a root path.
+ *
+ * @param rootDir - Root directory to scan recursively.
+ */
+function discoverFixtures(rootDir) {
+    const fixtures = [];
+    const visit = (directory) => {
+        const grammarPath = fixtureGrammarPath(directory);
+        if (grammarPath !== null) {
+            const inputFiles = (0, node_fs_1.readdirSync)(directory)
+                .filter((name) => name.startsWith('input') && name.endsWith('.txt'))
+                .sort();
+            for (const inputFile of inputFiles) {
+                const baseName = inputFile.replace(/^input/, '').replace(/\.txt$/, '');
+                const expectedName = baseName === '' ? 'expected.json' : `expected${baseName}.json`;
+                const expectedPath = (0, node_path_1.join)(directory, expectedName);
+                fixtures.push({
+                    name: `${directory.split('/').slice(-2).join('/')}/${inputFile}`,
+                    grammarPath,
+                    inputPath: (0, node_path_1.join)(directory, inputFile),
+                    expectedPath: (0, node_fs_1.existsSync)(expectedPath) ? expectedPath : null,
+                });
+            }
+        }
+        for (const entry of (0, node_fs_1.readdirSync)(directory, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                visit((0, node_path_1.join)(directory, entry.name));
+            }
+        }
+    };
+    visit(rootDir);
+    return fixtures;
+}
+/**
+ * Parses a fixture case and compares to expected JSON when present.
+ *
+ * @param fixture - Fixture metadata.
+ */
+function runFixtureCase(fixture, expectFn) {
+    const grammarSource = (0, node_fs_1.readFileSync)(fixture.grammarPath, 'utf8');
+    const input = (0, node_fs_1.readFileSync)(fixture.inputPath, 'utf8').trimEnd();
+    const context = parse_context_js_1.ParseContext.fromGrammar(grammarSource, 'lr1');
+    const ast = context.parseSource(input);
+    if (fixture.expectedPath !== null) {
+        const expected = JSON.parse((0, node_fs_1.readFileSync)(fixture.expectedPath, 'utf8'));
+        expectFn(ast).toEqual(expected);
+    }
+    return ast;
+}
+//# sourceMappingURL=grammar-fixture.js.map

package/dist/lib-cjs/transform/grammar-fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar-fixture.js","sourceRoot":"","sources":["../../../src/lib/transform/grammar-fixture.ts"],"names":[],"mappings":"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"}

package/dist/lib-cjs/transform/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformCst = exports.describeProductionSlots = exports.CstTransformer = exports.referenceSlotIndex = exports.productionSlots = exports.parseRhsSymbolKey = void 0;
+var binding_map_js_1 = require("./binding-map.js");
+Object.defineProperty(exports, "parseRhsSymbolKey", { enumerable: true, get: function () { return binding_map_js_1.parseRhsSymbolKey; } });
+Object.defineProperty(exports, "productionSlots", { enumerable: true, get: function () { return binding_map_js_1.productionSlots; } });
+Object.defineProperty(exports, "referenceSlotIndex", { enumerable: true, get: function () { return binding_map_js_1.referenceSlotIndex; } });
+var cst_transformer_js_1 = require("./cst-transformer.js");
+Object.defineProperty(exports, "CstTransformer", { enumerable: true, get: function () { return cst_transformer_js_1.CstTransformer; } });
+Object.defineProperty(exports, "describeProductionSlots", { enumerable: true, get: function () { return cst_transformer_js_1.describeProductionSlots; } });
+Object.defineProperty(exports, "transformCst", { enumerable: true, get: function () { return cst_transformer_js_1.transformCst; } });
+//# sourceMappingURL=index.js.map

package/dist/lib-cjs/transform/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/transform/index.ts"],"names":[],"mappings":";;;AAAA,mDAA0F;AAAjF,mHAAA,iBAAiB,OAAA;AAAE,iHAAA,eAAe,OAAA;AAAE,oHAAA,kBAAkB,OAAA;AAE/D,2DAA6F;AAApF,oHAAA,cAAc,OAAA;AAAE,6HAAA,uBAAuB,OAAA;AAAE,kHAAA,YAAY,OAAA"}

package/docs/grammar.md

@@ -155,6 +155,85 @@ transform
       ;
 ```
 
+### Choosing `pass`, `build`, and `flatten`
+
+| Transform | Use when |
+|-----------|----------|
+| `pass(slot)` | Lift one bound child unchanged. `pass(boundSlot)` preserves the bound production symbol and its `#` variant. `pass(terminalName)` at the same rule may collapse to that terminal. |
+| `build(type.#variant, …)` | Construct an AST node with a fixed shape. Omit absent optional bindings from the argument list. |
+| `flatten(type.#variant, head, tail)` | Turn a `{ repeat }` list into one AST node with ordered children. Use the repeat non-terminal (for example `list$repeat_0`) as `tail` on the head production. |
+
+**Production symbols are preserved.** When a CST node has parse-table metadata, transforms keep its production name even if it has only one terminal child. Bare `CLS` through `pass(stmt)` where `[stmt]:cls_stmt` yields an `cls_stmt` node, not `kw_cls`.
+
+Run `parser-lr table validate -g mylang.grammar` to check `ast` / `transform` consistency. The validator warns when `pass(boundSlot)` targets a production that can match a single terminal and has no transform rule.
+
+## Statement authoring
+
+Statements follow the same `grammar` / `ast` / `transform` pattern as expressions. Dispatch on stable `*_stmt` production names instead of keyword tokens.
+
+```ebnf
+grammar
+    statement =
+        #cls pass(stmt)
+      | #print pass(stmt)
+      | #end pass(stmt)
+      ;
+
+    cls_stmt =
+        #bare kw_cls
+      | #with kw_cls kw_with [bg]:expr
+      ;
+
+    print_stmt =
+        #bare kw_print
+      | #items kw_print [list]:print_list
+      ;
+
+    end_stmt =
+        #program kw_end
+      | #if kw_end kw_if
+      ;
+
+ast
+    cls_stmt =
+        #bare kw_cls
+      | #with kw_cls kw_with [bg]:expr
+      ;
+
+    print_stmt =
+        #bare kw_print
+      | #items kw_print [list]:print_list
+      ;
+
+    end_stmt =
+        #program kw_end
+      | #if kw_end kw_if
+      ;
+
+transform
+    statement ->
+        #cls pass(stmt)
+      | #print pass(stmt)
+      | #end pass(stmt)
+      ;
+
+    cls_stmt ->
+        #bare cls_stmt.#bare(kw_cls)
+      | #with cls_stmt.#with(kw_cls, kw_with, bg) ;
+
+    print_stmt ->
+        #bare print_stmt.#bare(kw_print)
+      | #items print_stmt.#items(kw_print, list) ;
+
+    end_stmt ->
+        #program end_stmt.#program(kw_end)
+      | #if end_stmt.#if(kw_end, kw_if) ;
+```
+
+After `pass(stmt)`, consumers see `cls_stmt`, `print_stmt`, or `end_stmt` at the statement root. Add `ast` + `transform` rules per statement production rather than scanning for keyword terminals in bridge code.
+
+See [`docs/parser-lr-enhancement-proposals.md`](parser-lr-enhancement-proposals.md) for the EduBASIC migration that motivated these conventions.
+
 ## Complete example
 
 See [`grammars/calc.grammar`](../grammars/calc.grammar) for a small working grammar with `grammar`, `ast`, and `transform` sections. [`grammars/lisp.grammar`](../grammars/lisp.grammar) and [`grammars/6502.grammar`](../grammars/6502.grammar) show larger languages.
@@ -163,6 +242,7 @@ See [`grammars/calc.grammar`](../grammars/calc.grammar) for a small working gram
 
 ```bash
 parser-lr table generate -g mylang.grammar -o mylang.json
+parser-lr table validate -g mylang.grammar
 parser-lr parse -i source.txt -g mylang.grammar
 parser-lr parse -i source.txt -t mylang.json
 ```