Debugging

Debugging complex and nested StringTemplate trees can be challenging. Kay Roepke is building a graphical interface similar to ANTLRWorks for StringTemplate but until then you have a number of tools that you can use.

You can ask for the enclosing template structure with StringTemplate.getEnclosingInstanceStackString() and can get the entire structure with toStructureString() that does not print the values but shows the nested structure with the attribute names.

If for some reason StringTemplate goes into an infinite loop when you try to render a template, you probably have a circular reference in your template containment hierarchy. Turning on lint mode with StringTemplate.setLintMode() will check for these cyclic references and a number of other features. This will slow down template rendering so only use this during debugging.

Added StringTemplate. getDOTForDependencyGraph() a DOT diagram showing edges from n->m where template n contains template m. It finds all direct template invocations too like <foo()> but not indirect ones like <(name)()>. This is done statically and hence StringTemplate cannot see runtime arg values on statically included templates. You get a template back that lets you reset node shape, fontsize, width, height attributes. Use removeAttribute before setting so you are sure you only get one value.

Perhaps the most potent debugging tool you have for unraveling the complex structures emitted from nested StringTemplate containment hierarchies is the use of start and stop tags that marked the beginning and end of the text generated from a particular template. Method StringTemplateGroup.emitDebugStartStopStrings() indicates whether StringTemplate should emit <templatename>...</templatename> output for templates from this group. This easily answers an important question: "what template emitted a particular piece of text in the output?" In many cases you will not want every single template to have those tags in the output. For example, in the ANTLR code generator, there is a template that indicates what the output file extension is. Clearly one does not want the file extension to have the debugging information has the code generator could not open a file with those angle brackets and so on. Here's the snippet from the code generator:

if ( EMIT_TEMPLATE_DELIMITERS ) {
	templates.emitDebugStartStopStrings(true);
	templates.doNotEmitDebugStringsForTemplate("codeFileExtension");
}

Sometimes you use or define templates improperly. Either you set an attribute that is not used or forget to set one or reference the wrong template etc... The following code snippets enable Java and C# to display template hierarchies in a tree view.

Java

I have made a toy visualization tool via that shows both the attributes and the way StringTemplate breaks up your template into chunks. It properly handles StringTemplate objects as attributes and other nested structures. Here is the way to launch a Swing frame to view your template:

StringTemplate st = ...;
StringTemplateTreeView viz = new StringTemplateTreeView("sample",st);
viz.setVisible(true);

Here is an example display:

C#

The StringTemplateViewer project is a basic visualization tool that shows both the attributes and the way StringTemplate breaks up your template into chunks. It properly handles StringTemplate objects as attributes and other nested structures. Here is the way to launch a StringTemplateTreeView form to view your template:

StringTemplate st = ...;
StringTemplateTreeView stForm = new StringTemplateTreeView("StringTemplateTreeView Example", st);
Application.Run(stForm);

Here is a snapshot. The display is associated with the fill-a-table example below.

The StringTemplateViewer tool for StringTemplate visualization is an alpha quality release. Expect all the usual problems associated with alpha quality code.