JBurg2 Reference

JBurg Reference

• JBurg Reference
• Invocation
  • Command-line options
  • Building with Apache Ant
• JBurg Specification Elements
  • Directives
    • Language
    • package
    • extends
    • header
    • INodeType
    • NodeType
    • INodeAdapter
    • Inline INode adapter
    • Get/Set Annotation
    • OpcodeType
    • NonterminalType
    • DefaultErrorHandler
    • VolatileCostFunctions
    • Constant
  • Members
  • @Include
  • Macro Substitution
• Rules
  • Pattern Rules
    • Pattern Match: Subtree with Children
    • Pattern Match: Subtree with no Children (Leaf)
    • Pattern Match: Subtree with Variadic Children
  • Transformation Rules
    • Simple Transformation Rule
    • General Transformation Rule
  • Reduction Actions
    • Inline Reduction Action
    • Reduction Action Specified via JBurg.Reduction
    • Reduction Action with a Prologue
  • Cost Expressions
    • Cost as an Integer Literal
    • Cost as a reference to a JBurg.Constant or a field
    • Cost Computed via Function Call

Invocation

java -jar jburg.jar [options] specificationFile

Command-line options

Commonly used options

• -g : generate debugging code
• -outputdir : emit the BURM in the specified directory
• -inputdir : read the specification from the specified directory
• -outputfile : emit the BURM into the specified file

All command-line options

Building with Apache Ant

JBurg integrates well into ant builds via a jburg macrodef.

JBurg Specification Elements

Directives

Language

Optional. Specifies the generated code's implementation language. Default is Java.

@Language Cpp;

package

Optional, Java-only. Specifies a package for the BURM.

@Package jburg.tutorial.first;

extends

Optional. Specifies a base class for the BURM.

@Extends BaseBURM; // Optional

header

Optional. Copies the contents of its block into the header of the generated class.

// C++ header
@Header {
    #include "support.h"
}

// Java header
@Header {
    import java.util.Map;
}

INodeType

Required. Specifies the type of the input tree nodes.

@INodeType CommonTree;  // Use ANTLR AST nodes as the i-node type

NodeType

Optional, may be specified multiple times.
Specifies that nodes matching a particular pattern are of the designated type. The code emitters implement this via a C-style cast.

@NodeType INT = burmTest.LiteralIntNode;

INodeAdapter

Optional. Use the specified class to emit logic to query the input tree.
See also working with I-nodes in JBurg2.

@INodeAdapter jburg.burg.inode.Antlr3JavaAdapter;

Inline INode adapter

Optional. Use the three logic snippets given to query the input tree.

@GetINodeOperator(x) {
    return x->getIRElementType();
}

@GetINodeCount(x) {
    return x->getIRElementChildCount();
}

@GetINodeChild(x,index) {
    return x->getIRElementChild(index);
}

Get/Set Annotation

Optional. By default, the first 'labeling' pass builds an annotation tree that uses a distinct annotation object for each i-node in the input; but if the i-nodes have a way to store and retrieve the annotations, they can in many instances be shared.

@SetAnnotation(p, SemanticAnnotation* anno) {
    p->setAnnotation(anno);
}

@GetAnnotation(p) {
    return (JBurgAnnotation<IRRef>*)p->getAnnotation();
}

OpcodeType

Optional, default is 'int' on most targets. Specifies the type of the opcodes, which may be the target platform's enumeration type, e.g., enum.

@OpcodeType ASTNodeID;

NonterminalType

Optional. By default, JBurg builds a set of integer constants to code nonterminal types; this directive specifies an enumeration that supplies nonterminal types.

@NonterminalType burmTest.NonterminalTypes;

DefaultErrorHandler

Optional. By default, a call to reduce() on a tree with no cover for the desired nonterminal state will throw an exception; this directive specifies error handling logic.

Note that it's still usually necessary to throw an exception, since there's no restart logic in the BURM; but if the error handler can in some way modify the tree to allow a subsequent analysis to succeed, the caller could catch the exception and restart the labeling pass.

@DefaultErrorHandler {
    // p refers to the annotation object at
    // the root of the unreducible subtree.
    new UnknownTreeHandler().analyze(p);
}

See the debugging section for details.

VolatileCostFunctions

Optional. Specifies cost functions whose results should not be cached.

@VolatileCostFunctions volatileCost1, volatileCost2;

Constant

Optional, may be specified more than once. Defines a manifest constant for the BURG; this helps the BURG do more dynamic programming at compiler-compile time, i.e., free money.

@Constant ERROR_TRAP = 268435456;

Members

Optional, may be specified more than once. The code in the block is copied into the generated BURM.

@Members
{
    // Target and implementation specific code
}

@Include

More information

@Include "../arithmetic/IntegerArithmetic.jbg"

Macro Substitution

@include "IntegerArithmetic.jbg" SUBSTITUTE_ADD="ADD" SUBSTITUTE_INT="INT(void)" { "#int#"="intValue()" }

Rules

Pattern Rules

More information

Pattern Match: Subtree with Children

nonterminal = NODE_TYPE(subtreeNonterminal subtreeName, subtreeNonterminalPrime subtreeNamePrime): cost

Pattern Match: Subtree with no Children (Leaf)

nonterminal = NODE_TYPE(void): cost

Pattern Match: Subtree with Variadic Children

    nonterminal = NODE_TYPE(subtreeNonterminal subtreeName*): cost
    {reduction action}

or

    nonterminal = NODE_TYPE(subtreeNonterminal subtreeName+): cost

    {reduction action}

or

    nonterminal = NODE_TYPE(subtreeNonterminal subtreeName subtreeVariadicNonterminal subtreeName*): cost

    {reduction action}

Transformation Rules

More information

Simple Transformation Rule

nonterminalPrime = originalNonterminal;

General Transformation Rule

nonterminalPrime = originalNonterminal: cost
{reduction action};

Reduction Actions

More information

Inline Reduction Action

nonterminalName = NODE_TYPE(subtreeType subtree): cost
{
    return actionForNodeType(#nonterminalName, subtree);
}

Reduction Action Specified via JBurg.Reduction

intExpression = ADD(intExpression lhs, intExpression rhs): cost
JBurg.Reduction reducer.emitIntegerAdd(lhs, rhs);

Reduction Action with a Prologue

objExpression = FUNCTION(functionHeader header, functionBody body): cost
Prologue reducer.setUpFunctionExpression(p)
JBurg.Reduction reducer.emitFunctionExpression(__p, header, body);

Cost Expressions

More information

Cost as an Integer Literal

nonterminal = NODE_TYPE(void): 4 { reduction action; }

Cost as a reference to a JBurg.Constant or a field

nonterminal = NODE_TYPE(void): ManifestConstant { reduction action; }

Cost Computed via Function Call

nonterminal = NODE_TYPE(void): computedCost(getNode()) { reduction action; }