Updated Mojo documentation

This commit is contained in:
Sam Harwell 2013-01-19 15:55:07 -06:00
parent 8e738dad52
commit 502f0802fa
8 changed files with 104 additions and 253 deletions

View File

@ -66,10 +66,9 @@ import java.util.Map;
import java.util.Set;
/**
* Goal that picks up all the ANTLR grammars in a project and moves those that
* are required for generation of the compilable sources into the location
* that we use to compile them, such as {@code target/generated-sources/antlr4}.
*
* Parses ANTLR 4 grammar files {@code *.g4} and transforms them into Java
* source files.
*
* @author Sam Harwell
*/
@Mojo(
@ -84,8 +83,8 @@ public class Antlr4Mojo extends AbstractMojo {
//
/**
* If set to true then the ANTLR tool will generate a description of the atn
* for each rule in <a href="http://www.graphviz.org">Dot format</a>
* If set to true then the ANTLR tool will generate a description of the ATN
* for each rule in <a href="http://www.graphviz.org">Dot format</a>.
*/
@Parameter(property = "antlr4.atn", defaultValue = "false")
protected boolean atn;
@ -97,25 +96,25 @@ public class Antlr4Mojo extends AbstractMojo {
protected String encoding;
/**
* generate parse tree listener (default)
* Generate parse tree listener interface and base class.
*/
@Parameter(property = "antlr4.listener", defaultValue = "true")
protected boolean listener;
/**
* generate parse tree visitor
* Generate parse tree visitor interface and base class.
*/
@Parameter(property = "antlr4.visitor", defaultValue = "false")
protected boolean visitor;
/**
* treat warnings as errors
* Treat warnings as errors.
*/
@Parameter(property = "antlr4.treatWarningsAsErrors", defaultValue = "false")
protected boolean treatWarningsAsErrors;
/**
* use the ATN simulator for all predictions
* Use the ATN simulator for all predictions.
*/
@Parameter(property = "antlr4.forceATN", defaultValue = "false")
protected boolean forceATN;
@ -135,38 +134,37 @@ public class Antlr4Mojo extends AbstractMojo {
protected List<String> arguments;
/* --------------------------------------------------------------------
* The following are Maven specific parameters, rather than specificlly
* The following are Maven specific parameters, rather than specific
* options that the ANTLR tool can use.
*/
/**
* Provides an explicit list of all the grammars that should
* be included in the generate phase of the plugin. Note that the plugin
* is smart enough to realize that imported grammars should be included but
* not acted upon directly by the ANTLR Tool.
*
* Unless otherwise specified, the include list scans for and includes all
* files that end in ".g" in any directory beneath src/main/antlr4. Note that
* this version of the plugin looks for the directory antlr4 and not the directory
* antlr, so as to avoid clashes and confusion for projects that use both v3 and v4 grammars
* such as ANTLR itself.
*/
/**
* Provides an explicit list of all the grammars that should be included in
* the generate phase of the plugin. Note that the plugin is smart enough to
* realize that imported grammars should be included but not acted upon
* directly by the ANTLR Tool.
* <p/>
* A set of Ant-like inclusion patterns used to select files from the source
* directory for processing. By default, the pattern
* <code>**&#47;*.g4</code> is used to select grammar files.
*/
@Parameter
protected Set<String> includes = new HashSet<String>();
/**
* Provides an explicit list of any grammars that should be excluded from
* the generate phase of the plugin. Files listed here will not be sent for
* processing by the ANTLR tool.
* A set of Ant-like exclusion patterns used to prevent certain files from
* being processed. By default, this set is empty such that no files are
* excluded.
*/
@Parameter
protected Set<String> excludes = new HashSet<String>();
/**
* The current Maven project.
*/
@Parameter(property = "project", required = true, readonly = true)
protected MavenProject project;
/**
* Specifies the ANTLR directory containing grammar files.
* The directory where the ANTLR grammar files ({@code *.g4}) are located.
*/
@Parameter(defaultValue = "${basedir}/src/main/antlr4")
private File sourceDirectory;
@ -178,7 +176,7 @@ public class Antlr4Mojo extends AbstractMojo {
private File outputDirectory;
/**
* Specify location of grammars and tokens files.
* Specify location of imported grammars and tokens files.
*/
@Parameter(defaultValue = "${basedir}/src/main/antlr4/imports")
private File libDirectory;
@ -207,42 +205,28 @@ public class Antlr4Mojo extends AbstractMojo {
/**
* The main entry point for this Mojo, it is responsible for converting
* ANTLR 4.x grammars into the target language specified by the grammar.
*
* @throws MojoExecutionException When something is discovered such as a missing source
* @throws MojoFailureException When something really bad happens such as not being able to create the ANTLR Tool
*
* @throws MojoExecutionException if a configuration or grammar error causes
* the code generation process to fail
* @throws MojoFailureException if an instance of the ANTLR 4 {@link Tool}
* cannot be created
*/
@Override
public void execute() throws MojoExecutionException, MojoFailureException {
Log log = getLog();
// Check to see if the user asked for debug information, then dump all the
// parameters we have picked up if they did.
//
if (log.isDebugEnabled()) {
// Excludes
//
for (String e : excludes) {
log.debug("ANTLR: Exclude: " + e);
}
// Includes
//
for (String e : includes) {
log.debug("ANTLR: Include: " + e);
}
// Output location
//
log.debug("ANTLR: Output: " + outputDirectory);
// Library directory
//
log.debug("ANTLR: Library: " + libDirectory);
// Flags
//
}
if (!sourceDirectory.isDirectory()) {
@ -363,7 +347,7 @@ public class Antlr4Mojo extends AbstractMojo {
/**
*
* @param sourceDirectory
* @throws org.codehaus.plexus.compiler.util.scan.InclusionScanException
* @throws InclusionScanException
*/
@NotNull
private List<List<String>> processGrammarFiles(List<String> args, File sourceDirectory) throws InclusionScanException {
@ -445,7 +429,7 @@ public class Antlr4Mojo extends AbstractMojo {
* relative to the base of the output directory and reflect the input
* organization of the grammar files.
*
* @param sourceDirectory The source directory File object
* @param sourceDirectory The source directory {@link File} object
* @param grammarFileName The full path to the input grammar file
* @return The path to the grammar file relative to the source directory
*/

View File

@ -1,8 +1,8 @@
Imported Grammar Files
In order to have the ANTLR plugin automatically locate and use grammars used
as imports in your main .g4 files, you need to place the imported grammar
files in the imports directory beneath the root directory of your grammar
as imports in your main <<<.g4>>> files, you need to place the imported grammar
files in the <<<imports>>> directory beneath the root directory of your grammar
files (which is <<<src/main/antlr4>>> by default of course).
For a default layout, place your import grammars in the directory: <<<src/main/antlr4/imports>>>

View File

@ -2,23 +2,23 @@ Libraries
The introduction of the import directive in a grammar allows reuse of common grammar files
as well as the ability to divide up functional components of large grammars. However it has
caused some confusion in regard to the fact that generated vocab files (<<<xxx.tokens>>>) can also
caused some confusion in regard to the fact that generated vocabulary files (<<<*.tokens>>>) can also
be searched for with the <<<<libDirectory>>>> directive.
This has confused two separate functions and imposes a structure upon the layout of
your grammar files in certain cases. If you have grammars that both use the import
directive and also require the use of a vocab file then you will need to locate
the grammar that generates the .tokens file alongside the grammar that uses it. This
directive and also require the use of a vocabulary file then you will need to locate
the grammar that generates the <<<.tokens>>> file alongside the grammar that uses it. This
is because you will need to use the <<<<libDirectory>>>> directive to specify the
location of your imported grammars and ANTLR will not find any vocab files in
location of your imported grammars and ANTLR will not find any vocabulary files in
this directory.
The .tokens files for any grammars are generated within the same output directory structure
as the .java files. So, whereever the .java files are generated, you will also find the .tokens
files. ANTLR looks for .tokens files in both the <<<<libDirectory>>>> and the output directory
where it is placing the geenrated .java files. Hence when you locate the grammars that generate
.tokens files in the same source directory as the ones that use the .tokens files, then
the Maven plugin will find the expected .tokens files.
The <<<.tokens>>> files for any grammars are generated within the same output directory structure
as the <<<.java>>> files. So, wherever the <<<.java>>> files are generated, you will also find the <<<.tokens>>>
files. ANTLR looks for <<<.tokens>>> files in both the <<<<libDirectory>>>> and the output directory
where it is placing the generated <<<.java>>> files. Hence when you locate the grammars that generate
<<<.tokens>>> files in the same source directory as the ones that use the <<<.tokens>>> files, then
the Maven plugin will find the expected <<<.tokens>>> files.
The <<<<libDirectory>>>> is specified like any other directory parameter in Maven. Here is an
example:
@ -30,7 +30,6 @@ Libraries
<version>4.0-SNAPSHOT</version>
<executions>
<execution>
<configuration>
<goals>

View File

@ -1,7 +1,7 @@
Simple configuration
If your grammar files are organized into the default locations as described in the {{{../index.html}introduction}},
then configuring the pom.xml file for your project is as simple as adding this to it
then configuring the <<<pom.xml>>> file for your project is as simple as adding this to it
+--
<plugins>
@ -21,12 +21,12 @@ Simple configuration
</plugins>
+--
When the mvn command is executed all grammar files under <<<src/main/antlr4>>>, except any
When the <<<mvn>>> command is executed all grammar files under <<<src/main/antlr4>>>, except any
import grammars under <<<src/main/antlr4/imports>>> will be analyzed and converted to
java source code in the output directory <<<target/generated-sources/antlr4>>>.
Java source code in the output directory <<<target/generated-sources/antlr4>>>.
Your input files under <<<antlr4>>> should be stored in sub directories that
reflect the package structure of your java parsers. If your grammar file parser.g4 contains:
reflect the package structure of your java parsers. If your grammar file <<<parser.g4>>> contains:
+---
@header {
@ -34,7 +34,7 @@ package org.jimi.themuss;
}
+---
Then the .g4 file should be stored in: <<<src/main/antlr4/org/jimi/themuss/parser.g4>>>. THis way
the generated .java files will correctly reflect the package structure in which they will
Then the <<<.g4>>> file should be stored in: <<<src/main/antlr4/org/jimi/themuss/parser.g4>>>. This way
the generated <<<.java>>> files will correctly reflect the package structure in which they will
finally rest as classes.

View File

@ -0,0 +1 @@
FAQ

View File

@ -28,7 +28,7 @@ ANTLR v4 Maven plugin
use version 4.0 of the plugin, you will build your grammars using version 4.0 of the
ANTLR tool, version 4.2 of the plugin will use version 4.2 of the ANTLR tool and so on.
You may also find that there are patch versions of the plugin suchas 4.0-1 4.0-2 and
You may also find that there are patch versions of the plugin such as 4.0-1 4.0-2 and
so on. Use the latest patch release of the plugin.
The current version of the plugin is shown at the top of this page after the <<Last Deployed>> date.
@ -49,10 +49,10 @@ ANTLR v4 Maven plugin
+--- imports/ .g4 files that are imported by other grammars.
+--
If your grammar is intended to be part of a package called org.foo.bar then you would
If your grammar is intended to be part of a package called <<<org.foo.bar>>> then you would
place it in the directory <<<src/main/antlr4/org/foo/bar>>>. The plugin will then produce
.java and .tokens files in the output directory <<<target/generated-sources/antlr4/org/foo/bar>>>
When the Java files are compiled they will be in the correct location for the javac
<<<.java>>> and <<<.tokens>>> files in the output directory <<<target/generated-sources/antlr4/org/foo/bar>>>
When the Java files are compiled they will be in the correct location for the Javac
compiler without any special configuration. The generated java files are automatically
submitted for compilation by the plugin.
@ -60,4 +60,3 @@ ANTLR v4 Maven plugin
any grammar files that are imported by other grammar files (do not make subdirectories here.)
Such files are never built on their own, but the plugin will automatically tell the ANTLR
tool to look in this directory for library files.

View File

@ -1,193 +1,59 @@
Usage
The Maven plugin for antlr is simple to use but is at its simplest when you use the default
layouts for your grammars, as so:
The ANTLR 4 plugin for Maven can generate parsers for any number of grammars in
your project.
* Compiling Grammars into Parsers
By default, the <<<{{{./antlr-mojo.html}antlr}}>>> goal will search for grammar
files in the directory <<<$\{basedir\}/src/main/antlr4>>> and any additional
<<<.tokens>>> files in the directory <<<$\{basedir\}/src/main/antlr4/imports>>>.
This can be configured to search other directories using the plugin configuration
parameters as described in the <<<{{{./antlr-mojo.html}antlr}}>>> goal
documentation.
The following figure shows the expected layout of files for the default
configuration of this plugin.
+--
src/main/
|
+--- antlr4/... .g4 files organized in the required package structure
+--- antlr4/... .g4 files organized in the required package structure
|
+--- imports/ .g4 files that are imported by other grammars.
+--- imports/ user-created .tokens files and .g4 files that are imported by other grammars
+--
However, if you are not able to use this structure for whatever reason, you
can configure the locations of the grammar files, where library/import files
are located and where the output files should be generated.
* Plugin Descriptor
The current version of the plugin is shown at the top of this page after the <<Last Deployed>> date.
The full layout of the descriptor (at least, those parts that are not standard Maven things),
showing the default values of the configuration options, is as follows:
The next step is to configure your POM to call the plugin. The goals will
normally run during the generate-sources phase of the build. Examples of how to
configure your POM can be found on the various examples pages, reachable via
the page menu. If you stick with the default values, the snippet below will
suffice:
+--
<plugin>
<groupId>org.antlr</groupId>
<artifactId>antlr4-maven-plugin</artifactId>
<version>4.0-SNAPSHOT</version>
<executions>
<execution>
<configuration>
<goals>
<goal>antlr</goal>
</goals>
<conversionTimeout>10000</conversionTimeout>
<debug>false</debug>
<dfa>false</dfa>
<nfa>false</nfa>
<excludes><exclude/></excludes>
<includes><include/></includes>
<libDirectory>src/main/antlr4/imports</libDirectory>
<messageFormat>antlr</messageFormat>
<outputDirectory>target/generated-sources/antlr4</outputDirectory>
<printGrammar>false</printGrammar>
<profile>false</profile>
<report>false</report>
<sourceDirectory>src/main/antlr4</sourceDirectory>
<trace>false</trace>
<verbose>true</verbose>
</configuration>
</execution>
</executions>
</plugin>
<project>
...
<build>
<plugins>
<plugin>
<groupId>org.antlr</groupId>
<artifactId>antlr4-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<id>antlr</id>
<goals>
<goal>antlr</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
...
</build>
...
</project>
+--
Note that you can create multiple executions, and thus build some grammars with different
options to others (such as setting the debug option for instance).
** Configuration parameters
*** report
If set to true, then after the tool has processed an input grammar file
it will report variaous statistics about the parser, such as information
on cyclic DFAs, which rules may use backtracking, and so on.
default-value="false"
*** printGrammar
If set to true, then the ANTLR tool will print a version of the input
grammar which is devoid of any actions that may be present in the input file.
default-value = "false"
*** debug
If set to true, then the code generated by the ANTLR code generator will
be set to debug mode. This means that when run, the code will 'hang' and
wait for a debug connection on a TCP port (49100 by default).
default-value="false"
*** profile
If set to true, then then the generated parser will compute and report on
profile information at runtime.
default-value="false"
*** nfa
If set to true then the ANTLR tool will generate a description of the nfa
for each rule in <a href="http://www.graphviz.org">Dot format</a>
default-value="false"
protected boolean nfa;
*** dfa
If set to true then the ANTLR tool will generate a description of the DFA
for each decision in the grammar in <a href="http://www.graphviz.org">Dot format</a>
default-value="false"
*** trace
If set to true, the generated parser code will log rule entry and exit points
to stdout as an aid to debugging.
default-value="false"
*** messageFormat
If this parameter is set, it indicates that any warning or error messages returned
by ANLTR, shoould be formatted in the specified way. Currently, ANTLR supports the
built-in formats of antlr, gnu and vs2005.
default-value="antlr"
*** verbose
If this parameter is set to true, then ANTLR will report all sorts of things
about what it is doing such as the names of files and the version of ANTLR and so on.
default-value="true"
*** conversionTimeout
The number of milliseconds ANTLR will wait for analysis of each
alternative in the grammar to complete before giving up. You may raise
this value if ANTLR gives up on a complicated alt and tells you that
there are lots of ambiguties, but you know that it just needed to spend
more time on it. Note that this is an absolute time and not CPU time.
default-value="10000"
*** includes
Provides an explicit list of all the grammars that should
be included in the generate phase of the plugin. Note that the plugin
is smart enough to realize that imported grammars should be included but
not acted upon directly by the ANTLR Tool.
Unless otherwise specified, the include list scans for and includes all
files that end in ".g4" in any directory beneath src/main/antlr4. Note that
this version of the plugin looks for the directory antlr4 and not the directory
antlr, so as to avoid clashes and confusion for projects that use both v3 and v4 grammars
such as ANTLR itself.
*** excludes
Provides an explicit list of any grammars that should be excluded from
the generate phase of the plugin. Files listed here will not be sent for
processing by the ANTLR tool.
*** sourceDirectory
Specifies the Antlr directory containing grammar files. For
antlr version 4.x we default this to a directory in the tree
called antlr4 because the antlr directory is occupied by version
2.x grammars.
<<NB>> Take careful note that the default location for antlr grammars
is now <<antlr4>> and NOT <<antlr>>
default-value="<<<${basedir}/src/main/antlr4>>>"
*** outputDirectory
Location for generated Java files. For antlr version 4.x we default
this to a directory in the tree called antlr4 because the antlr
directory is occupied by version 2.x grammars.
default-value="<<<${project.build.directory}/generated-sources/antlr4>>>"
*** libDirectory
Location for imported token files, e.g. <code>.tokens</code> and imported grammars.
Note that ANTLR will not try to process grammars that it finds in this directory, but
will include this directory in the search for .tokens files and import grammars.
<<NB>> If you change the lib directory from the default but the directory is
still under<<<${basedir}/src/main/antlr4>>>, then you will need to exclude
the grammars from processing specifically, using the <<<<excludes>>>> option.
default-value="<<<${basedir}/src/main/antlr4/imports>>>"
Note that you can create multiple executions, and thus build some grammars with
different options to others (such as setting the <<<debug>>> option for
instance).

View File

@ -17,7 +17,9 @@
<menu name="Overview">
<item name="Introduction" href="index.html"/>
<item name="Goals" href="plugin-info.html"/>
<item name="Usage" href="usage.html"/>
<item name="FAQ" href="faq.html"/>
</menu>
<menu name="Examples">