Package org.stringtemplate.v4

Class 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 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.

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

      • Interpreter

        public Interpreter​(STGroup group,
                   boolean debug)

      • Interpreter

        public Interpreter​(STGroup group,
                   Locale locale,
                   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

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

      • getExprStartChar

        protected int getExprStartChar​(InstanceScope scope)

      • getExprStopChar

        protected int getExprStopChar​(InstanceScope scope)

      • rot_map

        protected void rot_map​(InstanceScope scope,
                       Object attr,
                       List<ST> prototypes)
        Renders expressions of the form <names:a()> or <names:a(),b()>.

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

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

      • convertAnythingIteratableToIterator

        public Object convertAnythingIteratableToIterator​(InstanceScope scope,
                                                  Object o)

      • testAttributeTrue

        protected boolean testAttributeTrue​(Object a)

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

      • getExecutionTrace

        public List<String> getExecutionTrace()

      • getShort

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