Generating Host Language BURMs

Using a tree grammar in production is typically done by generating a host language BURM. ("BURM" means "Bottom-Up Rewrite Machine," the conventional name for the pattern-matching tree walker.)

Usually you will need to generate several host language files, such as:

• The BURM implementation (a Java or C++ source file)
• The nonterminals' definitions as an enum class (a Java source file or C++ header file).
• A C++ BURM will also need a corresponding header file.

All host language generation by the JBurg3 entry point jburg.util.GenerateHostBURM. This entry point has two principal inputs, specified via the command line:

• The grammar to be translated.
• The format of the output desired.

Requirements

JBurg3 uses StringTemplate to generate its output, so the classpath required to run jburg.util.GenerateHostBURM is $JBURG_JAR:$ANTLR_JAR where ANTLR_JAR is the ANTLR (or simply StringTemplate) jar used to generate $JBURG_JAR.

Generating a Java BURM

java -cp ${JBURG_JAR}:$ANTLR_JAR jburg.util.GenerateHostBURM -grammar $GRAMMAR -templateGroup java.stg -classname $PARSER_CLASSNAME -nodeClass $NODE_CLASSNAME -nodeTypeClass $NODE_TYPE_CLASSNAME -nonterminalClass $NONTERMINAL_CLASSNAME -visitor $VISITOR_CLASSNAME -output $PARSER_FILE_PATH

• -grammar $GRAMMAR specifies the file path to the grammar XML file.
• -classname $PARSER_CLASS_NAME specifies the name to give to the generated tree parser (a.k.a. walker). It should match the name in -output $PARSER_FILE_PATH per Java conventions.
• -nodeClass $NODE_CLASSNAME specifies the class name of the node class.
• -nodeTypeClass $NODE_TYPE_CLASSNAME specifies the (enum, probably) name of the node type class.
• -nonterminalClass $NONTERMINAL_CLASSNAME specifies the name of the nonterminal class. It is best to let JBurg generate your nonterminals (it is practically required if the grammar has nested <Pattern> elements). See the next example.
• -visitor $VISITOR_CLASSNAME specifies the name of the visitor class.
• -templateGroup java.stg loads JBurg's StringTemplateGroup that emits a Java parser implementation.
• -output $PARSER_FILE_PATH specifies the file path for the generated code.

Generating Java nonterminals

This uses the javaNonterminals.stg group instead of java.stg, and the command line can omit elements that are not relevant:

java -cp ${JBURG_JAR}:$ANTLR_JAR jburg.util.GenerateHostBURM -grammar $GRAMMAR -templateGroup javaNonterminals.stg -nonterminalClass $NONTERMINAL_CLASSNAME -output $NONTERMINALS_FILE_PATH

Generating C++ Headers

This (optionally) uses one or more -include "#include <include-file.h>" specifiers to include perquisite include files.

java -cp ${JBURG_JAR}\;$ANTLR_JAR jburg.util.GenerateHostBURM -grammar $GRAMMAR -classname $PARSER_CLASSNAME -nodeClass $NODE_CLASSNAME -nonterminalClass $NONTERMINAL_CLASSNAME -nodeTypeClass $NODE_TYPE_CLASSNAME -visitor $VISITOR_CLASSNAME -templateGroup cppHeader.stg -include $HEADER_INCLUDE1 -include $HEADER_INCLUDE2 -output $HEADER_FILE_PATH

Generating C++ Nonterminals (.h file)

java -ea -cp ${JBURG_JAR}\;$ANTLR_JAR jburg.util.GenerateHostBURM -grammar $GRAMMAR -classname $PARSER_CLASSNAME -nodeClass $NODE_CLASSNAME -nonterminalClass $NONTERMINAL_CLASSNAME -nodeTypeClass $NODE_TYPE_CLASSNAME -visitor $VISITOR_CLASSNAME -templateGroup cppNonterminals.stg -output $NONTERMINAL_FILE_PATH

Generating C++ Implementation (.cpp file)

This will need to include the class header and nonterminal header files, plus any other implementation includes required. Includes are inserted in the order they're specified, so precompiled headers should be specified first.

java -cp ${JBURG_JAR}\;$ANTLR_JAR jburg.util.GenerateHostBURM -grammar $GRAMMAR -classname $PARSER_CLASSNAME -nodeClass $NODE_CLASSNAME -nonterminalClass $NONTERMINAL_CLASSNAME -nodeTypeClass $NODE_TYPE_CLASSNAME -include $PRECOMPILED_HEADERS -include $HEADER_FILE_PATH -include $IMPLEMENTATION_INCLUDE1 -visitor $VISITOR_CLASSNAME -templateGroup cppDefinition.stg -output $IMPLEMENTATION_FILE_PATH