Forward Computing and Control Pty. Ltd.
WebStringTemplate V1.5.0


Class StringTemplate

  extended byorg.antlr.stringtemplate.StringTemplate
Direct Known Subclasses:

public class StringTemplate
extends java.lang.Object

A StringTemplate is a "document" with holes in it where you can stick values.

(MPF - These docs are generated directly from Terence Parr's code. They are a bit thin in places.)

StringTemplate breaks up your template into chunks of text and attribute expressions, which are by default enclosed in angle brackets: <attribute-expression>. StringTemplate ignores everything outside of attribute expressions, treating it as just text to spit out when you call StringTemplate.toString().

StringTemplate is not a "system" or "engine" or "server"; it's a lib rary with two classes of interest: StringTemplate and StringTemplat eGroup. You can directly create a StringTemplate in Java code or you can load a template from a file.

A StringTemplate describes an output pattern/language like an exemplar.

StringTemplate and associated code is released under the BSD licence. See source.

Copyright (c) 2003 Terence Parr

A particular instance of a template may have a set of attributes that you set programmatically. A template refers to these single or multi- valued attributes when writing itself out. References within a template conform to a simple language with attribute references and references to other, embedded, templates. The references are surrounded by user-defined start/stop strings (default of <...>, but $...$ works well when referencing attributes in HTML to distinguish from tags).

StringTemplateGroup is a self-referential group of StringTemplate objects kind of like a grammar. It is very useful for keeping a group of templates together. For example,'s premium and guest sites are completely separate sets of template files organized with a StringTemplateGroup. Changing "skins" is a simple matter of switching groups. Groups know where to load templates by either looking under a rootDir you can specify for the group or by simply looking for a resource file in the current class path. If no rootDir is specified, template files are assumed to be resources. So, if you reference template foo() and you have a rootDir, it looks for file rootDir/ If you don't have a rootDir, it looks for file in the CLASSPATH. note that you can use org/antlr/misc/foo() (qualified template names) as a template ref.

StringTemplateErrorListener is an interface you can implement to specify where StringTemplate reports errors. Setting the listener for a group automatically makes all associated StringTemplate objects use the same listener. For example,

  StringTemplateGroup group = new StringTemplateGroup("loutSyndiags");
     new StringTemplateErrorListener() {
        public void error(String msg, Exception e) {
           System.err.println("StringTemplate error: "+
               msg+((e!=null)?": "+e.getMessage():""));


A StringTemplate is both class and instance like in Self. Given any StringTemplate (even one with attributes filled in), you can get a new "blank" instance of it.

When you define a template, the string pattern is parsed and broken up into chunks of either String or attribute/template actions. These are typically just attribute references. If a template is embedded within another template either via setAttribute or by implicit inclusion by referencing a template within a template, it inherits the attribute scope of the enclosing StringTemplate instance. All StringTemplate instances with the same pattern point to the same list of chunks since they are immutable there is no reason to have a copy in every instance of that pattern. The only thing that differs is that every StringTemplate Java object can have its own set of attributes. Each chunk points back at the original StringTemplate Java object whence they were constructed. So, there are multiple pointers to the list of chunks (one for each instance with that pattern) and only one back ptr from a chunk to the original pattern object. This is used primarily to get the grcoup of that original so new templates can be loaded into that group.

To write out a template, the chunks are walked in order and asked to write themselves out. String chunks are obviously just written out, but the attribute expressions/actions are evaluated in light of the attributes in that object and possibly in an enclosing instance.

Field Summary
static java.lang.String VERSION
Constructor Summary
          Create a blank template with no pattern and no attributes
StringTemplate(java.util.Map initialValues)
StringTemplate(java.lang.String template)
          Create an anonymous template.
StringTemplate(StringTemplateGroup group, java.lang.String template)
          Create an anonymous template with no name, but with a group
Method Summary
 void checkForTrouble()
          Executed after evaluating a template.
 java.lang.Object convertToArrayList(java.lang.Object value)
 java.lang.String convertToString(java.lang.Object obj)
 void debug(java.lang.String msg)
 void error(java.lang.String msg)
 void error(java.lang.String msg, java.lang.Throwable e)
 java.lang.Object get(StringTemplate self, java.lang.String attribute)
          Resolve an attribute reference.
 java.util.Map getArgumentContext()
 org.antlr.stringtemplate.language.StringTemplateAST getArgumentsAST()
 java.lang.Object getAttribute(java.lang.String name)
 java.util.Map getAttributes()
 java.util.List getChunks()
          Get a list of the strings and subtemplates and attribute refs in a template.
 StringTemplateErrorListener getErrorListener()
 StringTemplateGroup getGroup()
 StringTemplate getInstanceOf()
          Return a copy of the template only; no hash tables
 StringTemplate getInstanceOfWithAttributes(java.util.Map initialValues)
          Make an instance of this template; it contains an exact copy of everything (except the attributes and enclosing instance pointer).
 java.lang.String getName()
 java.lang.String getTemplate()
 int getTemplateID()
static boolean inLintMode()
static boolean isDebugMode()
 void removeAttribute(java.lang.String name)
 void reset()
 void setArgumentContext(java.util.Map ac)
 void setArgumentsAST(org.antlr.stringtemplate.language.StringTemplateAST argumentsAST)
 void setAttribute(java.lang.String name, java.lang.Object value)
          Set an attribute for this template.
 void setAttributes(java.util.Map attributes)
static void setDebugMode(boolean debug)
 void setEnclosingInstance(StringTemplate enclosingInstance)
 void setErrorListener(StringTemplateErrorListener listener)
 void setGroup(StringTemplateGroup group)
static void setLintMode(boolean lint)
          Make StringTemplate check your work as it evaluates templates.
 void setName(java.lang.String name)
 void setTemplate(java.lang.String template)
 boolean testObjectTrue(java.lang.Object a)
          Returns false for null object, obj.toString()=="false" or obj.toString()=="" All other objects return true
 java.lang.String toDebugString()
 java.lang.String toString()
 void warning(java.lang.String msg)
 void write( out)
          Walk the chunks, asking them to write themselves out according to attribute values of 'this.attributes'.
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail


public static final java.lang.String VERSION
See Also:
Constant Field Values
Constructor Detail


public StringTemplate()
Create a blank template with no pattern and no attributes


public StringTemplate(java.util.Map initialValues)


public StringTemplate(java.lang.String template)
Create an anonymous template. It has no name just chunks (which point to this anonymous template) and attributes.


public StringTemplate(StringTemplateGroup group,
                      java.lang.String template)
Create an anonymous template with no name, but with a group

Method Detail


public java.lang.Object convertToArrayList(java.lang.Object value)


public java.lang.String convertToString(java.lang.Object obj)


public boolean testObjectTrue(java.lang.Object a)
Returns false for null object, obj.toString()=="false" or obj.toString()=="" All other objects return true


public org.antlr.stringtemplate.language.StringTemplateAST getArgumentsAST()


public void setArgumentsAST(org.antlr.stringtemplate.language.StringTemplateAST argumentsAST)


public StringTemplate getInstanceOf()
Return a copy of the template only; no hash tables


public StringTemplate getInstanceOfWithAttributes(java.util.Map initialValues)
Make an instance of this template; it contains an exact copy of everything (except the attributes and enclosing instance pointer). So the new template refers to the previously compiled chunks of this template but does not have any attribute values.


public void setEnclosingInstance(StringTemplate enclosingInstance)


public java.util.Map getArgumentContext()


public void setArgumentContext(java.util.Map ac)


public java.lang.String getName()


public void setName(java.lang.String name)


public StringTemplateGroup getGroup()


public void setGroup(StringTemplateGroup group)


public void setTemplate(java.lang.String template)


public java.lang.String getTemplate()


public void setErrorListener(StringTemplateErrorListener listener)


public StringTemplateErrorListener getErrorListener()


public void reset()


public void removeAttribute(java.lang.String name)


public void setAttribute(java.lang.String name,
                         java.lang.Object value)
Set an attribute for this template. If you set the same attribute more than once, you get a multi-valued attribute. If you send in a StringTemplate object as a value, it's enclosing instance (where it will inherit values from) is set to 'this'. This would be the normal case, though you can set it back to null after this call if you want. If you send in a List plus other values to the same attribute, they all get flattened into one List of values. If you send in an array, it is converted to a List. Works with arrays of objects and arrays of {int,float,double}.


public java.lang.Object getAttribute(java.lang.String name)


public void write( out)
Walk the chunks, asking them to write themselves out according to attribute values of 'this.attributes'. This is like evaluating or interpreting the StringTemplate as a program using the attributes. The chunks will be identical (point at same list) for all instances of this template.



public java.lang.Object get(StringTemplate self,
                            java.lang.String attribute)
Resolve an attribute reference. It can be in three possible places: 1. the attribute list for the current template 2. if self is an embedded template, somebody invoked us possibly with arguments--check the argument context 3. if self is an embedded template, the attribute list for the enclosing instance


public int getTemplateID()


public java.util.Map getAttributes()


public java.util.List getChunks()
Get a list of the strings and subtemplates and attribute refs in a template.


public void setAttributes(java.util.Map attributes)


public void error(java.lang.String msg)


public void warning(java.lang.String msg)


public void debug(java.lang.String msg)


public void error(java.lang.String msg,
                  java.lang.Throwable e)


public static void setLintMode(boolean lint)
Make StringTemplate check your work as it evaluates templates. Problems are sent to error listener. Currently warns when you set attributes that are not used.


public static boolean inLintMode()


public static boolean isDebugMode()


public static void setDebugMode(boolean debug)


public void checkForTrouble()
Executed after evaluating a template. For now, checks for setting of attributes not reference.


public java.lang.String toDebugString()


public java.lang.String toString()

Forward Computing and Control Pty. Ltd.
WebStringTemplate V1.5.0


Copyright ©2003, Forward Computing and Control Pty. Ltd
ACN 003 669 994   NSW Australia,   All Rights Reserved.
WebStringTemplate and associated code is released under licence. See the source.
WebStringTemplate uses code from StringTemplates and Antlr, under licence.
See the WebStringTemplate licence file for details.