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(java.lang.String, java.lang.Object). To render its attacks, use render().

TODO: locals is not actually a hash table like the documentation says.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ST.AttributeList 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

Fields

Modifier and Type	Field and Description
ST.DebugState	debugState If STGroup.trackCreationEvents, track creation and add attribute events for each object.
static Object	EMPTY_ATTR
STGroup	groupThatCreatedThisInstance Created as instance of which group? We need this to initialize interpreter via render.
CompiledST	impl The implementation for this template among all instances of same template .
static String	IMPLICIT_ARG_NAME When there are no formal args for template t and you map t across some values, t implicitly gets arg "it".
protected Object[]	locals Safe to simultaneously write via add(java.lang.String, java.lang.Object), which is synchronized.
static String	UNKNOWN_NAME
static String	VERSION

Constructor Summary

Constructors

Modifier	Constructor and Description
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

Methods

Modifier and Type	Method and Description
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	convertToAttributeList(Object curvalue)
static String	format(int lineWidth, String template, Object... attributes)
static String	format(String template, Object... attributes) ST.format("name, phone | <name>:<phone>", n, p); ST.format("<%1>:<%2>", n, p); ST.format("<name>:<phone>", "name", x, "phone", y);
Object	getAttribute(String name) Find an attribute 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 locals attribute 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

UNKNOWN_NAME

public static final String UNKNOWN_NAME

See Also:

Constant Field Values

EMPTY_ATTR

public static final Object EMPTY_ATTR

IMPLICIT_ARG_NAME

public static final String IMPLICIT_ARG_NAME

When there are no formal args for template t and you map t across some values, t implicitly gets arg "it". E.g., "$it$"

See Also:

Constant Field Values

impl

public CompiledST impl

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

locals

protected Object[] locals

Safe to simultaneously write via add(java.lang.String, java.lang.Object), 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 initialize 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 that imports templates t and u 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 STGroup.trackCreationEvents, track creation and add attribute 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 arguments 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 delegate to ST(), which creates ConstructionEvent.

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 ST.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. The attribute name cannot be null or contain '.'.

Return this 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 locals attribute 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 attribute in this template only.

getAttributes

public Map<String,Object> getAttributes()

convertToAttributeList

protected static ST.AttributeList 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)

 ST.format("name, phone | <name>:<phone>", n, p);
 ST.format("<%1>:<%2>", n, p);
 ST.format("<name>:<phone>", "name", x, "phone", y);
 

format

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