parser-lr 0.0.0 → 0.2.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.0.0",
+    "version": "0.2.1",
     "description": "Shift-reduce parser library for EBNF grammars",
     "license": "MIT",
     "type": "module",
@@ -22,28 +22,36 @@
     },
     "files": [
         "bin",
-        "dist"
+        "dist",
+        "docs"
     ],
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"
     },
     "scripts": {
+        "publish": "npm run build && npm publish",
+        "bootstrap": "npm link && parser-lr table generate -g grammars/grammar.grammar -o src/lib/grammar/grammar.json",
         "build": "npm run build:clean && npm run build:lib && npm run build:cli",
         "build:clean": "rm -rf dist && rm -f bin/parser-lr.js bin/parser-lr.js.map",
-        "build:lib": "tsc -p tsconfig.lib.json",
-        "build:cli": "rollup -c rollup.cli.config.js",
+        "build:lib": "tsc -p tsconfig.lib.json && cp src/lib/grammar/grammar.json dist/lib/grammar/",
+        "build:cli": "rollup -c rollup.cli.config.js && chmod +x bin/parser-lr.js",
+        "test": "jest",
         "prepack": "npm run build"
     },
     "dependencies": {},
     "devDependencies": {
+        "@jest/globals": "29.x",
         "@rollup/plugin-commonjs": "28.x",
         "@rollup/plugin-json": "6.x",
         "@rollup/plugin-node-resolve": "16.x",
         "@rollup/plugin-typescript": "12.x",
+        "@types/jest": "29.x",
         "@types/node": "22.x",
         "commander": "12.x",
+        "jest": "29.x",
         "rollup": "4.x",
+        "ts-jest": "29.x",
         "tslib": "2.x",
         "typescript": "5.x"
     }