Package org.antlr.stringtemplate
Class StringTemplate
java.lang.Object
org.antlr.stringtemplate.StringTemplate
A StringTemplate is a "document" with holes in it where you can stick
values. StringTemplate breaks up your template into chunks of text and
attribute expressions. StringTemplate ignores everything outside
of attribute expressions, treating it as just text to spit
out when you call StringTemplate.toString().
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final class
An automatically created aggregate of properties.static final class
Just an alias for ArrayList, but this way I can track whether a list is something ST created or it's an incoming list. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
protected Map
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
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 Map
A Mapinvalid input: '<'Class,Object> that allows people to register a renderer for a particular kind of object to be displayed in this template.protected Map
Map an attribute name to its value(s).protected List
A list of alternating string and ASTExpr references.static StringTemplateGroup
protected StringTemplate
Enclosing instance if I'm embedded within another template.protected LinkedHashMap
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
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
If this template is defined within a group file, what line number?protected boolean
Does this template come from a invalid input: '<'@region>...invalid input: '<'@end> embedded in another template?protected String
What's the name of this template?protected StringTemplateGroup
What group originally defined the prototype for this template? This affects the set of templates I can refer to.protected int
How many formal arguments to this template have default values specified?protected boolean
Normally, formal parameters hide any attributes inherited from the enclosing template with the same name.protected String
The original, immutable pattern/language (not really used again after initial "compilation", setup/parsing).protected List
static final int
invalid input: '<'@r>...invalid input: '<'@end>static final int
static final int
invalid input: '<'@r()>protected int
If someone refs invalid input: '<'@r()> in template t, an implicitprotected Set
Set of implicit and embedded regions for this templateprotected int
static final String
-
Constructor Summary
ConstructorsConstructorDescriptionCreate a blank template with no pattern and no attributesStringTemplate
(String template) Create an anonymous template.StringTemplate
(String template, Class lexer) StringTemplate
(StringTemplateGroup group, String template) Create an anonymous template with no name, but with a groupStringTemplate
(StringTemplateGroup group, String template, HashMap attributes) -
Method Summary
Modifier and TypeMethodDescriptionvoid
void
addRegionName
(String name) protected void
Walk a template, breaking it into a list of chunks: Strings and actions/expressions.protected void
Executed after evaluating a template.protected void
checkNullAttributeAgainstFormalArguments
(StringTemplate self, 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
(String name) Does this template ref or embed region name?void
void
defineFormalArgument
(String name) void
defineFormalArgument
(String name, StringTemplate defaultValue) void
defineFormalArguments
(List names) protected void
dup
(StringTemplate from, StringTemplate to) Make the 'to' template look exactly like the 'from' template except for the attributes.void
void
get
(StringTemplate self, String attribute) Resolve an attribute reference.getAttribute
(String name) getAttributeRenderer
(Class attributeClassType) What renderer is registered for this attributeClassType for this template.Get a list of the strings and subtemplates and attribute refs in a template.void
getDependencyGraph
(Map edges, boolean showAttributes) Get a list of n->m edges where template n contains template m.getDOTForDependencyGraph
(boolean showAttributes) Generate a DOT file for displaying the template enclosure graph; e.g., digraph prof { "t1" -> "t2" "t1" -> "t3" "t4" -> "t5" }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]".getFormalArgument
(String name) getGroup()
int
Return the outermost template's group file line numberMake an instance of this template; it contains an exact copy of everything (except the attributes and enclosing instance pointer).getName()
int
protected String
getTemplateHeaderString
(boolean showAttributes) int
static boolean
static boolean
Look up the enclosing instance chain (and include this) to see if st is a template already in the enclosing instance chain.boolean
isRegion()
lookupFormalArgument
(String name) From this template upward in the enclosing template tree, recursively look for the formal parameter.parseAction
(String action) protected String
parseAggregateAttributeSpec
(String aggrSpec, List properties) Split "aggrName.{propName1,propName2}" into list [propName1,propName2] and the aggrName.void
protected void
putToMultiValuedMap
(Map map, Object key, Object value) Manage a hash table like it has multiple unique values.void
rawSetArgumentAttribute
(StringTemplate embedded, Map attributes, String name, 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
(Map attributes, String name, Object value) Map a value to a named attribute.void
registerRenderer
(Class attributeClassType, AttributeRenderer renderer) Register a renderer for all objects of a particular type.void
removeAttribute
(String name) void
reset()
static void
reset the template ID counter to 0; public so that testing routine can access but not really of interest to the user.void
void
setArgumentsAST
(StringTemplateAST argumentsAST) void
setAttribute
(String name, int value) Convenience method to box intsvoid
setAttribute
(String name, Object value) Set an attribute for this template.protected void
setAttribute
(String aggrSpec, Object[] values) Create an aggregate from the list of properties in aggrSpec and fill with values from values array.void
setAttribute
(String aggrSpec, Object v1, Object v2) Set an aggregate attribute with two values.void
setAttribute
(String aggrSpec, Object v1, Object v2, Object v3) void
void
void
setAttributeRenderers
(Map renderers) Specify a complete map of what object classes should map to which renderer objects.void
setAttributes
(Map attributes) void
Set any default argument values that were not set by the invoking template or by setAttribute directly.void
setEnclosingInstance
(StringTemplate enclosingInstance) void
setErrorListener
(StringTemplateErrorListener listener) void
void
setGroup
(StringTemplateGroup group) void
setGroupFileLine
(int groupFileLine) void
setIsRegion
(boolean isRegion) static void
setLintMode
(boolean lint) Make StringTemplate check your work as it evaluates templates.void
void
setNativeGroup
(StringTemplateGroup nativeGroup) 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.void
void
setRegionDefType
(int regionDefType) void
setTemplate
(String template) toString()
toString
(int lineWidth) Don't print values, just report the nested structure with attribute names.toStructureString
(int indent) protected void
Indicates that 'name' has been referenced in this template.void
int
Walk the chunks, asking them to write themselves out according to attribute values of 'this.attributes'.
-
Field Details
-
VERSION
- See Also:
-
REGION_IMPLICIT
public static final int REGION_IMPLICITinvalid input: '<'@r()>- See Also:
-
REGION_EMBEDDED
public static final int REGION_EMBEDDEDinvalid input: '<'@r>...invalid input: '<'@end>- See Also:
-
REGION_EXPLICIT
public static final int REGION_EXPLICIT- See Also:
-
ANONYMOUS_ST_NAME
- See Also:
-
referencedAttributes
-
name
What's the name of this template? -
templateID
protected int templateID -
enclosingInstance
Enclosing instance if I'm embedded within another template. IF-subtemplates are considered embedded as well. -
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. For example, invalid input: '<'name:bold(item=name, foo="x")> would result in an argument context of {[item=name], [foo="x"]} for this template. This template would be the bold() template and the enclosingInstance would point at the template that held that invalid input: '<'name:bold(...)> template call. When you want to get an attribute value, you first check the attributes for the 'self' template then the arg context then the enclosingInstance like resolving variables in pascal-like language with nested procedures. With multi-valued attributes such as invalid input: '<'faqList:briefFAQDisplay()> attribute "i" is set to 1..n. -
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. The "it" attribute must change with each application so that $names:bold(item=it)$ works. If you evaluate once before starting the application loop then it has a single fixed value. Eval.g saves the AST rather than evaluating before invoking applyListOfAlternatingTemplates(). Each iteration of a template application to a multi-valued attribute, these args are re-evaluated with an initial context of {[it=...], [i=...]}. -
formalArguments
When templates are defined in a group file format, the attribute list is provided including information about attribute cardinality such as present, optional, ... When this information is available, rawSetAttribute should do a quick existence check as should the invocation of other templates. So if you ref bold(item="foo") but item is not defined in bold(), then an exception should be thrown. When actually rendering the template, the cardinality is checked. This is a Mapinvalid input: '<'String,FormalArgument>. -
numberOfDefaultArgumentValues
protected int numberOfDefaultArgumentValuesHow many formal arguments to this template have default values specified? -
passThroughAttributes
protected boolean passThroughAttributesNormally, formal parameters hide any attributes inherited from the enclosing template with the same name. This is normally what you want, but makes it hard to invoke another template passing in all the data. Use notation now: invalid input: '<'otherTemplate(...)> to say "pass in all data". Works great. Can also say invalid input: '<'otherTemplate(foo="xxx",...)> -
nativeGroup
What group originally defined the prototype for this template? This affects the set of templates I can refer to. super.t() must always refer to the super of the original group. group base; t ::= "base"; group sub; t ::= "super.t()2" group subsub; t ::= "super.t()3" -
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. That's the way polymorphism works. -
groupFileLine
protected int groupFileLineIf this template is defined within a group file, what line number? -
pattern
The original, immutable pattern/language (not really used again after initial "compilation", setup/parsing). -
attributes
Map an attribute name to its value(s). These values are set by outside code via st.setAttribute(name, value). StringTemplate is like self in that a template is both the "class def" and "instance". When you create a StringTemplate or setTemplate, the text is broken up into chunks (i.e., compiled down into a series of chunks that can be evaluated later). You can have multiple -
attributeRenderers
A Mapinvalid input: '<'Class,Object> that allows people to register a renderer for a particular kind of object to be displayed in this template. This overrides any renderer set for this template's group. Most of the time this map is not used because the StringTemplateGroup has the general renderer map for all templates in that group. Sometimes though you want to override the group's renderers. -
chunks
A list of alternating string and ASTExpr references. This is compiled to when the template is loaded/defined and walked to write out a template instance. -
regionDefType
protected int regionDefTypeIf someone refs invalid input: '<'@r()> in template t, an implicit -
isRegion
protected boolean isRegionDoes this template come from a invalid input: '<'@region>...invalid input: '<'@end> embedded in another template? -
regions
Set of implicit and embedded regions for this template -
defaultGroup
-
-
Constructor Details
-
StringTemplate
public StringTemplate()Create a blank template with no pattern and no attributes -
StringTemplate
Create an anonymous template. It has no name just chunks (which point to this anonymous template) and attributes. -
StringTemplate
-
StringTemplate
Create an anonymous template with no name, but with a group -
StringTemplate
-
-
Method Details
-
resetTemplateCounter
public 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. -
dup
Make the 'to' template look exactly like the 'from' template except for the attributes. This is like creating an instance of a class in that the executable code is the same (the template chunks), but the instance data is blank (the attributes). Do not copy the enclosingInstance pointer since you will want this template to eval in a context different from the examplar. -
getInstanceOf
Make an instance of this template; it contains an exact copy of everything (except the attributes and enclosing instance pointer). So the new template refers to the previously compiled chunks of this template but does not have any attribute values. -
getEnclosingInstance
-
getOutermostEnclosingInstance
-
setEnclosingInstance
-
getArgumentContext
-
setArgumentContext
-
getArgumentsAST
-
setArgumentsAST
-
getName
-
getOutermostName
-
setName
-
getGroup
-
setGroup
-
getNativeGroup
-
setNativeGroup
-
getGroupFileLine
public int getGroupFileLine()Return the outermost template's group file line number -
setGroupFileLine
public void setGroupFileLine(int groupFileLine) -
setTemplate
-
getTemplate
-
setErrorListener
-
getErrorListener
-
reset
public void reset() -
setPredefinedAttributes
public void setPredefinedAttributes() -
removeAttribute
-
setAttribute
Set an attribute for this template. If you set the same attribute more than once, you get a multi-valued attribute. If you send in a StringTemplate object as a value, it's enclosing instance (where it will inherit values from) is set to 'this'. This would be the normal case, though you can set it back to null after this call if you want. If you send in a List plus other values to the same attribute, they all get flattened into one List of values. This will be a new list object so that incoming objects are not altered. If you send in an array, it is converted to an ArrayIterator. -
setAttribute
Convenience method to box ints -
setAttribute
Set an aggregate attribute with two values. The attribute name must have the format: "name.{propName1,propName2}". -
setAttribute
-
setAttribute
-
setAttribute
-
setAttribute
Create an aggregate from the list of properties in aggrSpec and fill with values from values array. This is not publically visible because it conflicts semantically with setAttribute("foo",new Object[] {...}); -
parseAggregateAttributeSpec
Split "aggrName.{propName1,propName2}" into list [propName1,propName2] and the aggrName. Space is allowed around ','. -
rawSetAttribute
Map a value to a named attribute. Throw NoSuchElementException if the named attribute is not formally defined in self's specific template and a formal argument list exists. -
rawSetArgumentAttribute
public void rawSetArgumentAttribute(StringTemplate embedded, Map attributes, String name, 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). So far, only eval.g uses arg self as something other than "this". -
getAttribute
-
write
Walk the chunks, asking them to write themselves out according to attribute values of 'this.attributes'. This is like evaluating or interpreting the StringTemplate as a program using the attributes. The chunks will be identical (point at same list) for all instances of this template.- Throws:
IOException
-
get
Resolve an attribute reference. It can be in four possible places: 1. the attribute list for the current template 2. if self is an embedded template, somebody invoked us possibly with arguments--check the argument context 3. if self is an embedded template, the attribute list for the enclosing instance (recursively up the enclosing instance chain) 4. if nothing is found in the enclosing instance chain, then it might be a map defined in the group or the its supergroup etc... Attribute references are checked for validity. If an attribute has a value, its validity was checked before template rendering. If the attribute has no value, then we must check to ensure it is a valid reference. Somebody could reference any random value like $xyz$; formal arg checks before rendering cannot detect this--only the ref can initiate a validity check. So, if no value, walk up the enclosed template tree again, this time checking formal parameters not attributes Map. The formal definition must exist even if no value. To avoid infinite recursion in toString(), we have another condition to check regarding attribute values. If your template has a formal argument, foo, then foo will hide any value available from "above" in order to prevent infinite recursion. This method is not static so people can override functionality. -
breakTemplateIntoChunks
protected void breakTemplateIntoChunks()Walk a template, breaking it into a list of chunks: Strings and actions/expressions. -
parseAction
-
getTemplateID
public int getTemplateID() -
getAttributes
-
getChunks
Get a list of the strings and subtemplates and attribute refs in a template. -
addChunk
-
setAttributes
-
getFormalArguments
-
setFormalArguments
-
setDefaultArgumentValues
public void setDefaultArgumentValues()Set any default argument values that were not set by the invoking template or by setAttribute directly. Note that the default values may be templates. Their evaluation context is the template itself and, hence, can see attributes within the template, any arguments, and any values inherited by the template. Default values are stored in the argument context rather than the template attributes table just for consistency's sake. -
lookupFormalArgument
From this template upward in the enclosing template tree, recursively look for the formal parameter. -
getFormalArgument
-
defineEmptyFormalArgumentList
public void defineEmptyFormalArgumentList() -
defineFormalArgument
-
defineFormalArguments
-
defineFormalArgument
-
setPassThroughAttributes
public 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. Setting this passThroughAttributes to true, will override that and allow a template to see through the formal arg list to inherited values. -
setAttributeRenderers
Specify a complete map of what object classes should map to which renderer objects. -
registerRenderer
Register a renderer for all objects of a particular type. This overrides any renderer set in the group for this class type. -
getAttributeRenderer
What renderer is registered for this attributeClassType for this template. If not found, the template's group is queried. -
error
-
warning
-
error
-
setLintMode
public static void setLintMode(boolean lint) Make StringTemplate check your work as it evaluates templates. Problems are sent to error listener. Currently warns when you set attributes that are not used. -
inLintMode
public static boolean inLintMode() -
trackAttributeReference
Indicates that 'name' has been referenced in this template. -
isRecursiveEnclosingInstance
Look up the enclosing instance chain (and include this) to see if st is a template already in the enclosing instance chain. -
getEnclosingInstanceStackTrace
-
getTemplateDeclaratorString
-
getTemplateHeaderString
-
checkNullAttributeAgainstFormalArguments
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. Don't do the check if no formal parameters exist for this template; ask enclosing. -
checkForTrouble
protected void checkForTrouble()Executed after evaluating a template. For now, checks for setting of attributes not reference. -
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]". -
isRegion
public boolean isRegion() -
setIsRegion
public void setIsRegion(boolean isRegion) -
addRegionName
-
containsRegionName
Does this template ref or embed region name? -
getRegionDefType
public int getRegionDefType() -
setRegionDefType
public void setRegionDefType(int regionDefType) -
toDebugString
-
toStructureString
Don't print values, just report the nested structure with attribute names. Follow (nest) attributes that are templates only. -
toStructureString
-
getDOTForDependencyGraph
Generate a DOT file for displaying the template enclosure graph; e.g., digraph prof { "t1" -> "t2" "t1" -> "t3" "t4" -> "t5" } -
getDependencyGraph
Get a list of n->m edges where template n contains template m. The map you pass in is filled with edges: key->value. Useful for having DOT print out an enclosing template graph. It finds all direct template invocations too like invalid input: '<'foo()> but not indirect ones like invalid input: '<'(name)()>. Ack, I just realized that this is done statically and hence cannot see runtime arg values on statically included templates. Hmm...someday figure out to do this dynamically as if we were evaluating the templates. There will be extra nodes in the tree because we are static like method and method[...] with args. -
putToMultiValuedMap
Manage a hash table like it has multiple unique values. Mapinvalid input: '<'Object,Set>. -
printDebugString
public void printDebugString() -
toString
-
toString
-