Settings Reference¶

Settings configure code generation. They are written at the top of the grammar file, before any productions, one per line.

Note

The settings and defaults in this chapter were verified against the CongoCC source (AppSettings.java). Because CongoCC is released as a rolling build, treat a setting marked here against a date as current as of that date.

Writing settings¶

A setting is a name, an optional value, and a semicolon. The name is case-insensitive. The value may be omitted for a boolean (a bare name means true):

FAULT_TOLERANT;                       // boolean shorthand for = true
SMART_NODE_CREATION = false;          // boolean
TAB_SIZE = 4;                         // integer
PARSER_PACKAGE = org.example.lang;    // package name
DEFAULT_LEXICAL_STATE = JSON;         // bare identifier
EXTRA_TOKENS = INDENT, DEDENT;        // comma-separated list

An unrecognized setting is not an error; CongoCC emits a warning — “The option X is not recognized and will be ignored.” — and continues. A few settings can also be supplied or overridden on the command line; see Invocation.

Naming and output¶

BASE_NAME: String. Default: derived from the grammar file name. Base for the generated class names — BASE_NAME = Foo yields FooParser and FooLexer.
PARSER_CLASS: String. Default: <BASE_NAME>Parser. Name of the generated parser class.
LEXER_CLASS: String. Default: <BASE_NAME>Lexer. Name of the generated lexer class.
PARSER_PACKAGE: String. Default: the lower-cased parser class name. Package for the parser and lexer.
NODE_PACKAGE: String. Default: <PARSER_PACKAGE>.ast. Package for the generated syntax-tree node classes.
ROOT_API_PACKAGE: Package name. Default: unset. When this is set, we do not generate base API such as Node (with its sub-interfaces Node.TerminalNode and Node.NodeType) but, rather, the code generated from this grammar piggy-backs off of the base Node API generated by another grammar. This setting specifies the PARSER_PACKAGE of that other grammar. This allows various sub-projects (each with their own CongoCC grammar) to share a common root Node ancestor, which means that the various nodes generated by different parsers can co-exist in a single parse tree. (This is simply not possible otherwise, since, in order for basic node traversal API to work, such as Node getParent() the node subclasses have to have the common Node ancestor.) When this option is in effect, we also re-use the TokenSource and ParseException classes from the other grammar’s ROOT_API_PACKAGE. For more detailed information on this, see this post from the discussion forum (NB: This whole issue of multiple grammar/parsers co-existing really needs its own section, I think. (JR))
BASE_NODE_CLASS: String. Default: BaseNode. Base class for generated node classes.
BASE_TOKEN_CLASS: String. Default: Token. Base class for the generated token class.
BASE_SRC_DIR: String. Default: ".". Output directory, absolute or relative to the grammar file. OUTPUT_DIRECTORY is a synonym, and the -d command-line flag sets the same thing.
NODE_PREFIX: String. Default: empty. A prefix applied to generated node class names.
COPYRIGHT_BLURB: String. Default: empty. Text inserted as a comment at the top of each generated file.

Tree building¶

See Tree Building for what these control.

TREE_BUILDING_ENABLED: Boolean. Default: true. Master switch; when false, no tree-building code is generated and the other tree settings are ignored (with a warning).
TREE_BUILDING_DEFAULT: Boolean. Default: true. Whether the parser builds a tree unless turned off at run time.
TOKENS_ARE_NODES: Boolean. Default: true. Whether tokens are included in the tree as terminal nodes.
UNPARSED_TOKENS_ARE_NODES: Boolean. Default: false. Whether unparsed (special) tokens, such as comments, are included as nodes. Requires TOKENS_ARE_NODES. SPECIAL_TOKENS_ARE_NODES is a legacy synonym read only as a fallback.
SMART_NODE_CREATION: Boolean. Default: true. When true, a production creates a node only if more than one node is on the stack, so trivial single-child productions do not add a level to the tree.
NODE_DEFAULT_VOID: Boolean. Default: false. When true, productions build no node unless they explicitly request one with a # descriptor.
NODE_USES_PARSER: Boolean. Default: false. Generates node classes that hold a reference to the parser.

Lexical¶

See Lexical Specification and Advanced Tokenization.

