Class ST

java.lang.Object
org.stringtemplate.v4.ST

public class ST extends Object
An instance of the StringTemplate. It consists primarily of a reference to its implementation (shared among all instances) and a hash table of attributes. Because of dynamic scoping, we also need a reference to any enclosing instance. For example, in a deeply nested template for an HTML page body, we could still reference the title attribute defined in the outermost page template.

To use templates, you create one (usually via STGroup) and then inject attributes using add(java.lang.String, java.lang.Object). To render its attacks, use render().

TODO: locals is not actually a hash table like the documentation says.

  • Field Details

    • VERSION

      public static final String VERSION
      See Also:
    • UNKNOWN_NAME

      public static final String UNKNOWN_NAME
      See Also:
    • EMPTY_ATTR

      public static final Object EMPTY_ATTR
    • IMPLICIT_ARG_NAME

      public static final String IMPLICIT_ARG_NAME
      When there are no formal args for template t and you map t across some values, t implicitly gets arg "it". E.g., "$it$"
      See Also:
    • impl

      public CompiledST impl
      The implementation for this template among all instances of same template .
    • locals

      protected Object[] locals
      Safe to simultaneously write via add(java.lang.String, java.lang.Object), which is synchronized. Reading during exec is, however, NOT synchronized. So, not thread safe to add attributes while it is being evaluated. Initialized to EMPTY_ATTR to distinguish null from empty.
    • groupThatCreatedThisInstance

      public STGroup groupThatCreatedThisInstance
      Created as instance of which group? We need this to initialize interpreter via render. So, we create st and then it needs to know which group created it for sake of polymorphism:
        st = skin1.getInstanceOf("searchbox");
        result = st.render(); // knows skin1 created it
        
      Say we have a group g1 with template t that imports templates t and u from another group g2. g1.getInstanceOf("u") finds u in g2 but remembers that g1 created it. If u includes t, it should create g1.t not g2.t.
         g1 = {t(), u()}
         |
         v
         g2 = {t()}
        
    • debugState

      public ST.DebugState debugState
      If STGroup.trackCreationEvents, track creation and add attribute events for each object. Create this object on first use.
  • Constructor Details

    • ST

      protected ST()
      Used by group creation routine, not by users
    • ST

      public ST(String template)
      Used to make templates inline in code for simple things like SQL or log records. No formal arguments are set and there is no enclosing instance.
    • ST

      public ST(String template, char delimiterStartChar, char delimiterStopChar)
      Create ST using non-default delimiters; each one of these will live in it's own group since you're overriding a default; don't want to alter STGroup.defaultGroup.
    • ST

      public ST(STGroup group, String template)
    • ST

      public ST(ST proto)
      Clone a prototype template. Copy all fields minus debugState; don't delegate to ST(), which creates ConstructionEvent.
  • Method Details

    • add

      public ST add(String name, Object value)
      Inject an attribute (name/value pair). If there is already an attribute with that name, this method turns the attribute into an ST.AttributeList with both the previous and the new attribute as elements. This method will never alter a List that you inject. If you send in a List and then inject a single value element, add copies original list and adds the new value. The attribute name cannot be null or contain '.'.

      Return this so we can chain:

      t.add("x", 1).add("y", "hi")

    • addAggr

      public ST addAggr(String aggrSpec, Object... values)
      Split aggrName.{propName1,propName2} into list [propName1, propName2] and the aggrName. Spaces are allowed around ','.
    • remove

      public void remove(String name)
      Remove an attribute value entirely (can't remove attribute definitions).
    • rawSetAttribute

      protected void rawSetAttribute(String name, Object value)
      Set locals attribute value when you only know the name, not the index. This is ultimately invoked by calling ST#add from outside so toss an exception to notify them.
    • getAttribute

      public Object getAttribute(String name)
      Find an attribute in this template only.
    • getAttributes

      public Map<String,Object> getAttributes()
    • convertToAttributeList

      protected static ST.AttributeList convertToAttributeList(Object curvalue)
    • getName

      public String getName()
    • isAnonSubtemplate

      public boolean isAnonSubtemplate()
    • write

      public int write(STWriter out) throws IOException
      Throws:
      IOException
    • write

      public int write(STWriter out, Locale locale)
    • write

      public int write(STWriter out, STErrorListener listener)
    • write

      public int write(STWriter out, Locale locale, STErrorListener listener)
    • write

      public int write(File outputFile, STErrorListener listener) throws IOException
      Throws:
      IOException
    • write

      public int write(File outputFile, STErrorListener listener, String encoding) throws IOException
      Throws:
      IOException
    • write

      public int write(File outputFile, STErrorListener listener, String encoding, int lineWidth) throws IOException
      Throws:
      IOException
    • write

      public int write(File outputFile, STErrorListener listener, String encoding, Locale locale, int lineWidth) throws IOException
      Throws:
      IOException
    • render

      public String render()
    • render

      public String render(int lineWidth)
    • render

      public String render(Locale locale)
    • render

      public String render(Locale locale, int lineWidth)
    • inspect

      public STViz inspect()
    • inspect

      public STViz inspect(int lineWidth)
    • inspect

      public STViz inspect(Locale locale)
    • inspect

      public STViz inspect(ErrorManager errMgr, Locale locale, int lineWidth)
    • getEvents

      public List<InterpEvent> getEvents()
    • getEvents

      public List<InterpEvent> getEvents(int lineWidth)
    • getEvents

      public List<InterpEvent> getEvents(Locale locale)
    • getEvents

      public List<InterpEvent> getEvents(Locale locale, int lineWidth)
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • format

      public static String format(String template, Object... attributes)
       ST.format("<%1>:<%2>", n, p);
       
    • format

      public static String format(int lineWidth, String template, Object... attributes)