lein-antlr

lein-antlr is a Leiningen 2 plugin for generating source code from one or more ANTLR 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.2.0"]]

Leiningen 1.x users can use the old 0.1.0 version of lein-antlr.

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 {:verbose 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') 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
:debug	boolean	false	Generate code in debug mode (i.e. starts up and waits for a debug connection on a TCP port). Useful for interacting with ANTLRWorks; be sure to disable for production code.
:trace	boolean	false	Generate code that will log rule entry and exit points to stdout when executed.
:profile	boolean	false	Generate code that will collect and report profiling information when executed.
:report	boolean	false	Report information about the grammars as they are processed.
:verbose	boolean	true	Put the ANTLR tool into verbose mode; will not affect the generated code.
:print-grammar	boolean	false	Print a version of the grammar with actions removed as it is processed.
:message-format	String	"antlr"	Determines the format to use for warning and error messages returned by ANTLR. Should be one of "antlr", "gnu", or "vs2005".
:max-switch-case-labels	integer	300	The maximum number of rule alternatives that ANTLR will condense into a case statement.
:dfa	boolean	false	Generate a description of the DFA for each decision in the grammar as it is processed.
:nfa	boolean	false	Print a description of the NFA for each rule as it is analyzed.

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