Class Interpreter
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 ClassesModifier and TypeClassDescriptionprotected static class
protected static class
static enum
-
Field Summary
FieldsModifier and TypeFieldDescriptionboolean
Whentrue
, track events inside templates and inevents
.static final int
(package private) ErrorManager
protected List
<InterpEvent> Track everything happening in interpreter across all templates ifdebug
.Iftrace
istrue
, track trace here.(package private) STGroup
Render template with respect to this group.(package private) Locale
For renderers, we have to pass in the locale.(package private) int
The number of characters written on this template line so far.(package private) Object[]
Operand stack, grows upwards.(package private) int
Stack pointer register.static boolean
Dump bytecode instructions as they are executed. -
Constructor Summary
ConstructorsConstructorDescriptionInterpreter
(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
Modifier and TypeMethodDescriptionprotected int
_exec
(STWriter out, InstanceScope scope) protected void
addToList
(InstanceScope scope, List<Object> list, Object o) Iterator
<?> convertAnythingToIterator
(InstanceScope scope, Object o) int
exec
(STWriter out, InstanceScope scope) Execute templateself
and return how many characters it wrote toout
.first
(InstanceScope scope, Object v) Return the first attribute if multi-valued, or the attribute itself if single-valued.getAttribute
(InstanceScope scope, String name) Find an attribute via dynamic scoping up enclosing scope chain.getDictionary
(STGroup g, String name) getEnclosingInstanceStack
(InstanceScope scope, boolean topdown) static String
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) 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) last
(InstanceScope scope, Object v) Return the last attribute if multi-valued, or the attribute itself if single-valued.Return the length of a multi-valued attribute or 1 if it is a single attribute.(package private) void
protected void
map
(InstanceScope scope, Object attr, ST st) (package private) void
protected void
printForTrace
(StringBuilder tr, InstanceScope scope, Object o) private <T> String
renderObject
(InstanceScope scope, String formatString, Object o, Class<T> attributeType) rest
(InstanceScope scope, Object v) Return everything but the first attribute if multi-valued, ornull
if single-valued.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()>
.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) (package private) void
storeArgs
(InstanceScope scope, int nargs, ST st) (package private) void
strip
(InstanceScope scope, Object v) Return a new list withoutnull
values.(package private) void
super_new
(InstanceScope scope, String name, int nargs) (package private) void
protected boolean
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.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 Details
-
DEFAULT_OPERAND_STACK_SIZE
public static final int DEFAULT_OPERAND_STACK_SIZE- See Also:
-
predefinedAnonSubtemplateAttributes
-
operands
Object[] operandsOperand stack, grows upwards. -
sp
int spStack pointer register. -
nwline
int nwlineThe number of characters written on this template line so far. -
group
STGroup groupRender template with respect to this group.- See Also:
-
locale
Locale localeFor renderers, we have to pass in the locale. -
errMgr
ErrorManager errMgr -
trace
public static boolean traceDump bytecode instructions as they are executed. This field is mostly for StringTemplate development. -
executeTrace
Iftrace
istrue
, track trace here. -
debug
public boolean debugWhentrue
, track events inside templates and inevents
. -
events
Track everything happening in interpreter across all templates ifdebug
. The last event in this field is theEvalTemplateEvent
for the root template.
-
-
Constructor Details
-
Interpreter
-
Interpreter
-
Interpreter
-
Interpreter
-
-
Method Details
-
exec
Execute templateself
and return how many characters it wrote toout
.- Returns:
- the number of characters written to
out
-
_exec
-
load_str
-
super_new
-
super_new
-
passthru
-
storeArgs
-
storeArgs
-
indent
-
writeObjectNoOptions
Write out an expression result that doesn't use expression options. E.g.,<name>
-
writeObjectWithOptions
Write out an expression result that uses expression options. E.g.,<names; separator=", ">
-
writeObject
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
-
renderObject
private <T> String renderObject(InstanceScope scope, String formatString, Object o, Class<T> attributeType) -
getExprStartChar
-
getExprStopChar
-
map
-
rot_map
Renders expressions of the form<names:a()>
or<names:a(),b()>
. -
rot_map_iterator
-
zip_map
Renders expressions of the form<names,phones:{n,p | ...}>
or<a,b:t()>
. -
setFirstArgument
-
addToList
-
first
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
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
Return everything but the first attribute if multi-valued, ornull
if single-valued. -
trunc
Return all but the last element.trunc(x)==null
ifx
is single-valued. -
strip
Return a new list withoutnull
values. -
reverse
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
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
-
convertAnythingIteratableToIterator
-
convertAnythingToIterator
-
testAttributeTrue
-
getObjectProperty
-
getAttribute
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
-
setDefaultArguments
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
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
-
getScopeStack
-
getEvalTemplateEventStack
public static List<EvalTemplateEvent> getEvalTemplateEventStack(InstanceScope scope, boolean topdown) -
trace
-
printForTrace
-
getEvents
-
trackDebugEvent
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
-
getShort
public static int getShort(byte[] memory, int index)
-