diff options
Diffstat (limited to 'antlr3-maven-plugin/src/site/apt/usage.apt.vm')
| -rw-r--r-- | antlr3-maven-plugin/src/site/apt/usage.apt.vm | 193 |
1 files changed, 193 insertions, 0 deletions
diff --git a/antlr3-maven-plugin/src/site/apt/usage.apt.vm b/antlr3-maven-plugin/src/site/apt/usage.apt.vm new file mode 100644 index 0000000..9b7ad0f --- /dev/null +++ b/antlr3-maven-plugin/src/site/apt/usage.apt.vm @@ -0,0 +1,193 @@ +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: + ++-- + src/main/ + | + +--- antlr3/... .g files organized in the required package structure + | + +--- imports/ .g 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: + ++-- +<plugin> + <groupId>org.antlr</groupId> + <artifactId>antlr3-maven-plugin</artifactId> + <version>3.1.3-1</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/antlr3/imports</libDirectory> + <messageFormat>antlr</messageFormat> + <outputDirectory>target/generated-sources/antlr3</outputDirectory> + <printGrammar>false</printGrammar> + <profile>false</profile> + <report>false</report> + <sourceDirectory>src/main/antlr3</sourceDirectory> + <trace>false</trace> + <verbose>true</verbose> + </configuration> + </execution> + </executions> + +</plugin> ++-- + + 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 ".g" in any directory beneath src/main/antlr3. Note that + this version of the plugin looks for the directory antlr3 and not the directory + antlr, so as to avoid clashes and confusion for projects that use both v2 and v3 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 3.x we default this to a directory in the tree + called antlr3 because the antlr directory is occupied by version + 2.x grammars. + + <<NB>> Take careful note that the default location for antlr grammars + is now <<antlr3>> and NOT <<antlr>> + + default-value="<<<${basedir}/src/main/antlr3>>>" + +*** outputDirectory + + Location for generated Java files. For antlr version 3.x we default + this to a directory in the tree called antlr3 because the antlr + directory is occupied by version 2.x grammars. + + default-value="<<<${project.build.directory}/generated-sources/antlr3>>>" + +*** 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/antlr3>>>, then you will need to exclude + the grammars from processing specifically, using the <<<<excludes>>>> option. + + default-value="<<<${basedir}/src/main/antlr3/imports>>>" + |