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

  • Field Details

    • DEFAULT_OPERAND_STACK_SIZE

      public static final int DEFAULT_OPERAND_STACK_SIZE
      See Also:

    • predefinedAnonSubtemplateAttributes

      public static final Set<String> predefinedAnonSubtemplateAttributes

    • operands

      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.
      See Also:

    • locale

      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 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 Details

    • 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 Details

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

    • load_str

      void load_str(ST self, int ip)

    • super_new

      void super_new(InstanceScope scope, String name, int nargs)

    • super_new

      void super_new(InstanceScope scope, String name, Map<String,Object> attrs)

    • passthru

      void passthru(InstanceScope scope, String templateName, Map<String,Object> attrs)

    • storeArgs

      void storeArgs(InstanceScope scope, Map<String,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, 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

    • renderObject

      private <T> String renderObject(InstanceScope scope, String formatString, Object o, Class<T> attributeType)

    • 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 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(InstanceScope scope, Object v)
      Return everything but the first attribute if multi-valued, or null if single-valued.

    • trunc

      public Object trunc(InstanceScope scope, Object v)
      Return all but the last element. trunc(x)==null if x is single-valued.

    • strip

      public Object strip(InstanceScope scope, Object v)
      Return a new list without null values.

    • reverse

      public Object reverse(InstanceScope scope, 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, 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.

    • getDictionary

      public Object getDictionary(STGroup g, 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(String, 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(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 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)