org.antlr.stringtemplate
Class StringTemplateGroup

java.lang.Object
  extended by 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.


Field Summary
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.
static StringTemplateErrorListener DEFAULT_ERROR_LISTENER
           
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 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
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)
          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
protected  void checkRefreshInterval()
           
 StringTemplate createStringTemplate()
          StringTemplate object factory; each group can have its own.
 void defineMap(java.lang.String name, java.util.Map mapping)
           
 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 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)
protected  java.io.InputStreamReader getInputStreamReader(java.io.InputStream in)
           
 StringTemplate getInstanceOf(java.lang.String name)
           
 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()
           
 java.lang.String getTemplateNameFromFileName(java.lang.String fileName)
          Convert a filename relativePath/name.st to relativePath/name.
 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)
           
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)
          Get the template called 'name' from the group.
protected  void parseGroup(java.io.Reader r)
           
 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 groupName)
           
 void setSuperGroup(StringTemplateGroup superGroup)
           
 java.lang.String toString()
           
 
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?


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


superGroup

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


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.


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().


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)
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()

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 groupName)

getSuperGroup

public StringTemplateGroup getSuperGroup()

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

public StringTemplate getInstanceOf(java.lang.String name)
                             throws java.lang.IllegalArgumentException
Throws:
java.lang.IllegalArgumentException

getEmbeddedInstanceOf

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

lookupTemplate

public StringTemplate lookupTemplate(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.

Throws:
java.lang.IllegalArgumentException

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.


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)

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)

error

public void error(java.lang.String msg)

error

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

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object


Copyright ? 2006-2008 Terence Parr