Class STGroup
- Direct Known Subclasses:
STGroupDir
,STGroupFile
,STGroupString
.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
FieldsModifier and TypeFieldDescriptionprotected final Map
<Class<?>, ModelAdaptor<?>> A dictionary that allows people to register a model adaptor for a particular kind of object (subclass or implementation).static final ErrorManager
static final String
static STGroup
char
char
static final String
When we use key as a value in a dictionary, this is how we signify.Maps dictionary names toMap
objects representing the dictionaries defined by the user liketypeInitMap ::= ["int":"0"]
.The encoding to use for loading files.TheErrorManager
for entire group; all compilations and executions.static final String
Every group can import templates/dictionaries from other groups.boolean
v3 compatibility; used to iterate acrossMap.values()
instead of v4's defaultMap.keySet()
.protected static final CompiledST
Used to indicate that the template doesn't exist.protected Map
<Class<?>, AttributeRenderer<?>> A dictionary that allows people to register a renderer for a particular kind of object for any template evaluated relative to this group.private static final boolean[]
static final String
protected Map
<String, CompiledST> Maps template name toCompiledST
object.static boolean
For debugging withSTViz
.static boolean
Watch loading of groups and templates. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptioncompile
(String srcName, String name, List<FormalArgument> args, String template, org.antlr.runtime.Token templateToken) Compile a template.createSingleton
(org.antlr.runtime.Token templateToken) Create singleton template for use with dictionary values.Differentiate so we can avoid having creation events for regions, map operations, and other implicit "new ST" events during rendering.createStringTemplateInternally
(ST proto) void
defineDictionary
(String name, Map<String, Object> mapping) Define a map for this group.defineRegion
(String enclosingTemplateName, org.antlr.runtime.Token regionT, String template, org.antlr.runtime.Token templateToken) defineTemplate
(String templateName, String template) for testingdefineTemplate
(String name, String argsS, String template) for testingdefineTemplate
(String fullyQualifiedTemplateName, org.antlr.runtime.Token nameT, List<FormalArgument> args, String template, org.antlr.runtime.Token templateToken) 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) <T> AttributeRenderer
<? super T> getAttributeRenderer
(Class<T> attributeType) Get renderer for classT
associated with this group.protected ST
getEmbeddedInstanceOf
(Interpreter interp, InstanceScope scope, String name) getInstanceOf
(String name) The primary means of getting an instance of a template from this group.static String
getMangledRegionName
(String enclosingTemplateName, String name) The"foo"
oft() ::= "<@foo()>"
is mangled to"/region__/t__foo"
<T> ModelAdaptor
<? super T> getModelAdaptor
(Class<T> attributeType) getName()
Return root dir if this is group dir; return dir containing group file if this is group file.static String
getUnMangledTemplateName
(String mangledName) Return"t.foo"
from"/region__/t__foo"
void
importTemplates
(org.antlr.runtime.Token fileNameToken) Import template files, directories, and group files.void
Make this group import templates/dictionaries fromg
.protected void
importTemplates
(STGroup g, boolean clearOnUnload) boolean
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) 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 st from disk if directory or load whole group file if .stg file (then return just one template).loadAbsoluteTemplateFile
(String fileName) Load template file into this group using absolutefileName
.void
loadGroupFile
(String prefix, String fileName) Load a group file with full pathfileName
; it's relative to root byprefix
.loadTemplateFile
(String prefix, String unqualifiedFileName, org.antlr.runtime.CharStream templateStream) Load template stream into this group.protected CompiledST
lookupImportedTemplate
(String name) lookupTemplate
(String name) Look up a fully-qualified name.void
rawDefineTemplate
(String name, CompiledST code, org.antlr.runtime.Token defT) rawGetDictionary
(String name) rawGetTemplate
(String name) <T> void
registerModelAdaptor
(Class<T> attributeType, ModelAdaptor<? super T> adaptor) Add an adaptor for a kind of object so ST knows how to pull properties from them.<T> void
registerRenderer
(Class<T> attributeType, AttributeRenderer<? super T> r) Register a renderer for all objects of a particular "kind" for all templates evaluated relative to this group.<T> void
registerRenderer
(Class<T> attributeType, AttributeRenderer<? super T> r, boolean recursive) void
setListener
(STErrorListener listener) show()
toString()
void
undefineTemplate
(String name) void
unload()
Unload all templates, dictionaries and import relationships, but leave renderers and adaptors.
-
Field Details
-
GROUP_FILE_EXTENSION
-
TEMPLATE_FILE_EXTENSION
-
RESERVED_CHARACTERS
private static final boolean[] RESERVED_CHARACTERS -
DICT_KEY
When we use key as a value in a dictionary, this is how we signify.- See Also:
-
DEFAULT_KEY
- See Also:
-
encoding
The encoding to use for loading files. Defaults to UTF-8. -
imports
Every group can import templates/dictionaries from other groups. The list must be synchronized (seeimportTemplates(org.stringtemplate.v4.STGroup)
). -
importsToClearOnUnload
-
delimiterStartChar
public char delimiterStartChar -
delimiterStopChar
public char delimiterStopChar -
templates
Maps template name toCompiledST
object. This map is synchronized. -
dictionaries
Maps dictionary names toMap
objects representing the dictionaries defined by the user liketypeInitMap ::= ["int":"0"]
. -
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 setDate.class
to an object whosetoString(Object)
method properly formats aDate
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 objecto
ift.isAssignableFrom(o.getClass()) // would assignment t = o work?
So it works ifo
is subclass or implementst
.This structure is synchronized.
-
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
Object
s,Map
s, andST
s.The last one you register gets priority; do least to most specific.
-
NOT_FOUND_ST
Used to indicate that the template doesn't exist. Prevents duplicate group file loads and unnecessary file checks. -
DEFAULT_ERR_MGR
-
verbose
public static boolean verboseWatch loading of groups and templates. -
trackCreationEvents
public static boolean trackCreationEvents -
iterateAcrossValues
public boolean iterateAcrossValuesv3 compatibility; used to iterate acrossMap.values()
instead of v4's defaultMap.keySet()
. But to convert ANTLR templates, it's too hard to find without static typing in templates. -
defaultGroup
-
errMgr
TheErrorManager
for entire group; all compilations and executions. This gets copied to parsers, walkers, and interpreters.
-
-
Constructor Details
-
STGroup
public STGroup() -
STGroup
public STGroup(char delimiterStartChar, char delimiterStopChar)
-
-
Method Details
-
getInstanceOf
The primary means of getting an instance of a template from this group. Names must be absolute, fully-qualified names like/a/b
. -
getEmbeddedInstanceOf
-
createSingleton
Create singleton template for use with dictionary values. -
isDefined
Is this template defined in this group or from this group below? Names must be absolute, fully-qualified names like/a/b
. -
lookupTemplate
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 togetInstanceOf(java.lang.String)
to reload templates. Callunload()
on each group in theimports
list, and remove all elements inimportsToClearOnUnload
fromimports
. -
load
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
-
rawGetTemplate
-
rawGetDictionary
-
isDictionary
-
defineTemplate
for testing -
defineTemplate
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
-
undefineTemplate
-
compile
public CompiledST compile(String srcName, String name, List<FormalArgument> args, String template, org.antlr.runtime.Token templateToken) Compile a template. -
getMangledRegionName
The"foo"
oft() ::= "<@foo()>"
is mangled to"/region__/t__foo"
-
getUnMangledTemplateName
Return"t.foo"
from"/region__/t__foo"
-
defineDictionary
Define a map for this group.Not thread safe...do not keep adding these while you reference them.
-
importTemplates
Make this group import templates/dictionaries fromg
.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 templatet()
then we search fort()
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
-
getImportedGroups
-
loadGroupFile
Load a group file with full pathfileName
; it's relative to root byprefix
. -
loadAbsoluteTemplateFile
Load template file into this group using absolutefileName
. -
loadTemplateFile
public CompiledST loadTemplateFile(String prefix, String unqualifiedFileName, org.antlr.runtime.CharStream templateStream) Load template stream into this group.unqualifiedFileName
is"a.st"
. Theprefix
is path from group root tounqualifiedFileName
like"/subdir"
if file is in/subdir/a.st
. -
registerModelAdaptor
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 addsObject
,Map
,ST
, andAggregate
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 theadaptor
argument.This must invalidate cache entries, so set your adaptors up before calling
ST.render()
for efficiency. -
getModelAdaptor
-
registerRenderer
Register a renderer for all objects of a particular "kind" for all templates evaluated relative to this group. User
to render if object in question is an instance ofattributeType
. Recursively set renderer into all import groups. -
registerRenderer
public <T> void registerRenderer(Class<T> attributeType, AttributeRenderer<? super T> r, boolean recursive) -
getAttributeRenderer
Get renderer for classT
associated with this group.For non-imported groups and object-to-render of class
T
, use renderer (if any) registered forT
. 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 forString
, say, then just make uber combined renderer with more specific format names. -
createStringTemplate
-
createStringTemplateInternally
Differentiate so we can avoid having creation events for regions, map operations, and other implicit "new ST" events during rendering. -
createStringTemplateInternally
-
getName
-
getFileName
-
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
-
toString
-
show
-
getListener
-
setListener
-
getTemplateNames
-