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
Fields Modifier and Type Field 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 toMap
objects representing the dictionaries defined by the user liketypeInitMap ::= ["int":"0"]
.String
encoding
The encoding to use for loading files.ErrorManager
errMgr
TheErrorManager
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 acrossMap.values()
instead of v4's defaultMap.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 toCompiledST
object.static boolean
trackCreationEvents
For debugging withSTViz
.static boolean
verbose
Watch loading of groups and templates.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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 testingCompiledST
defineTemplate(String name, String argsS, String template)
for testingCompiledST
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)
<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)
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"
oft() ::= "<@foo()>"
is mangled to"/region__/t__foo"
<T> ModelAdaptor<? super T>
getModelAdaptor(Class<T> 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(org.antlr.runtime.Token fileNameToken)
Import template files, directories, and group files.void
importTemplates(STGroup g)
Make this group import templates/dictionaries fromg
.protected void
importTemplates(STGroup g, boolean clearOnUnload)
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)
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(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 absolutefileName
.void
loadGroupFile(String prefix, String fileName)
Load a group file with full pathfileName
; it's relative to root byprefix
.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)
<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)
String
show()
String
toString()
void
undefineTemplate(String name)
void
unload()
Unload all templates, dictionaries and import relationships, but leave renderers and adaptors.
-
-
-
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 (seeimportTemplates(org.stringtemplate.v4.STGroup)
).
-
delimiterStartChar
public char delimiterStartChar
-
delimiterStopChar
public char delimiterStopChar
-
templates
protected Map<String,CompiledST> templates
Maps template name toCompiledST
object. This map is synchronized.
-
dictionaries
protected Map<String,Map<String,Object>> dictionaries
Maps dictionary names toMap
objects representing the dictionaries defined by the user liketypeInitMap ::= ["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 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
protected final 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
Object
s,Map
s, andST
s.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
-
iterateAcrossValues
public boolean iterateAcrossValues
v3 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
public static STGroup defaultGroup
-
errMgr
public ErrorManager errMgr
TheErrorManager
for entire group; all compilations and executions. This gets copied to parsers, walkers, and interpreters.
-
-
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, InstanceScope scope, 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 togetInstanceOf(java.lang.String)
to reload templates. Callunload()
on each group in theimports
list, and remove all elements inimportsToClearOnUnload
fromimports
.
-
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.
-
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(String name)
-
rawGetTemplate
public CompiledST rawGetTemplate(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"
oft() ::= "<@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 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
protected void importTemplates(STGroup g, boolean clearOnUnload)
-
loadGroupFile
public void loadGroupFile(String prefix, String fileName)
Load a group file with full pathfileName
; it's relative to root byprefix
.
-
loadAbsoluteTemplateFile
public CompiledST loadAbsoluteTemplateFile(String fileName)
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
public <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. 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
public <T> ModelAdaptor<? super T> getModelAdaptor(Class<T> attributeType)
-
registerRenderer
public <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. 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
public <T> AttributeRenderer<? super T> getAttributeRenderer(Class<T> attributeType)
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
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.
-
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.
-
show
public String show()
-
getListener
public STErrorListener getListener()
-
setListener
public void setListener(STErrorListener listener)
-
-