Migrating from JavaCC / JavaCC21

CongoCC reads current CongoCC syntax only; it does not accept legacy JavaCC grammars. Moving an existing grammar over is a two-part job: convert the syntax, then adjust for the structural differences. The exhaustive old-to-new mapping is in Appendix: Legacy Mapping; this chapter is the workflow.

Step 1: convert the syntax

CongoCC itself has no converter. Use the syntax converter included with recent JavaCC 21 builds to modernize the grammar’s surface syntax:

$ java -jar javacc-full.jar convert OldGrammar.jj

This handles the mechanical changes — the options { … } block becoming top-level settings, void Foo() : {} { … } becoming Foo : … ;, LOOKAHEAD(…) becoming SCAN / =>||, and so on.

Step 2: build with CongoCC and fix what remains

Generate the converted grammar with CongoCC and work through what conversion does not cover. The recurring items are:

  • Imports and package references in any embedded code and injections.

  • Two packages. Tree building always generates a parser package and a separate node package; code cannot go in the default (unnamed) package. Set PARSER_PACKAGE (and NODE_PACKAGE if you want something other than the default …​.ast).

  • No ``XXXConstants`` interface. Token kinds are now the TokenType enum; replace integer-constant references accordingly (Generated API).

  • The base node class lives in the node package.

  • Hand edits to generated files must move into INJECT statements (Code Injection), since regeneration overwrites the output.

Step 3: reconcile behavior

Once it builds, confirm it behaves as before:

  • If the old grammar depended on JavaCC’s original lookahead quirks, set LEGACY_GLITCHY_LOOKAHEAD = true; to reproduce them; otherwise prefer to fix the affected choice points properly with SCAN / =>||.

  • Re-run your corpus through the test harness and compare results against the old parser.

  • Expect the tree shape to differ: tree building is on by default, tokens are nodes, and smart node creation suppresses trivial wrappers. Adjust with # descriptors and the tree settings (Tree Building) until the tree matches what your application expects.

Coming from JavaCC 21

JavaCC 21 grammars are much closer to CongoCC, since CongoCC descends from it. The main adjustments are the package-layout and XXXConstants changes above, plus possibly LEGACY_GLITCHY_LOOKAHEAD; most grammars need little more.