Getting started

Getting started

This library was built to make it easier for people to build IntelliJ plugins based on ANTLRv4 grammars. It consists mostly of adaptors to plug ANTLR lexers and parsers to IntelliJ's PSI infrastructure, as well as utility methods.

About grammars

Whether you are using an existing grammar or are writing your own from scratch, there are a few rules that you will need to follow in order to build a reliable plugin.

• Never -> skip tokens. As stated in the Implementing Lexer section of the IntelliJ Platform SDK DevGuide,

Lexers [...] need to be created in such a way that they always match the entire contents of the file, without any gaps between tokens, and generate special tokens for characters which are not valid at their location. Lexers must never abort prematurely because of an invalid character.

Skipping tokens will introduce gaps in your token stream, and IntelliJ will definitely hate that. Symptoms will include erratic syntax highlighting or cryptic error messages like java.lang.IllegalStateException: Gap at offset 82 near segment 39 after modifications in the editor.

Instead of skipping tokens, send them to the HIDDEN channel. This way, they won't be sent to the channel but will still be available in the PSI tree.