org.stringtemplate.v4
Class ST

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

public class ST
extends 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.DebugState Events during template hierarchy construction (not evaluation)
static class	ST.RegionType <@r()>, <@r>...<@end>, and @t.r() ::= "..." defined manually by coder

Field Summary

static STNoSuchAttributeException	cachedNoSuchAttrException Cache exception since this could happen a lot if people use "missing" to mean boolean false.
ST.DebugState	debugState If Interpreter.trackCreationEvents, track creation, add-attr events for each object.
static Object	EMPTY_ATTR
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 Object[]	locals Safe to simultaneously write via add, which is synchronized.
static String	UNKNOWN_NAME
static String	VERSION

Constructor Summary

protected	ST() Used by group creation routine, not by users
	ST(ST proto) Clone a prototype template.
	ST(STGroup group, String template)
	ST(String template) Used to make templates inline in code for simple things like SQL or log records.
	ST(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(String name, Object value) Inject an attribute (name/value pair).
ST	addAggr(String aggrSpec, Object... values) Split "aggrName.{propName1,propName2}" into list [propName1,propName2] and the aggrName.
protected static ST.AttributeList<Object>	convertToAttributeList(Object curvalue)
static String	format(int lineWidth, String template, Object... attributes)
static String	format(String template, Object... attributes)
Object	getAttribute(String name) Find an attr in this template only.
Map<String,Object>	getAttributes()
List<InterpEvent>	getEvents()
List<InterpEvent>	getEvents(int lineWidth)
List<InterpEvent>	getEvents(Locale locale)
List<InterpEvent>	getEvents(Locale locale, int lineWidth)
String	getName()
STViz	inspect()
STViz	inspect(ErrorManager errMgr, Locale locale, int lineWidth)
STViz	inspect(int lineWidth)
STViz	inspect(Locale locale)
boolean	isAnonSubtemplate()
protected void	rawSetAttribute(String name, Object value) Set this.locals attr value when you only know the name, not the index.
void	remove(String name) Remove an attribute value entirely (can't remove attribute definitions).
String	render()
String	render(int lineWidth)
String	render(Locale locale)
String	render(Locale locale, int lineWidth)
String	toString()
int	write(File outputFile, STErrorListener listener)
int	write(File outputFile, STErrorListener listener, String encoding)
int	write(File outputFile, STErrorListener listener, String encoding, int lineWidth)
int	write(File outputFile, STErrorListener listener, String encoding, Locale locale, int lineWidth)
int	write(STWriter out)
int	write(STWriter out, Locale locale)
int	write(STWriter out, 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 String VERSION

See Also:

Constant Field Values

UNKNOWN_NAME

public static final String UNKNOWN_NAME

See Also:

Constant Field Values

EMPTY_ATTR

public static final Object EMPTY_ATTR

cachedNoSuchAttrException

public static STNoSuchAttributeException cachedNoSuchAttrException

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

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()}

debugState

public ST.DebugState debugState

If Interpreter.trackCreationEvents, track creation, add-attr events for each object. Create this object on first use.

Constructor Detail

ST

protected ST()

Used by group creation routine, not by users

ST

public ST(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(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,
          String template)

ST

public ST(ST proto)

Clone a prototype template. Copy all fields minus debugState; don't call this(), which creates ctor event

Method Detail

add

public ST add(String name,
              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");

addAggr

public ST addAggr(String aggrSpec,
                  Object... values)

Split "aggrName.{propName1,propName2}" into list [propName1,propName2] and the aggrName. Spaces are allowed around ','.

remove

public void remove(String name)

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

rawSetAttribute

protected void rawSetAttribute(String name,
                               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 Object getAttribute(String name)

Find an attr in this template only.

getAttributes

public Map<String,Object> getAttributes()

convertToAttributeList

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

getName

public String getName()

isAnonSubtemplate

public boolean isAnonSubtemplate()

write

public int write(STWriter out)
          throws IOException

Throws:

IOException

write

public int write(STWriter out,
                 Locale locale)

write

public int write(STWriter out,
                 STErrorListener listener)

write

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

write

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

Throws:

IOException

write

public int write(File outputFile,
                 STErrorListener listener,
                 String encoding)
          throws IOException

Throws:

IOException

write

public int write(File outputFile,
                 STErrorListener listener,
                 String encoding,
                 int lineWidth)
          throws IOException

Throws:

IOException

write

public int write(File outputFile,
                 STErrorListener listener,
                 String encoding,
                 Locale locale,
                 int lineWidth)
          throws IOException

Throws:

IOException

render

public String render()

render

public String render(int lineWidth)

render

public String render(Locale locale)

render

public String render(Locale locale,
                     int lineWidth)

inspect

public STViz inspect()

inspect

public STViz inspect(int lineWidth)

inspect

public STViz inspect(Locale locale)

inspect

public STViz inspect(ErrorManager errMgr,
                     Locale locale,
                     int lineWidth)

getEvents

public List<InterpEvent> getEvents()

getEvents

public List<InterpEvent> getEvents(int lineWidth)

getEvents

public List<InterpEvent> getEvents(Locale locale)

getEvents

public List<InterpEvent> getEvents(Locale locale,
                                   int lineWidth)

toString

public String toString()

Overrides:

toString in class Object

format

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

format

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