isabella232 / lein-antlr

Plugin to allow processing of ANTLR grammars using the Leiningen build system for Clojure.

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

Copyright (c) 2010 Revelytix, Inc.

The lein-antlr project is distrubuted under the Apache Software License, Version 2.0