ANTLR 4 and StringTemplate 4 - using tree walker with templates

Question

Disclaimer: I never used Java before last month, and I had never heard of ANTLR or StringTemplate before then either. For my internship this summer I was given a project using tools that nobody else at the company has ever used. Everyone "has faith in me" that I will "figure it out." Hence the huge gaps in my understanding. I love this project and I've learned a ton, so don't take this as complaining. I just want to make it work.

Right now I'm working on a pretty printer proof of concept for an old domain-specific language. My ANTLR grammar is producing nice parse trees, and I'm able to output simple StringTemplate examples like the ones in the introduction.

Say I have an simple template in my .stg file:

module(type, name, content) ::= "<type> MODULE <name>; <content>; END MODULE."

In Java I'm able to use add() to set the values for each of the template arguments:

STGroup g = new STGroupFile("example.stg");
ST st = g.getInstanceOf("module");
st.add("type", "MAIN");
st.add("name", "test");
st.add("content", "abc");
System.out.println(st.render()); 
// prints "MAIN MODULE test; abc; END MODULE."

How do I get ANTLR and ST to read in a text file and produce pretty-printed output?

MAIN MODULE test;
abc;
END MODULE.

Should become

MAIN MODULE test; abc; END MODULE.

For example. (That's not how I plan to format all the output, don't worry. It'll pretty print much prettier than that.)

In this answer I learned that ANTLR 4 generates walkers automatically. Assuming my ANTLR grammar is correct/well-written, how do I match up the ANTLR rules/tokens to my template arguments to generate output from an input text file?

If I missed it in the documentation somewhere let me know. There are much fewer examples of ANTLR 4 and ST 4 than the previous versions.

Answer 1

Given a parser rule

r : a b c ;

the generated parse-tree will contain a node rContext with child nodes aContext, bContext, cContex, each potentially having further child nodes, for each instance in the input stream where the rule is matched.

The walk will produce the series of listener (or visitor) calls

enterR
enterA
....
exitA
enterB
....
exitB
enterC
....
exitC
exitR

Each call contains a reference to the instance context within the parse-tree, giving access to the actual values that could be passed to ST in prefix/suffix order relative to intervening child nodes.

Where simple prefix/suffix access ordering alone is not sufficient (or undesirably complex), use one or more prior parse-tree walks to analyze the more complex nodes and annotate the node instances with the analysis products. In the final output walk, reference the analysis products for the values to pass to ST.

Depending on actual circumstances, it would not be unusual for the analysis of a node to collect values from its children, pass the lot to a template for detail expansion, formatting, etc, and store the result as a node annotation string pending output in the final output walk.

Update

To annotate parse-tree nodes, you can use ParseTreeProperty.

Where the annotation set becomes more than 'trivial', a typical option is to associate a node-type specific 'decorator' class instance with a parse-tree node/context instance largely as a better data container. Of course, the node-type specific methods can then be embedded into their corresponding decorator classes to keep concerns nicely separated.

The listener methods become something like this:

public void exitNodeB(NodeBContext ctx) {
    super.exitNodeB(ctx);
    NodeBDescriptor descriptor = (NodeBDescriptor) getDescriptor(ctx);
    if (analysisPhase) {
        descriptor.process(); // node-type specific analysis
    } else {
        descriptor.output();  // node-type specific output generation
    }
}

The specifics of when to analyze (on enter, exit, or both) and when to output will be dependent on the particular application. Implement to suit your purposes.