Debian Codegraph @

doc/tool-options.md

raw
1 # ANTLR Tool Command Line Options
2
3 If you invoke the ANTLR tool without command line arguments, you’ll get a help message:
4
5 ```bash
6 $ antlr4
7 ANTLR Parser Generator Version 4.7.1
8 -o ___ specify output directory where all output is generated
9 -lib ___ specify location of grammars, tokens files
10 -atn generate rule augmented transition network diagrams
11 -encoding ___ specify grammar file encoding; e.g., euc-jp
12 -message-format ___ specify output style for messages in antlr, gnu, vs2005
13 -long-messages show exception details when available for errors and warnings
14 -listener generate parse tree listener (default)
15 -no-listener don't generate parse tree listener
16 -visitor generate parse tree visitor
17 -no-visitor don't generate parse tree visitor (default)
18 -package ___ specify a package/namespace for the generated code
19 -depend generate file dependencies
20 -D<option>=value set/override a grammar-level option
21 -Werror treat warnings as errors
22 -XdbgST launch StringTemplate visualizer on generated code
23 -XdbgSTWait wait for STViz to close before continuing
24 -Xforce-atn use the ATN simulator for all predictions
25 -Xlog dump lots of logging info to antlr-timestamp.log
26 -Xexact-output-dir all output goes into -o dir regardless of paths/package
27 ```
28
29 Here are more details on the options:
30
31 ## `-o outdir`
32
33 ANTLR generates output files in the current directory by default. This option specifies the output directory where ANTLR should generate parsers, listeners, visitors, and tokens files.
34
35 ```bash
36 $ antlr4 -o /tmp T.g4
37 $ ls /tmp/T*
38 /tmp/T.tokens /tmp/TListener.java
39 /tmp/TBaseListener.java /tmp/TParser.java
40 ```
41
42 ## `-lib libdir`
43
44 When looking for tokens files and imported grammars, ANTLR normally looks in the current directory. This option specifies which directory to look in instead. It is only used for resolving grammar references for the import statement and the tokenVocab option. The path to the primary grammar must always be fully specified.
45
46 $ cat /tmp/B.g4
47
48 parser grammar B;
49
50 x : ID ;
51
52 $ cat A.g4
53
54 grammar A;
55
56 import B;
57
58 s : x ;
59
60 ID : [a-z]+ ;
61
62 $ antlr4 -lib /tmp A.g4
63
64 ## `-atn`
65
66 Generate DOT graph files that represent the internal ATN (augmented transition network) data structures that ANTLR uses to represent grammars. The files come out as Grammar.rule .dot. If the grammar is a combined grammar, the lexer rules are named Grammar Lexer.rule .dot.
67
68 $ cat A.g4
69
70 grammar A;
71
72 s : b ;
73
74 b : ID ;
75
76 ID : [a-z]+ ;
77
78 $ antlr4 -atn A.g4
79
80 $ ls *.dot
81
82 A.b.dot A.s.dot ALexer.ID.dot
83
84 ## `-encoding encodingname`
85
86 By default ANTLR loads grammar files using the UTF-8 encoding, which is a very common character file encoding that degenerates to ASCII for characters that fit in one byte. There are many character file encodings from around the world. If that grammar file is not the default encoding for your locale, you need this option so that ANTLR can properly interpret grammar files. This does not affect the input to the generated parsers, just the encoding of the grammars themselves.
87
88 ## `-message-format format`
89
90 ANTLR generates warning and error messages using templates from directory tool/resources/org/antlr/v4/tool/templates/messages/formats. By default, ANTLR uses the antlr.stg (StringTemplate group) file. You can change this to gnu or vs2005 to have ANTLR generate messages appropriate for Emacs or Visual Studio. To make your own called X, create resource org/antlr/v4/tool/templates/messages/formats/ X and place it in the CLASSPATH.
91
92 ## `-listener`
93
94 This option tells ANTLR to generate a parse tree listener and is the default.
95
96 ## `-no-listener`
97
98 This option tells ANTLR not to generate a parse tree listener.
99
100 ## `-visitor`
101
102 ANTLR does not generate parse tree visitors by default. This option turns that feature on. ANTLR can generate both parse tree listeners and visitors; this option and -listener aren’t mutually exclusive.
103
104 ## `-no-visitor`
105
106 Tell ANTLR not to generate a parse tree visitor; this is the default.
107
108 ## `-package`
109
110 Use this option to specify a package or namespace for ANTLR-generated files. Alternatively, you can add a @header {...} action but that ties the grammar to a specific language. If you use this option and @header, make sure that the header action does not contain a package specification otherwise the generated code will have two of them.
111
112 ## `-depend`
113
114 Instead of generating a parser and/or lexer, generate a list of file dependencies, one per line. The output shows what each grammar depends on and what it generates. This is useful for build tools that need to know ANTLR grammar dependencies. Here’s an example:
115
116 ```bash
117 $ antlr4 -depend T.g
118 T.g: A.tokens
119 TParser.java : T.g
120 T.tokens : T.g
121 TLexer.java : T.g
122 TListener.java : T.g
123 TBaseListener.java : T.g
124 ```
125
126 If you use -lib libdir with -depend and grammar option tokenVocab=A, then the dependencies include the library path as well: T.g: libdir/A.tokens. The output is also sensitive to the -o outdir option: outdir/TParser.java : T.g.
127
128 ## `-D<option>=value`
129
130 Use this option to override or set a grammar-level option in the specified grammar or grammars. This option is useful for generating parsers in different languages without altering the grammar itself. (I expect to have other targets in the near future.)
131
132 ```bash
133 $ antlr4 -Dlanguage=Java T.g4 # default
134 $ antlr4 -Dlanguage=C T.g4
135 error(31): ANTLR cannot generate C code as of version 4.0b3
136 ```
137
138 ## `-Werror`
139
140 As part of a large build, ANTLR warning messages could go unnoticed. Turn on this option to have warnings treated as errors, causing the ANTLR tool to report failure back to the invoking commandline shell.
141 There are also some extended options that are useful mainly for debugging ANTLR itself:
142
143 ## `-Xsave-lexer`
144
145 ANTLR generates both a parser and a lexer from a combined grammar. To create the lexer, ANTLR extracts a lexer grammar from the combined grammar. Sometimes it’s useful to see what that looks like if it’s not clear what token rules ANTLR is creating. This does not affect the generated parsers or lexers.
146
147 ## `-XdbgST`
148
149 For those building a code generation target, this option brings up a window showing the generated code and the templates used to generate that code. It invokes the StringTemplate inspector window.
150
151 ## `-Xforce-atn`
152
153 ANTLR normally builds traditional “switch on token type” decisions where possible (one token of lookahead is sufficient to distinguish between all alternatives in a decision). To force even these simple decisions into the adaptive LL(*) mechanism, use this option.
154
155 ## `-Xlog`
156
157 This option creates a log file containing lots of information messages from ANTLR as it processes your grammar. If you would like to see how ANTLR translates your left-recursive rules, turn on this option and look in the resulting log file.
158
159 ```bash
160 $ antlr4 -Xlog T.g4
161 wrote ./antlr-2012-09-06-17.56.19.log
162 ```
163
164 ## `-Xexact-output-dir`
165
166 (*See the [discussion](https://github.com/antlr/antlr4/pull/2065)*).
167
168 All output goes into `-o` dir regardless of paths/package.
169
170 * Output `-o` directory specifier is the exact directory containing the output. Previously it would include the relative path specified on the grammar itself for the purposes of packages.
171
172 **new**: `-o /tmp subdir/T.g4` => `/tmp/subdir/T.java`
173 **old**: `-o /tmp subdir/T.g4` => `/tmp/T.java`
174
175 * Previously we looked for the tokens vocab file in the `-lib` dir or in the output dir. **New**: also look in the directory containing the grammar, particularly if it it is specified with a path.
176
177 ### Example for the output directory (4.7)
178
179 Here is the existing 4.7 functionality.
180
181 (For these examples, assume a4.7 and a4.7.1 are aliases to the right version of ANTLR's `org.antlr.v4.Tool`.)
182
183 ```bash
184 $ cd /tmp/parrt
185 $ tree
186 .
187 ├── B.g4
188 └── src
189 └── pkg
190 └── A.g4
191 $ a4.7 -o /tmp/build src/pkg/A.g4
192 $ tree /tmp/build
193 /tmp/build/
194 └── src
195 └── pkg
196 ├── A.tokens
197 ├── ABaseListener.java
198 ├── ALexer.java
199 ├── ALexer.tokens
200 ├── AListener.java
201 └── AParser.java
202 ```
203
204 Now, let's build a grammar that sits in the current directory:
205
206 ```bash
207 $ a4.7 -o /tmp/build B.g4
208 $ tree /tmp/build
209 /tmp/build
210 ├── B.tokens
211 ├── BBaseListener.java
212 ├── BLexer.java
213 ├── BLexer.tokens
214 ├── BListener.java
215 ├── BParser.java
216 └── src
217 └── pkg
218 ├── A.tokens
219 ├── ABaseListener.java
220 ├── ALexer.java
221 ├── ALexer.tokens
222 ├── AListener.java
223 └── AParser.java
224 ```
225
226 Finally, if we don't specify the output directory, it paid attention to the relative path specified on the input grammar:
227
228 ```bash
229 $ a4.7 src/pkg/A.g4
230 $ tree
231 .
232 ├── B.g4
233 └── src
234 └── pkg
235 ├── A.g4
236 ├── A.tokens
237 ├── ABaseListener.java
238 ├── ALexer.java
239 ├── ALexer.tokens
240 ├── AListener.java
241 └── AParser.java
242 ```
243
244 ### Example for the output directory (4.7.1 with -Xexact-output-dir)
245
246 Now, the output directory is the exact directory where output is generated regardless of relative paths on the grammar
247
248 ```bash
249 $ cd /tmp/parrt
250 $ a4.7.1 -Xexact-output-dir -o /tmp/build src/pkg/A.g4
251 $ tree /tmp/build
252 /tmp/build
253 ├── A.tokens
254 ├── ABaseListener.java
255 ├── ALexer.java
256 ├── ALexer.tokens
257 ├── AListener.java
258 └── AParser.java
259 ```
260
261 If you use the package option, it still does not change where the output is generated if you use `-o`
262
263 ```bash
264 $ a4.7.1 -Xexact-output-dir -package pkg -o /tmp/build src/pkg/A.g4
265 $ tree /tmp/build
266 /tmp/build
267 ├── A.tokens
268 ├── ABaseListener.java
269 ├── ALexer.java
270 ├── ALexer.tokens
271 ├── AListener.java
272 └── AParser.java
273 ```
274
275 4.7.1 does however add the package specification into the generated files:
276
277 ```bash
278 $ grep package /tmp/build/A*.java
279 /tmp/build/ABaseListener.java:package pkg;
280 /tmp/build/ALexer.java:package pkg;
281 /tmp/build/AListener.java:package pkg;
282 /tmp/build/AParser.java:package pkg;
283 ```
284
285 Compare this to 4.7:
286
287 ```bash
288 $ a4.7 -package pkg -o /tmp/build src/pkg/A.g4
289 beast:/tmp/parrt $ tree /tmp/build
290 /tmp/build
291 └── src
292 └── pkg
293 ├── A.tokens
294 ├── ABaseListener.java
295 ├── ALexer.java
296 ├── ALexer.tokens
297 ├── AListener.java
298 └── AParser.java
299 ```
300
301 ### Example of where it looks for tokens vocab
302
303 In 4.7, we got an error for an obvious case that should work:
304
305 ```bash
306 $ cd /tmp/parrt
307 $ tree
308 .
309 └── src
310 └── pkg
311 ├── L.g4
312 └── P.g4
313 $ a4.7 -o /tmp/build src/pkg/*.g4
314 error(160): P.g4:2:21: cannot find tokens file /tmp/build/L.tokens
315 warning(125): P.g4:3:4: implicit definition of token A in parser
316 ```
317
318 In 4.7.1 it looks in the directory containing the grammars as well:
319
320 ```bash
321 $ a4.7.1 -o /tmp/build src/pkg/*.g4
322 $ tree /tmp/build
323 /tmp/build
324 ├── L.java
325 ├── L.tokens
326 ├── P.java
327 ├── P.tokens
328 ├── PBaseListener.java
329 ├── PListener.java
330 └── src
331 └── pkg
332 ├── L.java
333 └── L.tokens
334 ```