STGroup (StringTemplate 4 4.0.7-rc-2 API)

java.lang.Object
- org.stringtemplate.v4.STGroup

Direct Known Subclasses:

STGroupDir, STGroupFile, STGroupString
```
public class STGroup
extends Object
```
A directory or directory tree of .st template files and/or group files. Individual template files contain formal template definitions. In a sense, it's like a single group file broken into multiple files, one for each template. ST v3 had just the pure template inside, not the template name and header. Name inside must match filename (minus suffix).

Field Summary

Fields
Modifier and Type	Field and Description
`protected Map<Class<?>,ModelAdaptor>`	`adaptors` A dictionary that allows people to register a model adaptor for a particular kind of object (subclass or implementation).
`static ErrorManager`	`DEFAULT_ERR_MGR`
`static String`	`DEFAULT_KEY`
`static STGroup`	`defaultGroup`
`char`	`delimiterStartChar`
`char`	`delimiterStopChar`
`static String`	`DICT_KEY` When we use key as a value in a dictionary, this is how we signify.
`protected Map<String,Map<String,Object>>`	`dictionaries` Maps dictionary names to `Map` objects representing the dictionaries defined by the user like `typeInitMap ::= ["int":"0"]`.
`String`	`encoding` The encoding to use for loading files.
`ErrorManager`	`errMgr` The `ErrorManager` for entire group; all compilations and executions.
`static String`	`GROUP_FILE_EXTENSION`
`protected List<STGroup>`	`imports` Every group can import templates/dictionaries from other groups.
`protected List<STGroup>`	`importsToClearOnUnload`
`boolean`	`iterateAcrossValues` v3 compatibility; used to iterate across `Map.values()` instead of v4's default `Map.keySet()`.
`protected static CompiledST`	`NOT_FOUND_ST` Used to indicate that the template doesn't exist.
`protected Map<Class<?>,AttributeRenderer>`	`renderers` A dictionary that allows people to register a renderer for a particular kind of object for any template evaluated relative to this group.
`static String`	`TEMPLATE_FILE_EXTENSION`
`protected Map<String,CompiledST>`	`templates` Maps template name to `CompiledST` object.
`static boolean`	`trackCreationEvents` For debugging with `STViz`.
`protected Map<Class<?>,ModelAdaptor>`	`typeToAdaptorCache` Cache exact attribute type to `ModelAdaptor` object.
`protected Map<Class<?>,AttributeRenderer>`	`typeToRendererCache` Cache exact attribute type to `AttributeRenderer` object.
`static boolean`	`verbose` Watch loading of groups and templates.

Constructor Summary

Constructors
Constructor and Description

STGroup()

STGroup(char delimiterStartChar, char delimiterStopChar)

Constructors
Constructor and Description
`STGroup()`
`STGroup(char delimiterStartChar, char delimiterStopChar)`

Method Summary

