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 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
boolean	debug When true, track events inside templates and in events.
static int	DEFAULT_OPERAND_STACK_SIZE
protected java.util.List<InterpEvent>	events Track everything happening in interpreter across all templates if debug.
protected java.util.List<java.lang.String>	executeTrace If trace is true, track trace here.
static java.util.Set<java.lang.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, java.util.Locale locale, boolean debug)
Interpreter(STGroup group, java.util.Locale locale, ErrorManager errMgr, boolean debug)

Method Summary

Methods

Modifier and Type	Method and Description
protected int	_exec(STWriter out, InstanceScope scope)
protected void	addToList(InstanceScope scope, java.util.List<java.lang.Object> list, java.lang.Object o)
java.lang.Object	convertAnythingIteratableToIterator(InstanceScope scope, java.lang.Object o)
java.util.Iterator<?>	convertAnythingToIterator(InstanceScope scope, java.lang.Object o)
int	exec(STWriter out, InstanceScope scope) Execute template self and return how many characters it wrote to out.
java.lang.Object	first(InstanceScope scope, java.lang.Object v) Return the first attribute if multi-valued, or the attribute itself if single-valued.
java.lang.Object	getAttribute(InstanceScope scope, java.lang.String name) Find an attribute via dynamic scoping up enclosing scope chain.
java.lang.Object	getDictionary(STGroup g, java.lang.String name)
static java.util.List<ST>	getEnclosingInstanceStack(InstanceScope scope, boolean topdown)
static java.lang.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 java.util.List<EvalTemplateEvent>	getEvalTemplateEventStack(InstanceScope scope, boolean topdown)
java.util.List<InterpEvent>	getEvents()
java.util.List<java.lang.String>	getExecutionTrace()
protected int	getExprStartChar(InstanceScope scope)
protected int	getExprStopChar(InstanceScope scope)
protected java.lang.Object	getObjectProperty(STWriter out, InstanceScope scope, java.lang.Object o, java.lang.Object property)
static java.util.List<InstanceScope>	getScopeStack(InstanceScope scope, boolean topdown)
static int	getShort(byte[] memory, int index)
protected void	indent(STWriter out, InstanceScope scope, int strIndex)
java.lang.Object	last(InstanceScope scope, java.lang.Object v) Return the last attribute if multi-valued, or the attribute itself if single-valued.
java.lang.Object	length(java.lang.Object v) Return the length of a multi-valued attribute or 1 if it is a single attribute.
protected void	map(InstanceScope scope, java.lang.Object attr, ST st)
protected void	printForTrace(java.lang.StringBuilder tr, InstanceScope scope, java.lang.Object o)
java.lang.Object	rest(InstanceScope scope, java.lang.Object v) Return everything but the first attribute if multi-valued, or null if single-valued.
java.lang.Object	reverse(InstanceScope scope, 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(InstanceScope scope, java.util.Iterator<?> attr, java.util.List<ST> prototypes)
protected void	rot_map(InstanceScope scope, java.lang.Object attr, java.util.List<ST> prototypes) Renders expressions of the form <names:a()> or <names:a(),b()>.
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, java.lang.Object attr)
java.lang.Object	strip(InstanceScope scope, java.lang.Object v) Return a new list without null values.
protected boolean	testAttributeTrue(java.lang.Object a)
protected java.lang.String	toString(STWriter out, InstanceScope scope, java.lang.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.
java.lang.Object	trunc(InstanceScope scope, java.lang.Object v) Return all but the last element.
protected int	writeIterator(STWriter out, InstanceScope scope, java.lang.Object o, java.lang.String[] options)
protected int	writeObject(STWriter out, InstanceScope scope, java.lang.Object o, java.lang.String[] options) Generic method to emit text for an object.
protected int	writeObjectNoOptions(STWriter out, InstanceScope scope, java.lang.Object o) Write out an expression result that doesn't use expression options.
protected int	writeObjectWithOptions(STWriter out, InstanceScope scope, java.lang.Object o, java.lang.Object[] options) Write out an expression result that uses expression options.
protected int	writePOJO(STWriter out, InstanceScope scope, java.lang.Object o, java.lang.String[] options)
protected ST.AttributeList	zip_map(InstanceScope scope, java.util.List<java.lang.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 java.util.Set<java.lang.String> predefinedAnonSubtemplateAttributes

trace

public static boolean trace

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

executeTrace

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

If trace is true, track trace here.

debug

public boolean debug

When true, track events inside templates and in events.

events

protected java.util.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,
           java.util.Locale locale,
           boolean debug)

Interpreter

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

Interpreter

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

Method Detail

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)

indent

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

writeObjectNoOptions

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

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

writeObjectWithOptions

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

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

writeObject

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

Throws:

java.io.IOException

writePOJO

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

Throws:

java.io.IOException

getExprStartChar

protected int getExprStartChar(InstanceScope scope)

getExprStopChar

protected int getExprStopChar(InstanceScope scope)

map

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

rot_map

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

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

rot_map_iterator

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

zip_map

protected ST.AttributeList zip_map(InstanceScope scope,
                       java.util.List<java.lang.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,
                    java.lang.Object attr)

addToList

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

first

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

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

trunc

public java.lang.Object trunc(InstanceScope scope,
                     java.lang.Object v)

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

strip

public java.lang.Object strip(InstanceScope scope,
                     java.lang.Object v)

Return a new list without null values.

reverse

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

convertAnythingIteratableToIterator

public java.lang.Object convertAnythingIteratableToIterator(InstanceScope scope,
                                                   java.lang.Object o)

convertAnythingToIterator

public java.util.Iterator<?> convertAnythingToIterator(InstanceScope scope,
                                              java.lang.Object o)

testAttributeTrue

protected boolean testAttributeTrue(java.lang.Object a)

getObjectProperty

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

getAttribute

public java.lang.Object getAttribute(InstanceScope scope,
                            java.lang.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 java.lang.Object getDictionary(STGroup g,
                             java.lang.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 java.lang.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 java.util.List<ST> getEnclosingInstanceStack(InstanceScope scope,
                                           boolean topdown)

getScopeStack

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

getEvalTemplateEventStack

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

trace

protected void trace(InstanceScope scope,
         int ip)

printForTrace

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

getEvents

public java.util.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 java.util.List<java.lang.String> getExecutionTrace()

getShort

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