org.antlr.stringtemplate

Class StringTemplateGroup

java.lang.Object

org.antlr.stringtemplate.StringTemplateGroup

public class StringTemplateGroup
extends java.lang.Object

Manages a group of named mutually-referential StringTemplate objects. Currently the templates must all live under a directory so that you can reference them as foo.st or gutter/header.st. To refresh a group of templates, just create a new StringTemplateGroup and start pulling templates from there. Or, set the refresh interval. Use getInstanceOf(template-name) to get a string template to fill in. The name of a template is the file name minus ".st" ending if present unless you name it as you load it. You can use the group file format also to define a group of templates (this works better for code gen than for html page gen). You must give a Reader to the ctor for it to load the group; this is general and distinguishes it from the ctors for the old-style "load template files from the disk". 10/2005 I am adding a StringTemplateGroupLoader concept so people can define supergroups within a group and have it load that group automatically.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map	attributeRenderers A Map that allows people to register a renderer for a particular kind of object to be displayed for any template in this group.
protected boolean	debugTemplateOutput
static StringTemplateErrorListener	DEFAULT_ERROR_LISTENER
protected static java.lang.Class	defaultTemplateLexerClass You can set the lexer once if you know all of your groups use the same separator.
protected java.util.List	interfaces Keep track of all interfaces implemented by this group.
protected long	lastCheckedDisk
protected StringTemplateErrorListener	listener Where to report errors.
protected java.util.Map	maps Maps map names to HashMap objects.
protected java.lang.String	name What is the group name
protected static java.util.Map	nameToGroupMap Track all groups by name; maps name to StringTemplateGroup
protected static java.util.Map	nameToInterfaceMap Track all interfaces by name; maps name to StringTemplateGroupInterface
protected java.util.Set	noDebugStartStopStrings The set of templates to ignore when dumping start/stop debug strings
protected static StringTemplate	NOT_FOUND_ST Used to indicate that the template doesn't exist.
protected int	refreshIntervalInSeconds How long before tossing out all templates in seconds.
protected java.lang.String	rootDir Under what directory should I look for templates? If null, to look into the CLASSPATH for templates as resources.
protected StringTemplateGroup	superGroup Are we derived from another group? Templates not found in this group will be searched for in the superGroup recursively.
protected java.lang.Class	templateLexerClass How to pull apart a template into chunks?
protected java.util.Map	templates Maps template name to StringTemplate object
protected boolean	templatesDefinedInGroupFile When templates are files on the disk, the refresh interval is used to know when to reload.
protected java.lang.Class	userSpecifiedWriter Normally AutoIndentWriter is used to filter output, but user can specify a new one.

Constructor Summary

Constructors

Constructor and Description
StringTemplateGroup(java.io.Reader r) Create a group from the template group defined by a input stream.
StringTemplateGroup(java.io.Reader r, java.lang.Class lexer)
StringTemplateGroup(java.io.Reader r, java.lang.Class lexer, StringTemplateErrorListener errors)
StringTemplateGroup(java.io.Reader r, java.lang.Class lexer, StringTemplateErrorListener errors, StringTemplateGroup superGroup) Create a group from the input stream, but use a nondefault lexer to break the templates up into chunks.
StringTemplateGroup(java.io.Reader r, StringTemplateErrorListener errors)
StringTemplateGroup(java.lang.String name) Create a group manager for some templates, all of which are loaded as resources via the classloader.
StringTemplateGroup(java.lang.String name, java.lang.Class lexer)
StringTemplateGroup(java.lang.String name, java.lang.String rootDir) Create a group manager for some templates, all of which are at or below the indicated directory.
StringTemplateGroup(java.lang.String name, java.lang.String rootDir, java.lang.Class lexer)

Method Summary

Methods

