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 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
(package private) ErrorManager
errMgr
protected java.util.List<InterpEvent>
events
Track everything happening in interpreter across all templates ifdebug
.protected java.util.List<java.lang.String>
executeTrace
Iftrace
istrue
, track trace here.(package private) STGroup
group
Render template with respect to this group.(package private) java.util.Locale
locale
For renderers, we have to pass in the locale.(package private) int
nwline
The number of characters written on this template line so far.(package private) java.lang.Object[]
operands
Operand stack, grows upwards.static java.util.Set<java.lang.String>
predefinedAnonSubtemplateAttributes
(package private) int
sp
Stack pointer register.static boolean
trace
Dump bytecode instructions as they are executed.
-
Constructor Summary
Constructors Constructor Description Interpreter(STGroup group, boolean debug)
Interpreter(STGroup group, java.util.Locale locale, boolean debug)
Interpreter(STGroup group, java.util.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, 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 templateself
and return how many characters it wrote toout
.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 aString
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.(package private) void
load_str(ST self, int ip)
protected void
map(InstanceScope scope, java.lang.Object attr, ST st)
(package private) void
passthru(InstanceScope scope, java.lang.String templateName, java.util.Map<java.lang.String,java.lang.Object> attrs)
protected void
printForTrace(java.lang.StringBuilder tr, InstanceScope scope, java.lang.Object o)
private <T> java.lang.String
renderObject(InstanceScope scope, java.lang.String formatString, java.lang.Object o, java.lang.Class<T> attributeType)
java.lang.Object
rest(InstanceScope scope, java.lang.Object v)
Return everything but the first attribute if multi-valued, ornull
if single-valued.java.lang.Object
reverse(InstanceScope scope, java.lang.Object v)
Return a list with the same elements asv
but in reverse order.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()>
.protected java.util.List<ST>
rot_map_iterator(InstanceScope scope, java.util.Iterator<?> attr, java.util.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, java.lang.Object attr)
(package private) void
storeArgs(InstanceScope scope, int nargs, ST st)
(package private) void
storeArgs(InstanceScope scope, java.util.Map<java.lang.String,java.lang.Object> attrs, ST st)
java.lang.Object
strip(InstanceScope scope, java.lang.Object v)
Return a new list withoutnull
values.(package private) void
super_new(InstanceScope scope, java.lang.String name, int nargs)
(package private) void
super_new(InstanceScope scope, java.lang.String name, java.util.Map<java.lang.String,java.lang.Object> attrs)
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 overallevents
list and inself
'sInstanceScope.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()>
.
-
-
-
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
-
operands
java.lang.Object[] operands
Operand stack, grows upwards.
-
sp
int sp
Stack pointer register.
-
nwline
int nwline
The number of characters written on this template line so far.
-
group
STGroup group
Render template with respect to this group.
-
locale
java.util.Locale locale
For renderers, we have to pass in the locale.
-
errMgr
ErrorManager errMgr
-
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
Iftrace
istrue
, track trace here.
-
debug
public boolean debug
Whentrue
, track events inside templates and inevents
.
-
events
protected java.util.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, 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 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)
-
load_str
void load_str(ST self, int ip)
-
super_new
void super_new(InstanceScope scope, java.lang.String name, int nargs)
-
super_new
void super_new(InstanceScope scope, java.lang.String name, java.util.Map<java.lang.String,java.lang.Object> attrs)
-
passthru
void passthru(InstanceScope scope, java.lang.String templateName, java.util.Map<java.lang.String,java.lang.Object> attrs)
-
storeArgs
void storeArgs(InstanceScope scope, java.util.Map<java.lang.String,java.lang.Object> attrs, ST st)
-
storeArgs
void storeArgs(InstanceScope scope, int nargs, ST st)
-
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
-
renderObject
private <T> java.lang.String renderObject(InstanceScope scope, java.lang.String formatString, java.lang.Object o, java.lang.Class<T> attributeType)
-
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 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 java.lang.Object rest(InstanceScope scope, java.lang.Object v)
Return everything but the first attribute if multi-valued, ornull
if single-valued.
-
trunc
public java.lang.Object trunc(InstanceScope scope, java.lang.Object v)
Return all but the last element.trunc(x)==null
ifx
is single-valued.
-
strip
public java.lang.Object strip(InstanceScope scope, java.lang.Object v)
Return a new list withoutnull
values.
-
reverse
public java.lang.Object reverse(InstanceScope scope, java.lang.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 java.lang.Object length(java.lang.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 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 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 java.lang.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 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 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.
-
getExecutionTrace
public java.util.List<java.lang.String> getExecutionTrace()
-
getShort
public static int getShort(byte[] memory, int index)
-
-