parser-lr 0.2.0 → 0.2.1

package/README.md

@@ -1,49 +1,113 @@
 # parser-lr
 
-Shift-reduce parser library for EBNF grammars. Build an LR parse table from a grammar, then parse source into an AST.
+Shift-reduce parser for EBNF grammars. Write a `.grammar` file, build an LR parse table, then lex and parse source into a concrete syntax tree or AST.
 
-## Layout
+Grammar file syntax is documented in [`docs/grammar.md`](docs/grammar.md).
 
-| Path | Role |
-|------|------|
-| `grammars/` | EBNF grammar specs (`grammar.grammar` meta-grammar, plus sample grammars) |
-| `src/lib/` | Library API (Node and browser) — see [`src/lib/README.md`](src/lib/README.md) |
-| `src/cli/` | Node CLI — see [`src/cli/README.md`](src/cli/README.md) |
+## Install
 
-## Library API
+From npm:
 
-| Type | Purpose |
-|------|---------|
-| `Grammar` | Parsed `.grammar` file (lexer, parse productions, optional `AstSchema`) |
-| `AstSchema` | AST types from the `ast` section |
-| `TransformSchema` | CST-to-AST rules from the `transform` section |
-| `AstNode` | Parse tree node (interior symbols and terminal leaves) |
-| `Token` | Lexeme from tokenization (name, text, source span) |
-| `ParseTable` | Serializable LR table metadata with token inventory |
-| `ParserLr` | Shift-reduce parser (table build and parse) |
+```bash
+npm install parser-lr
+```
 
-## Build and test
+From a clone of this repository:
 
 ```bash
-npm run build    # tsc → dist/lib/, Rollup → bin/parser-lr.js
-npm test
+npm install
+npm run build
 ```
 
-## Bootstrap
+## CLI
 
-Grammar files are lexed and parsed with a bootstrapped meta-grammar table checked in at `src/lib/grammar/grammar.json`. Regenerate it after changing `grammars/grammar.grammar`:
+The `parser-lr` command is published as the package `bin` entry. After a local build, link it globally:
 
 ```bash
-npm run bootstrap
+npm link
 ```
 
-The meta-grammar LR parser builds the `Grammar` model used to bootstrap table generation.
+You can then run `parser-lr` from any directory. Without linking, use `npx parser-lr` (published install) or `node node_modules/parser-lr/bin/parser-lr.js`.
 
-## CLI
+### Build a parse table
+
+Generate a serialized LR table from a grammar file:
 
 ```bash
-parser-lr table generate -g grammars/lisp.grammar -o table.json
-parser-lr parse -i source.txt -g grammars/lisp.grammar
+parser-lr table generate -g mylang.grammar -o mylang.table.json
 ```
 
-The `parse` command outputs a concrete syntax tree as JSON (`{ "ast": … }`).
+Options:
+
+| Option | Description |
+|--------|-------------|
+| `-g, --grammar <path>` | `.grammar` file (required) |
+| `-o, --output <path>` | Output path (default: stdout) |
+| `-a, --algorithm <name>` | `lr0`, `slr`, `lalr`, or `lr1` (default: `lr1`) |
+
+The JSON table includes lexer token rules, skip rules, and the full ACTION/GOTO table. You can ship this file without the original grammar.
+
+### Parse a source file
+
+Parse input using either the grammar (table built in memory) or a saved table:
+
+```bash
+parser-lr parse -i program.txt -g mylang.grammar
+parser-lr parse -i program.txt -t mylang.table.json
+```
+
+Options:
+
+| Option | Description |
+|--------|-------------|
+| `-i, --input <path>` | Source file to parse (required) |
+| `-g, --grammar <path>` | `.grammar` file (one of grammar or table) |
+| `-t, --table <path>` | Serialized table JSON from `table generate` |
+| `-o, --output <path>` | Output path (default: stdout) |
+| `--format <name>` | Output format (default: `json`) |
+
+Output is a JSON object `{ "ast": … }`. On a syntax error, `ast` is `null`.
+
+When the grammar defines `ast` and `transform` sections, the CLI applies CST-to-AST transforms and returns the abstract tree.
+
+## Library
+
+Import from `parser-lr` in Node or bundler projects (ESM). The API is browser-safe; the CLI is Node-only.
+
+```typescript
+import { readFile } from 'node:fs/promises';
+import { ParseContext } from 'parser-lr';
+
+const grammarSource = await readFile('mylang.grammar', 'utf8');
+const context = ParseContext.fromGrammar(grammarSource, 'lr1');
+
+const source = await readFile('program.txt', 'utf8');
+const ast = context.parseSource(source);
+```
+
+Load a pre-built table instead of a grammar file:
+
+```typescript
+import { readFile } from 'node:fs/promises';
+import { ParseContext } from 'parser-lr';
+
+const tableJson = await readFile('mylang.table.json', 'utf8');
+const context = ParseContext.fromTableJson(tableJson);
+
+const source = await readFile('program.txt', 'utf8');
+const ast = context.parse(context.lex(source));
+```
+
+`ParseContext` exposes `lex`, `parse`, and `createLexer` for finer control. See [`src/lib/README.md`](src/lib/README.md) for the main types.
+
+## Example grammars
+
+Sample `.grammar` files ship in [`grammars/`](grammars/) (`calc.grammar`, `lisp.grammar`, `6502.grammar`, and the meta-grammar `grammar.grammar`). Use them as templates when writing your own language.
+
+## Developing this package
+
+Contributors who change the meta-grammar should regenerate the bootstrapped table:
+
+```bash
+npm run bootstrap
+```

