From 502f0802fac17f8ffd700a56b118fed08910e619 Mon Sep 17 00:00:00 2001 From: Sam Harwell Date: Sat, 19 Jan 2013 15:55:07 -0600 Subject: [PATCH] Updated Mojo documentation --- .../org/antlr/mojo/antlr4/Antlr4Mojo.java | 82 +++---- .../src/site/apt/examples/import.apt | 4 +- .../src/site/apt/examples/libraries.apt | 21 +- .../src/site/apt/examples/simple.apt | 12 +- antlr4-maven-plugin/src/site/apt/faq.apt.vm | 1 + antlr4-maven-plugin/src/site/apt/index.apt | 9 +- antlr4-maven-plugin/src/site/apt/usage.apt.vm | 226 ++++-------------- antlr4-maven-plugin/src/site/site.xml | 2 + 8 files changed, 104 insertions(+), 253 deletions(-) create mode 100644 antlr4-maven-plugin/src/site/apt/faq.apt.vm diff --git a/antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java b/antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java index 88296ecb4..a190b13bf 100644 --- a/antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java +++ b/antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java @@ -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 Dot format + * If set to true then the ANTLR tool will generate a description of the ATN + * for each rule in Dot format. */ @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 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. + *

+ * A set of Ant-like inclusion patterns used to select files from the source + * directory for processing. By default, the pattern + * **/*.g4 is used to select grammar files. + */ @Parameter protected Set includes = new HashSet(); /** - * 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 excludes = new HashSet(); /** + * 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> processGrammarFiles(List 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 */ diff --git a/antlr4-maven-plugin/src/site/apt/examples/import.apt b/antlr4-maven-plugin/src/site/apt/examples/import.apt index 7e71ea913..4bdfd46ab 100644 --- a/antlr4-maven-plugin/src/site/apt/examples/import.apt +++ b/antlr4-maven-plugin/src/site/apt/examples/import.apt @@ -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 <<>> directory beneath the root directory of your grammar files (which is <<>> by default of course). For a default layout, place your import grammars in the directory: <<>> diff --git a/antlr4-maven-plugin/src/site/apt/examples/libraries.apt b/antlr4-maven-plugin/src/site/apt/examples/libraries.apt index 8a052242d..8b2477273 100644 --- a/antlr4-maven-plugin/src/site/apt/examples/libraries.apt +++ b/antlr4-maven-plugin/src/site/apt/examples/libraries.apt @@ -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 (<<>>) can also + caused some confusion in regard to the fact that generated vocabulary files (<<<*.tokens>>>) can also be searched for with the <<<>>> 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 <<<>>> 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 <<<>>> 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 <<<>>> 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 <<<>>> is specified like any other directory parameter in Maven. Here is an example: @@ -30,7 +30,6 @@ Libraries 4.0-SNAPSHOT - diff --git a/antlr4-maven-plugin/src/site/apt/examples/simple.apt b/antlr4-maven-plugin/src/site/apt/examples/simple.apt index aa5ef0469..3c3412ada 100644 --- a/antlr4-maven-plugin/src/site/apt/examples/simple.apt +++ b/antlr4-maven-plugin/src/site/apt/examples/simple.apt @@ -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 <<>> file for your project is as simple as adding this to it +-- @@ -21,12 +21,12 @@ Simple configuration +-- - When the mvn command is executed all grammar files under <<>>, except any + When the <<>> command is executed all grammar files under <<>>, except any import grammars under <<>> will be analyzed and converted to - java source code in the output directory <<>>. + Java source code in the output directory <<>>. Your input files under <<>> 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 <<>> contains: +--- @header { @@ -34,7 +34,7 @@ package org.jimi.themuss; } +--- - Then the .g4 file should be stored in: <<>>. THis way - the generated .java files will correctly reflect the package structure in which they will + Then the <<<.g4>>> file should be stored in: <<>>. This way + the generated <<<.java>>> files will correctly reflect the package structure in which they will finally rest as classes. diff --git a/antlr4-maven-plugin/src/site/apt/faq.apt.vm b/antlr4-maven-plugin/src/site/apt/faq.apt.vm new file mode 100644 index 000000000..d6360a1c1 --- /dev/null +++ b/antlr4-maven-plugin/src/site/apt/faq.apt.vm @@ -0,0 +1 @@ +FAQ diff --git a/antlr4-maven-plugin/src/site/apt/index.apt b/antlr4-maven-plugin/src/site/apt/index.apt index f954e5a3a..cfbfaf293 100644 --- a/antlr4-maven-plugin/src/site/apt/index.apt +++ b/antlr4-maven-plugin/src/site/apt/index.apt @@ -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 <> 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 <<>> then you would place it in the directory <<>>. The plugin will then produce - .java and .tokens files in the output directory <<>> - When the Java files are compiled they will be in the correct location for the javac + <<<.java>>> and <<<.tokens>>> files in the output directory <<>> + 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. - diff --git a/antlr4-maven-plugin/src/site/apt/usage.apt.vm b/antlr4-maven-plugin/src/site/apt/usage.apt.vm index cff53a01d..e3f41d672 100644 --- a/antlr4-maven-plugin/src/site/apt/usage.apt.vm +++ b/antlr4-maven-plugin/src/site/apt/usage.apt.vm @@ -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 <> 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: +-- - - org.antlr - antlr4-maven-plugin - 4.0-SNAPSHOT - - - - - - - antlr - - 10000 - false - false - false - - - src/main/antlr4/imports - antlr - target/generated-sources/antlr4 - false - false - false - src/main/antlr4 - false - true - - - - - + + ... + + + + org.antlr + antlr4-maven-plugin + ${project.version} + + + antlr + + antlr + + + + + + ... + + ... + +-- - 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 Dot format - - 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 Dot format - - 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. - - <> Take careful note that the default location for antlr grammars - is now <> and NOT <> - - 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. .tokens 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. - - <> 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 <<<>>> 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 <<>> option for + instance). diff --git a/antlr4-maven-plugin/src/site/site.xml b/antlr4-maven-plugin/src/site/site.xml index 96467c1a3..0cf1aa278 100644 --- a/antlr4-maven-plugin/src/site/site.xml +++ b/antlr4-maven-plugin/src/site/site.xml @@ -17,7 +17,9 @@

+ +