Skip to content

pompon0/rules_antlr

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

65 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Build Status Java 8+ License

ANTLR Rules for Bazel

These build rules are used for processing ANTLR grammars with Bazel.

Rules

Different rules are available that align with the ANTLR release streams.

Quick Setup

Add the following to your WORKSPACE file to include the external repository and load the external dependencies necessary for the antlr4 rule:

http_archive(
    name = "rules_antlr",
    sha256 = "acd2a25f31aeeea5f58cdb434ae109d03826ae7cc11fe9efce1740102e3f4531",
    strip_prefix = "rules_antlr-0.1.0",
    urls = ["https://github.com/marcohu/rules_antlr/archive/0.1.0.tar.gz"],
)

load("@rules_antlr//antlr:deps.bzl", "antlr_dependencies")
antlr_dependencies()

More detailed instructions can be found in the Setup section.

Basic Example

Suppose you have the following directory structure for a simple ANTLR project:

[workspace]/
  WORKSPACE
  HelloWorld/
    BUILD
    src/
      main/
        antlr4/
          Hello.g4

HelloWorld/src/main/antlr4/Hello.g4

grammar Hello;
r  : 'hello' ID;
ID : [a-z]+;
WS : [ \t\r\n]+ -> skip;

HelloWorld/BUILD

package(default_visibility = ["//visibility:public"])

load("@rules_antlr//antlr:antlr4.bzl", "antlr4")

antlr4(
    name = "generated",
    srcs = ["src/main/antlr4/Hello.g4"],
    package = "hello.world",
)

java_library(
    name = "HelloWorld",
    srcs = [":generated"],
)

Compiling the project generates the lexer/parser files:

$ bazel build //HelloWorld
INFO: Analysed target //HelloWorld:HelloWorld (0 packages loaded).
INFO: Found 1 target...
Target //HelloWorld:HelloWorld up-to-date:
  bazel-bin/HelloWorld/libHelloWorld.jar
INFO: Elapsed time: 0.940s, Critical Path: 0.76s
INFO: Build completed successfully, 4 total actions

The generated source files can be found in the generated.srcjar archive below your workspace bazel-bin/HelloWorld directory.

To just generate the source files you would use:

$ bazel build //HelloWorld:generated

Refer to the examples directory for further samples.

Project Layout

ANTLR rules will store all generated source files in a target-name.srcjar zip archive below your workspace bazel-bin folder. Depending on the ANTLR version, there are three ways to control namespacing and directory structure for generated code, all with their pros and cons.

  1. The package rule attribute (antlr4 only). Setting the namespace via the package attribute will generate the corresponding target language specific namespacing code (where applicable) and puts the generated source files below a corresponding directory structure. To not create the directory structure, set the layout attribute to flat.
    Very expressive and allows language independent grammars, but only available with ANTLR 4, requires several runs for different namespaces, might complicate refactoring and can conflict with language specific code in @header {...} sections as they are mutually exclusive.

  2. Language specific application code in grammar @header {...} section. To not create the corresponding directory structure, set the layout attribute to flat.
    Allows different namespaces to be processed in a single run and will not require changes to build files upon refactoring, but ties grammars to a specific language and can conflict with the package attribute as they are mutually exclusive.

  3. The project layout (antlr4 only). Putting your grammars below a common project directory will determine namespace and corresponding directory structure for the generated source files from the relative project path. ANTLR rules uses different defaults for the different target languages (see below), but you can define the root directory yourself via the layout attribute.
    Allows different namespaces to be processed in a single run without language coupling, but requires conformity to a specific (albeit configurable) project layout and the layout attribute for certain languages.

Common Project Directories

The antlr4 rule supports a common directory layout to figure out namespacing from the relative directory structure. The table below lists the default paths for the different target languages. The version number at the end is optional.

Language Default Directory
C src/antlr4
Cpp src/antlr4
CSharp, CSharp2, CSharp3 src/antlr4
Go  
Java src/main/antlr4
JavaScript src/antlr4
Python, Python2, Python3 src/antlr4
Swift  