DEFAULT_LEXICAL_STATE: Identifier. Default: DEFAULT. The lexical state the lexer starts in.
IGNORE_CASE: Boolean. Default: false. Makes the entire lexer case-insensitive. (Case can also be ignored per token production with [IGNORE_CASE].)
REQUIRE_TOKEN_DECLARATION: Boolean. Default: false. When true, every token must be declared in a token production; an undeclared string literal used in a production is an error rather than an implicit token.

Added 2026-06-10.
DEACTIVATE_TOKENS: List. Default: none. Token names that start out inactive and must be switched on with ACTIVATE_TOKENS during parsing.
EXTRA_TOKENS: List. Default: none. Synthetic token types not produced by the lexical grammar (for example INDENT/DEDENT inserted by a token hook). An entry may name its class as NAME#ClassName.
TOKEN_CHAINING: Boolean. Default: false (auto-enabled if the grammar uses preInsert ). Allows synthetic tokens to be chained into the token stream.
LEXER_USES_PARSER: Boolean. Default: false. Generates a lexer that holds a reference to the parser, for tightly coupled context-sensitive lexing.

Output text formatting¶

TAB_SIZE: Integer. Default: 1. Width to which tab characters are expanded in generated output. TABS_TO_SPACES is a synonym.
PRESERVE_TABS: Boolean. Default: true unless a tab size is set. Keeps tab characters instead of expanding them.
PRESERVE_LINE_ENDINGS: Boolean. Default: false. Preserves the input’s line endings instead of normalizing them.
ENSURE_FINAL_EOL: Boolean. Default: false. Appends a newline to the input to be parsed (if it is not already there.)
TERMINATING_STRING: String. Default: empty (or "\n" when ENSURE_FINAL_EOL is set). A string appended to the input to be parsed. (If it is not already present.)

Parsing behavior¶

USE_CHECKED_EXCEPTION: Boolean. Default: false. Whether the generated ParseException is a checked exception.
LEGACY_GLITCHY_LOOKAHEAD: Boolean. Default: false. Restores the quirky lookahead behavior of legacy JavaCC, for grammars that depended on it. See Appendix: Legacy Mapping.
ASSERT_APPLIES_IN_LOOKAHEAD: Boolean. Default: false. Whether a plain ASSERT is also evaluated during lookahead (ENSURE always is). See Disambiguation.
USES_PREPROCESSOR: Boolean. Default: false (true when C_CONTINUATION_LINE is set). Enables the preprocessor. See The Grammar File.
C_CONTINUATION_LINE: Boolean. Default: false. Honors C-style backslash line continuations in the preprocessor.

Fault tolerance¶

See Fault-Tolerant Parsing.

FAULT_TOLERANT: Boolean. Default: false. Enables the experimental fault-tolerant parsing mode.
FAULT_TOLERANT_DEFAULT: Boolean. Default: true. When fault tolerance is enabled, whether it is on by default at run time.

Testing¶

TEST_PRODUCTION: Identifier. Default: none. The production used as the entry point by the generated self-test harness.
TEST_EXTENSION: String. Default: none. The file extension the self-test harness uses to find test inputs.

Target-language options¶

JAVA_UNICODE_ESCAPE: Boolean. Default: false. (Java) Processes \u escapes in the input stream the way legacy JavaCC’s JavaCharStream did.

Experimental and advanced¶

Settings whose names begin with X_ are experimental and may change without notice.

X_JTB_PARSE_TREE: Boolean. Default: false. Experimental alternate parse-tree mode.
X_SYNTHETIC_NODES_ENABLED: Boolean. Default: false. Experimental synthetic-node generation.

Deprecated and ignored¶

JDK_TARGET: Deprecated and has no effect; setting it produces the warning “Option JDK_TARGET is deprecated and currently has no effect. (It never did!)”.
NODE_CLASS: Accepted for backward compatibility but unused; use BASE_NODE_CLASS instead.
TOKEN_MANAGER_USES_PARSER: Accepted for backward compatibility but unused — the legacy name for the lexer was the “token manager”. Use LEXER_USES_PARSER instead.

The many configuration options of legacy JavaCC that CongoCC removed entirely — STATIC, a global LOOKAHEAD, the ambiguity-check options, and others — are listed with their replacements in Appendix: Legacy Mapping.