• Stars
    star
    467
  • Rank 93,935 (Top 2 %)
  • Language
    Java
  • License
    BSD 3-Clause "New...
  • Created about 11 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

An IntelliJ plugin for ANTLR v4

IntelliJ Idea Plugin for ANTLR v4 Java CI Latest version Downloads

An IntelliJ 2020.3+ plugin for ANTLR v4 (plugin source at github). (Technically, the plugin will load in 2019.2+ but you might not have much luck earlier than 2020.3)

Plugin page at intellij

This plugin is for ANTLR v4 grammars and includes ANTLR 4.13.0. Works with IntelliJ IDEA and other IntelliJ-based IDEs.

Features:

  • syntax highlighting
  • syntax error checking
  • semantic error checking
  • navigation window
  • goto-declaration
  • find usages
  • rename tokens
  • rename rules
  • save parse trees as svg/jpg/png; right click in parse tree view (1.9)
  • comment grammar rule lines with meta-/ (1.7)
  • generates Java code; shortcut (ctrl-shift-G / meta-shift-G) but it's in Tools menu and popups.
  • code completion for tokens, rule names;
  • finds tokenVocab option for code gen if there is a tokenVocab option, don't warn about implicit tokens.
  • handles separate parsers and lexers like TParser.g4 and TLexer.g4 (1.7)
  • Parse tree nodes show the alternative number the parser chose to match that node. (1.7)
  • has live grammar interpreter for grammar preview. Right click on rule and say "Test ANTLR Rule".
  • can view parse trees for input matched in more than one way (ambiguities) (1.7)
  • can view lookahead trees to show how input directed ANTLR to match a particular alternative (1.7)
  • changes to grammar seen in parse tree upon save of grammar.
  • refactoring: extra rule, inline rule

You can configure the ANTLR tool options per grammar file; right-click in a grammar or on a grammar element within the structured view. When you change and save a grammar, it automatically builds with ANTLR in the background according to the preferences you have set. ANTLR tool errors appear in a console you can opened by clicking on a button in the bottom tab.

You can use the ctrl-key while moving the mouse and it will show you token information in the preview editor box via tooltips. Meta-key shows parser call stack.

Errors within the preview editor are now highlighted with tooltips and underlining just like a regular editor window. The difference is that this window's grammar is specified in your grammar file.

meta-j pops up a list of live templates, just like it does for Java programming. Currently, there are a number of lexical rules for common tokens such as comments and identifiers that you can automatically inject. There are shortcuts like rid that lets you jump directly to the lexical rule you would like to generate. If you type the shortcut and wait a second, intellij should pop up an action you can select for that shortcut.

ctrl-return, or whatever you have configured for the generate pop-up, will bring up a list of things you can generate. The only one so far is a generator to create lexical rules for any literals, referenced in the parser grammar, that have not been defined.

Limitations

The ANTLR Preview window is based on a grammar interpreter, not on the actual generated parser. This means that things like actions and predicates will not be evaluated during live preview, because the interpreter is language agnostic.

For the same reasons, if your parser and/or lexer classes extend a custom implementation of the base parser/lexer classes, your custom code will not be run during live preview.

History

See Releases

Screenshots

Java grammar view

Java grammar view

Find usages

Find usages

Code completion

Code completion

Live templates

You can inject predefined lexer rules. Use meta-j or type the abbreviation like rid and wait a second. It should pop up that choice.

predefined lexer rules

Refactoring: generate rules for literals

It guesses rule names or just uses T__<n>. Respects literals already defined. Use Code::Generate menu item or key equivalent.

def-literals.png

Live parse tree preview

You can test any rule in the (parser) grammar. Right click on rule in grammar or navigator to "Test ANTLR Rule". Changing grammar and saving, updates parse tree. It works with combined grammars and separated but separated must be in same directory and named XParser.g4 and XLexer.g4. No raw Java actions are executed obviously during interpretation in live preview.

Live parse preview

Live preview Live preview

You can also use the ctrl key while moving the mouse in preview window to get token info.

Live preview

The meta key while moving the mouse shows the parser call stack (path to the root of parse tree).

When there are errors, you will see the output in the small console under the input editor in case you need to cut and paste. But, for general viewing you can however the cursor over an underlined error and it will show you the message in a pop-up. Basically the input window behaves like a regular editor window except that it is subject to the grammar in your other editor.

error-popup.png

With alt-mouse movement, you'll see parse region for rule matching token under cursor. Click and it jumps to grammar definition.

parse-region.png

Grammar Profiler

The profiler helps you understand which decisions in your grammar are complicated or expensive. Profiling data is always available just like the parse tree during grammar interpretation. The profiler cannot track code execution because it is running the grammar interpreter not executing compiled code. It provides both a simplified set of columns and an expert set the provides a great deal more information. Clicking on a row in the profiler highlights the decision in the grammar and also highlights relevant pieces of the input, such as ambiguities or the deepest lookahead. You can sort the columns by clicking on the header row. Hover over the header row to get tooltips describing the column.

If you see ambiguities highlighted, those you should definitely take a look at in your grammar. If you see decisions requiring full context sensitivity, when viewing the expert columns, those are very expensive and could be causing speed problems. Note that the profiler always tries to keep up-to-date with the input. The profiler uses the parser interpreter but is fairly consistent with the speed of a generated and compiled parser but it does use single-stage full LL parsing which can be slower. It needs to do that so that it gets full and complete profiling information. For those in the know, it uses PredictionMode.LL_EXACT_AMBIG_DETECTION. For really big files and slow grammars, there is an appreciable delay when displaying the parse tree or profiling information.