For languages with no default, you have to set your preference with the layout attribute.

Build Rule Reference

antlr4

antlr4(name, deps=[], srcs=[], atn, depend, encoding, error,
       force_atn, imports=[], language, layout, listener, log,
       long_messages, message_format, no_listener, no_visitor,
       options={}, package, visitor)

Runs ANTLR 4 on the given grammar files.

Attributes

name

Name; Required

A unique name for this rule.

deps

List of labels; Optional; Default is ['@antlr4_tool//jar', '@antlr4_runtime//jar', '@antlr3_runtime//jar', '@stringtemplate4//jar', '@javax_json//jar']

The dependencies to use. Defaults to the official ANTLR 4 release, but if you need to use a different version, you can specify the dependencies here.

srcs

List of labels; Required

The grammar files to process.

atn

Boolean; Optional; Default is False

Generate rule augmented transition network diagrams.

depend

Boolean; Optional; Default is False

Generate a list of file dependencies instead of parser and/or lexer.

encoding

String; Optional; Default is 'UTF-8'

The grammar file encoding, e.g. euc-jp.

error

Boolean; Optional; Default is False

Treat warnings as errors.

force_atn

Boolean; Optional; Default is False

Use the ATN simulator for all predictions.

imports

List of labels; Optional; Default is []

The grammar and .tokens files to import. Must be all in the same directory.

language

String; Optional; Default is ''

The code generation target language. Either Cpp, CSharp, Go, JavaScript, Java, Python2, Python3 or Swift (case-sensitive).

layout

String; Optional; Default is ''

The directory layout to match file paths against for package/namespace detection by convention. The default depends on the target language.

listener

Boolean; Optional; Default is True

Generate parse tree listener.

log

Boolean; Optional; Default is False

Dump lots of logging info to antlr-timestamp.log.

long_messages

Boolean; Optional; Default is False

Show exception details when available for errors and warnings.

message_format

String; Optional; Default is 'antlr'

The output style for messages. Either antlr, gnu or vs2005.

no_listener

Boolean; Optional; Default is False

Do not generate parse tree listener.

no_visitor

Boolean; Optional; Default is True

Do not generate parse tree visitor.

options

Dictionary mapping strings to string; Optional; Default is {}

Set/override grammar-level options.

package

String; Optional; Default is ''

The package/namespace for the generated code.

visitor

Boolean; Optional; Default is False

Generate parse tree visitor.

antlr3

antlr3(name, deps=[], srcs=[], debug, depend, dfa, dump, imports=[],
       language, message_format, nfa, profile, report, trace,
       Xconversiontimeout, Xdbgst, Xdbgconversion, Xdfa, Xdfaverbose,
       Xgrtree, Xm,  Xmaxdfaedges, Xmaxinlinedfastates, Xminswitchalts,
       Xmultithreaded, Xnfastates, Xnocollapse, Xnomergestopstates,
       Xnoprune, Xsavelexer, Xwatchconversion)

Runs ANTLR 3 on the given grammar files.

Attributes

name

Name; Required

A unique name for this rule.

deps

List of labels; Optional; Default is ['@antlr3_runtime//jar', '@antlr3_tool//jar', '@stringtemplate4//jar']

The dependencies to use. Defaults to the most recent ANTLR 3 release, but if you need to use a different version, you can specify the dependencies here.

srcs

List of labels; Required

The grammar files to process.

Xconversiontimeout

Integer; Optional; Default is 0

Set NFA conversion timeout for each decision.

Xdbgconversion

Boolean; Optional; Default is False

Dump lots of info during NFA conversion.

Xdbgst

Boolean; Optional; Default is False

Put tags at start/stop of all templates in output.

Xdfa

Boolean; Optional; Default is False

Print DFA as text.

Xdfaverbose

Boolean; Optional; Default is False

Generate DFA states in DOT with NFA configs.

Xgrtree