Modifier and Type	Method and Description
protected void	checkRefreshInterval()
StringTemplate	createStringTemplate() StringTemplate object factory; each group can have its own.
StringTemplate	defineImplicitRegionTemplate(StringTemplate enclosingTemplate, java.lang.String name) Track all references to regions <@foo()>.
void	defineMap(java.lang.String name, java.util.Map mapping) Define a map for this group; not thread safe...do not keep adding these while you reference them.
StringTemplate	defineRegionTemplate(java.lang.String enclosingTemplateName, java.lang.String regionName, java.lang.String template, int type) Track all references to regions <@foo>...<@end> or <@foo()>.
StringTemplate	defineRegionTemplate(StringTemplate enclosingTemplate, java.lang.String regionName, java.lang.String template, int type) Track all references to regions <@foo>...<@end> or <@foo()>.
StringTemplate	defineTemplate(java.lang.String name, java.lang.String template) Define an examplar template; precompiled and stored with no attributes.
StringTemplate	defineTemplateAlias(java.lang.String name, java.lang.String target) Make name and alias for target.
void	doNotEmitDebugStringsForTemplate(java.lang.String templateName)
void	emitDebugStartStopStrings(boolean emit) Indicate whether ST should emit ... strings for debugging around output for templates from this group.
void	emitTemplateStartDebugString(StringTemplate st, StringTemplateWriter out)
void	emitTemplateStopDebugString(StringTemplate st, StringTemplateWriter out)
void	error(java.lang.String msg)
void	error(java.lang.String msg, java.lang.Exception e)
AttributeRenderer	getAttributeRenderer(java.lang.Class attributeClassType) What renderer is registered for this attributeClassType for this group? If not found, as superGroup if it has one.
StringTemplate	getEmbeddedInstanceOf(StringTemplate enclosingInstance, java.lang.String name)
StringTemplateErrorListener	getErrorListener()
java.lang.String	getFileCharEncoding()
java.lang.String	getFileNameFromTemplateName(java.lang.String templateName) (public so that people can override behavior; not a general purpose method)
java.lang.String	getGroupHierarchyStackString() Walk up group hierarchy and show top down to this group
protected java.io.InputStreamReader	getInputStreamReader(java.io.InputStream in)
StringTemplate	getInstanceOf(java.lang.String name) The primary means of getting an instance of a template from this group.
StringTemplate	getInstanceOf(java.lang.String name, java.util.Map attributes) The primary means of getting an instance of a template from this group when you have a predefined set of attributes you want to use.
protected StringTemplate	getInstanceOf(StringTemplate enclosingInstance, java.lang.String name) A support routine that gets an instance of name knowing which ST encloses it for error messages.
java.lang.String	getMangledRegionName(java.lang.String enclosingTemplateName, java.lang.String name) The "foo" of t() ::= "<@foo()>" is mangled to "region#t#foo"
java.util.Map	getMap(java.lang.String name)
java.lang.String	getName()
int	getRefreshInterval()
java.lang.String	getRootDir()
StringTemplateWriter	getStringTemplateWriter(java.io.Writer w) return an instance of a StringTemplateWriter that spits output to w.
StringTemplateGroup	getSuperGroup()
StringTemplate	getTemplateDefinition(java.lang.String name) Get the ST for 'name' in this group only
java.lang.Class	getTemplateLexerClass() What lexer class to use to break up templates.
java.lang.String	getTemplateNameFromFileName(java.lang.String fileName) Convert a filename relativePath/name.st to relativePath/name.
java.util.Set	getTemplateNames()
java.lang.String	getUnMangledTemplateName(java.lang.String mangledName) Return "t" from "region__t__foo"
void	implementInterface(java.lang.String interfaceName) Indicate that this group implements this interface; load if necessary if not in the nameToInterfaceMap.
void	implementInterface(StringTemplateGroupInterface I) Just track the new interface; check later.
boolean	isDefined(java.lang.String name) Is there *any* definition for template 'name' in this template or above it in the group hierarchy?
boolean	isDefinedInThisGroup(java.lang.String name)
static StringTemplateGroup	loadGroup(java.lang.String name)
static StringTemplateGroup	loadGroup(java.lang.String name, java.lang.Class lexer, StringTemplateGroup superGroup)
static StringTemplateGroup	loadGroup(java.lang.String name, StringTemplateGroup superGroup)
static StringTemplateGroupInterface	loadInterface(java.lang.String name)
protected StringTemplate	loadTemplate(java.lang.String name, java.io.BufferedReader r)
protected StringTemplate	loadTemplate(java.lang.String name, java.lang.String fileName)
protected StringTemplate	loadTemplateFromBeneathRootDirOrCLASSPATH(java.lang.String fileName) Load a template whose name is derived from the template filename.
StringTemplate	lookupTemplate(java.lang.String name)
StringTemplate	lookupTemplate(StringTemplate enclosingInstance, java.lang.String name) Get the template called 'name' from the group.
protected void	parseGroup(java.io.Reader r)
static void	registerDefaultLexer(java.lang.Class lexerClass)
static void	registerGroupLoader(StringTemplateGroupLoader loader)
void	registerRenderer(java.lang.Class attributeClassType, java.lang.Object renderer) Register a renderer for all objects of a particular type for all templates in this group.
void	setAttributeRenderers(java.util.Map renderers) Specify a complete map of what object classes should map to which renderer objects for every template in this group (that doesn't override it per template).
void	setErrorListener(StringTemplateErrorListener listener)
void	setFileCharEncoding(java.lang.String fileCharEncoding)
void	setName(java.lang.String name)
void	setRefreshInterval(int refreshInterval) How often to refresh all templates from disk.
void	setRootDir(java.lang.String rootDir)
void	setStringTemplateWriter(java.lang.Class c) Specify a StringTemplateWriter implementing class to use for filtering output
void	setSuperGroup(java.lang.String superGroupName) Called by group parser when ": supergroupname" is found.
void	setSuperGroup(StringTemplateGroup superGroup)
java.lang.String	toString()
java.lang.String	toString(boolean showTemplatePatterns)
protected void	verifyInterfaceImplementations() verify that this group satisfies its interfaces

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

name

protected java.lang.String name

What is the group name

templates

protected java.util.Map templates

Maps template name to StringTemplate object

maps

protected java.util.Map maps

Maps map names to HashMap objects. This is the list of maps defined by the user like typeInitMap ::= ["int":"0"]

templateLexerClass

protected java.lang.Class templateLexerClass

How to pull apart a template into chunks?

defaultTemplateLexerClass

protected static java.lang.Class defaultTemplateLexerClass

You can set the lexer once if you know all of your groups use the same separator. If the instance has templateLexerClass set then it is used as an override.

rootDir

protected java.lang.String rootDir

Under what directory should I look for templates? If null, to look into the CLASSPATH for templates as resources.

nameToGroupMap

protected static java.util.Map nameToGroupMap

Track all groups by name; maps name to StringTemplateGroup

nameToInterfaceMap

protected static java.util.Map nameToInterfaceMap

Track all interfaces by name; maps name to StringTemplateGroupInterface

superGroup

protected StringTemplateGroup superGroup

Are we derived from another group? Templates not found in this group will be searched for in the superGroup recursively.

interfaces

protected java.util.List interfaces

Keep track of all interfaces implemented by this group.

templatesDefinedInGroupFile

protected boolean templatesDefinedInGroupFile

When templates are files on the disk, the refresh interval is used to know when to reload. When a Reader is passed to the ctor, it is a stream full of template definitions. The former is used for web development, but the latter is most likely used for source code generation for translators; a refresh is unlikely. Anyway, I decided to track the source of templates in case such info is useful in other situations than just turning off refresh interval. I just found another: don't ever look on the disk for individual templates if this group is a group file...immediately look into any super group. If not in the super group, report no such template.

userSpecifiedWriter

protected java.lang.Class userSpecifiedWriter

Normally AutoIndentWriter is used to filter output, but user can specify a new one.

debugTemplateOutput

protected boolean debugTemplateOutput

noDebugStartStopStrings

protected java.util.Set noDebugStartStopStrings

The set of templates to ignore when dumping start/stop debug strings

attributeRenderers

protected java.util.Map attributeRenderers

A Map that allows people to register a renderer for a particular kind of object to be displayed for any template in this group. For example, a date should be formatted differently depending on the locale. You can set Date.class to an object whose toString(Object) method properly formats a Date attribute according to locale. Or you can have a different renderer object for each locale. These render objects are used way down in the evaluation chain right before an attribute's toString() method would normally be called in ASTExpr.write(). Synchronized at creation time.

listener

protected StringTemplateErrorListener listener

Where to report errors. All string templates in this group use this error handler by default.

DEFAULT_ERROR_LISTENER

public static StringTemplateErrorListener DEFAULT_ERROR_LISTENER

NOT_FOUND_ST

protected static final StringTemplate NOT_FOUND_ST

Used to indicate that the template doesn't exist. We don't have to check disk for it; we know it's not there.

refreshIntervalInSeconds

protected int refreshIntervalInSeconds

How long before tossing out all templates in seconds.

lastCheckedDisk

protected long lastCheckedDisk

Constructor Detail

StringTemplateGroup

public StringTemplateGroup(java.lang.String name,
                   java.lang.String rootDir)

Create a group manager for some templates, all of which are at or below the indicated directory.

StringTemplateGroup

public StringTemplateGroup(java.lang.String name,
                   java.lang.String rootDir,
                   java.lang.Class lexer)

StringTemplateGroup

public StringTemplateGroup(java.lang.String name)

Create a group manager for some templates, all of which are loaded as resources via the classloader.

StringTemplateGroup

public StringTemplateGroup(java.lang.String name,
                   java.lang.Class lexer)

StringTemplateGroup

public StringTemplateGroup(java.io.Reader r)

Create a group from the template group defined by a input stream. The name is pulled from the file. The format is group name; t1(args) ::= "..." t2() ::= << >> ...

StringTemplateGroup

public StringTemplateGroup(java.io.Reader r,
                   StringTemplateErrorListener errors)

StringTemplateGroup

public StringTemplateGroup(java.io.Reader r,
                   java.lang.Class lexer)

StringTemplateGroup

public StringTemplateGroup(java.io.Reader r,
                   java.lang.Class lexer,
                   StringTemplateErrorListener errors)

StringTemplateGroup

public StringTemplateGroup(java.io.Reader r,
                   java.lang.Class lexer,
                   StringTemplateErrorListener errors,
                   StringTemplateGroup superGroup)

Create a group from the input stream, but use a nondefault lexer to break the templates up into chunks. This is usefor changing the delimiter from the default $...$ to <...>, for example.

Method Detail

getTemplateLexerClass

public java.lang.Class getTemplateLexerClass()

What lexer class to use to break up templates. If not lexer set for this group, use static default.

getName

public java.lang.String getName()

setName

public void setName(java.lang.String name)

setSuperGroup

public void setSuperGroup(StringTemplateGroup superGroup)

setSuperGroup

public void setSuperGroup(java.lang.String superGroupName)

Called by group parser when ": supergroupname" is found. This method forces the supergroup's lexer to be same as lexer for this (sub) group.

implementInterface

public void implementInterface(StringTemplateGroupInterface I)

Just track the new interface; check later. Allows dups, but no biggie.

implementInterface

public void implementInterface(java.lang.String interfaceName)

Indicate that this group implements this interface; load if necessary if not in the nameToInterfaceMap.

getSuperGroup

public StringTemplateGroup getSuperGroup()

getGroupHierarchyStackString

public java.lang.String getGroupHierarchyStackString()

Walk up group hierarchy and show top down to this group

getRootDir

public java.lang.String getRootDir()

setRootDir

public void setRootDir(java.lang.String rootDir)

createStringTemplate

public StringTemplate createStringTemplate()

StringTemplate object factory; each group can have its own.

getInstanceOf

protected StringTemplate getInstanceOf(StringTemplate enclosingInstance,
                           java.lang.String name)
                                throws java.lang.IllegalArgumentException

A support routine that gets an instance of name knowing which ST encloses it for error messages.

Throws:

java.lang.IllegalArgumentException

getInstanceOf

public StringTemplate getInstanceOf(java.lang.String name)

The primary means of getting an instance of a template from this group.

getInstanceOf

public StringTemplate getInstanceOf(java.lang.String name,
                           java.util.Map attributes)

The primary means of getting an instance of a template from this group when you have a predefined set of attributes you want to use.

getEmbeddedInstanceOf

public StringTemplate getEmbeddedInstanceOf(StringTemplate enclosingInstance,
                                   java.lang.String name)
                                     throws java.lang.IllegalArgumentException

Throws:

java.lang.IllegalArgumentException

lookupTemplate

public StringTemplate lookupTemplate(StringTemplate enclosingInstance,
                            java.lang.String name)
                              throws java.lang.IllegalArgumentException

Get the template called 'name' from the group. If not found, attempt to load. If not found on disk, then try the superGroup if any. If not even there, then record that it's NOT_FOUND so we don't waste time looking again later. If we've gone past refresh interval, flush and look again. If I find a template in a super group, copy an instance down here

Throws:

java.lang.IllegalArgumentException

lookupTemplate

public StringTemplate lookupTemplate(java.lang.String name)

checkRefreshInterval

protected void checkRefreshInterval()

loadTemplate

protected StringTemplate loadTemplate(java.lang.String name,
                          java.io.BufferedReader r)
                               throws java.io.IOException

Throws:

java.io.IOException

loadTemplateFromBeneathRootDirOrCLASSPATH

protected StringTemplate loadTemplateFromBeneathRootDirOrCLASSPATH(java.lang.String fileName)

Load a template whose name is derived from the template filename. If there is no root directory, try to load the template from the classpath. If there is a rootDir, try to load the file from there.

getFileNameFromTemplateName

public java.lang.String getFileNameFromTemplateName(java.lang.String templateName)

(public so that people can override behavior; not a general purpose method)

getTemplateNameFromFileName

public java.lang.String getTemplateNameFromFileName(java.lang.String fileName)

Convert a filename relativePath/name.st to relativePath/name. (public so that people can override behavior; not a general purpose method)

loadTemplate

protected StringTemplate loadTemplate(java.lang.String name,
                          java.lang.String fileName)

getInputStreamReader

protected java.io.InputStreamReader getInputStreamReader(java.io.InputStream in)

getFileCharEncoding

public java.lang.String getFileCharEncoding()

setFileCharEncoding

public void setFileCharEncoding(java.lang.String fileCharEncoding)

defineTemplate

public StringTemplate defineTemplate(java.lang.String name,
                            java.lang.String template)

Define an examplar template; precompiled and stored with no attributes. Remove any previous definition.

defineRegionTemplate

public StringTemplate defineRegionTemplate(java.lang.String enclosingTemplateName,
                                  java.lang.String regionName,
                                  java.lang.String template,
                                  int type)

Track all references to regions <@foo>...<@end> or <@foo()>.

defineRegionTemplate

public StringTemplate defineRegionTemplate(StringTemplate enclosingTemplate,
                                  java.lang.String regionName,
                                  java.lang.String template,
                                  int type)

Track all references to regions <@foo>...<@end> or <@foo()>.

defineImplicitRegionTemplate

public StringTemplate defineImplicitRegionTemplate(StringTemplate enclosingTemplate,
                                          java.lang.String name)

Track all references to regions <@foo()>. We automatically define as

getMangledRegionName

public java.lang.String getMangledRegionName(java.lang.String enclosingTemplateName,
                                    java.lang.String name)

The "foo" of t() ::= "<@foo()>" is mangled to "region#t#foo"

getUnMangledTemplateName

public java.lang.String getUnMangledTemplateName(java.lang.String mangledName)

Return "t" from "region__t__foo"

defineTemplateAlias

public StringTemplate defineTemplateAlias(java.lang.String name,
                                 java.lang.String target)

Make name and alias for target. Replace any previous def of name

isDefinedInThisGroup

public boolean isDefinedInThisGroup(java.lang.String name)

getTemplateDefinition

public StringTemplate getTemplateDefinition(java.lang.String name)

Get the ST for 'name' in this group only

isDefined

public boolean isDefined(java.lang.String name)

Is there *any* definition for template 'name' in this template or above it in the group hierarchy?

parseGroup

protected void parseGroup(java.io.Reader r)

verifyInterfaceImplementations

protected void verifyInterfaceImplementations()

verify that this group satisfies its interfaces

getRefreshInterval

public int getRefreshInterval()

setRefreshInterval

public void setRefreshInterval(int refreshInterval)

How often to refresh all templates from disk. This is a crude mechanism at the moment--just tosses everything out at this frequency. Set interval to 0 to refresh constantly (no caching). Set interval to a huge number like MAX_INT to have no refreshing at all (DEFAULT); it will cache stuff.

setErrorListener

public void setErrorListener(StringTemplateErrorListener listener)

getErrorListener

public StringTemplateErrorListener getErrorListener()

setStringTemplateWriter

public void setStringTemplateWriter(java.lang.Class c)

Specify a StringTemplateWriter implementing class to use for filtering output

getStringTemplateWriter

public StringTemplateWriter getStringTemplateWriter(java.io.Writer w)

return an instance of a StringTemplateWriter that spits output to w. If a writer is specified, use it instead of the default.

setAttributeRenderers

public void setAttributeRenderers(java.util.Map renderers)

Specify a complete map of what object classes should map to which renderer objects for every template in this group (that doesn't override it per template).

registerRenderer

public void registerRenderer(java.lang.Class attributeClassType,
                    java.lang.Object renderer)

Register a renderer for all objects of a particular type for all templates in this group.

getAttributeRenderer

public AttributeRenderer getAttributeRenderer(java.lang.Class attributeClassType)

What renderer is registered for this attributeClassType for this group? If not found, as superGroup if it has one.

getMap

public java.util.Map getMap(java.lang.String name)

defineMap

public void defineMap(java.lang.String name,
             java.util.Map mapping)

Define a map for this group; not thread safe...do not keep adding these while you reference them.

registerDefaultLexer

public static void registerDefaultLexer(java.lang.Class lexerClass)

registerGroupLoader

public static void registerGroupLoader(StringTemplateGroupLoader loader)

loadGroup

public static StringTemplateGroup loadGroup(java.lang.String name)

loadGroup

public static StringTemplateGroup loadGroup(java.lang.String name,
                            StringTemplateGroup superGroup)

loadGroup

public static StringTemplateGroup loadGroup(java.lang.String name,
                            java.lang.Class lexer,
                            StringTemplateGroup superGroup)

loadInterface

public static StringTemplateGroupInterface loadInterface(java.lang.String name)

error

public void error(java.lang.String msg)

error

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

getTemplateNames

public java.util.Set getTemplateNames()

emitDebugStartStopStrings

public void emitDebugStartStopStrings(boolean emit)

Indicate whether ST should emit ... strings for debugging around output for templates from this group.

doNotEmitDebugStringsForTemplate

public void doNotEmitDebugStringsForTemplate(java.lang.String templateName)

emitTemplateStartDebugString

public void emitTemplateStartDebugString(StringTemplate st,
                                StringTemplateWriter out)
                                  throws java.io.IOException

Throws:

java.io.IOException

emitTemplateStopDebugString

public void emitTemplateStopDebugString(StringTemplate st,
                               StringTemplateWriter out)
                                 throws java.io.IOException

Throws:

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

toString

public java.lang.String toString(boolean showTemplatePatterns)