- XPath implementation.
- Vocabulary implementation.
- Complete Interval implementation.
- Parser and lexer interpreters.
- Numerous bug fixes and other changes.
- Smaller node package (no test specs or other unnecessary files).
- No CommonJS support anymore (ESM only). No differentiation between node and browser environments.
- Includes the
antlr4ng-clitool to generate parser files compatible with this runtime. This tool uses a custom build of the ANTLR4 tool.
This package is a blend of the original JS implementation and antlr4ts, which is a TypeScript implementation of the ANTLR4 runtime, but was abandoned. It tries to keep the best of both worlds, while following the Java runtime as close as possible. It's a bit slower than the JS runtime, but faster than antlr4ts.
To install the package, run the following command:
npm install antlr4ng
This package has a peer dependency to
antlr4ng-cli, which is the tool to generate parser files compatible with this runtime, so it is strongly recommended to install this one too:
npm install --save-dev antlr4ng-cli
See its readme for more information.
If you come from one of the other JS/TS runtimes, you may have to adjust your code a bit. The antlr4ng package more strictly exposes the Java nullability for certain members. This will require that you either use the non-null assertion operator to force the compiler to accept your code, or you have to check for null values before accessing a member. The latter is the recommended way, as it is safer.
Additionally, some members have been renamed to more TypeScript like names. The following table shows the most important changes:
|Old Name||New Name|
The package requires ES2022 or newer, for features like static initialization blocks in classes and private fields (
#field). It is recommended to use the latest TypeScript version.
This runtime is monitored for performance regressions. The following table shows the results of the benchmarks run on last release:
|Test||Cold Run||Warm Run|
|Query Collection||8464 ms||230 ms|
|Example File||1043 ms||112 ms|
|Large Inserts||11022 ms||10616 ms|
|Total||20599 ms||10978 ms|
Last release (pure TypeScript):
|Test||Cold Run||Warm Run|
|Query Collection||5930 ms||338 ms|
|Example File||1074 ms||194 ms|
|Large Inserts||14226 ms||14248 ms|
|Total||21290 ms||14800 ms|
The numbers are interesting. While the cold run for the query collection is almost 3 seconds faster with pure TS, the overall numbers in warm state are worse. So it's not a pure JS vs. TS situation, but something else must have additional influence and this will be investigated. After all the TypeScript code is ultimately transpiled to JS, so it's probably a matter of how effective the TS code is translated to JS.
Overall the numbers in the pure TS runtime are pretty good, especially when comparing them with antlr4ts.
The benchmarks consist of a set of query files, which are parsed by a MySQL parser. The MySQL grammar is one of the largest and most complex grammars you can find for ANTLR4, which, I think, makes it a perfect test case for parser tests.
The query collection file contains more than 900 MySQL queries of all kinds, from very simple comments-only statements to complex stored procedures, including some deeply nested select queries that can easily exhaust the available stack space (in certain situations, such as parsing in a thread with default stack size). The minimum MySQL server version used was 8.0.0.
The large binary inserts file contains only a few dozen queries, but they are really large with deep recursions, so they stress the prediction engine of the parser. In addition, one query contains binary (image) data containing input characters from the entire UTF-8 range.
The example file is a copy of the largest test file in this repository, and is known to be very slow to parse with other MySQL grammars. The one used here, however, is fast.
- There are changes in the package content (typings are now in the dist folder too, instead of source).
- There are now index.ts files in every folder and used for the final export index.ts. This makes it easier to see if something is missing and to include new or renamed files.
- And there are some build changes/fixes as preparation for profiling the runtime.
The entire runtime now exclusively uses TypeScript. It was tested with the standard ANTLR4 runtime tests and completed the test suite successfully.
These releases contain mostly internal changes and bug fixes. The antlr4ng-cli tool dependency has been updated to the latest version and build + test processes has been improved (esbuild instead of webpack, Jest instead of Jasmine).
There are also some smaller fixes in
ParseTreeVisitor. The latter now has the same implementation as the Java runtime.
- Fixed Bug #8 Wrong property name, using
Bug fix releases. They contain many bugs found while integrating the runtime into a large project.
This release includes a lot of cleanup.
- Generated parser rules that can appear as either returning a single parse context or a list of that no longer use the
__list()appendix in their name. Instead method overloading is used now to distinguish between the two cases.
- The members
getTypedRuleContextshave been renamed to
getRuleContextsrespectively, just as in the Java runtime.
- There are more renames (
->inputStream` and more).
- The package has been stripped down to just a single bundle file. This is an ESM module now, so it can be used in both, node and browser environments. No differentiation is made anymore between the two.
- The internal folder structure has been changed to match the Java runtime.
- Extended some classes, added new type definitions and exported some more classes.
BitSetto use less memory.
- Fixed recognizer token type and rule index maps.
- Added new peer dependency
antlr4ng-cli, which is the tool to generate parser files compatible with this runtime.
- Added benchmarks.
- Introduced the
IntStreaminterface as the base for
TokenStream. This avoids duplicate code in the stream type definitions.
FileStreamas a preparation to get rid of the separate package files for node and browser. If something needs to be loaded from a file, the particular environment should provide the code for that.
- Github build action
- Updated package.json
- Some smaller fixes
- Added and/or replaced all copyrights to a common ANTLR version.
- Removed all individual default exports. Only the final lib exports contain both, default and non-default exports. This avoids namespace access like
antlr4.atn. Everything is available under a top level import.
- Renamed ErrorListener to BaseErrorListener, as that is what it is actually when comparing it to the Java runtime.
- Initial release.