Methods
Modifier and Type	Method and Description
`CompiledST`	`compile(String srcName, String name, List<FormalArgument> args, String template, org.antlr.runtime.Token templateToken)` Compile a template.
`ST`	`createSingleton(org.antlr.runtime.Token templateToken)` Create singleton template for use with dictionary values.
`ST`	`createStringTemplate(CompiledST impl)`
`ST`	`createStringTemplateInternally(CompiledST impl)` Differentiate so we can avoid having creation events for regions, map operations, and other implicit "new ST" events during rendering.
`ST`	`createStringTemplateInternally(ST proto)`
`void`	`defineDictionary(String name, Map<String,Object> mapping)` Define a map for this group.
`CompiledST`	`defineRegion(String enclosingTemplateName, org.antlr.runtime.Token regionT, String template, org.antlr.runtime.Token templateToken)`
`CompiledST`	`defineTemplate(String templateName, String template)` for testing
`CompiledST`	`defineTemplate(String name, String argsS, String template)` for testing
`CompiledST`	`defineTemplate(String fullyQualifiedTemplateName, org.antlr.runtime.Token nameT, List<FormalArgument> args, String template, org.antlr.runtime.Token templateToken)`
`CompiledST`	`defineTemplateAlias(org.antlr.runtime.Token aliasT, org.antlr.runtime.Token targetT)` Make name and alias for target.
`void`	`defineTemplateOrRegion(String fullyQualifiedTemplateName, String regionSurroundingTemplateName, org.antlr.runtime.Token templateToken, String template, org.antlr.runtime.Token nameToken, List<FormalArgument> args)`
`AttributeRenderer`	`getAttributeRenderer(Class<?> attributeType)` Get renderer for class `T` associated with this group.
`protected ST`	`getEmbeddedInstanceOf(Interpreter interp, ST enclosingInstance, int ip, String name)`
`String`	`getFileName()`
`List<STGroup>`	`getImportedGroups()`
`ST`	`getInstanceOf(String name)` The primary means of getting an instance of a template from this group.
`STErrorListener`	`getListener()`
`static String`	`getMangledRegionName(String enclosingTemplateName, String name)` The `"foo"` of `t() ::= "<@foo()>"` is mangled to `"/region__/t__foo"`
`ModelAdaptor`	`getModelAdaptor(Class<?> attributeType)`
`String`	`getName()`
`URL`	`getRootDirURL()` Return root dir if this is group dir; return dir containing group file if this is group file.
`Set<String>`	`getTemplateNames()`
`static String`	`getUnMangledTemplateName(String mangledName)` Return `"t.foo"` from `"/region__/t__foo"`
`URL`	`getURL(String fileName)`
`void`	`importTemplates(STGroup g)` Make this group import templates/dictionaries from `g`.
`protected void`	`importTemplates(STGroup g, boolean clearOnUnload)`
`void`	`importTemplates(org.antlr.runtime.Token fileNameToken)` Import template files, directories, and group files.
`void`	`invalidateModelAdaptorCache(Class<?> attributeType)` Remove at least all types in cache that are subclasses or implement `attributeType`.
`boolean`	`isDefined(String name)` Is this template defined in this group or from this group below? Names must be absolute, fully-qualified names like `/a/b`.
`boolean`	`isDictionary(String name)`
`void`	`load()` Force a load if it makes sense for the group.
`protected CompiledST`	`load(String name)` Load st from disk if directory or load whole group file if .stg file (then return just one template).
`CompiledST`	`loadAbsoluteTemplateFile(String fileName)` Load template file into this group using absolute `fileName`.
`void`	`loadGroupFile(String prefix, String fileName)` Load a group file with full path `fileName`; it's relative to root by `prefix`.
`CompiledST`	`loadTemplateFile(String prefix, String unqualifiedFileName, org.antlr.runtime.CharStream templateStream)` Load template stream into this group.
`protected CompiledST`	`lookupImportedTemplate(String name)`
`CompiledST`	`lookupTemplate(String name)` Look up a fully-qualified name.
`void`	`rawDefineTemplate(String name, CompiledST code, org.antlr.runtime.Token defT)`
`Map<String,Object>`	`rawGetDictionary(String name)`
`CompiledST`	`rawGetTemplate(String name)`
`void`	`registerModelAdaptor(Class<?> attributeType, ModelAdaptor adaptor)` Add an adaptor for a kind of object so ST knows how to pull properties from them.
`void`	`registerRenderer(Class<?> attributeType, AttributeRenderer r)` Register a renderer for all objects of a particular "kind" for all templates evaluated relative to this group.
`void`	`registerRenderer(Class<?> attributeType, AttributeRenderer r, boolean recursive)`
`void`	`setListener(STErrorListener listener)`
`String`	`show()`
`String`	`toString()`
`void`	`undefineTemplate(String name)`
`void`	`unload()` Unload all templates, dictionaries and import relationships, but leave renderers and adaptors.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - GROUP_FILE_EXTENSION
```
public static final String GROUP_FILE_EXTENSION
```
  - TEMPLATE_FILE_EXTENSION
```
public static final String TEMPLATE_FILE_EXTENSION
```
  - DICT_KEY
```
public static final String DICT_KEY
```
    When we use key as a value in a dictionary, this is how we signify.
    
    See Also:
    Constant Field Values
  - DEFAULT_KEY
```
public static final String DEFAULT_KEY
```
    See Also:
    Constant Field Values
  - encoding
```
public String encoding
```
    The encoding to use for loading files. Defaults to UTF-8.
  - imports
