org.stringtemplate.v4
Class ST

java.lang.Object
  org.stringtemplate.v4.ST

Direct Known Subclasses:

DebugST

public class ST
extends java.lang.Object

An instance of the StringTemplate. It consists primarily of a reference to its implementation (shared among all instances) and a hash table of attributes. Because of dynamic scoping, we also need a reference to any enclosing instance. For example, in a deeply nested template for an HTML page body, we could still reference the title attribute defined in the outermost page template. To use templates, you create one (usually via STGroup) and then inject attributes using add(). To render its attacks, use render().

Nested Class Summary

static class	ST.AttributeList<T> Just an alias for ArrayList, but this way I can track whether a list is something ST created or it's an incoming list.
static class	ST.RegionType <@r()>, <@r>...<@end>, and @t.r() ::= "..." defined manually by coder

Field Summary

static STNoSuchPropertyException	cachedNoSuchPropException Cache exception since this could happen a lot if people use "missing" to mean boolean false.
static java.lang.Object	EMPTY_ATTR
ST	enclosingInstance Enclosing instance if I'm embedded within another template.
STGroup	groupThatCreatedThisInstance Created as instance of which group? We need this to init interpreter via render.
CompiledST	impl The implementation for this template among all instances of same tmpelate .
protected java.lang.Object[]	locals Safe to simultaneously write via add, which is synchronized.
static java.lang.String	UNKNOWN_NAME
static java.lang.String	VERSION

Constructor Summary

ST()
Used by group creation routine, not by users

ST(ST proto)
Clone a prototype template for application in MAP operations; copy all fields

ST(STGroup group, java.lang.String template)

ST(java.lang.String template)
Used to make templates inline in code for simple things like SQL or log records.

ST(java.lang.String template, char delimiterStartChar, char delimiterStopChar)
Create ST using non-default delimiters; each one of these will live in it's own group since you're overriding a default; don't want to alter STGroup.defaultGroup.

Method Summary

