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 particularSTGroup
. To execute the byte codes, we need an output stream and a reference to anST
instance. That instance'sST.impl
field points at aCompiledST
, 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 bySTViz
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()
, orST.getEvents()
.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description protected static class
Interpreter.ArgumentsMap
protected static class
Interpreter.ObjectList
static class
Interpreter.Option
-
Field Summary
Fields Modifier and Type Field Description boolean
debug
Whentrue
, track events inside templates and inevents
.static int
DEFAULT_OPERAND_STACK_SIZE
protected List<InterpEvent>
events
Track everything happening in interpreter across all templates ifdebug
.protected List<String>
executeTrace
Iftrace
istrue
, track trace here.static Set<String>
predefinedAnonSubtemplateAttributes
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
All Methods Static Methods Instance Methods Concrete Methods 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 templateself
and return how many characters it wrote toout
.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 aString
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.protected void
map(InstanceScope scope, Object attr, ST st)
protected void
printForTrace(StringBuilder tr, InstanceScope scope, Object o)
Object
rest(InstanceScope scope, Object v)
Return everything but the first attribute if multi-valued, ornull
if single-valued.Object
reverse(InstanceScope scope, Object v)
Return a list with the same elements asv
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 byST.add(java.lang.String, java.lang.Object)
directly.protected void
setFirstArgument(InstanceScope scope, ST st, Object attr)
Object
strip(InstanceScope scope, Object v)
Return a new list withoutnull
values.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 overallevents
list and inself
'sInstanceScope.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()>
.
-
-
-
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
-
trace
public static boolean trace
Dump bytecode instructions as they are executed. This field is mostly for StringTemplate development.
-
debug
public boolean debug
Whentrue
, track events inside templates and inevents
.
-
events
protected List<InterpEvent> events
Track everything happening in interpreter across all templates ifdebug
. The last event in this field is theEvalTemplateEvent
for the root template.
-
-
Constructor Detail
-
Interpreter
public Interpreter(STGroup group, 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, InstanceScope scope)
Execute templateself
and return how many characters it wrote toout
.- 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, 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
-
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 aList
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, ornull
if single-valued.
-
trunc
public Object trunc(InstanceScope scope, Object v)
Return all but the last element.trunc(x)==null
ifx
is single-valued.
-
strip
public Object strip(InstanceScope scope, Object v)
Return a new list withoutnull
values.
-
reverse
public Object reverse(InstanceScope scope, Object v)
Return a list with the same elements asv
but in reverse order.Note that
null
values are not stripped out; usereverse(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. Ifv
isnull
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.
-
setDefaultArguments
public void setDefaultArguments(STWriter out, InstanceScope scope)
Set any default argument values that were not set by the invoking template or byST.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 aString
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 overallevents
list and inself
'sInstanceScope.events
list so that each template has a list of events used to create it. Ife
is anEvalTemplateEvent
, store in parent'sInstanceScope.childEvalTemplateEvents
list forSTViz
tree view.
-
getShort
public static int getShort(byte[] memory, int index)
-
-