JBurg Users' Guide

Integrating the generated BURM into your compiler

Unable to find a rule to process x(22){-1}

Installing JBurg

The compiled distribution of jburg is in the distribution's bin/jburg.jar file. The jarfile is only necessary to generate the BURM.

Generating a BURM with JBurg

First create a JBurg specification, then invoke jburg.burg.JBurgMain to generate the corresponding BURM.

Required parameters

Name of the specification
Name of the output file

Optional parameters

-g debugging flag
When -g is set, the generated BURM contains debugging code.

Example ANT task that generates a BURM

	<target name="reducer">
		<java classname="jburg.burg.JBurgMain" failonerror="yes" fork="yes" dir="reducer">
			<arg value="MyLanguage.jbg"/>
			<arg value="MyLanguageTreeParser.java"/>
			<!-- <arg value="-g"/> -->
			<classpath>
				<pathelement path="${jburg.jar}"/>
				<pathelement path="${ANTLR.jar}"/>
			</classpath>
		</java>
	</target>

Integrating the generated BURM into your compiler

Required data structures

JBurg's generated BURMs work on a n-ary tree generated by other passes of the compiler. The object class that represents a tree node (the "INode class") must provide the following methods:

int getOperator()
Returns: a numeric designation of the node's operator type (e.g., PLUS). The generated BURM can implement multiple interfaces that contain symbolic names for these operators.
int getArity()
Returns: The number of children this INode has. Children should be presented as a densely indexed sequence.
INode class getNthChild(int index)
Returns: This INode' child at position index.

Setting properties in the generated BURM

Use the BURMProperty JBurg specification directive to include a property in your generated BURM. For example, to include a BCEL ClassGen object as the property classGen:

BURMProperty org.apache.bcel.generic.ClassGen classGen;

JBurg will include a field of the specified type and get/set methods.

Debugging your generated BURM

Debugging a BURM is not too different from debugging any other Java code. The theory page will help you understand the structure and control flow of the BURM.

Usual BURM failure modes

Unable to find a rule to process x(22){-1}

The BURM throws this exception if it cannot find any rule to match a particular node. The elements of the diagnostic line are:

Unable to find a rule to process x(22){-1}
This is the INode's string representation of itself, from the INode's toString() method.
Unable to find a rule to process x(22){-1}
This is the INode's operator, from the INode's getOperator() method.
Unable to find a rule to process x(22){-1}
This is the goal state the BURM was attempting to satisfy. Goal state -1 tells the BURM to "use any available goal."

The most common causes of this exception are:

"Type conversion" problems.
For example, suppose the BURM is trying to reduce a + 1 and it has the following rules:
```
	int_value = PLUS(int_value, int_value): 1 { ... }
	int_value = INTEGER_LITERAL(void): 1 { ... }
	obj_value = IDENTIFIER(void) : 5 { ... }
	
```
In this case, the BURM will not be able to match the PLUS pattern, because there is no rule that allows PLUS to accept an object and an int.
The solution is to add a rule that allows the BURM to transform an object into an int:
```
	int_value = obj_value: 5
	{
		//  Call Integer.parseInt(obj.toString)), or something similar.
	}
	
```
Omitting a rule to handle a particular node type.

BURM debug option output

Your BURM will support emitting XML-formatted debugging information if you generate it with the JBurg -g command-line switch.

Debugging output can be written by including a default error handler, for example:

/* * Error recovery routine: deduce what we can from the problem * tree, then abort this BURM with an exception that the caller * can catch and report. */ DefaultErrorHandler { dump(p, "/tmp/failedBurm.xml"); throw new IllegalStateException("see debugging output in /tmp/failedBurm.xml"); }

Build ErrorAnalyzer.jar from the ant build target:
ant ErrorAnalyzer.jar and then run the error analyzer against the debugging output:
java -jar lib/ErrorAnalyzer.jar /tmp/failedBurm.xml

Debug Information

The error analyzer presents the annotated tree that caused the failure.

Notes on modifying JBurg

Rebuilding JBurg

JBurg's build is ant-based. The default ant target compiles the Java files and builds jburg.jar.

The files that make up JBurg are:

The ANTLR grammar, which also contains JBurg's main() method, in grammars/jburg.g.
Java files generated by ANTLR are:
- JBurgANTLRLexer.java
- JBurgParser.java
- JBurgTokenTypes.java
JBurgGenerator.java
JBurgGenerator.java contains the code that creates the actual BURM.