ANTLR3

Description

Invokes the ANTLR3 Translator generator on a grammar file.

Prerequisites

Apache ant version 1.7.0 and later is required, but ant version 1.6.5 should support antlibs, too.

Installation

The recommended procedure is to copy the antlr3.jar in your $ANT_HOME/lib directory, but it suffices to have it in your classpath.

Parameters

Attribute	Description	Required
target	The grammar file to process.	Yes
outputdirectory	The directory to write the generated files to. If not set, the files are written to the directory containing the grammar file.	No
libdirectory	The directory where to find token files.	No
depend	When set to “true”, ANTLRs ‘depend’ option is used to resolve dependencies and to decide whether to invoke ANTLR for compilation. When set to “false”, try to figure out if an ANTLR generated file is out of date without invoking ANTLR with its ‘depend’ option. Default setting is “false” to keep backwards compatibility.	No
report	When set to "true", prints out a report about the grammar processed. Default is “false”.	No
print	When set to "true", print out the grammar without actions. Default is “false”.	No
debug	When set to "true", the generated parser emits debugging events. Default is “false”	No
profile	When set to "true", generates a parser that computes profiling information. Default is “false”.	No
nfa	When set to "true", generate an NFA for each rule. Default is “false”.	No
dfa	When set to "true", generate an DFA for each rule. Default is “false”.	No
messageFormat	When set to a message format the specified output style for messages is used. Default is “false”.	No
multithreaded	When set to "true", run the analysis in 2 threads. Default is “false”.	No
dir	The directory to invoke the VM in.	No
dbgST	When set to “true”, put tags at start/stop of all templates in output. Default is “false”.	No
noprune	Test lookahead against EBNF block exit branches. Default is “false”.	No
nocollapse	collapse incident edges into DFA states Default is “false”.	No
conversiontimeout	Set the NFA conversion timeout for each decisition to the supplied number of milliseconds. Default is 100 as per ANTLR3	No

As nearly everywhere in ant “true” respectively “false” can be used instead of “yes” and “no” to activate or deactivate an attribute.

Nested Elements

ANTLR3 supports a nested <classpath> element, that represents a PATH like structure

. It is given as a convenience if you have to specify the original ANTLR directory. In most cases, having the antlr-3.x.jar, the antlr-2.7.7.jar and the stringtemplate-3.x.jar referenced in the classpath or via the ANTLR_HOME environment variable will be enough.

jvmarg

Additional parameters may be passed to the new VM via nested <jvmarg> attributes, for example:

<antlr:antlr3 xmlns:antlr="antlib:org/apache/tools/ant/antlr" target="...">
 <jvmarg value="-Xmx512M"/>
 ...
</antlr:antlr3>

would set the maximum Java heap size to 512 Megabyte when running ANTLR3.

<jvmarg> allows all attributes described in Command line arguments.

Example

<antlr:antlr3 xmlns:antlr="antlib:org/apache/tools/ant/antlr"
target="etc/java.g"
outputdirectory="build/src"

libdirectory="build/src"

multithreaded="true"

</antlr:antlr3>

This invokes ANTLR3 on grammar file etc/java.g, writing the generated files to build/src. The analysis is being done in two threads.
A complete build file showing the usage of the ANTLR3 task might look like this:

<project name="d2u" default="dist" basedir=".">

<description>

More than a DOS to UNIX conversion of line ends.

</description>

<property name="project.name" value="d2u" />

<!-- program version -->

<property name="version" value="1.00" />

<!-- set global properties for this build -->

<property name="build" location="."/>

<property name="src" location="src"/>

<property name="classes" location="classes"/>

<property name="dist" location="dist" />

<property name="doc" location="docs/api"/>

<property name="grammar" location="grammar"/>

<property name="package" value="org/myorg/${project.name}"/>

<!-- where to write/find token files -->

<property name="token.lib" location="${src}/${package}" />

<!-- antlr options -->

<property name="profile" value="false" />

<property name="report" value="true" />

<property name="multithreaded" value="true" />

<!-- where to find antlr and associates -->

<!-- If the jar-archives listed below are already in the classpath -->

<!-- the definition of antlr.path could be dropped, because -->

<!-- antlr3.jar will resolve the libraries by itself. -->

<!-- As antlr.libdir and antlr.libs are just auxiliary -->

<!-- parameters helping to create antlr.path, -->

<!-- they could be eliminated in this case, too. -->

<property name="antlr.libdir" location="C:/Programme/antlr/lib" />

<patternset id="antlr.libs">

<include name="antlr-3.1.jar" />

<include name="antlr-2.7.7.jar" />

<include name="stringtemplate-3.2.jar" />

<include name="antlr-runtime-3.1.jar" />

</patternset>

<path id="antlr.path">

<fileset dir="${antlr.libdir}" casesensitive="yes">

<patternset refid="antlr.libs" />

</fileset>

</path>

<target name="init">

<!-- Create the time stamp -->

<tstamp />

<!-- Create the build directory structure used by compile -->

<mkdir dir="${grammar}" />

<mkdir dir="${src}/${package}" />

<mkdir dir="${classes}/${package}" />

<mkdir dir="${classes}/META-INF" />

<mkdir dir="${dist}/lib" />

<mkdir dir="${doc}/${package}" />

</target>

<target name="antlr" depends="init" description="run antlr on grammar">

<echo message="antlr ${grammar}/${grammar.name}" />

<antlr:antlr3 xmlns:antlr="antlib:org/apache/tools/ant/antlr"