package/bin/parser-lr.js

@@ -3781,7 +3781,7 @@ const {
   Help,
 } = commander;
 
-var version$1 = "0.2.0";
+var version$1 = "0.2.1";
 var packageDefinition = {
 	version: version$1};
 

package/docs/grammar.md

@@ -0,0 +1,170 @@
+# `.grammar` file syntax
+
+A `.grammar` file describes a language: lexer rules, parser productions, and optional AST shape and transform rules. Files are plain text with `//` line comments.
+
+## Overview
+
+A grammar file contains these sections in order:
+
+1. `name` — grammar name
+2. Zero or more of: `tokens`, `skip`, `states`
+3. `start` — entry non-terminal
+4. `grammar` — parse productions
+5. Optional `ast` — AST type definitions
+6. Optional `transform` — CST-to-AST mapping rules
+
+Whitespace between sections is ignored. Skip rules discard matched text before tokenization.
+
+## `name`
+
+```ebnf
+name "mylang" ;
+name mylang ;
+```
+
+The name is an identifier or double-quoted string.
+
+## `tokens`
+
+Declares lexer tokens as regular expressions:
+
+```ebnf
+tokens
+    identifier = /[A-Za-z_][A-Za-z0-9_]*/ ;
+    number = /[0-9]+/ ;
+    plus = /\+/ ;
+```
+
+Each rule is `name = /pattern/ flags ;`. The pattern is a JavaScript regular expression body between slashes. Optional flag letters (`g`, `i`, `m`, `s`, `u`, `y`) may follow the closing slash.
+
+## `skip`
+
+Declares patterns to discard (whitespace, comments):
+
+```ebnf
+skip
+    whitespace = /[ \t\r\n]+/ ;
+    comment = /\/\/[^\n\r]*/ ;
+```
+
+Syntax matches `tokens`.
+
+## `states`
+
+Optional lexer start states (for multi-mode lexing):
+
+```ebnf
+states default, string ;
+```
+
+## `start`
+
+Names the parser entry non-terminal:
+
+```ebnf
+start program ;
+```
+
+## `grammar`
+
+Parse productions use EBNF expression syntax:
+
+```ebnf
+grammar
+    program = statement { statement } ;
+    statement = identifier equal expression semicolon ;
+```
+
+### Expressions
+
+| Form | Syntax | Meaning |
+|------|--------|---------|
+| Sequence | `a b c` | Match in order |
+| Choice | `a \| b \| c` | Match one alternative |
+| Optional | `[ a ]` | Zero or one |
+| Repeat | `{ a }` | Zero or more |
+| Group | `( a )` | Precedence grouping |
+| Terminal | `"while"` | Literal string in the input |
+| Reference | `identifier` | Non-terminal or token name |
+| Label | `#name` | Names an alternative for transforms |
+| Binding | `[slot]:symbol` | Names a child slot for AST transforms |
+
+Example with labels and bindings:
+
+```ebnf
+expr =
+    #add expr plus term
+  | #term term
+  ;
+```
+
+### Production syntax
+
+Each production ends with a semicolon:
+
+```ebnf
+identifier = expression ;
+```
+
+## `ast`
+
+Optional section declaring AST node shapes. Uses the same expression syntax as `grammar`, with `#` variants and `[slot]:` bindings naming child fields:
+
+```ebnf
+ast
+    expr =
+        #binary [left]:expr [operator]:operator [right]:expr
+      | #literal number
+      ;
+```
+
+When present, transform rules map parse trees to these types.
+
+## `transform`
+
+Maps labeled parse alternatives to AST construction. One rule per parse production:
+
+```ebnf
+transform
+    expr ->
+        #add fold-left(expr.#binary, left, operator, right)
+      | #term pass(term)
+      ;
+```
+
+### Transform expressions
+
+| Form | Syntax |
+|------|--------|
+| Drop | `drop` |
+| Pass | `pass(reference)` |
+| Build | `type.#variant` or `type.#variant(arg, …)` |
+| Fold left | `fold-left(type.#variant, ref, …)` |
+| Fold right | `fold-right(type.#variant, ref, …)` |
+| Flatten | `flatten(type.#variant, head, tail)` |
+
+`type.#variant` refers to an AST type and variant from the `ast` section. Arguments are binding names from the parse production.
+
+Example (calculator):
+
+```ebnf
+transform
+    expr ->
+        #binary expr.#binary(left, operator, right)
+      | #literal expr.#literal(number)
+      ;
+```
+
+## 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.
+
+## Building and using a grammar
+
+```bash
+parser-lr table generate -g mylang.grammar -o mylang.table.json
+parser-lr parse -i source.txt -g mylang.grammar
+parser-lr parse -i source.txt -t mylang.table.json
+```
+
+See the [project README](../README.md) for install and library usage.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "parser-lr",
     "author": "Adam R Moss <adamrmoss@gmail.com>",
-    "version": "0.2.0",
+    "version": "0.2.1",
     "description": "Shift-reduce parser library for EBNF grammars",
     "license": "MIT",
     "type": "module",
@@ -22,7 +22,8 @@
     },
     "files": [
         "bin",
-        "dist"
+        "dist",
+        "docs"
     ],
     "publishConfig": {
         "access": "public",