org.stringtemplate.v4
Class STGroup

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

Direct Known Subclasses:

STGroupDir, STGroupFile, STGroupString

public class STGroup
extends java.lang.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 java.util.Map<java.lang.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 java.lang.String	DEFAULT_KEY
static STGroup	defaultGroup
char	delimiterStartChar
char	delimiterStopChar
static java.lang.String	DICT_KEY When we use key as a value in a dictionary, this is how we signify.
protected java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>>	dictionaries Maps dict names to HashMap objects.
java.lang.String	encoding Load files using what encoding?
ErrorManager	errMgr The errMgr for entire group; all compilations and executions.
protected java.util.List<STGroup>	imports Every group can import templates/dictionaries from other groups.
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 java.util.Map<java.lang.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 java.util.Map<java.lang.String,CompiledST>	templates Maps template name to StringTemplate object.
static boolean	trackCreationEvents For debugging with STViz.
protected java.util.Map<java.lang.Class,ModelAdaptor>	typeToAdaptorCache Cache exact attribute type to adaptor object
protected java.util.Map<java.lang.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(java.lang.String srcName, java.lang.String name, java.util.List<FormalArgument> args, java.lang.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(java.lang.String name, java.util.Map<java.lang.String,java.lang.Object> mapping) Define a map for this group; not thread safe...do not keep adding these while you reference them.
CompiledST	defineRegion(java.lang.String enclosingTemplateName, org.antlr.runtime.Token regionT, java.lang.String template, org.antlr.runtime.Token templateToken)
CompiledST	defineTemplate(java.lang.String templateName, java.lang.String template)
CompiledST	defineTemplate(java.lang.String name, java.lang.String argsS, java.lang.String template)
CompiledST	defineTemplate(java.lang.String templateName, org.antlr.runtime.Token nameT, java.util.List<FormalArgument> args, java.lang.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(java.lang.String templateName, java.lang.String regionSurroundingTemplateName, org.antlr.runtime.Token templateToken, java.lang.String template, org.antlr.runtime.Token nameToken, java.util.List<FormalArgument> args)
AttributeRenderer	getAttributeRenderer(java.lang.Class attributeType)
protected ST	getEmbeddedInstanceOf(Interpreter interp, ST enclosingInstance, int ip, java.lang.String name)
java.lang.String	getFileName()
ST	getInstanceOf(java.lang.String name) The primary means of getting an instance of a template from this group.
STErrorListener	getListener()
static java.lang.String	getMangledRegionName(java.lang.String enclosingTemplateName, java.lang.String name) The "foo" of t() ::= "<@foo()>" is mangled to "region#t#foo"
ModelAdaptor	getModelAdaptor(java.lang.Class attributeType)
java.lang.String	getName()
java.net.URL	getRootDirURL() Return root dir if this is group dir; return dir containing group file if this is group file.
static java.lang.String	getUnMangledTemplateName(java.lang.String mangledName) Return "t.foo" from "region__t__foo"
java.net.URL	getURL(java.lang.String fileName)
void	importTemplates(STGroup g) Make this group import templates/dictionaries from g.
void	importTemplates(org.antlr.runtime.Token fileNameToken) Import template files, directories, and group files.
void	invalidateModelAdaptorCache(java.lang.Class attributeType) remove at least all types in cache that are subclasses or implement attributeType
boolean	isDefined(java.lang.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(java.lang.String name)
void	load() Force a load if it makes sense for the group
protected CompiledST	load(java.lang.String name) Load st from disk if dir or load whole group file if .stg file (then return just one template).
CompiledST	loadAbsoluteTemplateFile(java.lang.String fileName) Load template file into this group using absolute filename
void	loadGroupFile(java.lang.String prefix, java.lang.String fileName) Load a group file with full path fileName; it's relative to root by prefix.
CompiledST	loadTemplateFile(java.lang.String prefix, java.lang.String fileName, org.antlr.runtime.CharStream templateStream) Load template stream into this group
protected CompiledST	lookupImportedTemplate(java.lang.String name)
CompiledST	lookupTemplate(java.lang.String name) Look up a fully-qualified name
void	rawDefineTemplate(java.lang.String name, CompiledST code, org.antlr.runtime.Token defT)
java.util.Map<java.lang.String,java.lang.Object>	rawGetDictionary(java.lang.String name)
CompiledST	rawGetTemplate(java.lang.String name)
void	registerModelAdaptor(java.lang.Class attributeType, ModelAdaptor adaptor) Add an adaptor for a kind of object so ST knows how to pull properties from them.
void	registerRenderer(java.lang.Class attributeType, AttributeRenderer r) Register a renderer for all objects of a particular "kind" for all templates evaluated relative to this group.
void	setListener(STErrorListener listener)
java.lang.String	show()
java.lang.String	toString()
void	undefineTemplate(java.lang.String name)
void	unload() "unload" all templates and dictionaries but leave renderers, adaptors, and import relationships.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DICT_KEY

public static final java.lang.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 java.lang.String DEFAULT_KEY

See Also:

Constant Field Values

encoding

public java.lang.String encoding

Load files using what encoding?

imports

protected java.util.List<STGroup> imports

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

delimiterStartChar

public char delimiterStartChar

delimiterStopChar

public char delimiterStopChar

templates

protected java.util.Map<java.lang.String,CompiledST> templates

Maps template name to StringTemplate object. synchronized.

dictionaries

protected java.util.Map<java.lang.String,java.util.Map<java.lang.String,java.lang.Object>> dictionaries

Maps dict names to HashMap objects. This is the list of dictionaries defined by the user like typeInitMap ::= ["int":"0"]

renderers

protected java.util.Map<java.lang.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 java.util.Map<java.lang.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 java.util.Map<java.lang.Class,ModelAdaptor> typeToAdaptorCache

Cache exact attribute type to adaptor object

typeToRendererCache

protected java.util.Map<java.lang.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(java.lang.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,
                                   java.lang.String name)

createSingleton

public ST createSingleton(org.antlr.runtime.Token templateToken)

Create singleton template for use with dictionary values

isDefined

public boolean isDefined(java.lang.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(java.lang.String name)

Look up a fully-qualified name

unload

public void unload()

"unload" all templates and dictionaries but leave renderers, adaptors, and import relationships. This essentially forces next getInstanceOf to reload templates.

load

protected CompiledST load(java.lang.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(java.lang.String name)

rawGetTemplate

public CompiledST rawGetTemplate(java.lang.String name)

rawGetDictionary

public java.util.Map<java.lang.String,java.lang.Object> rawGetDictionary(java.lang.String name)

isDictionary

public boolean isDictionary(java.lang.String name)

defineTemplate

public CompiledST defineTemplate(java.lang.String templateName,
                                 java.lang.String template)

defineTemplate

public CompiledST defineTemplate(java.lang.String name,
                                 java.lang.String argsS,
                                 java.lang.String template)

defineTemplate

public CompiledST defineTemplate(java.lang.String templateName,
                                 org.antlr.runtime.Token nameT,
                                 java.util.List<FormalArgument> args,
                                 java.lang.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(java.lang.String enclosingTemplateName,
                               org.antlr.runtime.Token regionT,
                               java.lang.String template,
                               org.antlr.runtime.Token templateToken)

defineTemplateOrRegion

public void defineTemplateOrRegion(java.lang.String templateName,
                                   java.lang.String regionSurroundingTemplateName,
                                   org.antlr.runtime.Token templateToken,
                                   java.lang.String template,
                                   org.antlr.runtime.Token nameToken,
                                   java.util.List<FormalArgument> args)

rawDefineTemplate

public void rawDefineTemplate(java.lang.String name,
                              CompiledST code,
                              org.antlr.runtime.Token defT)

undefineTemplate

public void undefineTemplate(java.lang.String name)

compile

public CompiledST compile(java.lang.String srcName,
                          java.lang.String name,
                          java.util.List<FormalArgument> args,
                          java.lang.String template,
                          org.antlr.runtime.Token templateToken)

Compile a template

getMangledRegionName

public static java.lang.String getMangledRegionName(java.lang.String enclosingTemplateName,
                                                    java.lang.String name)

The "foo" of t() ::= "<@foo()>" is mangled to "region#t#foo"

getUnMangledTemplateName

public static java.lang.String getUnMangledTemplateName(java.lang.String mangledName)

Return "t.foo" from "region__t__foo"

defineDictionary

public void defineDictionary(java.lang.String name,
                             java.util.Map<java.lang.String,java.lang.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.

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. If you specify an absolute file name or directory name, the import statement uses that directly. If it is not an absolute path, we look that entity up in the directory holding the group that initiates the import. If file or directory is not in that directory, then we load using the classpath. 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.

loadGroupFile

public void loadGroupFile(java.lang.String prefix,
                          java.lang.String fileName)

Load a group file with full path fileName; it's relative to root by prefix.

loadAbsoluteTemplateFile

public CompiledST loadAbsoluteTemplateFile(java.lang.String fileName)

Load template file into this group using absolute filename

loadTemplateFile

public CompiledST loadTemplateFile(java.lang.String prefix,
                                   java.lang.String fileName,
                                   org.antlr.runtime.CharStream templateStream)

Load template stream into this group

registerModelAdaptor

public void registerModelAdaptor(java.lang.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(java.lang.Class attributeType)

remove at least all types in cache that are subclasses or implement attributeType

getModelAdaptor

public ModelAdaptor getModelAdaptor(java.lang.Class attributeType)

registerRenderer

public void registerRenderer(java.lang.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).

getAttributeRenderer

public AttributeRenderer getAttributeRenderer(java.lang.Class attributeType)

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 java.lang.String getName()

getFileName

public java.lang.String getFileName()

getRootDirURL

public java.net.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 java.net.URL getURL(java.lang.String fileName)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

show

public java.lang.String show()

getListener

public STErrorListener getListener()

setListener

public void setListener(STErrorListener listener)