forked from jasder/antlr
Updated Mojo documentation
This commit is contained in:
Sam Harwell
parent
8e738dad52
commit
502f0802fa
|
|
@ -66,9 +66,8 @@ 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
|
||||
*/
|
||||
|
|
@ -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>**/*.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;
|
||||
|
|
@ -208,41 +206,27 @@ 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
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -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>>>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
FAQ
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
||||
+--- 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:
|
||||
|
||||
+--
|
||||
<project>
|
||||
...
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.antlr</groupId>
|
||||
<artifactId>antlr4-maven-plugin</artifactId>
|
||||
<version>4.0-SNAPSHOT</version>
|
||||
|
||||
<version>${project.version}</version>
|
||||
<executions>
|
||||
|
||||
<execution>
|
||||
<configuration>
|
||||
<id>antlr</id>
|
||||
<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>
|
||||
</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).
|
||||
|
|
|
|||
|
|
@ -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">
|
||||
|
|
|
|||
Loading…
Reference in New Issue