ST condensed -- API -- StringTemplateGroup

Skip to end of metadata
Go to start of metadata

Javadocs from http://www.stringtemplate.org/api/org/antlr/stringtemplate/StringTemplateGroup.html
2009-05-24. StringTemplateGroup presumably version 3.2 and current, but no date or version number shown
See annotations by GW in red, or search for [GW] to find them.

org.antlr.stringtemplate
Class StringTemplateGroup

java.lang.Object
  extended byorg.antlr.stringtemplate.StringTemplateGroup

Overview of StringTemplateGroup

Note: There are really two separate sets of constructors for this class, corresponding to two somewhat different modes of operation. The overview blurb has been expanded over the time these features were added, and some of it applies to one mode but not the other, hence some confusion.

Java doc says... [GW] Comments
Manages a group of named mutually-referential StringTemplate objects. Ie: a group of StringTemplate objects having a name field. These StringTemplates can refer to each other using these names (but are not required to refer to each other of course).
Currently the templates must all live under a directory so that you can reference them as foo.st or gutter/header.st. That's one way. Since that was written, this class has been revised to support StringTemplateGroup files (xxx.stg) which work differently.
To refresh a group of templates, just create a new StringTemplateGroup and start pulling templates from there. "Refresh" means to deal with the situation where templates have been loaded from individual *.st files, and those files have been independently changed, and now we want our StringTemplate objects to reflect the changed template texts. The comment here says to refresh the existing StringTemplate objects by creating a new StringTemplateGroup etc from scratch. (A parallel approach would work with an stg file too).
Or, set the refresh interval. ...so that the refreshing happens automatically. (Not applicable to stg files.)
Use getInstanceOf(template-name) to get a string template to fill in. Not sure if these means the caller is not supposed to directly apply the StringTemplate objects that are in the STG, but maybe the point is that the STG can act as a longer-term holder of StringTemplates that your program wants to use multiple times with different attribute values... and hence should work with copies. (Also if refresh is enabled, the templates in the STG might get disrupted?)   "Fill in" meaning "supply attributes/values to.".
The name of a template is the file name minus ".st" ending if present unless you name it as you load it. "name it as you load it":  using what method(s)?  Also this is not applicable to the xxx.stg mode of operation.
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). stg format is now getting mentioned here, which makes this intro blurb a bit muddled, since other parts don't apply to stg but aren't clear about that.
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". Ie: What distinguishes the stg-suitable constructors is that they require a Reader argument. The constructors suited to retrieving template texts from *.st files don't have that pattern.
10/2005 I am adding a StringTemplateGroupLoader concept so people can define supergroups within a group and have it load that group automatically. Hmmm. This might mean as follows:  Within a group file (xxx.stg) use the syntax
group mygroup: mysupergroup;
... to specify a supergroup to inherit from. In this case the StringTemplate library should find and load the supergroup file automatically, if your application implements a StringTemplateGroupLoader object.
   

Constructors

