Package org.stringtemplate.v4

Class Interpreter

java.lang.Object

org.stringtemplate.v4.Interpreter

public class Interpreter
extends Object

This class knows how to execute template bytecodes relative to a particular STGroup. To execute the byte codes, we need an output stream and a reference to an ST instance. That instance's ST.impl field points at a CompiledST, which contains all of the byte codes and other information relevant to execution.

This interpreter is a stack-based bytecode interpreter. All operands go onto an operand stack.

If debug set, we track interpreter events. For now, I am only tracking instance creation events. These are used by STViz to pair up output chunks with the template expressions that generate them.

We create a new interpreter for each invocation of ST.render(), ST.inspect(), or ST.getEvents().

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	Interpreter.ArgumentsMap
protected static class	Interpreter.ObjectList
static enum	Interpreter.Option

Field Summary

Fields

Modifier and Type	Field	Description
boolean	debug	When true, track events inside templates and in events.
static final int	DEFAULT_OPERAND_STACK_SIZE
(package private) ErrorManager	errMgr
protected List<InterpEvent>	events	Track everything happening in interpreter across all templates if debug.
protected List<String>	executeTrace	If trace is true, track trace here.
(package private) STGroup	group	Render template with respect to this group.
(package private) Locale	locale	For renderers, we have to pass in the locale.
(package private) int	nwline	The number of characters written on this template line so far.
(package private) Object[]	operands	Operand stack, grows upwards.
static final Set<String>	predefinedAnonSubtemplateAttributes
(package private) int	sp	Stack pointer register.
static boolean	trace	Dump bytecode instructions as they are executed.

Constructor Summary

Constructors

Constructor	Description
Interpreter(STGroup group, boolean debug)
Interpreter(STGroup group, Locale locale, boolean debug)
Interpreter(STGroup group, Locale locale, ErrorManager errMgr, boolean debug)
Interpreter(STGroup group, ErrorManager errMgr, boolean debug)

Method Summary

Modifier and Type	Method	Description
protected int	_exec(STWriter out, InstanceScope scope)
protected void	addToList(InstanceScope scope, List<Object> list, Object o)
Object	convertAnythingIteratableToIterator(InstanceScope scope, Object o)
Iterator<?>	convertAnythingToIterator(InstanceScope scope, Object o)
int	exec(STWriter out, InstanceScope scope)	Execute template self and return how many characters it wrote to out.
Object	first(InstanceScope scope, Object v)	Return the first attribute if multi-valued, or the attribute itself if single-valued.
Object	getAttribute(InstanceScope scope, String name)	Find an attribute via dynamic scoping up enclosing scope chain.
Object	getDictionary(STGroup g, String name)
static List<ST>	getEnclosingInstanceStack(InstanceScope scope, boolean topdown)
static String	getEnclosingInstanceStackString(InstanceScope scope)	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].
static List<EvalTemplateEvent>	getEvalTemplateEventStack(InstanceScope scope, boolean topdown)
List<InterpEvent>	getEvents()
List<String>	getExecutionTrace()
protected int	getExprStartChar(InstanceScope scope)
protected int	getExprStopChar(InstanceScope scope)
protected Object	getObjectProperty(STWriter out, InstanceScope scope, Object o, Object property)
static List<InstanceScope>	getScopeStack(InstanceScope scope, boolean topdown)
static int	getShort(byte[] memory, int index)
protected void	indent(STWriter out, InstanceScope scope, int strIndex)
Object	last(InstanceScope scope, Object v)	Return the last attribute if multi-valued, or the attribute itself if single-valued.
Object	length(Object v)	Return the length of a multi-valued attribute or 1 if it is a single attribute.
(package private) void	load_str(ST self, int ip)
protected void	map(InstanceScope scope, Object attr, ST st)
(package private) void	passthru(InstanceScope scope, String templateName, Map<String,Object> attrs)
protected void	printForTrace(StringBuilder tr, InstanceScope scope, Object o)
private <T> String	renderObject(InstanceScope scope, String formatString, Object o, Class<T> attributeType)
Object	rest(InstanceScope scope, Object v)	Return everything but the first attribute if multi-valued, or null if single-valued.
Object	reverse(InstanceScope scope, Object v)	Return a list with the same elements as v but in reverse order.
protected void	rot_map(InstanceScope scope, Object attr, List<ST> prototypes)	Renders expressions of the form <names:a()> or <names:a(),b()>.
protected List<ST>	rot_map_iterator(InstanceScope scope, Iterator<?> attr, List<ST> prototypes)
void	setDefaultArguments(STWriter out, InstanceScope scope)	Set any default argument values that were not set by the invoking template or by ST.add(java.lang.String, java.lang.Object) directly.
protected void	setFirstArgument(InstanceScope scope, ST st, Object attr)
(package private) void	storeArgs(InstanceScope scope, int nargs, ST st)
(package private) void	storeArgs(InstanceScope scope, Map<String,Object> attrs, ST st)
Object	strip(InstanceScope scope, Object v)	Return a new list without null values.
(package private) void	super_new(InstanceScope scope, String name, int nargs)
(package private) void	super_new(InstanceScope scope, String name, Map<String,Object> attrs)
protected boolean	testAttributeTrue(Object a)
protected String	toString(STWriter out, InstanceScope scope, Object value)
protected void	trace(InstanceScope scope, int ip)
protected void	trackDebugEvent(InstanceScope scope, InterpEvent e)	For every event, we track in overall events list and in self's InstanceScope.events list so that each template has a list of events used to create it.
Object	trunc(InstanceScope scope, Object v)	Return all but the last element.
protected int	writeIterator(STWriter out, InstanceScope scope, Object o, String[] options)
protected int	writeObject(STWriter out, InstanceScope scope, Object o, String[] options)	Generic method to emit text for an object.
protected int	writeObjectNoOptions(STWriter out, InstanceScope scope, Object o)	Write out an expression result that doesn't use expression options.
protected int	writeObjectWithOptions(STWriter out, InstanceScope scope, Object o, Object[] options)	Write out an expression result that uses expression options.
protected int	writePOJO(STWriter out, InstanceScope scope, Object o, String[] options)
protected ST.AttributeList	zip_map(InstanceScope scope, List<Object> exprs, ST prototype)	Renders expressions of the form <names,phones:{n,p | ...}> or <a,b:t()>.

