Context Navigation

options.html

Last change on this file was 1, checked in by lnalod, 15 years ago
Initial import of YAO sources
File size: 29.0 KB

Line
1	<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
2	<html>
3	<head>
4	<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
5	<title>ANTLR Options</title>
6	</head>
7	<body bgcolor="#FFFFFF" text="#000000">
8	<h2><a name="Options">Options</a></h2> <h3><a name="File, Grammar, and Rule">File, Grammar, and Rule</a> Options</h3>
9	<p>
10	Rather than have the programmer specify a bunch of command-line arguments to the parser generator, an options section within the grammar itself serves this purpose. This solution is preferrable because it associates the required options with the grammar rather than ANTLR invocation. The section is preceded by the <tt>options</tt> keyword and contains a series of option/value assignments surrounded by curly braces such as:
11	</p>
12	<pre><tt>
13	options {
14	k = 2;
15	tokenVocbaulary = IDL;
16	defaultErrorHandler = false;
17	</tt>}</pre>
18	<p>
19	The options section for an entire (.g) file, if specified, immediately follows the (optional) file header:
20	</p>
21	<pre><tt>header { package X; }
22	options {language="FOO";}</tt></pre>
23	<p>
24	The options section for a grammar, if specified, must immediately follow the ';' of the class specifier:
25	</p>
26	<p>
27	<tt>class MyParser extends Parser;
28	<br>
29	options { k=2; }</tt>
30	</p>
31	<p>
32	The options section for a rule, if specified, must immediately follow the rule name:
33	</p>
34	<pre><tt>myrule[<em>args</em>] returns [<em>retval</em>]
35	options { defaultErrorHandler=false; }
36	: // body of rule...
37	;</tt> </pre>
38	<p>
39	The option names are not keywords in ANTLR, but rather are entries in a symbol table examined by ANTLR. The scope of option names is limited to the <tt>options</tt> section; identifiers within your grammar may overlap with these symbols.
40	</p>
41	<p>
42	The only ANTLR options not specified in the <tt>options</tt> section are things that do not vary with the grammar, but rather than invocation of ANTLR itself. The best example is debugging information. Typically, the programmer will want a makefile to change an ANTLR flag indicating a debug or release build.
43	</p>
44	<h3><a name="_bb2"></a><a name="Options supported">Options supported in ANTLR</a></h3>
45	<p>
46	<a name="Options supported">Key for the type column: F=file, G=grammar, R=rule, L=lexer, S=subrule, C=C++ only. </a>
47	</p>
48	<div align="center">
49	<center>
50	<table border="2" cellpadding="4" height="1473">
51	<tr>
52	<th height="19">
53	<a name="Options supported">Symbol</a>
54	</th>
55	<th height="19">
56	<a name="Options supported">Type</a>
57	</th>
58	<th height="19">
59	<a name="Options supported">Description</a>
60	</th>
61	</tr>
62	<tr>
63	<td height="19">
64	<font face="Courier New" size="3"><tt><a href="#language">language</a></tt></font>
65	</td>
66	<td align="center" height="19">
67	F
68	</td>
69	<td height="19">
70	Set the generated language
71	</td>
72	</tr>
73	<tr>
74	<td height="19">
75	<font face="Courier New" size="3"><tt><a href="#k">k</a></tt></font>
76	</td>
77	<td align="center" height="19">
78	G
79	</td>
80	<td height="19">
81	Set the lookahead depth
82	</td>
83	</tr>
84	<tr>
85	<td height="19">
86	<font face="Courier New" size="3"><a href="#importVocab"><tt>importVocab</tt></a></font>
87	</td>
88	<td align="center" height="19">
89	G
90	</td>
91	<td height="19">
92	Initial grammar vocabulary
93	</td>
94	</tr>
95	<tr>
96	<td height="19">
97	<font face="Courier New" size="3"><a href="#exportVocab"><tt>exportVocab</tt></a></font>
98	</td>
99	<td align="center" height="19">
100	G
101	</td>
102	<td height="19">
103	Vocabulary exported from grammar
104	</td>
105	</tr>
106	<tr>
107	<td height="19">
108	<font face="Courier New" size="3"><tt>testLiterals</tt></font>
109	</td>
110	<td align="center" height="19">
111	LG,LR
112	</td>
113	<td height="19">
114	Generate literal-testing code
115	</td>
116	</tr>
117	<tr>
118	<td height="38">
119	<font face="Courier New" size="3"><tt><a href="#defaultErrorHandler">defaultErrorHandler</a></tt></font>
120	</td>
121	<td align="center" height="38">
122	G,R
123	</td>
124	<td height="38">
125	Control default exception-handling
126	</td>
127	</tr>
128	<tr>
129	<td height="19">
130	<font face="Courier New" size="3"><tt><a href="lexer.html#Nongreedy_Subrules">greedy</a></tt></font>
131	</td>
132	<td align="center" height="19">
133	S
134	</td>
135	<td height="19">
136	False implies you want subrule loop, (..)* and (..)+, to exit when it sees lookahead consistent with what follows the loop.
137	</td>
138	</tr>
139	<tr>
140	<td height="19">
141	<font face="Courier New" size="3"><tt><a href="#codeGenMakeSwitchThreshold">codeGenMakeSwitchThreshold</a></tt></font>
142	</td>
143	<td align="center" height="19">
144	G
145	</td>
146	<td height="19">
147	Control code generation
148	</td>
149	</tr>
150	<tr>
151	<td height="19">
152	<font face="Courier New" size="3"><tt><a href="#codeBitsetTestThreshold">codeGenBitsetTestThreshold</a></tt></font>
153	</td>
154	<td align="center" height="19">
155	G
156	</td>
157	<td height="19">
158	Control code generation
159	</td>
160	</tr>
161	<tr>
162	<td height="57">
163	<font face="Courier New" size="3"><tt><a href="#buildAST">buildAST</a></tt></font>
164	</td>
165	<td align="center" height="57">
166	G
167	</td>
168	<td height="57">
169	Set automatic AST construction in Parser (transform mode in Tree-Parser)
170	</td>
171	</tr>
172	<tr>
173	<td height="57">
174	<font face="Courier New" size="3"><tt>analyzerDebug</tt></font>
175	</td>
176	<td align="center" height="57">
177	G
178	</td>
179	<td height="57">
180	Spit out lots of debugging information while performing grammar analysis.
181	</td>
182	</tr>
183	<tr>
184	<td height="57">
185	<font face="Courier New" size="3"><tt>codeGenDebug</tt></font>
186	</td>
187	<td align="center" height="57">
188	G
189	</td>
190	<td height="57">
191	Spit out lots of debugging information while doing code generation.
192	</td>
193	</tr>
194	<tr>
195	<td height="57">
196	<font face="Courier New" size="3"><tt>ASTLabelType</tt></font>
197	</td>
198	<td align="center" height="57">
199	G
200	</td>
201	<td height="57">
202	Specify the type of all user-defined labels, overrides default of <tt>AST</tt>.
203	</td>
204	</tr>
205	<tr>
206	<td height="19">
207	<font face="Courier New" size="3"><tt><a href="#charVocabulary">charVocabulary</a></tt></font>
208	</td>
209	<td align="center" height="19">
210	LG
211	</td>
212	<td height="19">
213	Set the lexer character vocabulary
214	</td>
215	</tr>
216	<tr>
217	<td height="76">
218	<font face="Courier New" size="3"><tt>interactive</tt></font>
219	</td>
220	<td align="center" height="76">
221	G
222	</td>
223	<td height="76">
224	Both the lexer and the parser have an interactive option, which defaults to "false". See the parser speed section above.
225	</td>
226	</tr>
227	<tr>
228	<td height="95">
229	<tt><font face="Courier New" size="3">caseSensitive</font></tt>
230	</td>
231	<td align="center" height="95">
232	LG
233	</td>
234	<td height="95">
235	Case is ignored when comparing against character and string literals in the lexer. The case of the input stream is maintained when stored in the token objects.
236	</td>
237	</tr>
238	<tr>
239	<td height="152">
240	<font face="Courier New" size="3">ignore</font>
241	</td>
242	<td align="center" height="152">
243	LR
244	</td>
245	<td height="152">
246	Specify a lexer rule to use as whitespace between lexical rule atomic elements (chars, strings, and rule references). The grammar analysis and, hence, the lookhaead sets are aware of the whitespace references. This is a lexer rule option.
247	</td>
248	</tr>
249	<tr>
250	<td height="57">
251	<font face="Courier New" size="3"><a href="err.html#Modifying Default Error Messages With Paraphrases">paraphrase</a></font>
252	</td>
253	<td align="center" height="57">
254	LR
255	</td>
256	<td height="57">
257	An easy way to specify a string to use in place of the token name during error processing.
258	</td>
259	</tr>
260	<tr>
261	<td height="38">
262	<font face="Courier New" size="3">caseSensitiveLiterals</font>
263	</td>
264	<td align="center" height="38">
265	LG
266	</td>
267	<td height="38">
268	Case is ignored when comparing tokens against the listerals table.
269	</td>
270	</tr>
271	<tr>
272	<td height="114">
273	<font face="Courier New" size="3">classHeaderPrefix</font>
274	</td>
275	<td align="center" height="114">
276	G
277	</td>
278	<td height="114">
279	Replace the usual class prefix ("public" in Java) for the enclosing class definition.
280	</td>
281	</tr>
282	<tr>
283	<td height="114">
284	<font face="Courier New" size="3">classHeaderSuffix</font>
285	</td>
286	<td align="center" height="114">
287	G
288	</td>
289	<td height="114">
290	Append a string to the enclosing class definition. In Java, this amounts to a comma-separated list of interfaces that your lexer, parser, or tree walker must implement.
291	</td>
292	</tr>
293	<tr>
294	<td height="57">
295	<font size="3"><tt>mangleLiteralPrefix</tt></font>
296	</td>
297	<td align="center" height="57">
298	F
299	</td>
300	<td height="57">
301	Sets the prefix for the token type definitions of literals rather than using the default of "<tt>TOKEN_</tt>".
302	</td>
303	</tr>
304	<tr>
305	<td height="152">
306	<font size="3"><tt><a href="#warnWhenFollowAmbig">warnWhenFollowAmbig</a></tt></font>
307	</td>
308	<td align="center" height="152">
309	S
310	</td>
311	<td height="152">
312	Warnings will be printed when the lookahead set of what follows a subrule containing an empty alternative conflicts with a subrule alternative or when the implicit exit branch of a closure loop conflicts with an alternative.  The default is true.
313	</td>
314	</tr>
315	<tr>
316	<td height="152">
317	<font size="3"><tt>generateAmbigWarnings</tt></font>
318	</td>
319	<td align="center" height="152">
320	S
321	</td>
322	<td height="152">
323	When true, no ambiguity/nondeterminism warning is generated for the decision associated with the subrule.  Use this very carefully--you may change the subrule and miss an ambiguity because of the option.  Make very sure that the ambiguity you mask is handled properly by ANTLR.  ANTLR-generated parsers resolve ambiguous decisions by consuming input as soon as possible (or by choosing the alternative listed first).
324	<p>
325	See the Java and HTML grammars for proper use of this option.  A comment should be supplied for each use indicating why it is ok to shut off the warning.
326	</td>
327	</tr>
328	<tr>
329	<td height="152">
330	<font size="3"><tt><a href="lexer.html#Filtering Input Streams">filter</a></tt></font>
331	</td>
332	<td align="center" height="152">
333	LG
334	</td>
335	<td height="152">
336	When true, the lexer ignores any input not exactly matching one of the nonprotected lexer rules.  When set to a rule name, the filter option using the rule to parse input characters between valid tokens or those tokens of interest.
337	</td>
338	</tr>
339	<tr>
340	<td height="76">
341	<font size="3"><tt>namespace</tt></font>
342	</td>
343	<td align="center" height="76">
344	FGC
345	</td>
346	<td height="76">
347	When set, all the C++ code generated is wrapped in the namespace mentioned here.
348	</td>
349	</tr>
350	<tr>
351	<td height="76">
352	<font size="3"><tt>namespaceStd</tt></font>
353	</td>
354	<td align="center" height="76">
355	FGC
356	</td>
357	<td height="76">
358	When set, the ANTLR_USE_NAMESPACE(std) macros in the generated C++ code are replaced by this value. This is a cosmetic option that only makes the code more readable. It does not replace this macro in the support C++ files. Note: use this option directly after setting the language to C++.
359	</td>
360	</tr>
361	<tr>
362	<td height="76">
363	<font size="3"><tt>namespaceAntlr</tt></font>
364	</td>
365	<td align="center" height="76">
366	FGC
367	</td>
368	<td height="76">
369	When set, the ANTLR_USE_NAMESPACE(antlr) macros in the generated C++ code are replaced by this value. This is a cosmetic option that only makes the code more readable. It does not replace this macro in the support C++ files. Note: use this option directly after setting the language to C++.
370	</td>
371	</tr>
372	<tr>
373	<td height="76">
374	<font size="3"><tt>genHashLines</tt></font>
375	</td>
376	<td align="center" height="76">
377	FGC
378	</td>
379	<td height="76">
380	Boolean toggle, when set to 'true' #line <linenumber> "filename" lines are inserted in the generated code so compiler errors/warnings refer the .g files.
381	</td>
382	</tr>
383	<tr>
384	<td height="76">
385	<font size="3"><tt>noConstructors</tt></font>
386	</td>
387	<td align="center" height="76">
388	FGLC
389	</td>
390	<td height="76">
391	Boolean toggle, when set to 'true' the default constructors
392	for the generated lexer/parser/treewalker are omitted. The
393	user then has the option to specify them himself (with extra
394	initializers etc.)
395	</td>
396	</tr>
397	</table>
398	</center>
399	</div>
400	<h3><a name="_bb3"></a><a name="language">language: Setting the generated language</a></h3>
401	<p>
402	ANTLR supports multiple, installable code generators. Any code-generator conforming to the ANTLR specification may be invoked via the language option. The default language is "Java", but "Cpp" and "CSharp" are also supported.   The language option is specified at the file-level, for example:
403	</p>
404	<pre><tt>header { package zparse; }
405	options { language="Java"; }
406	... classes follow ...</tt> </pre> <h3><a name="_bb4"></a><a name="k">k: Setting the lookahead depth </a></h3>
407	<p>
408	You may set the lookahead depth for any grammar (parser, lexer, or tree-walker), by using the k= option:
409	</p>
410	<pre><tt>class MyLexer extends Lexer;
411	options { k=3; }
412	...</tt></pre>
413	<p>
414	Setting the lookahead depth changes the maximum number of tokens that will be examined to select alternative productions, and test for exit conditions of the EBNF constructs (...)?, (...)+, and (...)*. The lookahead analysis is <i>linear approximate</i> (as opposed to full LL(k) ). This is a bit involved to explain in detail, but consider this example with k=2:
415	</p>
416	<pre><tt>r : ( A B \| B A )
417	\| A A
418	;</tt></pre>
419	<p>
420	Full LL(k) analysis would resolve the ambiguity and produce a lookahead test for the first alternate like:
421	</p>
422	<pre><tt>if ( (LA(1)==A && LA(2)==B) \|\| (LA(1)==B && LA(2)==A) )</tt></pre>
423	<p>
424	However, linear approximate analysis would logically OR the lookahead sets at each depth, resulting in a test like:
425	</p>
426	<pre><tt>if ( (LA(1)==A \|\| LA(1)==B) && (LA(2)==A \|\| LA(2)==B) )</tt></pre>
427	<p>
428	Which is ambiguous with the second alternate for {A,A}. Because of this, setting the lookahead depth very high tends to yield diminishing returns in most cases, because the lookahead sets at large depths will include almost everything.
429	</p>
430	<h3><a name="_bb5"></a><a name="importVocab">importVocab: Initial Grammar Vocabulary</a></h3>
431	<p>
432	[<em>See the documentation on <a href="vocab.html">vocabularies</a> for more information</em>]
433	</p>
434	<p>
435	To specify an initial vocabulary (tokens, literals, and token types), use the importVocab grammar option.
436	</p>
437	<p>
438	<tt>class MyParser extends Parser;
439	<br>
440	options {
441	<br>
442	importVocab=V;
443	<br>
444	}</tt>
445	</p>
446	<p>
447	ANTLR will look for VTokenTypes.txt in the current directory and preload the token manager for MyParser with the enclosed information.
448	</p>
449	<p>
450	This option is useful, for example, if you create an external lexer and want to connect it to an ANTLR parser. Conversely, you may create an external parser and wish to use the token set with an ANTLR lexer. Finally, you may find it more convenient to place your grammars in separate files, especially if you have multiple tree-walkers that do not add any literals to the token set.
451	</p>
452	<p>
453	The vocabulary file has an identifier on the first line that names the token vocabulary that is followed by lines of the form ID=value or "literal"=value. For example:
454	</p>
455	<pre><tt>ANTLR // vocabulary name
456	"header"=3
457	ACTION=4
458	COLON=5
459	SEMI=6
460	...</tt></pre>
461	<p>
462	A file of this form is automatically generated by ANTLR for each grammar.
463	</p>
464	<p>
465	Note: you must take care to run ANTLR on the vocabulay-generating grammar files <b>before</b> you run ANTLR on the vocabulary-consuming grammar files.
466	</p>
467	<h3><a name="_bb6"></a><a name="exportVocab">exportVocab: Naming Export Vocabulary</a></h3>
468	<p>
469	[<em>See the documentation on <a href="vocab.html">vocabularies</a> for more information</em>]
470	</p>
471	<p>
472	The vocabulary of a grammar is the union of the set of tokens provided by an importVocab option and the set of tokens and literals defined in the grammar.  ANTLR exports a vocabulary for each grammar whose default name is the same as the grammar.   So, the following grammar yields a vocabulary called P:
473	</p>
474	<pre>class P extends Parser;
475	a : A;</pre>
476	<p>
477	ANTLR generates files PTokenTypes.txt and PTokenTypes.java.
478	</p>
479	<p>
480	You can specify the name of the exported vocabulary with the exportVocab option.   The following grammar generates a vocabulary called V not P.
481	</p>
482	<pre>class P extends Parser;
483	options {
484	exportVocab=V;
485	}
486	a : A;</pre>
487	<p>
488	All grammars in the same file witht the same vocabulary name contribute to the same vocabulary (and resulting files).  If the the grammars were in separate files, on the other hand, they would all overwrite the same file.  For example, the following parser and lexer grammars both may contribute literals and tokens to the MyTokens vocabulary.
489	</p>
490	<pre><tt>class MyParser extends Parser;
491	options {
492	exportVocab=MyTokens;
493	}
494	...
495
496	class MyLexer extends Lexer;
497	options {
498	exportVocab=MyTokens;
499	}
500	...</tt> </pre> <h3><a name="_bb8"></a><a name="testLiterals">testLiterals: Generate literal-testing code</a></h3>
501	<p>
502	By default, ANTLR will generate code in all lexers to test each token against the literals table (the table generated for literal strings), and change the token type if it matches the table. However, you may suppress this code generation in the lexer by using a grammar option:
503	</p>
504	<pre><tt>class L extends Lexer;
505	options { testLiterals=false; }
506	...</tt></pre>
507	<p>
508	If you turn this option off for a lexer, you may re-enable it for specific rules. This is useful, for example, if all literals are keywords, which are special cases of ID:
509	</p>
510	<pre><tt>ID
511	options { testLiterals=true; }
512	: LETTER (LETTER \| DIGIT)*
513	;</tt></pre>
514	<p>
515	<font size="3">If you want to test only a portion of a token's text for a match in the literals table, explicitly test the substring within an action using method:</font>
516	</p>
517	<pre><font size="3">    public int testLiteralsTable(String text, int ttype) {...}</font></pre>
518	<p>
519	<font size="3">For example, you might want to test the literals table for just the tag word in an HTML word.</font>
520	</p>
521	<h3><a name="_bb9"></a><a name="defaultErrorHandler">defaultErrorHandler: Controlling default exception-handling</a></h3>
522	<p>
523	By default, ANTLR will generate default exception handling code for a parser or tree-parser rule. The generated code will catch any parser exceptions, synchronize to the follow set of the rule, and return. This is simple and often useful error-handling scheme, but it is not very sophisticated. Eventually, you will want to install your own exepttion handlers. ANTLR will automatically turn off generation of default exception handling for rule where an exception handler is specified. You may also explicitly control generation of default exception handling on a per-grammar or per-rule basis. For example, this will turn off default error-handing for the entire grammar, but turn it back on for rule "r":
524	</p>
525	<pre><tt>class P extends Parser;
526	options {defaultErrorHandler=false;}
527
528	r
529	options {defaultErrorHandler=true;}
530	: A B C;</tt></pre>
531	<p>
532	For more information on exception handling in the lexer, go <a href="err.html#Default Exception Handling in the Lexer">here</a>.
533	</p>
534	<h3><a name="_bb10"></a><a name="codeGenMakeSwitchThreshold">codeGenMakeSwitchThreshold: controlling code generation</a></h3>
535	<p>
536	ANTLR will optimize lookahead tests by generating a switch statement instead of a series of if/else tests for rules containing a sufficiently large number of alternates whose lookahead is strictly LL(1). The option codeGenMakeSwitchThreshold controls this test. You may want to change this to control optimization of the parser. You may also want to disable it entirely for debugging purposes, by setting it to a large number:
537	</p>
538	<pre><tt>class P extends Parser;
539	options { codeGenMakeSwitchThreshold=999; }
540	...</tt></pre> <h3><a name="_bb11"></a><a name="codeBitsetTestThreshold">codeGenBitsetTestThreshold: controlling code generation</a></h3>
541	<p>
542	ANTLR will optimize lookahead tests by generating a bitset test instead of an if statement, for very complex lookahead sets. The option codeGenBitsetTestThreshold controls this test. You may want to change this to control optimization of the parser:
543	</p>
544	<pre><tt>class P extends Parser;
545	// make bitset if test involves five or more terms
546	options { codeGenBitsetTestThreshold=5; }
547	...</tt></pre>
548	<p>
549	You may also want to disable it entirely for debugging purposes, by setting it to a large number:
550	</p>
551	<pre><tt>class P extends Parser;
552	options { codeGenBitsetTestThreshold=999; }
553	...</tt> </pre> <h3><a name="_bb12"></a><a name="buildAST">buildAST: Automatic AST construction </a></h3>
554	<p>
555	In a Parser, you can tell ANTLR to generate code to construct ASTs corresponding to the structure of the recognized syntax. The option, if set to true, will cause ANTLR to generate AST-building code. With this option set, you can then use all of the <a href="trees.html">AST-building syntax and support methods</a>.
556	</p>
557	<p>
558	In a Tree-Parser, this option turns on "transform mode", which means an output AST will be generated that is a transformation of the input AST. In a tree-walker, the default action of <tt>buildAST</tt> is to generate a copy of the portion of the input AST that is walked. Tree-transformation is almost identical to building an AST in a Parser, except that the input is an AST, not a stream of tokens.
559	</p>
560	<h3><a name="_bb13">ASTLabelType: Setting label type</a></h3>
561	<p>
562	When you must define your own AST node type, your actions within the grammar will require lots of downcasting from AST (the default type of any user-defined label) to your tree node type; e.g.,
563	</p>
564	<pre>decl : d:ID {MyAST t=(MyAST)#d;}
565	;</pre>
566	<p>
567	This makes your code a pain to type in and hard to read.  To avoid this, use the grammar option <tt>ASTLabelType</tt> to have ANTLR automatically do casts and define labels of the appropriate type.
568	</p>
569	<pre>class ExprParser extends Parser;
570
571	options {
572	buildAST=true;
573	ASTLabelType = "MyAST";
574	}
575
576	expr : a:term ;</pre>
577	<p>
578	The type of <tt>#a</tt> within an action is <tt>MyAST</tt> not <tt>AST</tt>.
579	</p>
580	<h3><a name="_bb14"></a><a name="charVocabulary">charVocabulary: Setting the lexer character vocabulary</a></h3>
581	<p>
582	ANTLR processes Unicode. Because of this this, ANTLR cannot make any assumptions about the character set in use, else it would wind up generating huge lexers. Instead ANTLR assumes that the character literals, string literals, and character ranges used in the lexer constitute the entire character set of interest. For example, in this lexer:
583	</p>
584	<pre><tt>class L extends Lexer;
585	A : 'a';
586	B : 'b';
587	DIGIT : '0' .. '9';</tt></pre>
588	<p>
589	The implied character set is { 'a', 'b', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9' }. This can produce unexpected results if you assume that the normal ASCII character set is always used. For example, in:
590	</p>
591	<pre><tt>class L extends Lexer;
592	A : 'a';
593	B : 'b';
594	DIGIT : '0' .. '9';
595	STRING: '"' (~'"")* '"';</tt></pre>
596	<p>
597	The lexer rule STRING will only match strings containing 'a', 'b' and the digits, which is usually not what you want. To control the character set used by the lexer, use the <tt>charVocbaulary</tt> option. This example will use a general eight-bit character set.
598	</p>
599	<pre><tt>class L extends Lexer;
600	options { charVocabulary = '\3'..'\377'; }
601	...</tt></pre>
602	<p>
603	This example uses the ASCII character set in conjunction with some values from the extended Unicode character set:
604	</p>
605	<pre><tt>
606	class L extends Lexer;
607	options {
608	charVocabulary = '\3'..'\377' \| '\u1000'..'\u1fff';
609	}
610	...</tt></pre> <h3><a name="_bb15"></a><a name="warnWhenFollowAmbig">warnWhenFollowAmbig</a></h3>
611	<p>
612	[<strong>Warning</strong>: you should know what you are doing before you use this option.  I deliberately made it a pain to shut warnings off (rather than a single character operator) so you would not just start turning off all the warnings.  I thought for long time before implementing this exact mechanism.  I recommend a comment in front of any use of this option that explains why it is ok to hush the warning.]
613	</p>
614	<p>
615	This subrule option is true by default and controls the generation of nondeterminism (ambiguity) warnings when comparing the FOLLOW lookahead sets for any subrule with an empty alternative and any closure subrule such as (..)+ and (...)*.  For example, the following simple rule has a nondeterministic subrule, which arises from a language ambiguity that you could attach an ELSE clause to the most recent IF <strong>or</strong> to an outer IF because the construct can nest.
616	</p>
617	<pre>stat : "if" expr "then" stat ("else" stat)?
618	\| ID ASSIGN expr SEMI
619	;</pre>
620	<p>
621	Because the language is ambiguous, the context-free grammar must be ambiguous and the resulting parser nondeterministic (in theory).  However, being the practical language folks that we are, we all know you can trivially solve this problem by having ANTLR resolve conflicts by consuming input as soon as possible; I have yet to see a case where this was the wrong thing to do, by the way.  This option, when set to false, merely informs ANTLR that it has made the correct assumption and can shut off an ambiguity related to this subrule and an empty alternative or exit path.  Here is a version of the rule that does not yield a warning message:
622	</p>
623	<p>
624
625	</p>
626	<pre>stat : "if" expr "then" stat
627	(
628	// standard if-then-else ambig
629	options {
630	warnWhenFollowAmbig=false;
631	}
632	: "else" stat
633	)?
634	\| ID ASSIGN expr SEMI
635	;</pre>
636	<p>
637	One important note: This option does not affect non-empty alternatives.  For example, you will still get a warning for the following subrule between alts 1 and 3 (upon lookahead A):
638	</p>
639	<pre>(
640	options {
641	warnWhenFollowAmbig=false;
642	}
643	: A
644	\| B
645	\| A
646	)</pre>
647	<p>
648	Further, this option is insensitive to lookahead.  Only completely empty alternatives count as candidate alternatives for hushing warnings.  So, at k=2, just because ANTLR can see past alternatives with single tokens, you still can get warnings.
649	</p>
650	<h3><a name="Command Line Options">Command Line Options</a></h3>
651	<table border="1" width="100%">
652	<tr>
653	<td width="20%">
654	<font face="Courier New">-o outputDir</font>
655	</td>
656	<td width="50%">
657	specify output directory where all output generated.
658	</td>
659	</tr>
660	<tr>
661	<td width="20%">
662	<font face="Courier New">-glib supergrammarFile</font>
663	</td>
664	<td width="50%">
665	Specify a file with a supergrammar for the generated file.
666	</td>
667	</tr>
668	<tr>
669	<td width="20%">
670	<font face="Courier New">-debug</font>
671	</td>
672	<td width="50%">
673	launch the ParseView debugger upon parser invocation.  Unless you have downloaded and unzipped the debugger over the top of the standard ANTLR distribution, the code emanating from ANTLR with this option will not compile (likewise for Swing).
674	</td>
675	</tr>
676	<tr>
677	<td width="20%">
678	<font face="Courier New">-html</font>
679	</td>
680	<td width="50%">
681	generate a HTML file from your grammar without actions and so on.   This is only a <strong>prototype</strong>, but seems to do something useful.   It only works for parsers, not lexers or tree parsers.
682	</td>
683	</tr>
684	<tr>
685	<td width="20%">
686	<font face="Courier New">-docbook</font>
687	</td>
688	<td width="50%">
689	generate a docbook SGML file from your grammar without actions and so on.   This is only a <strong>prototype</strong>, but seems to do something useful.   It only works for parsers, not lexers or tree parsers.
690	</td>
691	</tr>
692	<tr>
693	<td width="20%">
694	<font face="Courier New">-diagnostic</font>
695	</td>
696	<td width="50%">
697	generate a text file from your grammar with a lot of debugging info.
698	</td>
699	</tr>
700	<tr>
701	<td width="20%">
702	<font face="Courier New">-trace</font>
703	</td>
704	<td width="50%">
705	have all rules call traceIn/traceOut.
706	</td>
707	</tr>
708	<tr>
709	<td width="20%">
710	<font face="Courier New">-traceParser</font>
711	</td>
712	<td width="50%">
713	have parser rules call traceIn/traceOut.
714	</td>
715	</tr>
716	<tr>
717	<td width="20%">
718	<font face="Courier New">-traceLexer</font>
719	</td>
720	<td width="50%">
721	have lexer rules call traceIn/traceOut.
722	</td>
723	</tr>
724	<tr>
725	<td width="20%">
726	<font face="Courier New">-traceTreeParser</font>
727	</td>
728	<td width="50%">
729	have tree walker rules call traceIn/traceOut.
730	</td>
731	</tr>
732	<tr>
733	<td width="20%">
734	<font face="Courier New">-h\|-help\|--help</font>
735	</td>
736	<td width="50%">
737	help message.
738	</td>
739	</tr>
740	</table>
741	<p>
742	<font face="Arial" size="2">Version: $Id: //depot/code/org.antlr/release/antlr-2.7.7/doc/options.html#2 $</font>
743
744	</body>
745	</html>

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: trunk/yao/share/antlr-2.7.7/doc/options.html

Download in other formats: