1Usage
2
3 The Maven plugin for antlr is simple to use but is at its simplest when you use the default
4 layouts for your grammars, as so:
5
6+--
7 src/main/
8      |
9      +--- antlr3/... .g files organized in the required package structure
10             |
11             +--- imports/  .g files that are imported by other grammars.
12+--
13
14 However, if you are not able to use this structure for whatever reason, you
15 can configure the locations of the grammar files, where library/import files
16 are located and where the output files should be generated.
17
18* Plugin Descriptor
19
20 The current version of the plugin is shown at the top of this page after the <<Last Deployed>> date.
21
22 The full layout of the descriptor (at least, those parts that are not standard Maven things),
23 showing the default values of the configuration options, is as follows:
24
25+--
26<plugin>
27    <groupId>org.antlr</groupId>
28    <artifactId>antlr3-maven-plugin</artifactId>
29    <version>3.1.3-1</version>
30
31    <executions>
32        
33        <execution>
34            <configuration>
35                <goals>
36                    <goal>antlr</goal>
37                </goals>
38                <conversionTimeout>10000</conversionTimeout>
39                <debug>false</debug>
40                <dfa>false</dfa>
41                <nfa>false</nfa>
42                <excludes><exclude/></excludes>
43                <includes><include/></includes>
44                <libDirectory>src/main/antlr3/imports</libDirectory>
45                <messageFormat>antlr</messageFormat>
46                <outputDirectory>target/generated-sources/antlr3</outputDirectory>
47                <printGrammar>false</printGrammar>
48                <profile>false</profile>
49                <report>false</report>
50                <sourceDirectory>src/main/antlr3</sourceDirectory>
51                <trace>false</trace>
52                <verbose>true</verbose>
53            </configuration>
54        </execution>
55    </executions>
56
57</plugin>
58+--
59
60 Note that you can create multiple executions, and thus build some grammars with different
61 options to others (such as setting the debug option for instance).
62
63** Configuration parameters
64
65*** report
66
67    If set to true, then after the tool has processed an input grammar file
68    it will report variaous statistics about the parser, such as information
69    on cyclic DFAs, which rules may use backtracking, and so on.
70
71    default-value="false"
72
73*** printGrammar
74
75    If set to true, then the ANTLR tool will print a version of the input
76    grammar which is devoid of any actions that may be present in the input file.
77
78    default-value = "false"
79
80*** debug
81
82     If set to true, then the code generated by the ANTLR code generator will
83     be set to debug mode. This means that when run, the code will 'hang' and
84     wait for a debug connection on a TCP port (49100 by default).
85     
86     default-value="false"
87     
88*** profile
89
90     If set to true, then then the generated parser will compute and report on
91     profile information at runtime.
92     
93     default-value="false"
94     
95*** nfa
96
97     If set to true then the ANTLR tool will generate a description of the nfa
98     for each rule in <a href="http://www.graphviz.org">Dot format</a>
99     
100     default-value="false"
101     
102    protected boolean nfa;
103    
104*** dfa
105
106     If set to true then the ANTLR tool will generate a description of the DFA
107     for each decision in the grammar in <a href="http://www.graphviz.org">Dot format</a>
108     
109     default-value="false"
110     
111*** trace
112
113     If set to true, the generated parser code will log rule entry and exit points
114     to stdout as an aid to debugging.
115     
116     default-value="false"
117     
118*** messageFormat
119
120     If this parameter is set, it indicates that any warning or error messages returned
121     by ANLTR, shoould be formatted in the specified way. Currently, ANTLR supports the
122     built-in formats of antlr, gnu and vs2005.
123
124     default-value="antlr"
125     
126*** verbose
127
128     If this parameter is set to true, then ANTLR will report all sorts of things
129     about what it is doing such as the names of files and the version of ANTLR and so on.
130     
131     default-value="true"
132     
133*** conversionTimeout
134
135     The number of milliseconds ANTLR will wait for analysis of each
136     alternative in the grammar to complete before giving up. You may raise
137     this value if ANTLR gives up on a complicated alt and tells you that
138     there are lots of ambiguties, but you know that it just needed to spend
139     more time on it. Note that this is an absolute time and not CPU time.
140     
141     default-value="10000"
142     
143*** includes
144
145     Provides an explicit list of all the grammars that should
146     be included in the generate phase of the plugin. Note that the plugin
147     is smart enough to realize that imported grammars should be included but
148     not acted upon directly by the ANTLR Tool.
149     
150     Unless otherwise specified, the include list scans for and includes all
151     files that end in ".g" in any directory beneath src/main/antlr3. Note that
152     this version of the plugin looks for the directory antlr3 and not the directory
153     antlr, so as to avoid clashes and confusion for projects that use both v2 and v3 grammars
154     such as ANTLR itself.
155     
156*** excludes
157
158     Provides an explicit list of any grammars that should be excluded from
159     the generate phase of the plugin. Files listed here will not be sent for
160     processing by the ANTLR tool.
161     
162*** sourceDirectory
163
164     Specifies the Antlr directory containing grammar files. For
165     antlr version 3.x we default this to a directory in the tree
166     called antlr3 because the antlr directory is occupied by version
167     2.x grammars.
168
169     <<NB>> Take careful note that the default location for antlr grammars
170     is now <<antlr3>> and NOT <<antlr>>
171
172     default-value="<<<${basedir}/src/main/antlr3>>>"
173     
174*** outputDirectory
175
176     Location for generated Java files. For antlr version 3.x we default
177     this to a directory in the tree called antlr3 because the antlr
178     directory is occupied by version 2.x grammars.
179     
180     default-value="<<<${project.build.directory}/generated-sources/antlr3>>>"
181     
182*** libDirectory
183
184     Location for imported token files, e.g. <code>.tokens</code> and imported grammars.
185     Note that ANTLR will not try to process grammars that it finds in this directory, but
186     will include this directory in the search for .tokens files and import grammars.
187
188     <<NB>> If you change the lib directory from the default but the directory is
189     still under<<<${basedir}/src/main/antlr3>>>, then you will need to exclude
190     the grammars from processing specifically, using the <<<<excludes>>>> option.
191
192     default-value="<<<${basedir}/src/main/antlr3/imports>>>"
193
194