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 and Description
protected static class	Interpreter.ArgumentsMap
protected static class	Interpreter.ObjectList
static class	Interpreter.Option

Field Summary

Fields

Modifier and Type	Field and Description
InstanceScope	currentScope Stack of enclosing instances (scopes).
boolean	debug When true, track events inside templates and in events.
static int	DEFAULT_OPERAND_STACK_SIZE
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.
static Set<String>	predefinedAnonSubtemplateAttributes
static boolean	trace Dump bytecode instructions as they are executed.

Constructor Summary

Constructors

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

Methods

Modifier and Type	Method and Description
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 multi-valued, or the attribute itself if single-valued.
Object	getAttribute(ST self, 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(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 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.
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 multi-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) Renders expressions of the form <names:a()> or <names:a(),b()>.
void	setDefaultArguments(STWriter out, ST invokedST) 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(ST self, ST st, Object attr)
Object	strip(Object v) Return a new list without 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 events list and in self's InstanceScope.events 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) 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 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 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 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.

Returns:

the number of characters written 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., <name>

writeObjectWithOptions

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

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

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)

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

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)

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

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 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(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(Object v)

Return everything but the first attribute if multi-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 without null values.

reverse

public Object reverse(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,
              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 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,
                       ST invokedST)

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