Class StringTemplateGroup

java.lang.Object
org.antlr.stringtemplate.StringTemplateGroup

public class StringTemplateGroup extends 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 Details

    • name

      protected String name
      What is the group name
    • templates

      protected Map templates
      Maps template name to StringTemplate object
    • maps

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

      protected Class templateLexerClass
      How to pull apart a template into chunks?
    • defaultTemplateLexerClass

      protected static 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 String rootDir
      Under what directory should I look for templates? If null, to look into the CLASSPATH for templates as resources.
    • nameToGroupMap

      protected static Map nameToGroupMap
      Track all groups by name; maps name to StringTemplateGroup
    • nameToInterfaceMap

      protected static 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 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 Class userSpecifiedWriter
      Normally AutoIndentWriter is used to filter output, but user can specify a new one.
    • debugTemplateOutput

      protected boolean debugTemplateOutput
    • noDebugStartStopStrings

      protected Set noDebugStartStopStrings
      The set of templates to ignore when dumping start/stop debug strings
    • attributeRenderers

      protected Map 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

      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 Details

    • StringTemplateGroup

      public StringTemplateGroup(String name, String rootDir)
      Create a group manager for some templates, all of which are at or below the indicated directory.
    • StringTemplateGroup

      public StringTemplateGroup(String name, String rootDir, Class lexer)
    • StringTemplateGroup

      public StringTemplateGroup(String name)
      Create a group manager for some templates, all of which are loaded as resources via the classloader.
    • StringTemplateGroup

      public StringTemplateGroup(String name, Class lexer)
    • StringTemplateGroup

      public StringTemplateGroup(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() ::= invalid input: '<'invalid input: '<' >> ...
    • StringTemplateGroup

      public StringTemplateGroup(Reader r, StringTemplateErrorListener errors)
    • StringTemplateGroup

      public StringTemplateGroup(Reader r, Class lexer)
    • StringTemplateGroup

      public StringTemplateGroup(Reader r, Class lexer, StringTemplateErrorListener errors)
    • 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

      public Class getTemplateLexerClass()
      What lexer class to use to break up templates. If not lexer set for this group, use static default.
    • getName

      public String getName()
    • setName

      public void setName(String name)
    • setSuperGroup

      public void setSuperGroup(StringTemplateGroup superGroup)
    • setSuperGroup

      public void setSuperGroup(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(String interfaceName)
      Indicate that this group implements this interface; load if necessary if not in the nameToInterfaceMap.
    • getSuperGroup

      public StringTemplateGroup getSuperGroup()
    • getGroupHierarchyStackString

      public String getGroupHierarchyStackString()
      Walk up group hierarchy and show top down to this group
    • getRootDir

      public String getRootDir()
    • setRootDir

      public void setRootDir(String rootDir)
    • createStringTemplate

      public StringTemplate 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

      public StringTemplate getInstanceOf(String name)
      The primary means of getting an instance of a template from this group.
    • getInstanceOf

      public StringTemplate 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.
    • 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

      public StringTemplate lookupTemplate(String name)
    • checkRefreshInterval

      protected void checkRefreshInterval()
    • loadTemplate

      protected StringTemplate loadTemplate(String name, BufferedReader r) throws IOException
      Throws:
      IOException
    • loadTemplateFromBeneathRootDirOrCLASSPATH

      protected StringTemplate loadTemplateFromBeneathRootDirOrCLASSPATH(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 String getFileNameFromTemplateName(String templateName)
      (public so that people can override behavior; not a general purpose method)
    • getTemplateNameFromFileName

      public String getTemplateNameFromFileName(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(String name, String fileName)
    • getInputStreamReader

      protected InputStreamReader getInputStreamReader(InputStream in)
    • getFileCharEncoding

      public String getFileCharEncoding()
    • setFileCharEncoding

      public void setFileCharEncoding(String fileCharEncoding)
    • defineTemplate

      public StringTemplate defineTemplate(String name, String template)
      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

      public StringTemplate defineImplicitRegionTemplate(StringTemplate enclosingTemplate, String name)
      Track all references to regions invalid input: '<'@foo()>. We automatically define as
    • getMangledRegionName

      public String getMangledRegionName(String enclosingTemplateName, String name)
      The "foo" of t() ::= "invalid input: '<'@foo()>" is mangled to "region#t#foo"
    • getUnMangledTemplateName

      public String getUnMangledTemplateName(String mangledName)
      Return "t" from "region__t__foo"
    • defineTemplateAlias

      public StringTemplate defineTemplateAlias(String name, String target)
      Make name and alias for target. Replace any previous def of name
    • isDefinedInThisGroup

      public boolean isDefinedInThisGroup(String name)
    • getTemplateDefinition

      public StringTemplate getTemplateDefinition(String name)
      Get the ST for 'name' in this group only
    • isDefined

      public boolean isDefined(String name)
      Is there *any* definition for template 'name' in this template or above it in the group hierarchy?
    • parseGroup

      protected void parseGroup(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(Class c)
      Specify a StringTemplateWriter implementing class to use for filtering output
    • getStringTemplateWriter

      public StringTemplateWriter getStringTemplateWriter(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(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(Class attributeClassType, Object renderer)
      Register a renderer for all objects of a particular type for all templates in this group.
    • getAttributeRenderer

      public AttributeRenderer getAttributeRenderer(Class attributeClassType)
      What renderer is registered for this attributeClassType for this group? If not found, as superGroup if it has one.
    • getMap

      public Map getMap(String name)
    • defineMap

      public void defineMap(String name, 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(Class lexerClass)
    • registerGroupLoader

      public static void registerGroupLoader(StringTemplateGroupLoader loader)
    • loadGroup

      public static StringTemplateGroup loadGroup(String name)
    • loadGroup

      public static StringTemplateGroup loadGroup(String name, StringTemplateGroup superGroup)
    • loadGroup

      public static StringTemplateGroup loadGroup(String name, Class lexer, StringTemplateGroup superGroup)
    • loadInterface

      public static StringTemplateGroupInterface loadInterface(String name)
    • error

      public void error(String msg)
    • error

      public void error(String msg, Exception e)
    • getTemplateNames

      public 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(String templateName)
    • 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

      public String toString()
      Overrides:
      toString in class Object
    • toString

      public String toString(boolean showTemplatePatterns)