lein-antlr

lein-antlr is a Leiningen 2 plugin for generating source code from one or more ANTLR 4 grammars in a Leiningen project. It has roughly the same functionality as the Maven ANTLR plugin, and is intended to allow developers to integrate ANTLR-generated source code into a Clojure project without resorting to Maven or some other manual process.

To use lein-antlr in your project, simply add it to :plugins in your project.clj:

:plugins [[lein-antlr "0.3.0"]]

Version Compatibility

The ANTLR and Leiningen version supported by this plugin are as follows:

lein-antlr 0.3: ANTLR4 and Leiningen 2
lein-antlr 0.2: ANTLR3 and Leiningen 2
lein-antlr 0.1: ANTLR3 and Leiningen 1

Note that source code generated by ANTLR4 is not backwards-compatible with the ANTLR3 runtime. If you upgrade your project to use the 0.3 version of the lein-antlr plugin, you will also need to upgrade your project's ANTLR runtime dependency from version 3 to version 4. See the ANTLR4 migration guide for more details.

Usage

The lein-antlr plugin can be called from the command-line as follows:

% lein antlr

The plugin is configured in your project.clj as follows:

(defproject my-project
  ...
  :antlr-src-dir "src/antlr"
  :antlr-dest-dir "gen-src"
  :antlr-options {:Werror true
                  ... }
)

The plugin will scan the source directory specified by :antlr-src-dir and its subdirectories for all ANTLR grammar files (i.e. those files whose names end in '.g' or '.g4') and compile them, placing the generated source code into the destination directory specified by :antlr-dest-dir. Grammar files located in subdirectories of the source directory will have their generated code placed into corresponding subdirectories in the destination directory.

The default values for :antlr-src-dir and :antlr-dest-dir are 'src/antlr' and 'gen-src' respectively.

Options

The behavior of the ANTLR tool is configured using the :antlr-options entry in your project description. This entry should be a map of keyword-value pairs as follows:

Option	Type	Default Value	Description
`:atn`	boolean	false	generate rule augmented transition network diagrams
`:encoding`	String		specify grammar file encoding; e.g., euc-jp
`:message-format`	String		specify output style for messages in antlr, gnu, vs2005
`:long-messages`	boolean	false	show exception details when available for errors and warnings
`:listener`	boolean	true	generate parse tree listener (default)
`:no-listener`	boolean	false	don't generate parse tree listener
`:visitor`	boolean	false	generate parse tree visitor
`:no-visitor`	boolean	true	don't generate parse tree visitor (default)
`:package`	String	as specified in grammar-files	specify a package/namespace for the generated code
`:depend`	boolean	false	generate file dependencies
`:Werror`	boolean	false	treat warnings as errors
`:Xlog`	boolean	false	dump lots of logging info to antlr-timestamp.log

Cleaning Up

The plugin can be configured to clean the generated source directory as part of the Leiningen 'clean' task, but this must be manually set up by adding the leiningen.antlr namespace to the project hooks, like so:

(defproject my-project
  ...
  :hooks [leiningen.antlr]
  ...
)

License & Copyright