public class STGroup extends Object
.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).Modifier and Type | Field and 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 to
Map objects representing the dictionaries
defined by the user like typeInitMap ::= ["int":"0"] . |
String |
encoding
The encoding to use for loading files.
|
ErrorManager |
errMgr
The
ErrorManager 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 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 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 to
CompiledST object. |
static boolean |
trackCreationEvents
For debugging with
STViz . |
static boolean |
verbose
Watch loading of groups and templates.
|
Constructor and Description |
---|
STGroup() |
STGroup(char delimiterStartChar,
char delimiterStopChar) |
Modifier and Type | Method and 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 testing
|
CompiledST |
defineTemplate(String name,
String argsS,
String template)
for testing
|
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,
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" 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.
|
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 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 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.
|
public static final String GROUP_FILE_EXTENSION
public static final String TEMPLATE_FILE_EXTENSION
public static final String DICT_KEY
public static final String DEFAULT_KEY
public String encoding
protected final List<STGroup> imports
importTemplates(org.stringtemplate.v4.STGroup)
).public char delimiterStartChar
public char delimiterStopChar
protected Map<String,CompiledST> templates
CompiledST
object. This map is synchronized.protected Map<String,Map<String,Object>> dictionaries
Map
objects representing the dictionaries
defined by the user like typeInitMap ::= ["int":"0"]
.protected Map<Class<?>,AttributeRenderer> renderers
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.
protected final Map<Class<?>,ModelAdaptor> adaptors
ST initializes with model adaptors that know how to pull
properties out of Object
s, Map
s, and ST
s.
The last one you register gets priority; do least to most specific.
protected static final CompiledST NOT_FOUND_ST
public static final ErrorManager DEFAULT_ERR_MGR
public static boolean verbose
public static boolean trackCreationEvents
public boolean iterateAcrossValues
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.public static STGroup defaultGroup
public ErrorManager errMgr
ErrorManager
for entire group; all compilations and executions.
This gets copied to parsers, walkers, and interpreters.public STGroup()
public STGroup(char delimiterStartChar, char delimiterStopChar)
public ST getInstanceOf(String name)
/a/b
.protected ST getEmbeddedInstanceOf(Interpreter interp, InstanceScope scope, String name)
public ST createSingleton(org.antlr.runtime.Token templateToken)
public boolean isDefined(String name)
/a/b
.public CompiledST lookupTemplate(String name)
public void unload()
getInstanceOf(java.lang.String)
to reload templates. Call unload()
on each
group in the imports
list, and remove all elements in
importsToClearOnUnload
from imports
.protected CompiledST load(String name)
name
is fully-qualified.public void load()
protected CompiledST lookupImportedTemplate(String name)
public CompiledST rawGetTemplate(String name)
public boolean isDictionary(String name)
public CompiledST defineTemplate(String templateName, String template)
public CompiledST defineTemplate(String name, String argsS, String template)
public CompiledST defineTemplate(String fullyQualifiedTemplateName, org.antlr.runtime.Token nameT, List<FormalArgument> args, String template, org.antlr.runtime.Token templateToken)
public CompiledST defineTemplateAlias(org.antlr.runtime.Token aliasT, org.antlr.runtime.Token targetT)
public CompiledST defineRegion(String enclosingTemplateName, org.antlr.runtime.Token regionT, String template, org.antlr.runtime.Token templateToken)
public void defineTemplateOrRegion(String fullyQualifiedTemplateName, String regionSurroundingTemplateName, org.antlr.runtime.Token templateToken, String template, org.antlr.runtime.Token nameToken, List<FormalArgument> args)
public void rawDefineTemplate(String name, CompiledST code, org.antlr.runtime.Token defT)
public void undefineTemplate(String name)
public CompiledST compile(String srcName, String name, List<FormalArgument> args, String template, org.antlr.runtime.Token templateToken)
public static String getMangledRegionName(String enclosingTemplateName, String name)
"foo"
of t() ::= "<@foo()>"
is mangled to
"/region__/t__foo"
public static String getUnMangledTemplateName(String mangledName)
"t.foo"
from "/region__/t__foo"
public void defineDictionary(String name, Map<String,Object> mapping)
Not thread safe...do not keep adding these while you reference them.
public void importTemplates(STGroup g)
g
.
On unload imported templates are unloaded but stay in the imports
list.
public void importTemplates(org.antlr.runtime.Token fileNameToken)
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'.
protected void importTemplates(STGroup g, boolean clearOnUnload)
public void loadGroupFile(String prefix, String fileName)
fileName
; it's relative to root by prefix
.public CompiledST loadAbsoluteTemplateFile(String fileName)
fileName
.public CompiledST loadTemplateFile(String prefix, String unqualifiedFileName, org.antlr.runtime.CharStream templateStream)
unqualifiedFileName
is
"a.st"
. The prefix
is path from group root to
unqualifiedFileName
like "/subdir"
if file is in
/subdir/a.st
.public void registerModelAdaptor(Class<?> attributeType, ModelAdaptor adaptor)
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.
public ModelAdaptor getModelAdaptor(Class<?> attributeType)
public void registerRenderer(Class<?> attributeType, AttributeRenderer r)
r
to render if
object in question is an instance of attributeType
. Recursively
set renderer into all import groups.public void registerRenderer(Class<?> attributeType, AttributeRenderer r, boolean recursive)
public AttributeRenderer getAttributeRenderer(Class<?> attributeType)
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.
public ST createStringTemplate(CompiledST impl)
public ST createStringTemplateInternally(CompiledST impl)
public String getName()
public String getFileName()
public URL getRootDirURL()
public String show()
public STErrorListener getListener()
public void setListener(STErrorListener listener)
Copyright © 2024. All rights reserved.