Package org.antlr.stringtemplate
Class StringTemplateGroup
java.lang.Object
org.antlr.stringtemplate.StringTemplateGroup
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
FieldsModifier and TypeFieldDescriptionprotected Map
A Mapinvalid input: '<'Class,Object> that allows people to register a renderer for a particular kind of object to be displayed for any template in this group.protected boolean
static StringTemplateErrorListener
protected static Class
You can set the lexer once if you know all of your groups use the same separator.protected List
Keep track of all interfaces implemented by this group.protected long
protected StringTemplateErrorListener
Where to report errors.protected Map
Maps map names to HashMap objects.protected String
What is the group nameprotected static Map
Track all groups by name; maps name to StringTemplateGroupprotected static Map
Track all interfaces by name; maps name to StringTemplateGroupInterfaceprotected Set
The set of templates to ignore when dumping start/stop debug stringsprotected static final StringTemplate
Used to indicate that the template doesn't exist.protected int
How long before tossing out all templates in seconds.protected String
Under what directory should I look for templates? If null, to look into the CLASSPATH for templates as resources.protected StringTemplateGroup
Are we derived from another group? Templates not found in this group will be searched for in the superGroup recursively.protected Class
How to pull apart a template into chunks?protected Map
Maps template name to StringTemplate objectprotected boolean
When templates are files on the disk, the refresh interval is used to know when to reload.protected Class
Normally AutoIndentWriter is used to filter output, but user can specify a new one. -
Constructor Summary
ConstructorsConstructorDescriptionCreate a group from the template group defined by a input stream.StringTemplateGroup
(Reader r, Class lexer) StringTemplateGroup
(Reader r, Class lexer, StringTemplateErrorListener errors) StringTemplateGroup
(Reader r, 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
(Reader r, StringTemplateErrorListener errors) StringTemplateGroup
(String name) Create a group manager for some templates, all of which are loaded as resources via the classloader.StringTemplateGroup
(String name, Class lexer) StringTemplateGroup
(String name, String rootDir) Create a group manager for some templates, all of which are at or below the indicated directory.StringTemplateGroup
(String name, String rootDir, Class lexer) -
Method Summary
Modifier and TypeMethodDescriptionprotected void
StringTemplate object factory; each group can have its own.defineImplicitRegionTemplate
(StringTemplate enclosingTemplate, String name) Track all references to regions invalid input: '<'@foo()>.void
Define a map for this group; not thread safe...do not keep adding these while you reference them.defineRegionTemplate
(String enclosingTemplateName, String regionName, String template, int type) Track all references to regions invalid input: '<'@foo>...invalid input: '<'@end> or invalid input: '<'@foo()>.defineRegionTemplate
(StringTemplate enclosingTemplate, String regionName, String template, int type) Track all references to regions invalid input: '<'@foo>...invalid input: '<'@end> or invalid input: '<'@foo()>.defineTemplate
(String name, String template) Define an examplar template; precompiled and stored with no attributes.defineTemplateAlias
(String name, String target) Make name and alias for target.void
doNotEmitDebugStringsForTemplate
(String templateName) void
emitDebugStartStopStrings
(boolean emit) Indicate whether ST should emit... strings for debugging around output for templates from this group.void
void
void
void
getAttributeRenderer
(Class attributeClassType) What renderer is registered for this attributeClassType for this group? If not found, as superGroup if it has one.getEmbeddedInstanceOf
(StringTemplate enclosingInstance, String name) getFileNameFromTemplateName
(String templateName) (public so that people can override behavior; not a general purpose method)Walk up group hierarchy and show top down to this groupprotected InputStreamReader
getInstanceOf
(String name) The primary means of getting an instance of a template from this group.getInstanceOf
(String name, 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, String name) A support routine that gets an instance of name knowing which ST encloses it for error messages.getMangledRegionName
(String enclosingTemplateName, String name) The "foo" of t() ::= "invalid input: '<'@foo()>" is mangled to "region#t#foo"getName()
int
return an instance of a StringTemplateWriter that spits output to w.getTemplateDefinition
(String name) Get the ST for 'name' in this group onlyWhat lexer class to use to break up templates.getTemplateNameFromFileName
(String fileName) Convert a filename relativePath/name.st to relativePath/name.getUnMangledTemplateName
(String mangledName) Return "t" from "region__t__foo"void
implementInterface
(String interfaceName) Indicate that this group implements this interface; load if necessary if not in the nameToInterfaceMap.void
Just track the new interface; check later.boolean
Is there *any* definition for template 'name' in this template or above it in the group hierarchy?boolean
isDefinedInThisGroup
(String name) static StringTemplateGroup
static StringTemplateGroup
loadGroup
(String name, Class lexer, StringTemplateGroup superGroup) static StringTemplateGroup
loadGroup
(String name, StringTemplateGroup superGroup) static StringTemplateGroupInterface
loadInterface
(String name) protected StringTemplate
loadTemplate
(String name, BufferedReader r) protected StringTemplate
loadTemplate
(String name, String fileName) protected StringTemplate
Load a template whose name is derived from the template filename.lookupTemplate
(String name) lookupTemplate
(StringTemplate enclosingInstance, String name) Get the template called 'name' from the group.protected void
parseGroup
(Reader r) static void
registerDefaultLexer
(Class lexerClass) static void
void
registerRenderer
(Class attributeClassType, Object renderer) Register a renderer for all objects of a particular type for all templates in this group.void
setAttributeRenderers
(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
(String fileCharEncoding) void
void
setRefreshInterval
(int refreshInterval) How often to refresh all templates from disk.void
setRootDir
(String rootDir) void
Specify a StringTemplateWriter implementing class to use for filtering outputvoid
setSuperGroup
(String superGroupName) Called by group parser when ": supergroupname" is found.void
setSuperGroup
(StringTemplateGroup superGroup) toString()
toString
(boolean showTemplatePatterns) protected void
verify that this group satisfies its interfaces
-
Field Details
-
name
What is the group name -
templates
Maps template name to StringTemplate object -
maps
Maps map names to HashMap objects. This is the list of maps defined by the user like typeInitMap ::= ["int":"0"] -
templateLexerClass
How to pull apart a template into chunks? -
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
Under what directory should I look for templates? If null, to look into the CLASSPATH for templates as resources. -
nameToGroupMap
Track all groups by name; maps name to StringTemplateGroup -
nameToInterfaceMap
Track all interfaces by name; maps name to StringTemplateGroupInterface -
superGroup
Are we derived from another group? Templates not found in this group will be searched for in the superGroup recursively. -
interfaces
Keep track of all interfaces implemented by this group. -
templatesDefinedInGroupFile
protected boolean templatesDefinedInGroupFileWhen 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
Normally AutoIndentWriter is used to filter output, but user can specify a new one. -
debugTemplateOutput
protected boolean debugTemplateOutput -
noDebugStartStopStrings
The set of templates to ignore when dumping start/stop debug strings -
attributeRenderers
A Mapinvalid input: '<'Class,Object> 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
Where to report errors. All string templates in this group use this error handler by default. -
DEFAULT_ERROR_LISTENER
-
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 refreshIntervalInSecondsHow long before tossing out all templates in seconds. -
lastCheckedDisk
protected long lastCheckedDisk
-
-
Constructor Details
-
StringTemplateGroup
Create a group manager for some templates, all of which are at or below the indicated directory. -
StringTemplateGroup
-
StringTemplateGroup
Create a group manager for some templates, all of which are loaded as resources via the classloader. -
StringTemplateGroup
-
StringTemplateGroup
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() ::= invalid input: '<'invalid input: '<' >> ... -
StringTemplateGroup
-
StringTemplateGroup
-
StringTemplateGroup
-
StringTemplateGroup
public StringTemplateGroup(Reader r, 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 invalid input: '<'...>, for example.
-
-
Method Details
-
getTemplateLexerClass
What lexer class to use to break up templates. If not lexer set for this group, use static default. -
getName
-
setName
-
setSuperGroup
-
setSuperGroup
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
Just track the new interface; check later. Allows dups, but no biggie. -
implementInterface
Indicate that this group implements this interface; load if necessary if not in the nameToInterfaceMap. -
getSuperGroup
-
getGroupHierarchyStackString
Walk up group hierarchy and show top down to this group -
getRootDir
-
setRootDir
-
createStringTemplate
StringTemplate object factory; each group can have its own. -
getInstanceOf
protected StringTemplate getInstanceOf(StringTemplate enclosingInstance, String name) throws IllegalArgumentException A support routine that gets an instance of name knowing which ST encloses it for error messages.- Throws:
IllegalArgumentException
-
getInstanceOf
The primary means of getting an instance of a template from this group. -
getInstanceOf
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, String name) throws IllegalArgumentException - Throws:
IllegalArgumentException
-
lookupTemplate
public StringTemplate lookupTemplate(StringTemplate enclosingInstance, String name) throws 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:
IllegalArgumentException
-
lookupTemplate
-
checkRefreshInterval
protected void checkRefreshInterval() -
loadTemplate
- Throws:
IOException
-
loadTemplateFromBeneathRootDirOrCLASSPATH
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 so that people can override behavior; not a general purpose method) -
getTemplateNameFromFileName
Convert a filename relativePath/name.st to relativePath/name. (public so that people can override behavior; not a general purpose method) -
loadTemplate
-
getInputStreamReader
-
getFileCharEncoding
-
setFileCharEncoding
-
defineTemplate
Define an examplar template; precompiled and stored with no attributes. Remove any previous definition. -
defineRegionTemplate
public StringTemplate defineRegionTemplate(String enclosingTemplateName, String regionName, String template, int type) Track all references to regions invalid input: '<'@foo>...invalid input: '<'@end> or invalid input: '<'@foo()>. -
defineRegionTemplate
public StringTemplate defineRegionTemplate(StringTemplate enclosingTemplate, String regionName, String template, int type) Track all references to regions invalid input: '<'@foo>...invalid input: '<'@end> or invalid input: '<'@foo()>. -
defineImplicitRegionTemplate
Track all references to regions invalid input: '<'@foo()>. We automatically define as -
getMangledRegionName
The "foo" of t() ::= "invalid input: '<'@foo()>" is mangled to "region#t#foo" -
getUnMangledTemplateName
Return "t" from "region__t__foo" -
defineTemplateAlias
Make name and alias for target. Replace any previous def of name -
isDefinedInThisGroup
-
getTemplateDefinition
Get the ST for 'name' in this group only -
isDefined
Is there *any* definition for template 'name' in this template or above it in the group hierarchy? -
parseGroup
-
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
-
getErrorListener
-
setStringTemplateWriter
Specify a StringTemplateWriter implementing class to use for filtering output -
getStringTemplateWriter
return an instance of a StringTemplateWriter that spits output to w. If a writer is specified, use it instead of the default. -
setAttributeRenderers
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
Register a renderer for all objects of a particular type for all templates in this group. -
getAttributeRenderer
What renderer is registered for this attributeClassType for this group? If not found, as superGroup if it has one. -
getMap
-
defineMap
Define a map for this group; not thread safe...do not keep adding these while you reference them. -
registerDefaultLexer
-
registerGroupLoader
-
loadGroup
-
loadGroup
-
loadGroup
public static StringTemplateGroup loadGroup(String name, Class lexer, StringTemplateGroup superGroup) -
loadInterface
-
error
-
error
-
getTemplateNames
-
emitDebugStartStopStrings
public void emitDebugStartStopStrings(boolean emit) Indicate whether ST should emit... strings for debugging around output for templates from this group. -
doNotEmitDebugStringsForTemplate
-
emitTemplateStartDebugString
public void emitTemplateStartDebugString(StringTemplate st, StringTemplateWriter out) throws IOException - Throws:
IOException
-
emitTemplateStopDebugString
public void emitTemplateStopDebugString(StringTemplate st, StringTemplateWriter out) throws IOException - Throws:
IOException
-
toString
-
toString
-