forgetest1
/
antlr
forked from jasder/antlr
1
0
Fork 0
Code Issues Pull Requests 1 Releases Wiki Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java
View File

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

4
antlr4-maven-plugin/src/site/apt/examples/import.apt
View File

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

21
antlr4-maven-plugin/src/site/apt/examples/libraries.apt
View File

@ -2,23 +2,23 @@ Libraries
The introduction of the import directive in a grammar allows reuse of common grammar files 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 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. be searched for with the <<<<libDirectory>>>> directive.
This has confused two separate functions and imposes a structure upon the layout of 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 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 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 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 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. this directory.
The .tokens files for any grammars are generated within the same output directory structure 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 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 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 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 <<<.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 Maven plugin will find the expected <<<.tokens>>> files.
The <<<<libDirectory>>>> is specified like any other directory parameter in Maven. Here is an The <<<<libDirectory>>>> is specified like any other directory parameter in Maven. Here is an
example: example:
@ -30,7 +30,6 @@ Libraries
<version>4.0-SNAPSHOT</version> <version>4.0-SNAPSHOT</version>
<executions> <executions>
<execution> <execution>
<configuration> <configuration>
<goals> <goals>

12
antlr4-maven-plugin/src/site/apt/examples/simple.apt
View File

@ -1,7 +1,7 @@
Simple configuration Simple configuration
If your grammar files are organized into the default locations as described in the {{{../index.html}introduction}}, 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> <plugins>
@ -21,12 +21,12 @@ Simple configuration
</plugins> </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 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 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 { @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 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 the generated <<<.java>>> files will correctly reflect the package structure in which they will
finally rest as classes. finally rest as classes.

1
antlr4-maven-plugin/src/site/apt/faq.apt.vm Normal file
View File

@ -0,0 +1 @@
FAQ

7
antlr4-maven-plugin/src/site/apt/index.apt
View File

@ -49,10 +49,10 @@ ANTLR v4 Maven plugin
+--- imports/ .g4 files that are imported by other grammars. +--- 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 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>>> <<<.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 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 compiler without any special configuration. The generated java files are automatically
submitted for compilation by the plugin. 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.) 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 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. tool to look in this directory for library files.

202
antlr4-maven-plugin/src/site/apt/usage.apt.vm
View File

@ -1,193 +1,59 @@
Usage Usage
The Maven plugin for antlr is simple to use but is at its simplest when you use the default The ANTLR 4 plugin for Maven can generate parsers for any number of grammars in
layouts for your grammars, as so: 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/ 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 The next step is to configure your POM to call the plugin. The goals will
can configure the locations of the grammar files, where library/import files normally run during the generate-sources phase of the build. Examples of how to
are located and where the output files should be generated. 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
* Plugin Descriptor suffice:
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:
+-- +--
<project>
...
<build>
<plugins>
<plugin> <plugin>
<groupId>org.antlr</groupId> <groupId>org.antlr</groupId>
<artifactId>antlr4-maven-plugin</artifactId> <artifactId>antlr4-maven-plugin</artifactId>
<version>4.0-SNAPSHOT</version> <version>${project.version}</version>
<executions> <executions>
<execution> <execution>
<configuration> <id>antlr</id>
<goals> <goals>
<goal>antlr</goal> <goal>antlr</goal>
</goals> </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> </execution>
</executions> </executions>
</plugin> </plugin>
</plugins>
...
</build>
...
</project>
+-- +--
Note that you can create multiple executions, and thus build some grammars with different Note that you can create multiple executions, and thus build some grammars with
options to others (such as setting the debug option for instance). 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>>>"

2
antlr4-maven-plugin/src/site/site.xml
View File

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