yangjunhan / antlr4-autosuggest-js

JavaScript auto-suggest engine for ANTLR4 grammars

JavaScript autosuggest engine for ANTLR4 grammars

Oran Epelbaum

Getting the antlr-autosuggest JavaScript Module

npm install --save antlr4-autosuggest

Example

// Load the lexer and parser modules generated by antlr4
const lexerModule = require('./myGrammarLexer');
const parserModule = require('./myGrammarParser');

// Create an autosuggester, providing it with the lexer and parser classes
const autosuggest = require('antlr4-autosuggest');
const autosuggester = autosuggest.autosuggester(lexerModule.myGrammarLexer, parserModule.myGrammarParser);

// Suggest completions for the string "ABC"
let suggestions = autosuggester.autosuggest("ABC");

Advanced Features

Case Preference

Sometimes grammars support both uppercase and lowercase tokens, but completions are expected in just uppercase or lowercase. Specify an UPPER or LOWER case preference to limit suggestions to just uppercase or lowercase:

const autosuggester = autosuggest.autosuggester(lexerModule.myGrammarLexer, parserModule.myGrammarParser, 'LOWER');

How It Works

See explanation in the Java project.

Building & Contributing

To get started:

• Clone the antlr-autosuggest-js repository.
• Install Node and NPM (tested with 8)
• Run the command npm test.

Code contributions are most welcome, but need to maintain a high bar of code cleanliness and test coverage. At a minimum, before submitting a pull request, please run npm test and npm run-script lint to verify that your changes didn't break anything.

It's very important for grammar-related features and fixes to be covered by focused, narrow unit tests. Each unit test must include a short grammar, an even shorter input text, and an expected list of auto-complete suggestions. Unfortunately it's not really possible to write such tests directly in JavaScript, because antlr4's JavaScript engine requires test grammars to have their code generated in advance (i.e., it doesn't provide a runtime grammar interpreter).

To overcome this limitation and write good tests, we actually start out by coding and testing on the Java project first. In Java, antlr4 does offer an interpreter, and therefore unit tests are pretty neat! Once the code and tests are ready in Java, we port the tests automatically to JavaScript with code generation, using the make_js.py utility. The resulting JavaScript tests also looks quite neat despite being completely auto-generated. In the spirit of TDD, once we have failing tests in JavaScript, we manually port the code changes that fix them from Java.

Credits

Written by Oran Epelbaum at Intigua. When starting to write this, studied the following blog posts (though much has changed since):

• RAPID7: How to Implement ANTLR4 Autocomplete
• TOMASETTI: Building autocompletion for an editor based on ANTLR by Federico Tomassetti