parse-region.png

Grammar ambiguities and lookahead

A grammar that matches an input phrase more than one way is considered ambiguous and it's generally an error because we want to interpret input phrases in just one way. ANTLR resolves ambiguities on-the-fly to create a single interpretation (parse tree) but sometimes, for debugging purposes, you'd like to know how else to grammar can match some input. When you have selected an ambiguity using the profiler described in the previous section, you can right click in the preview input window like so:

ambig-right-click.png

It will pop up a dialog box that looks like this:

ambig1.png

The darkened background node is the node for the rule containing the decision that is ambiguous. The yellow boxes outlining nodes indicates that it differs from the chosen interpretation of the parse tree. Here's another example that shows two interpretations (of User f() {):

ambig2.png

Even when a grammar is getting a single interpretation of the input, we often wonder why it's not choosing the path we expected. When you right click on a lookahead sequence in the input window, it will pop up a dialog to show you how ANTLR tried to use the input to match the alternative. The trees with gray backgrounds indicate the parse trees that were attempted but that failed at some input depth. The tree with a white background chose the chosen parse tree:

lookahead1.png

Unicode chars are no problem

unicode.png

Per file ANTLR configuration

Configuration

ANTLR output console

Output console

Color preferences

Live preview

Contributing

We use Gradle to build. To contribute to the project, you need a recent version of IntelliJ IDEA (either Community or Ultimate) with the Gradle and Plugin DevKit plugins enabled.

Use File > Open and select the build.gradle file to import the project. Once everything is imported, you can run a sandboxed IDE using the runIde task, either from the Gradle tool window of from the CLI:

cd ~/antlr/code/intellij-plugin-v4
./gradlew runIde

To launch unit tests, run ./gradlew check.

To build a zipped version of the plugin and its dependencies, run ./gradlew buildPlugin.

You can tweak the version of the IntelliJ platform used to build/test the plugin in gradle.properties, such as:

ideaVersion=IC-2020.2.2

As of 1.18, java 11 is assumed but you might get away with earlier java.

A high level description of how the plugin works can be found in ARCHITECTURE.md.

Releasing

More Repositories

1

antlr4

ANTLR (ANother Tool for Language Recognition) is a powerful parser generator for reading, processing, executing, or translating structured text or binary files.
Java
17,043
star
2

grammars-v4

Grammars written for ANTLR v4; expectation that the grammars are free of actions.
ANTLR
10,114
star
3

stringtemplate4

StringTemplate 4
Java
943
star
4

codebuff

Language-agnostic pretty-printing through machine learning (uh, like, is this possible? YES, apparently).
Java
440
star
5

antlrcs

The C# port of ANTLR 3, StringTemplate 3, and StringTemplate 4
C#
281
star
6

antlr3

antlr v3 repository (pulled from p4 with history from //depot/code/antlr/antlr3-main
Java
241
star
7

antlr4-intellij-adaptor

A library to support the use of ANTLR grammars in jetbrains IDE plugins for building custom languages.
Java
209
star
8

jetbrains-plugin-sample

A sample plugin for jetbrains IDEs that uses an ANTLR grammar for a nontrivial custom language.
Java
118
star
9

antlrworks

AntlrWorks tool for ANTLR
Java
97
star
10

antlr4-tools

Tools to run antlr4 w/o needing to install java or antlr4!
Python
83
star
11

antlr-php-runtime

PHP Runtime for ANTLR4
PHP
81
star
12

antlr4-cpp

C++ target for ANTLR 4, including templates and runtime
C++
75
star
13

examples-v3

Java
59
star
14

antlr5

Java
52
star
15

symtab

Generic symbol table for lexically/statically scoped languages
Java
48
star
16

Antlr4Formatter

Formatter for ANTLR 4 grammars
ANTLR
40
star
17

antlr4-lab

A client/server for trying out and learning about ANTLR
Java
35
star
18

grammars-v3

Grammars written for ANTLR v3; expectation that the grammars are free of actions but it's not a hard and fast rule. there is no common license!
GAP
24
star
19

jetbrains-plugin-st4

An intellij/jetbrains plugin for StringTemplate .st and .stg files
Java
23
star
20

antlr4test-maven-plugin

A maven plugin used to test the grammars-v4 repo grammars
Java
17
star
21

stringtemplate3

StringTemplate v3
Java
15
star
22

website-antlr3

The ANTLR 3 Website
HTML
13
star
23

website-antlr4

The ANTLR 4 Website
HTML
11
star
24

antlr-php-runtime-phpstan

Static analysis for ANTLR4 PHP Runtime.
PHP
6
star
25

antlr5-specs

Specs for antlr5
4
star
26

grammars-v5

3
star
27

_grammar-test

Historical files from grammars-v4 repo
Java
2
star
28

performance

Test the performance of ANTLR parsers (initially just Java target)
Java
2
star
29

website-antlr2

The ANTLR 2 Website
Java
1
star
30

website-st4

stringtemplate.org content
HTML
1
star
31

antlr5-lab

TypeScript
1
star