ST condensed -- API -- StringTemplate

Javadocs from http://www.stringtemplate.org/api/org/antlr/stringtemplate/StringTemplate.html
2009-05-24. StringTemplate presumably version 3.2 and current, but no date or version number shown
See annotations by GW in red, or search for [GW] to find them.

org.antlr.stringtemplate
Class StringTemplate

java.lang.Object
  org.antlr.stringtemplate.StringTemplate

public class StringTemplate
extends java.lang.Object

Overview

Java doc says...	[GW] Comments
A `StringTemplate` is a "document" with holes in it where you can stick values.	A StringTemplate is a java object which produces output text based upon an input text ("template") which contains literal text to be copied to the output, alternating with expressions that StringTemplate fills in with values supplied by the calling program or more elaborately derived text. The template text may be provided to StringTemplate directly by the calling program, or from file or stream.
`StringTemplate` breaks up your template into chunks of text and attribute expressions.	Upon reading a template text, a StringTemplate distinguishes the literal text portions of the text from the expression portions. (I suggest not describing this as "breaking up the template into chunks". To the extent that StringTemplate's internal implementation derives collections of literal text and expressions, these are not usually exposed to or of interest to the calling program.)
`StringTemplate` ignores everything outside of attribute expressions,	StringTemplate does not ignore the text outside of the expressions. StringTemplate stores the literal text portions of the template text verbatim, to be combined with the processed expressions when it produces output (via toString( ) ).
treating it as just text to spit out when you call `StringTemplate.toString()`.	.. right.

Constructors

If a program creates and uses individual StringTemplate objects, then usually the caller would supply the template text when calling the constructor. There are variants to allow also making the StringTemplate a member of a group, and/or choosing which characters will be recognized as expression delimiters.

Constructor Summary javadoc		[GW Comments]
`StringTemplate()` Create a blank template with no pattern and no attributes	1	Is this actually useful for any use cases, or is this for internal use only?
`StringTemplate(java.lang.String template)` Create an anonymous template.	2	StringTemplate which doesn't invoke or get invoked by other templates. Expects text to use $...$ as expression delimiters.
`StringTemplate(java.lang.String template, java.lang.Class lexer)`	3	Like 2, but caller must specify a lexer to use. To use <...> expression delimiters, use `AngleBracketTemplateLexer.class` for the lexer argument.
`StringTemplate(StringTemplateGroup group, java.lang.String template)` Create an anonymous template with no name, but with a group	4	StringTemplate made part of a StringTemplateGroup. This StringTemplate may invoke other templates in the group, but can't be invoked by others as this one has no name. The choice of which expression delimiter this StringTemplate will recognize is set by the StringTemplateGroup.
`StringTemplate(StringTemplateGroup group, java.lang.String template, java.util.HashMap attributes)`	5	Like 4, but with attributes supplied at the same time. (Other constructors expect the caller to supply attributes in a separate step, for example with setAttribute.)

Methods

Only a small subset of methods would normally be used by the calling program. I have rearranged these to the top of the table, and grouped them under a few functional areas. Many more methods are exposed, but are primarily for internal use by StringTemplate. I have shaded these less-used methods.

Functional area	Method Summary	Description	[GW Comments]
Copy	`StringTemplate`	`getInstanceOf()` Make an instance of this template; it contains an exact copy of everything (except the attributes and enclosing instance pointer).
Attributes
	`void`	`setAttribute(java.lang.String name, int value)` Convenience method to box ints
	`void`	`setAttribute(java.lang.String name, java.lang.Object value)` Set an attribute for this template.
	`protected void`	`setAttribute(java.lang.String aggrSpec, java.lang.Object[] values)` Create an aggregate from the list of properties in aggrSpec and fill with values from values array.
	`void`	`setAttribute(java.lang.String aggrSpec, java.lang.Object v1, java.lang.Object v2)` Set an aggregate attribute with two values.
	`void`	`setAttribute(java.lang.String aggrSpec, java.lang.Object v1, java.lang.Object v2, java.lang.Object v3)`
	`void`	`setAttribute(java.lang.String aggrSpec, java.lang.Object v1, java.lang.Object v2, java.lang.Object v3, java.lang.Object v4)`
	`void`	`setAttribute(java.lang.String aggrSpec, java.lang.Object v1, java.lang.Object v2, java.lang.Object v3, java.lang.Object v4, java.lang.Object v5)`
	`void`	`setAttributes(java.util.Map attributes)`
	`void`	`removeAttribute(java.lang.String name)`
	`void`	`reset()`	Discard existing attributes (ie: Prepare to reuse this StringTemplate with new attributes.)
	`java.lang.Object`	`getAttribute(java.lang.String name)`
	`java.util.Map`	`getAttributes()`

Renderer
	`void`	`registerRenderer(java.lang.Class attributeClassType, AttributeRenderer renderer)` Register a renderer for all objects of a particular type.	Ie: This is the way to add the capability to format the strings produced when StringTemplate renders expressions. Also used with the "format" feature of expressions.
	`void`	`setAttributeRenderers(java.util.Map renderers)` Specify a complete map of what object classes should map to which renderer objects.
Output
	`java.lang.String`	`toString()`	Main output method!
	`java.lang.String`	`toString(int lineWidth)`	Alternative main output method!
	`java.lang.String`	`toStructureString()` Don't print values, just report the nested structure with attribute names.	"print" = put result into the String return value.
	`java.lang.String`	`toStructureString(int indent)`
	`java.lang.String`	`toDebugString()`	toDebugString and printDebugString produce different output, see source code.
	`void`	`printDebugString()`	Here "print" means send output to standard output, probably the java console.
Settings
	`void`	`setErrorListener(StringTemplateErrorListener listener)`	Without an error listener, warnings go to standard output, and error messages go to standard error output (and usually both of those go to the console window).
	`void`	`setPassThroughAttributes(boolean passThroughAttributes)` Normally if you call template y from x, y cannot see any attributes of x that are defined as formal parameters of y.	And so what this setting does is....
	`static void`	`setLintMode(boolean lint)` Make StringTemplate check your work as it evaluates templates.	Reports problems via warning( ), which will go to the (error) listener if set, else console.
Internal
	`void`	`addChunk(Expr e)`
	`void`	`addRegionName(java.lang.String name)`
	`protected void`	`breakTemplateIntoChunks()` Walk a template, breaking it into a list of chunks: Strings and actions/expressions.
	`protected void`	`checkForTrouble()` Executed after evaluating a template.
	`protected void`	`checkNullAttributeAgainstFormalArguments(StringTemplate self, java.lang.String attribute)` A reference to an attribute with no value, must be compared against the formal parameter to see if it exists; if it exists all is well, but if not, throw an exception.
	`boolean`	`containsRegionName(java.lang.String name)` Does this template ref or embed region name?
	`void`	`defineEmptyFormalArgumentList()`	Pretty sure internal only
	`void`	`defineFormalArgument(java.lang.String name)`	Pretty sure internal only
	`void`	`defineFormalArgument(java.lang.String name, StringTemplate defaultValue)`	Pretty sure internal only
	`void`	`defineFormalArguments(java.util.List names)`	Pretty sure internal only
	`protected void`	`dup(StringTemplate from, StringTemplate to)` Make the 'to' template look exactly like the 'from' template except for the attributes.
	`void`	`error(java.lang.String msg)`
	`void`	`error(java.lang.String msg, java.lang.Throwable e)`
	`java.lang.Object`	`get(StringTemplate self, java.lang.String attribute)` Resolve an attribute reference.
	`java.util.Map`	`getArgumentContext()`
	`StringTemplateAST`	`getArgumentsAST()`
	`AttributeRenderer`	`getAttributeRenderer(java.lang.Class attributeClassType)` What renderer is registered for this attributeClassType for this template.
	`java.util.List`	`getChunks()` Get a list of the strings and subtemplates and attribute refs in a template.
	`void`	`getDependencyGraph(java.util.Map edges, boolean showAttributes)` Get a list of n->m edges where template n contains template m.
	`StringTemplate`	`getDOTForDependencyGraph(boolean showAttributes)` Generate a DOT file for displaying the template enclosure graph; e.g., digraph prof { "t1" -> "t2" "t1" -> "t3" "t4" -> "t5" }
	`StringTemplate`	`getEnclosingInstance()`
	`java.lang.String`	`getEnclosingInstanceStackString()` If an instance of x is enclosed in a y which is in a z, return a String of these instance names in order from topmost to lowest; here that would be "[z y x]".
	`java.lang.String`	`getEnclosingInstanceStackTrace()`
	`StringTemplateErrorListener`	`getErrorListener()`
	`FormalArgument`	`getFormalArgument(java.lang.String name)`
	`java.util.Map`	`getFormalArguments()`
	`StringTemplateGroup`	`getGroup()`
	`int`	`getGroupFileLine()` Return the outermost template's group file line number
	`java.lang.String`	`getName()`
	`StringTemplateGroup`	`getNativeGroup()`
	`StringTemplate`	`getOutermostEnclosingInstance()`
	`java.lang.String`	`getOutermostName()`
	`int`	`getRegionDefType()`
	`java.lang.String`	`getTemplate()`
	`java.lang.String`	`getTemplateDeclaratorString()`
	`protected java.lang.String`	`getTemplateHeaderString(boolean showAttributes)`
	`int`	`getTemplateID()`
	`static boolean`	`inLintMode()`
	`static boolean`	`isRecursiveEnclosingInstance(StringTemplate st)` Look up the enclosing instance chain (and include this) to see if st is a template already in the enclosing instance chain.
	`boolean`	`isRegion()`
	`FormalArgument`	`lookupFormalArgument(java.lang.String name)` From this template upward in the enclosing template tree, recursively look for the formal parameter.
	`ASTExpr`	`parseAction(java.lang.String action)`
	`protected java.lang.String`	`parseAggregateAttributeSpec(java.lang.String aggrSpec, java.util.List properties)` Split "aggrName.{propName1,propName2}" into list [propName1,propName2] and the aggrName.
	`protected void`	`putToMultiValuedMap(java.util.Map map, java.lang.Object key, java.lang.Object value)` Manage a hash table like it has multiple unique values.
	`void`	`rawSetArgumentAttribute(StringTemplate embedded, java.util.Map attributes, java.lang.String name, java.lang.Object value)` Argument evaluation such as foo(x=y), x must be checked against foo's argument list not this's (which is the enclosing context).
	`protected void`	`rawSetAttribute(java.util.Map attributes, java.lang.String name, java.lang.Object value)` Map a value to a named attribute.
	`static void`	`resetTemplateCounter()` reset the template ID counter to 0; public so that testing routine can access but not really of interest to the user.
	`void`	`setArgumentContext(java.util.Map ac)`
	`void`	`setArgumentsAST(StringTemplateAST argumentsAST)`
	`void`	`setDefaultArgumentValues()` Set any default argument values that were not set by the invoking template or by setAttribute directly.
	`void`	`setEnclosingInstance(StringTemplate enclosingInstance)`
	`void`	`setFormalArguments(java.util.LinkedHashMap args)`
	`void`	`setGroup(StringTemplateGroup group)`
	`void`	`setGroupFileLine(int groupFileLine)`
	`void`	`setIsRegion(boolean isRegion)`
	`void`	`setName(java.lang.String name)`
	`void`	`setNativeGroup(StringTemplateGroup nativeGroup)`
	`void`	`setPredefinedAttributes()`
	`void`	`setRegionDefType(int regionDefType)`
	`void`	`setTemplate(java.lang.String template)`	Is there a use case for this, as opposed to setting the template in the constructor or via StringTemplateGroup?
	`protected void`	`trackAttributeReference(java.lang.String name)` Indicates that 'name' has been referenced in this template.	Contrary to the javadoc, this method does not indicate anything. It prepares the StringTemplate to track references to the attribute named 'name'. Part of diagnostics during write if setLintMode is enabled.
	`void`	`warning(java.lang.String msg)`
	`int`	`write(StringTemplateWriter out)` Walk the chunks, asking them to write themselves out according to attribute values of 'this.attributes'.

Field Summary

So far as I can see, in normal operation a calling program does not interact with any fields directly. Consequently, I have not refined the Field Summary, much: I have not reordered the rows. I have shaded out most of the rows, but left unshaded those which constitute core concepts for understanding StringTemplate. These mostly correspond to the unshaded methods above.

Field Summary		[GW Comments]
`static java.lang.String`	`ANONYMOUS_ST_NAME`
`protected java.util.Map`	`argumentContext` If this template is an embedded template such as when you apply a template to an attribute, then the arguments passed to this template represent the argument context--a set of values computed by walking the argument assignment list.
`protected StringTemplateAST`	`argumentsAST` If this template is embedded in another template, the arguments must be evaluated just before each application when applying template to a list of values.
`protected java.util.Map`	`attributeRenderers` A Map that allows people to register a renderer for a particular kind of object to be displayed in this template.
`protected java.util.Map`	`attributes` Map an attribute name to its value(s).
`protected java.util.List`	`chunks` A list of alternating string and ASTExpr references.
`static StringTemplateGroup`	`defaultGroup`
`protected StringTemplate`	`enclosingInstance` Enclosing instance if I'm embedded within another template.
`protected java.util.LinkedHashMap`	`formalArguments` When templates are defined in a group file format, the attribute list is provided including information about attribute cardinality such as present, optional, ...
`protected StringTemplateGroup`	`group` This template was created as part of what group? Even if this template was created from a prototype in a supergroup, its group will be the subgroup.
`protected int`	`groupFileLine` If this template is defined within a group file, what line number?
`protected boolean`	`isRegion` Does this template come from a <@region>...<@end> embedded in another template?
`(package private) static boolean`	`lintMode` track probable issues like setting attribute that is not referenced.
`(package private) StringTemplateErrorListener`	`listener` Where to report errors
`protected java.lang.String`	`name` What's the name of this template?
`protected StringTemplateGroup`	`nativeGroup` What group originally defined the prototype for this template? This affects the set of templates I can refer to.
`protected int`	`numberOfDefaultArgumentValues` How many formal arguments to this template have default values specified?
`protected boolean`	`passThroughAttributes` Normally, formal parameters hide any attributes inherited from the enclosing template with the same name.
`protected java.lang.String`	`pattern` The original, immutable pattern/language (not really used again after initial "compilation", setup/parsing).	Ie: Should be called "patternText" or somesuch. This is where the original template text gets stored.
`protected java.util.List`	`referencedAttributes`
`static int`	`REGION_EMBEDDED` <@r>...<@end>
`static int`	`REGION_EXPLICIT`
`static int`	`REGION_IMPLICIT` <@r()>
`protected int`	`regionDefType` If someone refs <@r()> in template t, an implicit
`protected java.util.Set`	`regions` Set of implicit and embedded regions for this template
`protected int`	`templateID`
`static java.lang.String`	`VERSION`