Package 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 Description protected java.util.Map
attributeRenderers
A Mapthat 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 nameprotected static java.util.Map
nameToGroupMap
Track all groups by name; maps name to StringTemplateGroupprotected static java.util.Map
nameToInterfaceMap
Track all interfaces by name; maps name to StringTemplateGroupInterfaceprotected java.util.Set
noDebugStartStopStrings
The set of templates to ignore when dumping start/stop debug stringsprotected 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 objectprotected 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 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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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 groupprotected 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 onlyjava.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 outputvoid
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
-
-
-
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 Mapthat 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 classjava.lang.Object
-
toString
public java.lang.String toString(boolean showTemplatePatterns)
-
-