target="${grammar}/${grammar.name}"

outputdirectory="${src}/${package}"

multithreaded="${multithreaded}"

report="${report}"

profile="${profile}">

</antlr:antlr3>

</target>

<target name="compile" depends="antlr" description="compile">

<!-- Compile the java code from ${src} into ${classes} -->

<javac debug="true" srcdir="${src}" destdir="${classes}"

listfiles="Yes" deprecation="Yes">

<classpath>

<path refid="antlr.path"/>

</classpath>

<compilerarg value="-Xlint:unchecked"/>

</javac>

</target>

<target name="manifest">

<manifest file="${classes}/META-INF/MANIFEST.MF">

<attribute name="Main-Class" value="${package}.Main" />

</manifest>

</target>

<target name="dist" depends="compile, manifest"

description="generate for distribution">

<jar jarfile="${dist}/lib/${project.name}.jar" basedir="${classes}"

manifest="${classes}/META-INF/MANIFEST.MF"/>

</target>

<target name="doc" description="generate documentation">

<javadoc destdir="${doc}"

author="true"

version="true"

use="true"

windowtitle="${project.name}"

sourcefiles="${src}/${package}/*.java"

Protected="All" Private="All"

Public="All"

linksource="yes"

breakiterator="Yes" />

</target>

<target name="clean" description="clean up">

<delete>

<fileset dir="${src}"

includes="**/*.class,**/*.tokens,**/*.g*" />

<fileset dir="${classes}" />

<fileset dir="${dist}" includes="**/*.jar" />

<fileset dir="${doc}" />

</delete>

</target>

<target name="all" depends="clean, dist, doc" description="clean up"/>

</project>

The same build file assuming antlr-3.1.jar, stringtemplate-3.2.jar and antlr-2.7.7.jar are part of the java classpath. Have a look at the antlr and compile targets which don’t reference antlr.path any more.

<project name="d2u" default="dist" basedir=".">

<description>

More than a DOS to UNIX conversion of line ends.

</description>

<property name="project.name" value="d2u" />

<!-- program version -->

<property name="version" value="1.00" />

<!-- set global properties for this build -->

<property name="build" location="."/>

<property name="src" location="src"/>

<property name="classes" location="classes"/>

<property name="dist" location="dist" />

<property name="doc" location="docs/api"/>

<property name="grammar" location="grammar"/>

<property name="package" value="org/myorg/${project.name}"/>

<!-- where to write/find token files -->

<property name="token.lib" location="${src}/${package}" />

<!-- antlr options -->

<property name="profile" value="false" />

<property name="report" value="true" />

<property name="multithreaded" value="true" />

<property name="depend" value="true" />

<target name="init">

<!-- Create the time stamp -->

<tstamp />

<!-- Create the build directory structure used by compile -->

<mkdir dir="${grammar}" />

<mkdir dir="${src}/${package}" />

<mkdir dir="${classes}/${package}" />

<mkdir dir="${classes}/META-INF" />

<mkdir dir="${dist}/lib" />

<mkdir dir="${doc}/${package}" />

</target>

<target name="antlr" depends="init" description="run antlr on grammar">

<echo message="antlr ${grammar}/${project.name}.g" />

<antlr:antlr3 xmlns:antlr="antlib:org/apache/tools/ant/antlr"

target="${grammar}/${project.name}.g"

outputdirectory="${src}/${package}"

libdirectory="${token.lib}"

multithreaded="${multithreaded}"

report="${report}"

profile="${profile}"

depend="${depend}">

</antlr:antlr3>

</target>

<target name="compile" depends="antlr" description="compile">

<!-- Compile the java code from ${src} into ${classes} -->

<javac debug="true" srcdir="${src}" destdir="${classes}"

listfiles="Yes" deprecation="Yes">

<compilerarg value="-Xlint:unchecked"/>

</javac>

</target>

.

.

.

</project>

How does the ant task for Antlr3 finds the Antlr3 libraries

The ant task for Antlr3 inspects the environment variable ANTLR_HOME. It looks in the ANTLR_HOME/lib directory and adds the libraries which fit the patterns “antlr-*.jar” and “stringtemplate-*.jar” to the classpath.
Then it checkes if ANTLRGrammarParseBehavior.class, ANTLRParser.class and StringTemplate.class can be resolved via the classpath.

Warning: If the Anltr3 libraries have already been listed in the classpath make sure they point to the same version ANTLR_HOME refers to, else you might get unexpected results.
Either use ANTLR_HOME to resolve the ANTLR3 libraries or add them to the CLASSPATH environment variable, but do not use both ways at the same time.

Trouble-Shooting

First check if the antlr3.jar can be resolved by ant. The command

ant –diagnostics

should list antlr3.jar in the “ANT_HOME/lib jar listing” section, if the installation recommendation had been adhered to.

Second try the ant verbose option “-v”:

ant –v

This will output some information of the internal processings of the ANTLR3 task.

Third make sure that the jar-archives of the actual antlr distribution are contained in your classpath. At the moment this would refer to antlr-3.x.jar, antlr-2.7.7.jar and stringtemplate-3.x.jar. As a consequence the definition of the antlr.path property , as shown in the example, is not required and the build file has no dependency on the antlr version. The advantage of this approach is that updates of antlr and possibly linked changes in the naming of the before mentioned antlr jar-archives result in no changes of existing ant build-files. Solely the modification of the classpath variable enables you to switch to a different version of antlr.