org.stringtemplate.v4
Class Interpreter

java.lang.Object
  org.stringtemplate.v4.Interpreter

public class Interpreter
extends java.lang.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 interface	Interpreter.OpcodeImpl
static class	Interpreter.Option

Field Summary

static int[]	count
static int	DEFAULT_OPERAND_STACK_SIZE
protected java.util.List<InterpEvent>	events Track everything happening in interp if debug across all templates
protected java.util.List<java.lang.String>	executeTrace If debug mode, track trace here
static java.util.Set<java.lang.String>	predefinedAnonSubtemplateAttributes
static boolean	trace Dump bytecode instructions as we execute them?

Constructor Summary

Interpreter(STGroup group)

Interpreter(STGroup group, ErrorManager errMgr)

Interpreter(STGroup group, java.util.Locale locale)

Interpreter(STGroup group, java.util.Locale locale, ErrorManager errMgr)

Method Summary

protected int	_exec(STWriter out, ST self)
protected void	addToList(java.util.List<java.lang.Object> list, java.lang.Object o)
static java.lang.Object	convertAnythingIteratableToIterator(java.lang.Object o)
static java.util.Iterator	convertAnythingToIterator(java.lang.Object o)
static void	dumpOpcodeFreq()
int	exec(STWriter out, ST self) Execute template self and return how many characters it wrote to out
java.lang.Object	first(java.lang.Object v) Return the first attribute if multiple valued or the attribute itself if single-valued.
java.util.List<InterpEvent>	getEvents()
java.util.List<InterpEvent>	getEvents(ST st)
java.util.List<java.lang.String>	getExecutionTrace()
protected int	getExprStartChar(ST self)
protected int	getExprStopChar(ST self)
protected java.lang.Object	getObjectProperty(STWriter out, ST self, java.lang.Object o, java.lang.Object property)
static int	getShort(byte[] memory, int index)
protected void	indent(STWriter out, ST self, int strIndex)
java.lang.Object	last(java.lang.Object v) Return the last attribute if multiple valued or the attribute itself if single-valued.
java.lang.Object	length(java.lang.Object v) Return the length of a mult-valued attribute or 1 if it is a single attribute.
protected void	map(ST self, java.lang.Object attr, ST st)
protected void	printForTrace(java.lang.StringBuilder tr, java.lang.Object o)
java.lang.Object	rest(java.lang.Object v) Return everything but the first attribute if multiple valued or null if single-valued.
java.lang.Object	reverse(java.lang.Object v) Return a list with the same elements as v but in reverse order.
protected java.util.List<ST>	rot_map_iterator(ST self, java.util.Iterator attr, java.util.List<ST> prototypes)
protected void	rot_map(ST self, java.lang.Object attr, java.util.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, java.lang.Object attr)
java.lang.Object	strip(java.lang.Object v) Return a new list w/o null values.
protected boolean	testAttributeTrue(java.lang.Object a)
protected java.lang.String	toString(STWriter out, ST self, java.lang.Object value)
protected void	trace(ST self, int ip)
java.lang.Object	trunc(java.lang.Object v) Return all but the last element.
protected int	writeIterator(STWriter out, ST self, java.lang.Object o, java.lang.String[] options)
protected int	writeObject(STWriter out, ST self, java.lang.Object o, java.lang.String[] options) Generic method to emit text for an object.
protected int	writeObjectNoOptions(STWriter out, ST self, java.lang.Object o) Write out an expression result that doesn't use expression options.
protected int	writeObjectWithOptions(STWriter out, ST self, java.lang.Object o, java.lang.Object[] options) Write out an expression result that uses expression options.
protected int	writePOJO(STWriter out, java.lang.Object o, java.lang.String[] options)
protected ST.AttributeList	zip_map(ST self, java.util.List<java.lang.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 java.util.Set<java.lang.String> predefinedAnonSubtemplateAttributes

trace

public static boolean trace

Dump bytecode instructions as we execute them?

events

protected java.util.List<InterpEvent> events

Track everything happening in interp if debug across all templates

executeTrace

protected java.util.List<java.lang.String> executeTrace

If debug mode, track trace here

count

public static int[] count

Constructor Detail

Interpreter

public Interpreter(STGroup group)

Interpreter

public Interpreter(STGroup group,
                   java.util.Locale locale)

Interpreter

public Interpreter(STGroup group,
                   ErrorManager errMgr)

Interpreter

public Interpreter(STGroup group,
                   java.util.Locale locale,
                   ErrorManager errMgr)

Method Detail

dumpOpcodeFreq

public static void dumpOpcodeFreq()

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,
                                   java.lang.Object o)

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

writeObjectWithOptions

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

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

writeObject

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

Throws:

java.io.IOException

writePOJO

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

Throws:

java.io.IOException

getExprStartChar

protected int getExprStartChar(ST self)

getExprStopChar

protected int getExprStopChar(ST self)

map

protected void map(ST self,
                   java.lang.Object attr,
                   ST st)

rot_map

protected void rot_map(ST self,
                       java.lang.Object attr,
                       java.util.List<ST> prototypes)

rot_map_iterator

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

zip_map

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

setFirstArgument

protected void setFirstArgument(ST self,
                                ST st,
                                java.lang.Object attr)

addToList

protected void addToList(java.util.List<java.lang.Object> list,
                         java.lang.Object o)

first

public java.lang.Object first(java.lang.Object v)

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

last

public java.lang.Object last(java.lang.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 java.lang.Object rest(java.lang.Object v)

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

trunc

public java.lang.Object trunc(java.lang.Object v)

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

strip

public java.lang.Object strip(java.lang.Object v)

Return a new list w/o null values.

reverse

public java.lang.Object reverse(java.lang.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 java.lang.Object length(java.lang.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 java.lang.String toString(STWriter out,
                                    ST self,
                                    java.lang.Object value)

convertAnythingIteratableToIterator

public static java.lang.Object convertAnythingIteratableToIterator(java.lang.Object o)

convertAnythingToIterator

public static java.util.Iterator convertAnythingToIterator(java.lang.Object o)

testAttributeTrue

protected boolean testAttributeTrue(java.lang.Object a)

getObjectProperty

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

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 template enclosing invokedST.

trace

protected void trace(ST self,
                     int ip)

printForTrace

protected void printForTrace(java.lang.StringBuilder tr,
                             java.lang.Object o)

getEvents

public java.util.List<InterpEvent> getEvents()

getEvents

public java.util.List<InterpEvent> getEvents(ST st)

getExecutionTrace

public java.util.List<java.lang.String> getExecutionTrace()

getShort

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