Details of ANTLR-Mode

1. Menus and Key-Bindings
2. Syntax Highlighting & Indentation
3. Makefile Rule Creation
4. Insertion of Options

Menus and Key-Bindings

This package defines the following menu entries and key-bindings

• There is a new menu Index containing the grammar classes and the rules and tokens which are defined in the current buffer. This feature is based on imenu, invoking the speedbar via M-x speedbar will also show the items.
• There is a new major-mode menu Antlr containing various commands whose keybindings are described in the next items.
• Enter C-c C-o to insert or change file, grammar, rule or subrule options. See below for details.
• Enter C-M-a or C-M-e to move point the previous or next rule. Enter C-c C-a or C-c C-e to move point the beginning or end of the rule body.
• Enter C-c C-v to make all actions and arguments invisible. Enter C-u 0 C-c C-v to make them visible again. See also the documentation of variable antlr-action-visibility.
• Enter C-c C-r to run ANTLR from within Emacs.

Syntax Highlighting & Indentation

Syntax highlighting & indentation can be best demonstrated by a small example. It shows how the first 35 lines from examples/java/exprAST/expr.g in the distribution of ANTLR-2.7.1 would look like after you have used the automatic indentation (see item Indent Region in the major mode menu Antlr). Of course, I assume that you have turned on font-lock-mode.

{
import java.io.*;
}

class ExprParser extends Parser;

options {
    codeGenMakeSwitchThreshold = 3;
    codeGenBitsetTestThreshold = 4;
    buildAST=true;
    ASTLabelType = "antlr.CommonAST"; // change default of "AST"
}

expr : assignExpr EOF! ;

assignExpr
    :   addExpr
        (
            ASSIGN^
            assignExpr 
        )?
    ;

addExpr
    :   multExpr 
        (
            pm:PLUS_MINUS^
            me:multExpr
            exception catch [ RecognitionException ex ] 
            { 
                System.out.println("Caught error in addExpr");
                reportError(ex.toString()); 
            }
        )*
    ;

Syntax highlighting emphasizes comments, ANTLR's keywords, syntactic symbols, rule and token definitions and references, characters and strings. The highlighting of the code in actions depends on ANTLR's language option: we use the usual syntax highlighting rules for that language.

The indentation is based on ANTLR's (intended) indentation style: we calculate the paren/brace/bracket depth-level and determine the position inside the rule (header, body, exception part). For the indentation of code in actions we use the indentation engine of package cc-mode.

Technical detail: documentation of variable antlr-font-lock-maximum-decoration, function antlr-indent-line and variable antlr-indent-style.

Makefile Rule Creation

The creation of Makefile rules can also best be shown by an example. It shows the Makefile rules ANTLR-Mode creates for the grammar files in directory examples/cpp/tinyc/ after you have copied file examples/cpp/inherit.tinyc/subc.g into that directory (to demonstrate grammar inheritance).

GENS1 = \
	TinyCLexer.cpp TinyCLexer.hpp \
	TinyCTokenTypes.txt TinyCTokenTypes.hpp
$(GENS1): lexer.g
	$(ANTLR) $<

GENS2 = expandedsubc.g \
	MyCParser.cpp MyCParser.hpp \
	MyCParserTokenTypes.txt MyCParserTokenTypes.hpp
$(GENS2): subc.g tinyc.g TinyCParserTokenTypes.txt
	$(ANTLR) -glib tinyc.g $<

GENS3 = \
	TinyCParser.cpp TinyCParser.hpp \
	TinyCParserTokenTypes.txt TinyCParserTokenTypes.hpp
$(GENS3): tinyc.g TinyCTokenTypes.txt
	$(ANTLR) $<

GENS = $(GENS1) $(GENS2) $(GENS3)

Technical detail: documentation of command antlr-show-makefile-rules.

Insertion of Options

Can can use submenus of the major mode menu Antlr or the key sequence C-c C-o to insert or change file, grammar, rule or subrule options.

• A menu item is not selectable in the following cases: the buffer is read-only, point is outside a rule for a rule option, point is outside a subrule for a subrule option, no class definition exists for a class option.
• You must confirm the insertion if you use a version of ANTLR which does not support the option you have selected or if you use a C++ specific option, but the file option language does not have the value Cpp.
• You do not have to put point at position where it is possible to insert an option, ANTLR-Mode does that for you. Of course, it respects your point position if it is in the valid range.
• In the minibuffer, you are asked to insert a value (or to change the existing value) for that option. If possible, you get completion over valid values. For some options, point is simply placed at the position where you should insert the value.
• The option with its value is inserted, or the existing option value changed, respectively. If necessary, the sorrounding options {...} and the final : is also inserted.

Technical detail: documentation of command antlr-insert-option.