Methods inherited from class java.lang.Object

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

Field Details

DEFAULT_OPERAND_STACK_SIZE

public static final int DEFAULT_OPERAND_STACK_SIZE

See Also:

• Constant Field Values

predefinedAnonSubtemplateAttributes

public static final Set<String> predefinedAnonSubtemplateAttributes

operands

Object[] operands

Operand stack, grows upwards.

sp

int sp

Stack pointer register.

nwline

int nwline

The number of characters written on this template line so far.

group

STGroup group

Render template with respect to this group.

See Also:

• ST.groupThatCreatedThisInstance
• CompiledST.nativeGroup

locale

Locale locale

For renderers, we have to pass in the locale.

errMgr

ErrorManager errMgr

trace

public static boolean trace

Dump bytecode instructions as they are executed. This field is mostly for StringTemplate development.

executeTrace

protected List<String> executeTrace

If trace is true, track trace here.

debug

public boolean debug

When true, track events inside templates and in events.

events

protected List<InterpEvent> events

Track everything happening in interpreter across all templates if debug. The last event in this field is the EvalTemplateEvent for the root template.

Constructor Details

Interpreter

public Interpreter(STGroup group,
 boolean debug)

Interpreter

public Interpreter(STGroup group,
 Locale locale,
 boolean debug)

Interpreter

public Interpreter(STGroup group,
 ErrorManager errMgr,
 boolean debug)

Interpreter

public Interpreter(STGroup group,
 Locale locale,
 ErrorManager errMgr,
 boolean debug)

Method Details

exec

public int exec(STWriter out,
 InstanceScope scope)

Execute template self and return how many characters it wrote to out.

Returns:

the number of characters written to out

_exec

protected int _exec(STWriter out,
 InstanceScope scope)

load_str

void load_str(ST self,
 int ip)

super_new

void super_new(InstanceScope scope,
 String name,
 int nargs)

super_new

void super_new(InstanceScope scope,
 String name,
 Map<String,Object> attrs)

passthru

void passthru(InstanceScope scope,
 String templateName,
 Map<String,Object> attrs)

storeArgs

void storeArgs(InstanceScope scope,
 Map<String,Object> attrs,
 ST st)

storeArgs

void storeArgs(InstanceScope scope,
 int nargs,
 ST st)

indent

protected void indent(STWriter out,
 InstanceScope scope,
 int strIndex)

writeObjectNoOptions

protected int writeObjectNoOptions(STWriter out,
 InstanceScope scope,
 Object o)

Write out an expression result that doesn't use expression options. E.g., <name>

writeObjectWithOptions

protected int writeObjectWithOptions(STWriter out,
 InstanceScope scope,
 Object o,
 Object[] options)

Write out an expression result that uses expression options. E.g., <names; separator=", ">

writeObject

protected int writeObject(STWriter out,
 InstanceScope scope,
 Object o,
 String[] options)

Generic method to emit text for an object. It differentiates between templates, iterable objects, and plain old Java objects (POJOs)

writeIterator

protected int writeIterator(STWriter out,
 InstanceScope scope,
 Object o,
 String[] options)
                     throws IOException

Throws:

IOException

writePOJO

protected int writePOJO(STWriter out,
 InstanceScope scope,
 Object o,
 String[] options)
                 throws IOException

Throws:

IOException

renderObject

private <T> String renderObject(InstanceScope scope,
 String formatString,
 Object o,
 Class<T> attributeType)

getExprStartChar

protected int getExprStartChar(InstanceScope scope)

getExprStopChar

protected int getExprStopChar(InstanceScope scope)

map

protected void map(InstanceScope scope,
 Object attr,
 ST st)

rot_map

protected void rot_map(InstanceScope scope,
 Object attr,
 List<ST> prototypes)

Renders expressions of the form <names:a()> or <names:a(),b()>.

rot_map_iterator

protected List<ST> rot_map_iterator(InstanceScope scope,
 Iterator<?> attr,
 List<ST> prototypes)

zip_map

protected ST.AttributeList zip_map(InstanceScope scope,
 List<Object> exprs,
 ST prototype)

Renders expressions of the form <names,phones:{n,p | ...}> or <a,b:t()>.

setFirstArgument

protected void setFirstArgument(InstanceScope scope,
 ST st,
 Object attr)

addToList

protected void addToList(InstanceScope scope,
 List<Object> list,
 Object o)

first

public Object first(InstanceScope scope,
 Object v)

Return the first attribute if multi-valued, or the attribute itself if single-valued.

This method is used for rendering expressions of the form <names:first()>.

last

public Object last(InstanceScope scope,
 Object v)

Return the last attribute if multi-valued, or the attribute itself if single-valued. Unless it's a List or array, this is pretty slow as it iterates until the last element.

This method is used for rendering expressions of the form <names:last()>.

rest

public Object rest(InstanceScope scope,
 Object v)

Return everything but the first attribute if multi-valued, or null if single-valued.

trunc

public Object trunc(InstanceScope scope,
 Object v)

Return all but the last element. trunc(x)==null if x is single-valued.

strip

public Object strip(InstanceScope scope,
 Object v)

Return a new list without null values.

reverse

public Object reverse(InstanceScope scope,
 Object v)

Return a list with the same elements as v but in reverse order.

Note that null values are not stripped out; use reverse(strip(v)) to do that.

length

public Object length(Object v)

Return the length of a multi-valued attribute or 1 if it is a single attribute. If v is null return 0.

The implementation treats several common collections and arrays as special cases for speed.

toString

protected String toString(STWriter out,
 InstanceScope scope,
 Object value)

convertAnythingIteratableToIterator

public Object convertAnythingIteratableToIterator(InstanceScope scope,
 Object o)

convertAnythingToIterator

public Iterator<?> convertAnythingToIterator(InstanceScope scope,
 Object o)

testAttributeTrue

protected boolean testAttributeTrue(Object a)

getObjectProperty

protected Object getObjectProperty(STWriter out,
 InstanceScope scope,
 Object o,
 Object property)

getAttribute

public Object getAttribute(InstanceScope scope,
 String name)

Find an attribute via dynamic scoping up enclosing scope chain. Only look for a dictionary definition if the attribute is not found, so attributes sent in to a template override dictionary names.

Return ST.EMPTY_ATTR if found definition but no value.

getDictionary

public Object getDictionary(STGroup g,
 String name)

setDefaultArguments

public void setDefaultArguments(STWriter out,
 InstanceScope scope)

Set any default argument values that were not set by the invoking template or by ST.add(java.lang.String, java.lang.Object) directly. Note that the default values may be templates.

The evaluation context is the invokedST template itself so template default arguments can see other arguments.

getEnclosingInstanceStackString

public static String getEnclosingInstanceStackString(InstanceScope scope)

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 static List<ST> getEnclosingInstanceStack(InstanceScope scope,
 boolean topdown)

getScopeStack

public static List<InstanceScope> getScopeStack(InstanceScope scope,
 boolean topdown)

getEvalTemplateEventStack

public static List<EvalTemplateEvent> getEvalTemplateEventStack(InstanceScope scope,
 boolean topdown)

trace

protected void trace(InstanceScope scope,
 int ip)

printForTrace

protected void printForTrace(StringBuilder tr,
 InstanceScope scope,
 Object o)

getEvents

public List<InterpEvent> getEvents()

trackDebugEvent

protected void trackDebugEvent(InstanceScope scope,
 InterpEvent e)

For every event, we track in overall events list and in self's InstanceScope.events list so that each template has a list of events used to create it. If e is an EvalTemplateEvent, store in parent's InstanceScope.childEvalTemplateEvents list for STViz tree view.

getExecutionTrace

public List<String> getExecutionTrace()

getShort

public static int getShort(byte[] memory,
 int index)