StringTemplate 4 4.3.4 · org.stringtemplate.v4.STGroup

Field Summary

Modifier and Type	Field and Description
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).
public static final ErrorManager	DEFAULT_ERR_MGR
public static final String	DEFAULT_KEY
public static STGroup	defaultGroup
public char	delimiterStartChar
public char	delimiterStopChar
public static final 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"]`.
public String	encoding The encoding to use for loading files.
public ErrorManager	errMgr The `ErrorManager` for entire group; all compilations and executions.
public static final String	GROUP_FILE_EXTENSION
protected final List<STGroup>	imports Every group can import templates/dictionaries from other groups.
protected final List<STGroup>	importsToClearOnUnload
public boolean	iterateAcrossValues v3 compatibility; used to iterate across `Map#values()` instead of v4's default `Map#keySet()`.
protected static final 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.
private static final boolean[]	RESERVED_CHARACTERS
public static final String	TEMPLATE_FILE_EXTENSION
protected Map<String, CompiledST>	templates Maps template name to `CompiledST` object.
public static boolean	trackCreationEvents For debugging with `STViz`.
public static boolean	verbose Watch loading of groups and templates.

Constructor Summary

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

Method Summary

Modifier and Type	Method and Description
public CompiledST	compile(String srcName, String name, List<FormalArgument> args, String template, Token templateToken) Compile a template.
public ST	createSingleton(Token templateToken) Create singleton template for use with dictionary values.
public ST	createStringTemplate(CompiledST impl)
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.
public ST	createStringTemplateInternally(ST proto)
public void	defineDictionary(String name, Map<String, Object> mapping) Define a map for this group.
public CompiledST	defineRegion(String enclosingTemplateName, Token regionT, String template, Token templateToken)
public CompiledST	defineTemplate(String templateName, String template) for testing
public CompiledST	defineTemplate(String name, String argsS, String template) for testing
public CompiledST	defineTemplate(String fullyQualifiedTemplateName, Token nameT, List<FormalArgument> args, String template, Token templateToken)
public CompiledST	defineTemplateAlias(Token aliasT, Token targetT) Make name and alias for target.
public void	defineTemplateOrRegion(String fullyQualifiedTemplateName, String regionSurroundingTemplateName, Token templateToken, String template, Token nameToken, List<FormalArgument> args)
public <T> AttributeRenderer<? super T>	getAttributeRenderer(Class<T> attributeType) Get renderer for class `T` associated with this group.
protected ST	getEmbeddedInstanceOf(Interpreter interp, InstanceScope scope, String name)
public String	getFileName()
public List<STGroup>	getImportedGroups()
public ST	getInstanceOf(String name) The primary means of getting an instance of a template from this group.
public STErrorListener	getListener()
public static String	getMangledRegionName(String enclosingTemplateName, String name) The `"foo"` of `t() ::= "<@foo()>"` is mangled to `"/region__/t__foo"`
public <T> ModelAdaptor<? super T>	getModelAdaptor(Class<T> attributeType)
public String	getName()
public URL	getRootDirURL() Return root dir if this is group dir; return dir containing group file if this is group file.
public Set<String>	getTemplateNames()
public static String	getUnMangledTemplateName(String mangledName) Return `"t.foo"` from `"/region__/t__foo"`
public URL	getURL(String fileName)
public void	importTemplates(STGroup g) Make this group import templates/dictionaries from `g`.
public void	importTemplates(Token fileNameToken) Import template files, directories, and group files.
protected void	importTemplates(STGroup g, boolean clearOnUnload)
public boolean	isDefined(String name) Is this template defined in this group or from this group below?
public boolean	isDictionary(String name)
public static boolean	Returns: `true` if the character is reserved by the StringTemplate language; otherwise, `false` if the character may be used as a delimiter. isReservedCharacter(char The character c) Determines if a specified character may be used as a user-specified delimiter.
protected CompiledST	load(String name) Load st from disk if directory or load whole group file if .stg file (then return just one template).
public void	load() Force a load if it makes sense for the group.
public CompiledST	loadAbsoluteTemplateFile(String fileName) Load template file into this group using absolute `fileName`.
public void	loadGroupFile(String prefix, String fileName) Load a group file with full path `fileName`; it's relative to root by `prefix`.
public CompiledST	loadTemplateFile(String prefix, String unqualifiedFileName, CharStream templateStream) Load template stream into this group.
protected CompiledST	lookupImportedTemplate(String name)
public CompiledST	lookupTemplate(String name) Look up a fully-qualified name.
public void	rawDefineTemplate(String name, CompiledST code, Token defT)
public Map<String, Object>	rawGetDictionary(String name)
public CompiledST	rawGetTemplate(String name)
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.
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.
public <T> void	registerRenderer(Class<T> attributeType, AttributeRenderer<? super T> r, boolean recursive)
public void	setListener(STErrorListener listener)
public String	show()
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
public void	undefineTemplate(String name)
public synchronized void	unload() Unload all templates, dictionaries and import relationships, but leave renderers and adaptors.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

