org.stringtemplate.v4
Class STGroup

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

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 dict names to HashMap objects.
String	encoding Load files using what encoding?
ErrorManager	errMgr The errMgr for entire group; all compilations and executions.
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 values not keys like v4.
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.
protected Map<String,CompiledST>	templates Maps template name to StringTemplate object.
static boolean	trackCreationEvents For debugging with STViz.
protected Map<Class,ModelAdaptor>	typeToAdaptorCache Cache exact attribute type to adaptor object
protected Map<Class,AttributeRenderer>	typeToRendererCache Cache exact attribute type to renderer object
static boolean	verbose Watch loading of groups and templates

Constructor Summary

STGroup()

STGroup(char delimiterStartChar, char delimiterStopChar)

Method Summary

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 "new ST" events used during interp.
ST	createStringTemplateInternally(ST proto)
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.
CompiledST	defineRegion(String enclosingTemplateName, org.antlr.runtime.Token regionT, String template, org.antlr.runtime.Token templateToken)
CompiledST	defineTemplate(String templateName, String template)
CompiledST	defineTemplate(String name, String argsS, String template)
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 dir 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

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

Load files using what encoding?

imports

protected final List<STGroup> imports

Every group can import templates/dictionaries from other groups. The list must be synchronized (see importTemplates).

importsToClearOnUnload

protected final List<STGroup> importsToClearOnUnload

delimiterStartChar

public char delimiterStartChar

delimiterStopChar

public char delimiterStopChar

templates

protected Map<String,CompiledST> templates

Maps template name to StringTemplate object. synchronized.

dictionaries

protected Map<String,Map<String,Object>> dictionaries

Maps dict names to HashMap objects. This is the list of 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 adaptor object

typeToRendererCache

protected Map<Class,AttributeRenderer> typeToRendererCache

Cache exact attribute type to renderer 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 values not keys like v4. 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 errMgr 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 next getInstanceOf to reload templates. Call unload() on each group in the imports list and remove every import from the imports list imported with "clearOnUnload".

load

protected CompiledST load(String name)

Load st from disk if dir 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)

defineTemplate

public CompiledST defineTemplate(String name,
                                 String argsS,
                                 String template)

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 def 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, and ST 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 arg. This must invalidate cache entries, so set your adaptors up before render()ing your templates 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 instanceof(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 "new ST" events used during interp.

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