Added sub project for parser generation

- The repo includes now a sub project which can be installed as npm package for generation of ANTLR4 parsers that are compatible with this runtime.
- Removed the generated files for the benchmarks. Instead the benchmark NPM script generates the files on-the-fly using the new sub project (eat your own dog food).

.eslintrc.json

@@ -15,6 +15,7 @@
         "src/**/*.js",
         "spec/**/*.*js",
         "dist/**/*",
+        "cli/index.js",
         "**/generated/*",
         "jest.config.ts"
     ],

.npmignore

@@ -1,13 +1,15 @@
 @@ -0,0 +1,10 @@
-spec
-webpack.config.js
-tsconfig.json
+.github
+.vscode
+cli/
+spec/
 src/**/*.js
 
-.vscode
 .babelrc
 .c8rc.json
 .eslintignore
 .eslintrc.json
 .project
+tsconfig.json
+webpack.config.js
 cspell.json

ReadMe.md

@@ -23,15 +23,21 @@ This runtime is constantly monitored for performance regressions. The following
 
 | Test | Cold Run | Warm Run|
 | ---- | -------- | ------- |
-| Query Collection| 8719 ms | 239 ms |
-| Example File | 1031 ms | 119 ms |
-| Large Inserts | 10748 ms | 10745 ms |
-| Total | 20568 ms | 11122 ms |
+| Query Collection| 8658 ms | 236 ms |
+| Example File | 1024 ms | 117 ms |
+| Large Inserts | 10612 ms | 10631 ms |
+| Total | 20354 ms | 11005 ms |
 
 The benchmarks consist of a set of query files, which are parsed by a MySQL parser.
 
 ## Release Notes
 
+### 1.0.6 - 1.0.7
+
+- Fixed recognizer token type and rule index maps.
+- Fixed `getTokens()` in `BufferedTokenStream`.
+- Added new peer dependency `antlr4ng-cli`, which is the tool to generate parser files compatible with this runtime.
+
 ### 1.0.5
 
 - Added benchmarks.

cli/LICENSE.txt

@@ -0,0 +1,29 @@
+[The "BSD license"]
+Copyright (c) 2012-2023 The ANTLR Project. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+3. Neither name of copyright holders nor the names of its contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cli/ReadMe.md

@@ -0,0 +1,31 @@
+# TypeScript Code Generator for ANTLR 4
+
+This package is a wrapper for the ANTLR 4 code generator (the [ANTLR4 tool](https://www.antlr.org/download.html)) version 4.13.2 (dev build). With it you can generate TypeScript parser and lexer files from a grammar file. It uses a custom build of the ANTLR4 jar, to generate code that is compatible with the [antlr4ng TypeScript runtime](https://www.npmjs.com/package/antlr4ng).
+
+## Installation
+
+To install the package, run the following command:
+
+```bash
+npm install --save-dev antlr4ng-cli
+```
+
+**Note: currently you need to have Java installed on your system, as the ANTLR4 jar is a Java application.**
+
+## Usage
+
+In your `package.json` file, add a script to generate the parser and lexer files:
+
+```json
+{
+  "scripts": {
+    "generate": "antlr4ng -o src/generated src/MyGrammar.g4"
+  }
+}
+```
+
+Then run the script:
+
+```bash
+npm run generate
+```

cli/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+/*
+ * Copyright (c) The ANTLR Project. All rights reserved.
+ * Use of this file is governed by the BSD 3-clause license that
+ * can be found in the LICENSE.txt file in the project root.
+ */
+
+const child_process = require('child_process');
+const path = require('path');
+const process = require('process');
+
+const value = ['-jar', path.join(__dirname, 'antlr4-4.13.2-SNAPSHOT-complete.jar')]
+    .concat(process.argv.slice(2));
+const child = child_process.spawn("java", value, { stdio: "inherit" });
+
+child.on('close', function (code) {
+    process.exitCode = code;
+    code && console.log("child process exited with code ", code);
+});

cli/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "antlr4ng-cli",
+    "version": "1.0.0",
+    "preferGlobal": true,
+    "description": "ANTLR 4 NG command line tool for TypeScript",
+    "author": "Mike Lischke",
+    "files": [
+        "License.txt",
+        "antlr4-4.13.2-SNAPSHOT-complete.jar",
+        "index.js"
+    ],
+    "bin": {
+        "antlr4ng": "./index.js"
+    },
+    "scripts": {},
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/mike-lischke/antlr4ng.git"
+    },
+    "keywords": [
+        "ANTLR4",
+        "TypeScript"
+    ],
+    "license": "BSD-3-Clause",
+    "bugs": {
+        "url": "https://github.com/mike-lischke/antlr4ng/issues"
+    },
+    "homepage": "https://github.com/mike-lischke/antlr4ng"
+}

cspell.json

@@ -15,7 +15,9 @@
     ],
     "ignoreWords": [
         "AMBIG",
+        "Dlanguage",
         "Harwell",
+        "Xexact",
         "bitrix",
         "interp",
         "localctx",

package.json

@@ -1,6 +1,6 @@
 {
     "name": "antlr4ng",
-    "version": "1.0.6",
+    "version": "1.0.7",
     "type": "module",
     "description": "Alternative JavaScript/TypeScript runtime for ANTLR4",
     "browser": "dist/antlr4.web.mjs",
@@ -19,6 +19,9 @@
         "url": "https://github.com/mike-lischke/antlr4ng/issues"
     },
     "homepage": "https://github.com/mike-lischke/antlr4ng",
+    "peerDependencies": {
+        "antlr4ng-cli": "1.0.0"
+    },
     "devDependencies": {
         "@babel/core": "7.22.15",
         "@babel/eslint-parser": "7.22.15",
@@ -50,8 +53,8 @@
         "test": "jasmine",
         "coverage": "c8 jasmine",
         "lint": "eslint src/antlr4/",
-        "generate-test-parser": "java -jar antlr/antlr4-4.13.2-SNAPSHOT-complete.jar -Dlanguage=TypeScript -o spec/benchmarks/generated -visitor -listener -Xexact-output-dir spec/benchmarks/MySQLLexer.g4 spec/benchmarks/MySQLParser.g4",
-        "benchmarks": "npm run build && node --no-warnings=ExperimentalWarning --loader ts-node/esm spec/benchmarks/run-benchmarks.ts"
+        "generate-test-parser": "cli/index.js -Dlanguage=TypeScript -o spec/benchmarks/generated -visitor -listener -Xexact-output-dir spec/benchmarks/MySQLLexer.g4 spec/benchmarks/MySQLParser.g4",
+        "benchmarks": "npm run build && npm run generate-test-parser && node --no-warnings=ExperimentalWarning --loader ts-node/esm spec/benchmarks/run-benchmarks.ts"
     },
     "engines": {
         "node": ">=16"