```
protected final List<STGroup> imports
```
    Every group can import templates/dictionaries from other groups. The list must be synchronized (see importTemplates(org.stringtemplate.v4.STGroup)).
  - importsToClearOnUnload
```
protected final List<STGroup> importsToClearOnUnload
```
  - delimiterStartChar
```
public char delimiterStartChar
```
  - delimiterStopChar
```
public char delimiterStopChar
```
  - templates
```
protected Map<String,CompiledST> templates
```
    Maps template name to CompiledST object. This map is synchronized.
  - dictionaries
```
protected Map<String,Map<String,Object>> dictionaries
```
    Maps dictionary names to Map objects representing the dictionaries defined by the user like typeInitMap ::= ["int":"0"].
  - renderers
```
protected Map<Class<?>,AttributeRenderer> renderers
```
    A dictionary that allows people to register a renderer for a particular kind of object for any template evaluated relative to 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.
    Order of addition is recorded and matters. If more than one renderer works for an object, the first registered has priority.
    Renderer associated with type t works for object o if
```
  t.isAssignableFrom(o.getClass()) // would assignment t = o work?
  
```
    So it works if o is subclass or implements t.
    This structure is synchronized.
  - adaptors
```
protected Map<Class<?>,ModelAdaptor> adaptors
```
    A dictionary that allows people to register a model adaptor for a particular kind of object (subclass or implementation). Applies for any template evaluated relative to this group.
    ST initializes with model adaptors that know how to pull properties out of Objects, Maps, and STs.
    The last one you register gets priority; do least to most specific.
  - typeToAdaptorCache
```
protected Map<Class<?>,ModelAdaptor> typeToAdaptorCache
```
    Cache exact attribute type to ModelAdaptor object.
  - typeToRendererCache
```
protected Map<Class<?>,AttributeRenderer> typeToRendererCache
```
    Cache exact attribute type to AttributeRenderer object.
  - NOT_FOUND_ST
```
protected static final CompiledST NOT_FOUND_ST
```
    Used to indicate that the template doesn't exist. Prevents duplicate group file loads and unnecessary file checks.
  - DEFAULT_ERR_MGR
```
public static final ErrorManager DEFAULT_ERR_MGR
```
  - verbose
```
public static boolean verbose
```
    Watch loading of groups and templates.
  - trackCreationEvents
```
public static boolean trackCreationEvents
```
    For debugging with STViz. Records where in code an ST was created and where code added attributes.
  - iterateAcrossValues
```
public boolean iterateAcrossValues
```
    v3 compatibility; used to iterate across Map.values() instead of v4's default Map.keySet(). But to convert ANTLR templates, it's too hard to find without static typing in templates.
  - defaultGroup
```
public static STGroup defaultGroup
```
  - errMgr
```
public ErrorManager errMgr
```
    The ErrorManager for entire group; all compilations and executions. This gets copied to parsers, walkers, and interpreters.
- Constructor Detail
  - STGroup
```
public STGroup()
```
  - STGroup
```
public STGroup(char delimiterStartChar,
       char delimiterStopChar)
```
- Method Detail
  - getInstanceOf
```
public ST getInstanceOf(String name)
```
    The primary means of getting an instance of a template from this group. Names must be absolute, fully-qualified names like /a/b.
  - getEmbeddedInstanceOf
```
protected ST getEmbeddedInstanceOf(Interpreter interp,
                       ST enclosingInstance,
                       int ip,
                       String name)
```
  - createSingleton
```
public ST createSingleton(org.antlr.runtime.Token templateToken)
```
    Create singleton template for use with dictionary values.
  - isDefined
```
public boolean isDefined(String name)
```
    Is this template defined in this group or from this group below? Names must be absolute, fully-qualified names like /a/b.
  - lookupTemplate
```
public CompiledST lookupTemplate(String name)
```
    Look up a fully-qualified name.
  - unload
```
public void unload()
```
    Unload all templates, dictionaries and import relationships, but leave renderers and adaptors. This essentially forces the next call to getInstanceOf(java.lang.String) to reload templates. Call unload() on each group in the imports list, and remove all elements in importsToClearOnUnload from imports.
  - load
```
protected CompiledST load(String name)
```
    Load st from disk if directory or load whole group file if .stg file (then return just one template). name is fully-qualified.
  - load