adaptors back to summary

adaptors	back to summary
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, and `ST`s. The last one you register gets priority; do least to most specific.

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 Objects, Maps, and STs.

The last one you register gets priority; do least to most specific.

DEFAULT_ERR_MGR	back to summary
public static final ErrorManager DEFAULT_ERR_MGR

DEFAULT_KEY	back to summary
public static final String DEFAULT_KEY

defaultGroup	back to summary
public static STGroup defaultGroup

delimiterStartChar	back to summary
public char delimiterStartChar

delimiterStopChar	back to summary
public char delimiterStopChar

DICT_KEY	back to summary
public static final String DICT_KEY When we use key as a value in a dictionary, this is how we signify.

dictionaries	back to summary
protected Map<String, Map<String, Object>> dictionaries Maps dictionary names to `Map` objects representing the dictionaries defined by the user like `typeInitMap ::= ["int":"0"]`.

encoding	back to summary
public String encoding The encoding to use for loading files. Defaults to UTF-8.

errMgr	back to summary
public ErrorManager errMgr The `ErrorManager` for entire group; all compilations and executions. This gets copied to parsers, walkers, and interpreters.

GROUP_FILE_EXTENSION	back to summary
public static final String GROUP_FILE_EXTENSION

imports	back to summary
protected final List<STGroup> imports Every group can import templates/dictionaries from other groups. The list must be synchronized (see `STGroup#importTemplates`).

importsToClearOnUnload	back to summary
protected final List<STGroup> importsToClearOnUnload

iterateAcrossValues	back to summary
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.

NOT_FOUND_ST	back to summary
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.

renderers back to summary

renderers	back to summary
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 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.

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

RESERVED_CHARACTERS	back to summary
private static final boolean[] RESERVED_CHARACTERS

TEMPLATE_FILE_EXTENSION	back to summary
public static final String TEMPLATE_FILE_EXTENSION

templates	back to summary
protected Map<String, CompiledST> templates Maps template name to `CompiledST` object. This map is synchronized.

trackCreationEvents	back to summary
public static boolean trackCreationEvents For debugging with `STViz`. Records where in code an `ST` was created and where code added attributes.

verbose	back to summary
public static boolean verbose Watch loading of groups and templates.

Constructor Detail

STGroup	back to summary
public STGroup()

STGroup	back to summary
public STGroup(char delimiterStartChar, char delimiterStopChar)

Method Detail

compile	back to summary
public CompiledST compile(String srcName, String name, List<FormalArgument> args, String template, Token templateToken) Compile a template.

createSingleton	back to summary
public ST createSingleton(Token templateToken) Create singleton template for use with dictionary values.

createStringTemplate	back to summary
public ST createStringTemplate(CompiledST impl)

createStringTemplateInternally	back to summary
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	back to summary
public ST createStringTemplateInternally(ST proto)

defineDictionary	back to summary
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.

defineDictionary

back to summary

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.

defineRegion	back to summary
public CompiledST defineRegion(String enclosingTemplateName, Token regionT, String template, Token templateToken)

