Package org.stringtemplate.v4

Class Interpreter

  • public class Interpreter
extends java.lang.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 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.

      • locale

        java.util.Locale locale
        For renderers, we have to pass in the locale.

      • 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
        If trace is true, track trace here.

      • debug

        public boolean debug
        When true, track events inside templates and in events.

      • events

        protected java.util.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,
                   java.util.Locale locale,
                   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 template self and return how many characters it wrote to out.
        Returns:
        the number of characters written to out

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

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

      • trunc

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

      • strip

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

      • reverse

        public java.lang.Object reverse​(InstanceScope scope,
                                java.lang.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 java.lang.Object length​(java.lang.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 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 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 java.lang.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 java.util.List<ST> getEnclosingInstanceStack​(InstanceScope scope,
                                                           boolean topdown)

      • printForTrace

        protected void printForTrace​(java.lang.StringBuilder tr,
                             InstanceScope scope,
                             java.lang.Object o)

      • getEvents

        public java.util.List<InterpEvent> getEvents()

      • getExecutionTrace

        public java.util.List<java.lang.String> getExecutionTrace()

      • getShort

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