```
public void load()
```
    Force a load if it makes sense for the group.
  - lookupImportedTemplate
```
protected CompiledST lookupImportedTemplate(String name)
```
  - rawGetTemplate
```
public CompiledST rawGetTemplate(String name)
```
  - rawGetDictionary
```
public Map<String,Object> rawGetDictionary(String name)
```
  - isDictionary
```
public boolean isDictionary(String name)
```
  - defineTemplate
```
public CompiledST defineTemplate(String templateName,
                        String template)
```
    for testing
  - defineTemplate
```
public CompiledST defineTemplate(String name,
                        String argsS,
                        String template)
```
    for testing
  - defineTemplate
```
public CompiledST defineTemplate(String fullyQualifiedTemplateName,
                        org.antlr.runtime.Token nameT,
                        List<FormalArgument> args,
                        String template,
                        org.antlr.runtime.Token templateToken)
```
  - defineTemplateAlias
```
public CompiledST defineTemplateAlias(org.antlr.runtime.Token aliasT,
                             org.antlr.runtime.Token targetT)
```
    Make name and alias for target. Replace any previous definition of name.
  - defineRegion
```
public CompiledST defineRegion(String enclosingTemplateName,
                      org.antlr.runtime.Token regionT,
                      String template,
                      org.antlr.runtime.Token templateToken)
```
  - defineTemplateOrRegion
```
public void defineTemplateOrRegion(String fullyQualifiedTemplateName,
                          String regionSurroundingTemplateName,
                          org.antlr.runtime.Token templateToken,
                          String template,
                          org.antlr.runtime.Token nameToken,
                          List<FormalArgument> args)
```
  - rawDefineTemplate
```
public void rawDefineTemplate(String name,
                     CompiledST code,
                     org.antlr.runtime.Token defT)
```
  - undefineTemplate
```
public void undefineTemplate(String name)
```
  - compile
```
public CompiledST compile(String srcName,
                 String name,
                 List<FormalArgument> args,
                 String template,
                 org.antlr.runtime.Token templateToken)
```
    Compile a template.
  - getMangledRegionName
```
public static String getMangledRegionName(String enclosingTemplateName,
                          String name)
```
    The "foo" of t() ::= "<@foo()>" is mangled to "/region__/t__foo"
  - getUnMangledTemplateName
```
public static String getUnMangledTemplateName(String mangledName)
```
    Return "t.foo" from "/region__/t__foo"
  - defineDictionary
```
public void defineDictionary(String name,
                    Map<String,Object> mapping)
```
    Define a map for this group.
    Not thread safe...do not keep adding these while you reference them.
  - importTemplates
```
public void importTemplates(STGroup g)
```
    Make this group import templates/dictionaries from g.
    On unload imported templates are unloaded but stay in the imports list.
  - importTemplates
```
public void importTemplates(org.antlr.runtime.Token fileNameToken)
```
    Import template files, directories, and group files. Priority is given to templates defined in the current group; this, in effect, provides inheritance. Polymorphism is in effect so that if an inherited template references template t() then we search for t() in the subgroup first.
    Templates are loaded on-demand from import dirs. Imported groups are loaded on-demand when searching for a template.
    The listener of this group is passed to the import group so errors found while loading imported element are sent to listener of this group.
    On unload imported templates are unloaded and removed from the imports list.
    This method is called when processing import statements specified in group files. Use importTemplates(STGroup) to import templates 'programmatically'.
  - importTemplates
```
protected void importTemplates(STGroup g,
                   boolean clearOnUnload)
```
  - getImportedGroups
```
public List<STGroup> getImportedGroups()
```
  - loadGroupFile
```
public void loadGroupFile(String prefix,
                 String fileName)
```
    Load a group file with full path fileName; it's relative to root by prefix.
  - loadAbsoluteTemplateFile
```
public CompiledST loadAbsoluteTemplateFile(String fileName)
```
    Load template file into this group using absolute fileName.
  - loadTemplateFile
```
public CompiledST loadTemplateFile(String prefix,
                          String unqualifiedFileName,
                          org.antlr.runtime.CharStream templateStream)
```
    Load template stream into this group. unqualifiedFileName is "a.st". The prefix is path from group root to unqualifiedFileName like "/subdir" if file is in /subdir/a.st.
  - registerModelAdaptor