Boolean; Optional; Default is False

Print the grammar AST.

Xm

Integer; Optional; Default is 0

Max number of rule invocations during conversion.

Xmaxdfaedges

Integer; Optional; Default is 0

Max "comfortable" number of edges for single DFA state.

Xmaxinlinedfastates

Integer; Optional; Default is 0

Max DFA states before table used rather than inlining.

Xminswitchalts

Integer; Optional; Default is 0

Don't generate switch() statements for dfas smaller than given number.

Xmultithreaded

Boolean; Optional; Default is False

Run the analysis in 2 threads.

Xnfastates

Boolean; Optional; Default is False

For nondeterminisms, list NFA states for each path.

Xnocollapse

Boolean; Optional; Default is False

Collapse incident edges into DFA states.

Xnomergestopstates

Boolean; Optional; Default is False

Do not merge stop states.

Xnoprune

Boolean; Optional; Default is False

Do not test EBNF block exit branches.

Xsavelexer

Boolean; Optional; Default is False

Don't delete temporary lexers generated from combined grammars.

Xwatchconversion

Boolean; Optional; Default is False

Print a message for each NFA before converting.

debug

Boolean; Optional; Default is False

Generate a parser that emits debugging events.

depend

Boolean; Optional; Default is False

Generate file dependencies; don't actually run antlr.

dfa

Boolean; Optional; Default is False

Generate a DFA for each decision point.

dump

Boolean; Optional; Default is False

Print out the grammar without actions.

imports

List of labels; Optional; Default is []

The grammar and .tokens files to import. Must be all in the same directory.

language

String; Optional; Default is ''

The code generation target language. Either C, Cpp, CSharp2, CSharp3, JavaScript, Java, ObjC, Python, Python3 or Ruby (case-sensitive).

message_format

String; Optional; Default is ''

Specify output style for messages.

nfa

Boolean; Optional; Default is False

Generate an NFA for each rule.

profile

Boolean; Optional; Default is False

Generate a parser that computes profiling information.

report

Boolean; Optional; Default is False

Print out a report about the grammar(s) processed.

trace

Boolean; Optional; Default is False

Generate a parser with trace output. If the default output is not enough, you can override the traceIn and traceOut methods.

antlr2

antlr2(name, deps=[], srcs=[], debug, diagnostic, docbook, html,
       imports=[], traceLexer, traceParser, traceTreeParser)

Runs ANTLR 2 on the given grammar files.

Attributes

name

Name; Required

A unique name for this rule.

deps

List of labels; Optional; Default is ['@antlr2//jar']

The dependencies to use. Defaults to the final ANTLR 2 release, but if you need to use a different version, you can specify the dependencies here.

srcs

List of labels; Optional; Default is []

The grammar files to process.

debug

Boolean; Optional; Default is False

Launch the ParseView debugger upon parser invocation. Unless you have downloaded and unzipped the debugger over the top of the standard ANTLR distribution, the code emanating from ANTLR with this option will not compile.

diagnostic

Boolean; Optional; Default is False

Generate a text file from your grammar with a lot of debugging info.

docbook

Boolean; Optional; Default is False

Generate a docbook SGML file from your grammar without actions and so on. It only works for parsers, not lexers or tree parsers.

html

Boolean; Optional; Default is False

Generate a HTML file from your grammar without actions and so on. It only works for parsers, not lexers or tree parsers.

imports

List of labels; Optional; Default is []

The grammar file to import.

trace

Boolean; Optional; Default is False

Have all rules call traceIn/traceOut.

traceLexer

Boolean; Optional; Default is False

Have lexer rules call traceIn/traceOut.

traceParser

Boolean; Optional; Default is False

Have parser rules call traceIn/traceOut.

traceTreeParser

Boolean; Optional; Default is False

Have tree walker rules call traceIn/traceOut.

About

ANTLR rules for Bazel

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Java 78.9%
  • Python 18.4%
  • GAP 2.6%
  • ANTLR 0.1%