public class StringTemplateGroup
extends java.lang.Object
Scheme Constructor Summary   [GW] Comments
xxx.stg file The constructors in this section load the contents of a StringTemplateGroup file (from a Reader), which contains one or more template texts etc. (It's the presence of an initial Reader argument which selects a constructor from this set of overloaded constructors.) (Or a template can be added from String using StringTemplate constructors or defineTemplate).
  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.		 1 If lexer is null, uses AngleBracetTemplateLexer.
Gets group name from "group" statement in template-group text from Reader.
  StringTemplateGroup(java.io.Reader r)
          Create a group from the template group defined by a input stream.		 2 Calls 1 with subset of args
  StringTemplateGroup(java.io.Reader r, java.lang.Class lexer)
           		 3 Calls 1 with subset of args
  StringTemplateGroup(java.io.Reader r, java.lang.Class lexer, StringTemplateErrorListener errors)
           		 4 Calls 1 with subset of args
  StringTemplateGroup(java.io.Reader r, StringTemplateErrorListener errors)
           		 5 Calls 1 with subset of args
STGdir/*.st The constructors in this section prepare a StringTemplateGroup to load one or more individual StringTemplate files (xxx.st) from a directory or CLASSPATH  (Or a template can be added from a String using StringTemplate constructors or defineTemplate).
  StringTemplateGroup(java.lang.String name, java.lang.String rootDir, java.lang.Class lexer)
           		 6 If lexer is null, uses DefaultTemplateLexer (which recognizes $...$).
  StringTemplateGroup(java.lang.String name, java.lang.Class lexer)
           		 7 Calls 6 with subset of args
Also, this is the STG constructor called by StringTemplate(tmplname, 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.		 8 Calls 6 with subset of args

 
  StringTemplateGroup(java.lang.String name)
          Create a group manager for some templates, all of which are loaded as resources via the classloader.		 9 Calls 6 with subset of args.  No group dir is specified. I think "classloader" means the xxx.st files are found via java CLASSPATH.
       

Methods

Funcional area Method Summary   [GW] Comments
Normal preparation
   StringTemplate defineTemplate(java.lang.String name, java.lang.String template)
          Define an examplar template; precompiled and stored with no attributes.		 Adds a named StringTemplate object to this STG, using the template text provided, and no attributes. "Exemplar" probably means to NOT use this template per se, but to use copies from getInstanceOf(tmpname)
   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.		 Add a map to this group. (Compare this with passing a Map-implementing object to a template as an attribute.)
   StringTemplate getInstanceOf(java.lang.String name)
          The primary means of getting an instance of a template from this group.		 Get an instance of an ST for actual invocation with particular attributes. Use with StringTemplate.setAttribute
   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.		 Similar to getInstanceOf(name), but supply attributes at the same time.
Renderers
   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).		  
Output filters
   void setStringTemplateWriter(java.lang.Class c)
          Specify a StringTemplateWriter implementing class to use for filtering output		  
Settings
   void setErrorListener(StringTemplateErrorListener listener)
           		 If not set, errors go to standard error, warnings to standard out (and normally that will be the java console).
   void setFileCharEncoding(java.lang.String fileCharEncoding)              
   void setRefreshInterval(int refreshInterval)
          How often to refresh all templates from disk.		 Only for *.st files, not for group files xxx.stg.
  static void registerDefaultLexer(java.lang.Class lexerClass)
           		 Can be set once for all StringTemplateGroups. (Note singleton)
Diagnostic output
   java.lang.String toString()
           		 Diagnostic?
   java.lang.String toString(boolean showTemplatePatterns)
           		 Diagnostic? Patterns = template texts
   void doNotEmitDebugStringsForTemplate(java.lang.String templateName)
           		 Diagnostic?
   void emitDebugStartStopStrings(boolean emit)
          Indicate whether ST should emit ... strings for debugging around output for templates from this group.		 Diagnostic?
   void emitTemplateStartDebugString(StringTemplate st, StringTemplateWriter out)
           		 Diagnostic?
   void emitTemplateStopDebugString(StringTemplate st, StringTemplateWriter out)
           		 Diagnostic?
Internal
  protected  void checkRefreshInterval()
           		 Does nothing for templates from stg file.
   StringTemplate createStringTemplate()
          StringTemplate object factory; each group can have its own.		 Not intended to be part of API?
   StringTemplate defineImplicitRegionTemplate(StringTemplate enclosingTemplate, java.lang.String name)
          Track all references to regions <@foo()>.		  
   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 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.		 as = ask
   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		 Diagnostic?
  protected  java.io.InputStreamReader getInputStreamReader(java.io.InputStream in)
           		  
  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 registerGroupLoader(StringTemplateGroupLoader loader)
           		  
   void setName(java.lang.String name)
           		  
   void setRootDir(java.lang.String rootDir)
           		  
   void setSuperGroup(java.lang.String superGroupName)
          Called by group parser when ": supergroupname" is found.		  
   void setSuperGroup(StringTemplateGroup superGroup)
           		  
  protected  void verifyInterfaceImplementations()
          verify that this group satisfies its interfaces		  
 

Fields

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.		  
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.		  
(package private)  java.lang.String fileCharEncoding
          How are the files encoded (ascii, UTF8, ...)? You might want to read UTF8 for example on an ascii machine.		  
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.		 This must assume that we're not directly using the templates in the group, but have instanced them.
protected  java.lang.String rootDir
          Under what directory should I look for templates? If null, to look into the CLASSPATH for templates as resources.		 I = This StringTemplateGroup
protected  StringTemplateGroup superGroup
          Are we derived from another group? Templates not found in this group will be searched for in the superGroup recursively.		 We = This StringTemplateGroup
protected  java.lang.Class templateLexerClass
          How to pull apart a template into chunks?		 Ie: Point to a lexer to use for lexing a template. This is of interest in order to choose which delimiter to use for template expressions. Ie: $...$ or <...>.
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.		 Also impacts where templates are sought. See source.
protected  java.lang.Class userSpecifiedWriter
          Normally AutoIndentWriter is used to filter output, but user can specify a new one.		  
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.