|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.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, which are by default enclosed in angle brackets: <attribute-expression>. StringTemplate ignores everything outside of attribute expressions, treating it as just text to spit out when you call StringTemplate.toString().
StringTemplate is not a "system" or "engine" or "server"; it's a lib rary with two classes of interest: StringTemplate and StringTemplat eGroup. You can directly create a StringTemplate in Java code or you can load a template from a file.
A StringTemplate describes an output pattern/language like an exemplar.
StringTemplate and associated code is released under the BSD licence. See
source.
Copyright (c) 2003-2005 Terence Parr
A particular instance of a template may have a set of attributes that
you set programmatically. A template refers to these single or multi-
valued attributes when writing itself out. References within a
template conform to a simple language with attribute references and
references to other, embedded, templates. The references are surrounded
by user-defined start/stop strings (default of <...>, but $...$ works
well when referencing attributes in HTML to distinguish from tags).
StringTemplateGroup is a self-referential group of StringTemplate objects kind of like a grammar. It is very useful for keeping a group of templates together. For example, jGuru.com's premium and guest sites are completely separate sets of template files organized with a StringTemplateGroup. Changing "skins" is a simple matter of switching groups. Groups know where to load templates by either looking under a rootDir you can specify for the group or by simply looking for a resource file in the current class path. If no rootDir is specified, template files are assumed to be resources. So, if you reference template foo() and you have a rootDir, it looks for file rootDir/foo.st. If you don't have a rootDir, it looks for file foo.st in the CLASSPATH. note that you can use org/antlr/misc/foo() (qualified template names) as a template ref.
StringTemplateErrorListener is an interface you can implement to
specify where StringTemplate reports errors. Setting the listener
for a group automatically makes all associated StringTemplate
objects use the same listener. For example,
StringTemplateGroup group = new StringTemplateGroup("loutSyndiags");
group.setErrorListener(
new StringTemplateErrorListener() {
public void error(String msg, Exception e) {
System.err.println("StringTemplate error: "+
msg+((e!=null)?": "+e.getMessage():""));
}
}
);
IMPLEMENTATION
A StringTemplate is both class and instance like in Self. Given any StringTemplate (even one with attributes filled in), you can get a new "blank" instance of it.
When you define a template, the string pattern is parsed and broken up into chunks of either String or attribute/template actions. These are typically just attribute references. If a template is embedded within another template either via setAttribute or by implicit inclusion by referencing a template within a template, it inherits the attribute scope of the enclosing StringTemplate instance. All StringTemplate instances with the same pattern point to the same list of chunks since they are immutable there is no reason to have a copy in every instance of that pattern. The only thing that differs is that every StringTemplate Java object can have its own set of attributes. Each chunk points back at the original StringTemplate Java object whence they were constructed. So, there are multiple pointers to the list of chunks (one for each instance with that pattern) and only one back ptr from a chunk to the original pattern object. This is used primarily to get the grcoup of that original so new templates can be loaded into that group.
To write out a template, the chunks are walked in order and asked to write themselves out. String chunks are obviously just written out, but the attribute expressions/actions are evaluated in light of the attributes in that object and possibly in an enclosing instance.
Nested Class Summary | |
static class |
StringTemplate.Aggregate
An automatically created aggregate of properties. |
Field Summary | |
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 |
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. |
protected static StringTemplateGroup |
defaultGroup
|
protected java.util.List |
embeddedInstances
A list of embedded templates |
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
What group originally defined the prototype for this template? This affects the set of templates I can refer to. |
protected java.lang.String |
name
What's the name of this template? |
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). |
protected java.util.List |
referencedAttributes
|
protected int |
templateID
|
static java.lang.String |
VERSION
|
Constructor Summary | |
StringTemplate()
Create a blank template with no pattern and no attributes |
|
StringTemplate(java.lang.String template)
Create an anonymous template. |
|
StringTemplate(java.lang.String template,
java.lang.Class lexer)
|
|
StringTemplate(StringTemplateGroup group,
java.lang.String template)
Create an anonymous template with no name, but with a group |
Method Summary | |
void |
addChunk(Expr e)
|
void |
addEmbeddedInstance(StringTemplate embeddedInstance)
|
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. |
void |
debug(java.lang.String msg)
Deprecated. 2.2 |
void |
defineEmptyFormalArgumentList()
|
void |
defineFormalArgument(java.lang.String name)
|
void |
defineFormalArgument(java.lang.String name,
StringTemplate defaultValue)
|
void |
defineFormalArguments(java.util.List names)
|
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()
|
java.lang.Object |
getAttribute(java.lang.String name)
|
AttributeRenderer |
getAttributeRenderer(java.lang.Class attributeClassType)
What renderer is registered for this attributeClassType for this template. |
java.util.Map |
getAttributes()
|
java.util.List |
getChunks()
Get a list of the strings and subtemplates and attribute refs in a template. |
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()
|
StringTemplate |
getInstanceOf()
Make an instance of this template; it contains an exact copy of everything (except the attributes and enclosing instance pointer). |
java.lang.String |
getName()
|
java.lang.String |
getOutermostName()
|
java.lang.String |
getTemplate()
|
java.lang.String |
getTemplateDeclaratorString()
|
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. |
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. |
void |
printDebugString()
|
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. |
void |
registerRenderer(java.lang.Class attributeClassType,
java.lang.Object renderer)
Register a renderer for all objects of a particular type. |
void |
removeAttribute(java.lang.String name)
|
void |
reset()
|
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 |
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 |
setAttributeRenderers(java.util.Map renderers)
Specify a complete map of what object classes should map to which renderer objects. |
void |
setAttributes(java.util.Map attributes)
|
void |
setDefaultArgumentValues()
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 |
setFormalArguments(java.util.LinkedHashMap args)
|
void |
setGroup(StringTemplateGroup group)
|
static void |
setLintMode(boolean lint)
Make StringTemplate check your work as it evaluates templates. |
void |
setName(java.lang.String name)
|
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 |
setPredefinedAttributes()
|
void |
setTemplate(java.lang.String template)
|
java.lang.String |
toDebugString()
UNUSED |
java.lang.String |
toString()
|
protected void |
trackAttributeReference(java.lang.String name)
Indicates that 'name' has been referenced in this template. |
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'. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
public static final java.lang.String VERSION
public static final java.lang.String ANONYMOUS_ST_NAME
protected java.util.List referencedAttributes
protected java.lang.String name
protected int templateID
protected StringTemplate enclosingInstance
protected java.util.List embeddedInstances
protected java.util.Map argumentContext
protected StringTemplateAST argumentsAST
protected java.util.LinkedHashMap formalArguments
protected int numberOfDefaultArgumentValues
protected boolean passThroughAttributes
protected StringTemplateGroup group
protected java.lang.String pattern
protected java.util.Map attributes
protected java.util.Map attributeRenderers
protected java.util.List chunks
protected static StringTemplateGroup defaultGroup
Constructor Detail |
public StringTemplate()
public StringTemplate(java.lang.String template)
public StringTemplate(java.lang.String template, java.lang.Class lexer)
public StringTemplate(StringTemplateGroup group, java.lang.String template)
Method Detail |
public static void resetTemplateCounter()
protected void dup(StringTemplate from, StringTemplate to)
public StringTemplate getInstanceOf()
public StringTemplate getEnclosingInstance()
public void setEnclosingInstance(StringTemplate enclosingInstance)
public void addEmbeddedInstance(StringTemplate embeddedInstance)
public java.util.Map getArgumentContext()
public void setArgumentContext(java.util.Map ac)
public StringTemplateAST getArgumentsAST()
public void setArgumentsAST(StringTemplateAST argumentsAST)
public java.lang.String getName()
public java.lang.String getOutermostName()
public void setName(java.lang.String name)
public StringTemplateGroup getGroup()
public void setGroup(StringTemplateGroup group)
public void setTemplate(java.lang.String template)
public java.lang.String getTemplate()
public void setErrorListener(StringTemplateErrorListener listener)
public StringTemplateErrorListener getErrorListener()
public void reset()
public void setPredefinedAttributes()
public void removeAttribute(java.lang.String name)
public void setAttribute(java.lang.String name, java.lang.Object value)
public void setAttribute(java.lang.String name, int value)
public void setAttribute(java.lang.String aggrSpec, java.lang.Object v1, java.lang.Object v2)
public void setAttribute(java.lang.String aggrSpec, java.lang.Object v1, java.lang.Object v2, java.lang.Object v3)
public void setAttribute(java.lang.String aggrSpec, java.lang.Object v1, java.lang.Object v2, java.lang.Object v3, java.lang.Object v4)
public 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)
protected void setAttribute(java.lang.String aggrSpec, java.lang.Object[] values)
protected java.lang.String parseAggregateAttributeSpec(java.lang.String aggrSpec, java.util.List properties)
protected void rawSetAttribute(java.util.Map attributes, java.lang.String name, java.lang.Object value)
public void rawSetArgumentAttribute(StringTemplate embedded, java.util.Map attributes, java.lang.String name, java.lang.Object value)
public java.lang.Object getAttribute(java.lang.String name)
public int write(StringTemplateWriter out) throws java.io.IOException
java.io.IOException
public java.lang.Object get(StringTemplate self, java.lang.String attribute)
protected void breakTemplateIntoChunks()
public ASTExpr parseAction(java.lang.String action)
public int getTemplateID()
public java.util.Map getAttributes()
public java.util.List getChunks()
public void addChunk(Expr e)
public void setAttributes(java.util.Map attributes)
public java.util.Map getFormalArguments()
public void setFormalArguments(java.util.LinkedHashMap args)
public void setDefaultArgumentValues()
public FormalArgument lookupFormalArgument(java.lang.String name)
public FormalArgument getFormalArgument(java.lang.String name)
public void defineEmptyFormalArgumentList()
public void defineFormalArgument(java.lang.String name)
public void defineFormalArguments(java.util.List names)
public void defineFormalArgument(java.lang.String name, StringTemplate defaultValue)
public void setPassThroughAttributes(boolean passThroughAttributes)
public void setAttributeRenderers(java.util.Map renderers)
public void registerRenderer(java.lang.Class attributeClassType, java.lang.Object renderer)
public AttributeRenderer getAttributeRenderer(java.lang.Class attributeClassType)
public void error(java.lang.String msg)
public void warning(java.lang.String msg)
public void debug(java.lang.String msg)
public void error(java.lang.String msg, java.lang.Throwable e)
public static void setLintMode(boolean lint)
public static boolean inLintMode()
protected void trackAttributeReference(java.lang.String name)
public static boolean isRecursiveEnclosingInstance(StringTemplate st)
public java.lang.String getEnclosingInstanceStackTrace()
public java.lang.String getTemplateDeclaratorString()
protected void checkNullAttributeAgainstFormalArguments(StringTemplate self, java.lang.String attribute)
protected void checkForTrouble()
public java.lang.String getEnclosingInstanceStackString()
public java.lang.String toDebugString()
public void printDebugString()
public java.lang.String toString()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |