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 an instance. That instance's 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 the group that we're executing relative to has 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 ST.render(), DebugST.inspect, or DebugST.getEvents() invocation.

Nested Class Summary

static class

Interpreter.Option

Field Summary

InstanceScope	currentScope Stack of enclosing instances (scopes).
boolean	debug Track events inside templates and in this.events
static int	DEFAULT_OPERAND_STACK_SIZE
protected List<InterpEvent>	events Track everything happening in interp if debug across all templates.
protected List<String>	executeTrace If trace mode, track trace here
static Set<String>	predefinedAnonSubtemplateAttributes
static boolean	trace Dump bytecode instructions as we execute them? mainly for parrt

Constructor Summary

Interpreter(STGroup group, boolean debug)

Interpreter(STGroup group, ErrorManager errMgr, boolean debug)

Interpreter(STGroup group, Locale locale, boolean debug)

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

Method Summary

protected int	_exec(STWriter out, ST self)
protected void	addToList(List<Object> list, Object o)
Object	convertAnythingIteratableToIterator(Object o)
Iterator	convertAnythingToIterator(Object o)
int	exec(STWriter out, ST self) Execute template self and return how many characters it wrote to out
Object	first(Object v) Return the first attribute if multiple valued or the attribute itself if single-valued.
Object	getAttribute(ST self, String name) Find an attr 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(ST self)
protected int	getExprStopChar(ST self)
protected Object	getObjectProperty(STWriter out, ST self, Object o, Object property)
static List<InstanceScope>	getScopeStack(InstanceScope scope, boolean topdown)
static int	getShort(byte[] memory, int index)
protected void	indent(STWriter out, ST self, int strIndex)
Object	last(Object v) Return the last attribute if multiple valued or the attribute itself if single-valued.
Object	length(Object v) Return the length of a mult-valued attribute or 1 if it is a single attribute.
protected void	map(ST self, Object attr, ST st)
protected void	printForTrace(StringBuilder tr, Object o)
Object	rest(Object v) Return everything but the first attribute if multiple valued or null if single-valued.
Object	reverse(Object v) Return a list with the same elements as v but in reverse order.
protected List<ST>	rot_map_iterator(ST self, Iterator attr, List<ST> prototypes)
protected void	rot_map(ST self, Object attr, List<ST> prototypes)
void	setDefaultArguments(STWriter out, ST invokedST) Set any default argument values that were not set by the invoking template or by setAttribute directly.
protected void	setFirstArgument(ST self, ST st, Object attr)
Object	strip(Object v) Return a new list w/o null values.
protected boolean	testAttributeTrue(Object a)
protected String	toString(STWriter out, ST self, Object value)
protected void	trace(ST self, int ip)
protected void	trackDebugEvent(ST self, InterpEvent e) For every event, we track in overall list and in self's event list so that each template has a list of events used to create it.
Object	trunc(Object v) Return all but the last element.
protected int	writeIterator(STWriter out, ST self, Object o, String[] options)
protected int	writeObject(STWriter out, ST self, Object o, String[] options) Generic method to emit text for an object.
protected int	writeObjectNoOptions(STWriter out, ST self, Object o) Write out an expression result that doesn't use expression options.
protected int	writeObjectWithOptions(STWriter out, ST self, Object o, Object[] options) Write out an expression result that uses expression options.
protected int	writePOJO(STWriter out, Object o, String[] options)
protected ST.AttributeList	zip_map(ST self, List<Object> exprs, ST prototype)

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_OPERAND_STACK_SIZE

public static final int DEFAULT_OPERAND_STACK_SIZE

See Also:

Constant Field Values

predefinedAnonSubtemplateAttributes

public static final Set<String> predefinedAnonSubtemplateAttributes

currentScope

public InstanceScope currentScope

Stack of enclosing instances (scopes). Used for dynamic scoping of attributes.

trace

public static boolean trace

Dump bytecode instructions as we execute them? mainly for parrt

executeTrace

protected List<String> executeTrace

If trace mode, track trace here

debug

public boolean debug

Track events inside templates and in this.events

events

protected List<InterpEvent> events

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

Constructor Detail

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 Detail

exec

public int exec(STWriter out,
                ST self)

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

_exec

protected int _exec(STWriter out,
                    ST self)

indent

protected void indent(STWriter out,
                      ST self,
                      int strIndex)

writeObjectNoOptions

protected int writeObjectNoOptions(STWriter out,
                                   ST self,
                                   Object o)

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

writeObjectWithOptions

protected int writeObjectWithOptions(STWriter out,
                                     ST self,
                                     Object o,
                                     Object[] options)

Write out an expression result that uses expression options. E.g.,

writeObject

protected int writeObject(STWriter out,
                          ST self,
                          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,
                            ST self,
                            Object o,
                            String[] options)
                     throws IOException

Throws:

IOException

writePOJO

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

Throws:

IOException

getExprStartChar

protected int getExprStartChar(ST self)

getExprStopChar

protected int getExprStopChar(ST self)

map

protected void map(ST self,
                   Object attr,
                   ST st)

rot_map

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

rot_map_iterator

protected List<ST> rot_map_iterator(ST self,
                                    Iterator attr,
                                    List<ST> prototypes)

zip_map

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

setFirstArgument

protected void setFirstArgument(ST self,
                                ST st,
                                Object attr)

addToList

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

first

public Object first(Object v)

Return the first attribute if multiple valued or the attribute itself if single-valued. Used in

last

public Object last(Object v)

Return the last attribute if multiple 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.

rest

public Object rest(Object v)

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

trunc

public Object trunc(Object v)

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

strip

public Object strip(Object v)

Return a new list w/o null values.

reverse

public Object reverse(Object v)

Return a list with the same elements as v but in reverse order. null values are NOT stripped out. use reverse(strip(v)) to do that.

length

public Object length(Object v)

Return the length of a mult-valued attribute or 1 if it is a single attribute. If attribute is null return 0. Special case several common collections and primitive arrays for speed. This method by Kay Roepke from v3.

toString

protected String toString(STWriter out,
                          ST self,
                          Object value)

convertAnythingIteratableToIterator

public Object convertAnythingIteratableToIterator(Object o)

convertAnythingToIterator

public Iterator convertAnythingToIterator(Object o)

testAttributeTrue

protected boolean testAttributeTrue(Object a)

getObjectProperty

protected Object getObjectProperty(STWriter out,
                                   ST self,
                                   Object o,
                                   Object property)

getAttribute

public Object getAttribute(ST self,
                           String name)

Find an attr via dynamic scoping up enclosing scope chain. If not found, look for a map. So attributes sent in to a template override dictionary names. return EMPTY_ATTR if found def but no value

getDictionary

public Object getDictionary(STGroup g,
                            String name)

setDefaultArguments

public void setDefaultArguments(STWriter out,
                                ST invokedST)

Set any default argument values that were not set by the invoking template or by setAttribute directly. Note that the default values may be templates. The evaluation context is the invokedST template itself so template default args can see other args.

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(ST self,
                     int ip)

printForTrace

protected void printForTrace(StringBuilder tr,
                             Object o)

getEvents

public List<InterpEvent> getEvents()

trackDebugEvent

protected void trackDebugEvent(ST self,
                               InterpEvent e)

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

getExecutionTrace

public List<String> getExecutionTrace()

getShort

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