ST	add(java.lang.String name, java.lang.Object value) Inject an attribute (name/value pair).
protected static ST.AttributeList<java.lang.Object>	convertToAttributeList(java.lang.Object curvalue)
static java.lang.String	format(int lineWidth, java.lang.String template, java.lang.Object... attributes)
static java.lang.String	format(java.lang.String template, java.lang.Object... attributes)
java.lang.Object	getAttribute(java.lang.String name) Find an attr via dynamic scoping up enclosing ST chain.
java.util.Map<java.lang.String,java.lang.Object>	getAttributes()
java.util.List<ST>	getEnclosingInstanceStack(boolean topdown)
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	getName()
boolean	isAnonSubtemplate()
protected void	rawSetAttribute(java.lang.String name, java.lang.Object value) Set this.locals attr value when you only know the name, not the index.
void	remove(java.lang.String name) Remove an attribute value entirely (can't remove attribute definitions).
java.lang.String	render()
java.lang.String	render(int lineWidth)
java.lang.String	render(java.util.Locale locale)
java.lang.String	render(java.util.Locale locale, int lineWidth)
java.lang.String	toString()
int	write(java.io.File outputFile, STErrorListener listener)
int	write(java.io.File outputFile, STErrorListener listener, java.lang.String encoding)
int	write(java.io.File outputFile, STErrorListener listener, java.lang.String encoding, int lineWidth)
int	write(java.io.File outputFile, STErrorListener listener, java.lang.String encoding, java.util.Locale locale, int lineWidth)
int	write(STWriter out)
int	write(STWriter out, java.util.Locale locale)
int	write(STWriter out, java.util.Locale locale, STErrorListener listener)
int	write(STWriter out, STErrorListener listener)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

VERSION

public static final java.lang.String VERSION

See Also:

Constant Field Values

UNKNOWN_NAME

public static final java.lang.String UNKNOWN_NAME

See Also:

Constant Field Values

EMPTY_ATTR

public static final java.lang.Object EMPTY_ATTR

cachedNoSuchPropException

public static STNoSuchPropertyException cachedNoSuchPropException

Cache exception since this could happen a lot if people use "missing" to mean boolean false.

impl

public CompiledST impl

The implementation for this template among all instances of same tmpelate .

locals

protected java.lang.Object[] locals

Safe to simultaneously write via add, which is synchronized. Reading during exec is, however, NOT synchronized. So, not thread safe to add attributes while it is being evaluated. Initialized to EMPTY_ATTR to distinguish null from empty.

enclosingInstance

public ST enclosingInstance

Enclosing instance if I'm embedded within another template. IF-subtemplates are considered embedded as well. We look up dynamically scoped attributes with this ptr. Set only at ST creation time not evaluation. Dictionary templates are cloned.

groupThatCreatedThisInstance

public STGroup groupThatCreatedThisInstance

Created as instance of which group? We need this to init interpreter via render. So, we create st and then it needs to know which group created it for sake of polymorphism: st = skin1.getInstanceOf("searchbox"); result = st.render(); // knows skin1 created it Say we have a group, g1, with template t and import t and u templates from another group, g2. g1.getInstanceOf("u") finds u in g2 but remembers that g1 created it. If u includes t, it should create g1.t not g2.t. g1 = {t(), u()} | v g2 = {t()}

Constructor Detail

ST

public ST()

Used by group creation routine, not by users

ST

public ST(java.lang.String template)

Used to make templates inline in code for simple things like SQL or log records. No formal args are set and there is no enclosing instance.

ST

public ST(java.lang.String template,
          char delimiterStartChar,
          char delimiterStopChar)

Create ST using non-default delimiters; each one of these will live in it's own group since you're overriding a default; don't want to alter STGroup.defaultGroup.

ST

public ST(STGroup group,
          java.lang.String template)

ST

public ST(ST proto)

Clone a prototype template for application in MAP operations; copy all fields

Method Detail

add

public ST add(java.lang.String name,
              java.lang.Object value)

Inject an attribute (name/value pair). If there is already an attribute with that name, this method turns the attribute into an AttributeList with both the previous and the new attribute as elements. This method will never alter a List that you inject. If you send in a List and then inject a single value element, add() copies original list and adds the new value. Return self so we can chain. t.add("x", 1).add("y", "hi");

remove

public void remove(java.lang.String name)

Remove an attribute value entirely (can't remove attribute definitions).

rawSetAttribute

protected void rawSetAttribute(java.lang.String name,
                               java.lang.Object value)

Set this.locals attr value when you only know the name, not the index. This is ultimately invoked by calling ST.add() from outside so toss an exception to notify them.

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Find an attr via dynamic scoping up enclosing ST chain. If not found, look for a map. So attributes sent in to a template override dictionary names.

getAttributes

public java.util.Map<java.lang.String,java.lang.Object> getAttributes()

convertToAttributeList

protected static ST.AttributeList<java.lang.Object> convertToAttributeList(java.lang.Object curvalue)

getEnclosingInstanceStackString

public 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]".

getEnclosingInstanceStack

public java.util.List<ST> getEnclosingInstanceStack(boolean topdown)

getName

public java.lang.String getName()

isAnonSubtemplate

public boolean isAnonSubtemplate()

write

public int write(STWriter out)
          throws java.io.IOException

Throws:

java.io.IOException

write

public int write(STWriter out,
                 java.util.Locale locale)

write

public int write(STWriter out,
                 STErrorListener listener)

write

public int write(STWriter out,
                 java.util.Locale locale,
                 STErrorListener listener)

write

public int write(java.io.File outputFile,
                 STErrorListener listener)
          throws java.io.IOException

Throws:

java.io.IOException

write

public int write(java.io.File outputFile,
                 STErrorListener listener,
                 java.lang.String encoding)
          throws java.io.IOException

Throws:

java.io.IOException

write

public int write(java.io.File outputFile,
                 STErrorListener listener,
                 java.lang.String encoding,
                 int lineWidth)
          throws java.io.IOException

Throws:

java.io.IOException

write

public int write(java.io.File outputFile,
                 STErrorListener listener,
                 java.lang.String encoding,
                 java.util.Locale locale,
                 int lineWidth)
          throws java.io.IOException

Throws:

java.io.IOException

render

public java.lang.String render()

render

public java.lang.String render(int lineWidth)

render

public java.lang.String render(java.util.Locale locale)

render

public java.lang.String render(java.util.Locale locale,
                               int lineWidth)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

format

public static java.lang.String format(java.lang.String template,
                                      java.lang.Object... attributes)

format

public static java.lang.String format(int lineWidth,
                                      java.lang.String template,
                                      java.lang.Object... attributes)