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

Fields

Modifier and Type	Field and Description
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 dictionary names to Map objects representing the dictionaries defined by the user like typeInitMap ::= ["int":"0"].
java.lang.String	encoding The encoding to use for loading files.
ErrorManager	errMgr The ErrorManager for entire group; all compilations and executions.
static java.lang.String	GROUP_FILE_EXTENSION
protected java.util.List<STGroup>	imports Every group can import templates/dictionaries from other groups.
protected java.util.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 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.
static java.lang.String	TEMPLATE_FILE_EXTENSION
protected java.util.Map<java.lang.String,CompiledST>	templates Maps template name to CompiledST object.
static boolean	trackCreationEvents For debugging with STViz.
static boolean	verbose Watch loading of groups and templates.

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
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 implicit "new ST" events during rendering.
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.
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) for testing
CompiledST	defineTemplate(java.lang.String name, java.lang.String argsS, java.lang.String template) for testing
CompiledST	defineTemplate(java.lang.String fullyQualifiedTemplateName, 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 fullyQualifiedTemplateName, 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) Get renderer for class T associated with this group.
protected ST	getEmbeddedInstanceOf(Interpreter interp, InstanceScope scope, java.lang.String name)
java.lang.String	getFileName()
java.util.List<STGroup>	getImportedGroups()
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.
java.util.Set<java.lang.String>	getTemplateNames()
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.
protected void	importTemplates(STGroup g, boolean clearOnUnload)
void	importTemplates(org.antlr.runtime.Token fileNameToken) Import template files, directories, and group files.
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)
static boolean	isReservedCharacter(char c) Determines if a specified character may be used as a user-specified delimiter.
void	load() Force a load if it makes sense for the group.
protected CompiledST	load(java.lang.String name) Load st from disk if directory 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 unqualifiedFileName, 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	registerRenderer(java.lang.Class<?> attributeType, AttributeRenderer r, boolean recursive)
void	setListener(STErrorListener listener)
java.lang.String	show()
java.lang.String	toString()
void	undefineTemplate(java.lang.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 java.lang.String GROUP_FILE_EXTENSION

TEMPLATE_FILE_EXTENSION

public static final java.lang.String TEMPLATE_FILE_EXTENSION

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

The encoding to use for loading files. Defaults to UTF-8.

imports

protected final java.util.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 java.util.List<STGroup> importsToClearOnUnload

delimiterStartChar

public char delimiterStartChar

delimiterStopChar

public char delimiterStopChar

templates

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

Maps template name to CompiledST object. This map is synchronized.

dictionaries

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

Maps dictionary names to Map objects representing the 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 final 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.

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(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,
                       InstanceScope scope,
                       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, 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(java.lang.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.

isReservedCharacter

public static boolean isReservedCharacter(char c)

Determines if a specified character may be used as a user-specified delimiter.

Parameters:

c - The character

Returns:

true if the character is reserved by the StringTemplate language; otherwise, false if the character may be used as a delimiter.

Since:

4.0.9

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)

for testing

defineTemplate

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

for testing

defineTemplate

public CompiledST defineTemplate(java.lang.String fullyQualifiedTemplateName,
                        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 definition 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 fullyQualifiedTemplateName,
                          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.

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 java.util.List<STGroup> getImportedGroups()

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 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(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, 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.

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 an instance of attributeType. Recursively set renderer into all import groups.

registerRenderer

public void registerRenderer(java.lang.Class<?> attributeType,
                    AttributeRenderer r,
                    boolean recursive)

getAttributeRenderer

public AttributeRenderer getAttributeRenderer(java.lang.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 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)

getTemplateNames

public java.util.Set<java.lang.String> getTemplateNames()