```
public void registerModelAdaptor(Class<?> attributeType,
                        ModelAdaptor adaptor)
```
    Add an adaptor for a kind of object so ST knows how to pull properties from them. Add adaptors in increasing order of specificity. ST adds Object, Map, ST, and Aggregate model adaptors for you first. Adaptors you add have priority over default adaptors.
    If an adaptor for type T already exists, it is replaced by the adaptor argument.
    This must invalidate cache entries, so set your adaptors up before calling ST.render() for efficiency.
  - invalidateModelAdaptorCache
```
public void invalidateModelAdaptorCache(Class<?> attributeType)
```
    Remove at least all types in cache that are subclasses or implement attributeType.
  - getModelAdaptor
```
public ModelAdaptor getModelAdaptor(Class<?> attributeType)
```
  - registerRenderer
```
public void registerRenderer(Class<?> attributeType,
                    AttributeRenderer r)
```
    Register a renderer for all objects of a particular "kind" for all templates evaluated relative to this group. Use r to render if object in question is an instance of attributeType. Recursively set renderer into all import groups.
  - registerRenderer
```
public void registerRenderer(Class<?> attributeType,
                    AttributeRenderer r,
                    boolean recursive)
```
  - getAttributeRenderer
```
public AttributeRenderer getAttributeRenderer(Class<?> attributeType)
```
    Get renderer for class T associated with this group.
    For non-imported groups and object-to-render of class T, use renderer (if any) registered for T. For imports, any renderer set on import group is ignored even when using an imported template. You should set the renderer on the main group you use (or all to be sure). I look at import groups as "helpers" that should give me templates and nothing else. If you have multiple renderers for String, say, then just make uber combined renderer with more specific format names.
  - createStringTemplate
```
public ST createStringTemplate(CompiledST impl)
```
  - createStringTemplateInternally
```
public ST createStringTemplateInternally(CompiledST impl)
```
    Differentiate so we can avoid having creation events for regions, map operations, and other implicit "new ST" events during rendering.
  - createStringTemplateInternally
```
public ST createStringTemplateInternally(ST proto)
```
  - getName
```
public String getName()
```
  - getFileName
```
public String getFileName()
```
  - getRootDirURL
```
public URL getRootDirURL()
```
    Return root dir if this is group dir; return dir containing group file if this is group file. This is derived from original incoming dir or filename. If it was absolute, this should come back as full absolute path. If only a URL is available, return URL of one dir up.
  - getURL
```
public URL getURL(String fileName)
```
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - show
```
public String show()
```
  - getListener
```
public STErrorListener getListener()
```
  - setListener
```
public void setListener(STErrorListener listener)
```
  - getTemplateNames
```
public Set<String> getTemplateNames()
```

Class STGroup

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

GROUP_FILE_EXTENSION

TEMPLATE_FILE_EXTENSION

DICT_KEY

DEFAULT_KEY

encoding

imports

importsToClearOnUnload

delimiterStartChar

delimiterStopChar

templates

dictionaries

renderers

adaptors

typeToAdaptorCache

typeToRendererCache

NOT_FOUND_ST

DEFAULT_ERR_MGR

verbose

trackCreationEvents

iterateAcrossValues

defaultGroup

errMgr

Constructor Detail

STGroup

STGroup

Method Detail

getInstanceOf

getEmbeddedInstanceOf

createSingleton

isDefined

lookupTemplate

unload

load

load

lookupImportedTemplate

rawGetTemplate

rawGetDictionary

isDictionary

defineTemplate

defineTemplate

defineTemplate

defineTemplateAlias

defineRegion

defineTemplateOrRegion

rawDefineTemplate

undefineTemplate

compile

getMangledRegionName

getUnMangledTemplateName

defineDictionary

importTemplates

importTemplates

importTemplates

getImportedGroups

loadGroupFile

loadAbsoluteTemplateFile

loadTemplateFile

registerModelAdaptor

invalidateModelAdaptorCache

getModelAdaptor

registerRenderer

registerRenderer

getAttributeRenderer

createStringTemplate

createStringTemplateInternally

createStringTemplateInternally

getName

getFileName

getRootDirURL

getURL

toString

show

getListener

setListener