JavaCC options

JavaCC Options

STATIC

This is a boolean option whose default value is true. If true, all methods and class variables are specified as static in the generated parser and token manager. This allows only one parser object to be present, but it improves the performance of the parser. To perform multiple parses during one run of your Java program, you will have to call the ReInit() method to reinitialize your parser if it is static. If the parser is non-static, you may use the "new" operator to construct as many parsers as you wish. These can all be used simultaneously from different threads.

In summary, it will cause PARSER, TokenManager were generated statically.

IGNORE_CASE

This is a boolean option whose default value is false. Setting this option to true causes the generated token manager to ignore case in the token specifications and the input files. This is useful for writing grammars for languages such as HTML. It is also possible to localize the effect of IGNORE_CASE by using an alternate mechanism described later.

LOOKAHEAD

The number of tokens to look ahead before making a decision at a choice point during parsing. The default value is 1. The smaller this number, the faster the parser. This number may be overridden for specific productions within the grammar as described later. See the description of the lookahead algorithm for complete details on how lookahead works.

CHOICE_AMBIGUITY_CHECK?

This is an integer option whose default value is 2. This is the number of tokens considered in checking choices of the form "A | B | ..." for ambiguity. For example, if there is a common two token prefix for both A and B, but no common three token prefix, (assume this option is set to 3) then JavaCC can tell you to use a lookahead of 3 for disambiguation purposes. And if A and B have a common three token prefix, then JavaCC only tell you that you need to have a lookahead of 3 or more. Increasing this can give you more comprehensive ambiguity information at the cost of more processing time. For large grammars such as the Java grammar, increasing this number any further causes the checking to take too much time.

OTHER_AMBIGUITY_CHECK?

This is an integer option whose default value is 1. This is the number of tokens considered in checking all other kinds of choices (i.e., of the forms "(A)*", "(A)+", and "(A)?") for ambiguity. This takes more time to do than the choice checking, and hence the default value is set to 1 rather than 2.

DEBUG_PARSER

This is a boolean option whose default value is false. This option is used to obtain debugging information from the generated parser. Setting this option to true causes the parser to generate a trace of its actions. Tracing may be disabled by calling the method disable_tracing() in the generated parser class. Tracing may be subsequently enabled by calling the method enable_tracing() in the generated parser class.