defineTemplate	back to summary
public CompiledST defineTemplate(String templateName, String template) for testing

defineTemplate	back to summary
public CompiledST defineTemplate(String name, String argsS, String template) for testing

defineTemplate	back to summary
public CompiledST defineTemplate(String fullyQualifiedTemplateName, Token nameT, List<FormalArgument> args, String template, Token templateToken)

defineTemplateAlias	back to summary
public CompiledST defineTemplateAlias(Token aliasT, Token targetT) Make name and alias for target. Replace any previous definition of name.

defineTemplateOrRegion	back to summary
public void defineTemplateOrRegion(String fullyQualifiedTemplateName, String regionSurroundingTemplateName, Token templateToken, String template, Token nameToken, List<FormalArgument> args)

getAttributeRenderer back to summary

getAttributeRenderer	back to summary
public <T> AttributeRenderer<? super T> getAttributeRenderer(Class<T> 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.

public <T> AttributeRenderer<? super T> getAttributeRenderer(Class<T> 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.

getEmbeddedInstanceOf	back to summary
protected ST getEmbeddedInstanceOf(Interpreter interp, InstanceScope scope, String name)

getFileName	back to summary
public String getFileName()

getImportedGroups	back to summary
public List<STGroup> getImportedGroups()

getInstanceOf	back to summary
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`.

getListener	back to summary
public STErrorListener getListener()

getMangledRegionName	back to summary
public static String getMangledRegionName(String enclosingTemplateName, String name) The `"foo"` of `t() ::= "<@foo()>"` is mangled to `"/region__/t__foo"`

getModelAdaptor	back to summary
public <T> ModelAdaptor<? super T> getModelAdaptor(Class<T> attributeType)

getName	back to summary
public String getName()

getRootDirURL	back to summary
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.

getTemplateNames	back to summary
public Set<String> getTemplateNames()

getUnMangledTemplateName	back to summary
public static String getUnMangledTemplateName(String mangledName) Return `"t.foo"` from `"/region__/t__foo"`

getURL	back to summary
public URL getURL(String fileName)

importTemplates back to summary

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 back to summary

public void importTemplates(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	back to summary
protected void importTemplates(STGroup g, boolean clearOnUnload)

isDefined	back to summary
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`.

isDictionary	back to summary
public boolean isDictionary(String name)

isReservedCharacter back to summary

public static boolean isReservedCharacter(char c)

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

Parameters

c:char: The character

Returns:boolean

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

load	back to summary
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	back to summary
public void load() Force a load if it makes sense for the group.

loadAbsoluteTemplateFile	back to summary
public CompiledST loadAbsoluteTemplateFile(String fileName) Load template file into this group using absolute `fileName`.

loadGroupFile	back to summary
public void loadGroupFile(String prefix, String fileName) Load a group file with full path `fileName`; it's relative to root by `prefix`.

loadTemplateFile	back to summary
public CompiledST loadTemplateFile(String prefix, String unqualifiedFileName, 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`.

lookupImportedTemplate	back to summary
protected CompiledST lookupImportedTemplate(String name)

lookupTemplate	back to summary
public CompiledST lookupTemplate(String name) Look up a fully-qualified name.

rawDefineTemplate	back to summary
public void rawDefineTemplate(String name, CompiledST code, Token defT)

rawGetDictionary	back to summary
public Map<String, Object> rawGetDictionary(String name)

rawGetTemplate	back to summary
public CompiledST rawGetTemplate(String name)

registerModelAdaptor back to summary

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

registerRenderer	back to summary
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. Use `r` to render if object in question is an instance of `attributeType`. Recursively set renderer into all import groups.

registerRenderer	back to summary
public <T> void registerRenderer(Class<T> attributeType, AttributeRenderer<? super T> r, boolean recursive)

setListener	back to summary
public void setListener(STErrorListener listener)

show	back to summary
public String show()

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object

Annotations

@Override

undefineTemplate	back to summary
public void undefineTemplate(String name)