A trace function will be added when a NT or token is generated.

   final public void term() throws ParseException {

+    trace_call("term");

+    try {

     Token t;

     switch ((jj_ntk==-1)?jj_ntk_f():jj_ntk) {

     case XXX_OP:{

       jj_consume_token(XXX_OP);

       ...

       jj_consume_token(-1);

       throw new ParseException();

     }  

+    } finally {

+      trace_return("term");

+    }

   }  

DEBUG_LOOKAHEAD

This is a boolean option whose default value is false. Setting this option to true causes the parser to generate all the tracing information it does when the option DEBUG_PARSER is true, and in addition, also causes it to generated a trace of actions performed during lookahead operation.

It's valid only when LOOKAHEAD greater than 1; otherwise  it has same affection as DEBUG_PARSER.

DEBUG_TOKEN_MANAGER

This is a boolean option whose default value is false. This option is used to obtain debugging information from the generated token manager. Setting this option to true causes the token manager to generate a trace of its actions. This trace is rather large and should only be used when you have a lexical error that has been reported to you and you cannot understand why. Typically, in this situation, you can determine the problem by looking at the last few lines of this trace.

ERROR_REPORTING

This is a boolean option whose default value is true. Setting it to false causes errors due to parse errors to be reported in somewhat less detail. The only reason to set this option to false is to improve performance.

SANITY_CHECK

This is a boolean option whose default value is true. JavaCC performs many syntactic and semantic checks on the grammar file during parser generation. Some checks such as detection of left recursion, detection of ambiguity, and bad usage of empty expansions may be suppressed for faster parser generation by setting this option to false. Note that the presence of these errors (even if they are not detected and reported by setting this option to false) can cause unexpected behavior from the generated parser.

FORCE_LA_CHECK

This is a boolean option whose default value is false. This option setting controls lookahead ambiguity checking performed by JavaCC. By default (when this option is false), lookahead ambiguity checking is performed for all choice points where the default lookahead of 1 is used. Lookahead ambiguity checking is not performed at choice points where there is an explicit lookahead specification, or if the option LOOKAHEAD is set to something other than 1. Setting this option to true performs lookahead ambiguity checking at all choice points regardless of the lookahead specifications in the grammar file.

UNICODE_INPUT

This is a boolean option whose default value is false. When set to true, the generated parser uses uses an input stream object that reads Unicode files. By default, ASCII files are assumed.

This option is ignored if either of options USER_TOKEN_MANAGER, USER_CHAR_STREAM is set to true.

JAVA_UNICODE_ESCAPE

This is a boolean option whose default value is false. When set to true, the generated parser uses an input stream object that processes Java Unicode escapes (\u...) before sending characters to the token manager. By default, Java Unicode escapes are not processed.

This option is ignored if either of options USER_TOKEN_MANAGER, USER_CHAR_STREAM is set to true.

USER_CHAR_STREAM

This is a boolean option whose default value is false. The default action is to generate a character stream reader as specified by the options JAVA_UNICODE_ESCAPE and UNICODE_INPUT. The generated token manager receives characters from this stream reader. If this option is set to true, then the token manager is generated to read characters from any character stream reader of type "CharStream.java". This file is generated into the generated parser directory.

This option is ignored if USER_TOKEN_MANAGER is set to true.

USER_TOKEN_MANAGER

This is a boolean option whose default value is false. The default action is to generate a token manager that works on the specified grammar tokens. If this option is set to true, then the parser is generated to accept tokens from any token manager of type "TokenManager" - this interface is generated into the generated parser directory.

• When false: a default TokenManager is generated, and used by Parser.

• When true: no default TokenManager is generate, instead a TokenManager interface is generated, so Parser can accept any TokenManager, as long as it's an implementation of TokenManager interface.

$ cat TokenManager.java

public interface TokenManager {

  public Token getNextToken();

}

SUPPORT_CLASS_VISIBILITY_PUBLIC

This is a boolean option whose default value is true. The default action is to generate support classes (such as Token.java, ParseException.java etc) with Public visibility. If set to false, the classes will be generated with package-private visibility.

So there is no public decoration, these classes will be package-private visibility.

BUILD_PARSER

This is a boolean option whose default value is true. The default action is to generate the parser file. When set to false, the parser file is not generated. Typically, this option is set to false when you wish to generate only the token manager and use it without the associated parser.

Otherwise, no Parser class will be generated, users must provide the parser themselves.

BUILD_TOKEN_MANAGER

This is a boolean option whose default value is true. The default action is to generate the token manager file. When set to false the token manager file is not generated. The only reason to set this option to false is to save some time during parser generation when you fix problems in the parser part of the grammar file and leave the lexical specifications untouched.

Otherwise, no TokenManager will be generated, users must provide the TokenManager themselves.

TOKEN_MANAGER_USES_PARSER

This is a boolean option whose default value is false. When set to true, the generated token manager will include a field called parser that references the instantiating parser instance . The main reason for having a parser in a token manager is using some of its logic in lexical actions. This option has no effect if the STATIC option is set to true.

A Parser type member was added into TokenManager class, so it can refer to the Parser.

/** Constructor. */

-public XXXTokenManager(SimpleCharStream stream);+

+public XXXTokenManager(XXXParser parserArg, SimpleCharStream stream);

TOKEN_EXTENDS

This is a string option whose default value is "", meaning that the generated Token class will extend java.lang.Object. This option may be set to the name of a class that will be used as the base class for the generated Token class.

It will cause Token class is inherited from ${ TOKEN_EXTENDS} other than Object:

-public class Token implements java.io.Serializable {

+public class Token extends ${TOKEN_EXTENDS} implements java.io.Serializable {

TOKEN_FACTORY

This is a string option whose default value is "", meaning that Tokens will be created by calling Token.newToken(). If set the option names a Token factory class containing a public static Token newToken(int ofKind, String image) method.

It will cause Token generated in XXXParserTokenManager.java using:

-   t = Token.newToken(jjmatchedKind, curTokenImage);

+  t = ${TOKEN_FACTORY}.newToken(jjmatchedKind, curTokenImage);

COMMON_TOKEN_ACTION

This is a boolean option whose default value is false. When set to true, every call to the token manager's method "getNextToken" (see the description of the Java Compiler Compiler API) will cause a call to a used defined method "CommonTokenAction" after the token has been scanned in by the token manager. The user must define this method within the TOKEN_MGR_DECLS section. The signature of this method is:

void CommonTokenAction(Token t);

It will cause CommonTokenAction() be called within getNextToken() when a Token is returned in file XXXParserTokenManager:

public Token getNextToken() {

         …

       matchedToken = jjFillToken();

       matchedToken.specialToken = specialToken;

+     CommonTokenAction(matchedToken);

       return matchedToken;

}

And CommonTokenAction function is usually defined within TOKEN_MGR_DECLS section:

TOKEN_MGR_DECLS :

{

    void CommonTokenAction(Token t) {

        ....

    }

    ...

}

CACHE_TOKENS

This is a boolean option whose default value is false. Setting this option to true causes the generated parser to lookahead for extra tokens ahead of time. This facilitates some performance improvements. However, in this case (when the option is true), interactive applications may not work since the parser needs to work synchronously with the availability of tokens from the input stream. In such cases, it's best to leave this option at its default value.

OUTPUT_DIRECTORY

This is a string valued option whose default value is the current directory. This controls where output files are generated.

For example:

OUTPUT_DIRECTORY = "gen/com/yourcompany/yourproduct/parser";

Refer to: https://javacc.java.net/doc/javaccgrm.html