Class ST


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

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  ST.AttributeList
      Just an alias for ArrayList, but this way I can track whether a list is something ST created or it's an incoming list.
      static class  ST.DebugState
      Events during template hierarchy construction (not evaluation)
      static class  ST.RegionType
      <@r()>, <@r>...<@end>, and @t.r() ::= "..." defined manually by coder
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected ST()
      Used by group creation routine, not by users
        ST​(java.lang.String template)
      Used to make templates inline in code for simple things like SQL or log records.
        ST​(java.lang.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​(ST proto)
      Clone a prototype template.
        ST​(STGroup group, java.lang.String template)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      ST add​(java.lang.String name, java.lang.Object value)
      Inject an attribute (name/value pair).
      ST addAggr​(java.lang.String aggrSpec, java.lang.Object... values)
      Split aggrName.{propName1,propName2} into list [propName1, propName2] and the aggrName.
      protected static ST.AttributeList convertToAttributeList​(java.lang.Object curvalue)  
      static java.lang.String format​(int lineWidth, java.lang.String template, java.lang.Object... attributes)  
      static java.lang.String format​(java.lang.String template, java.lang.Object... attributes)
      ST.format("<%1>:<%2>", n, p);
      java.lang.Object getAttribute​(java.lang.String name)
      Find an attribute in this template only.
      java.util.Map<java.lang.String,​java.lang.Object> getAttributes()  
      java.util.List<InterpEvent> getEvents()  
      java.util.List<InterpEvent> getEvents​(int lineWidth)  
      java.util.List<InterpEvent> getEvents​(java.util.Locale locale)  
      java.util.List<InterpEvent> getEvents​(java.util.Locale locale, int lineWidth)  
      java.lang.String getName()  
      STViz inspect()  
      STViz inspect​(int lineWidth)  
      STViz inspect​(java.util.Locale locale)  
      STViz inspect​(ErrorManager errMgr, java.util.Locale locale, int lineWidth)  
      boolean isAnonSubtemplate()  
      protected void rawSetAttribute​(java.lang.String name, java.lang.Object value)
      Set locals attribute value when you only know the name, not the index.
      void remove​(java.lang.String name)
      Remove an attribute value entirely (can't remove attribute definitions).
      java.lang.String render()  
      java.lang.String render​(int lineWidth)  
      java.lang.String render​(java.util.Locale locale)  
      java.lang.String render​(java.util.Locale locale, int lineWidth)  
      java.lang.String toString()  
      int write​(java.io.File outputFile, STErrorListener listener)  
      int write​(java.io.File outputFile, STErrorListener listener, java.lang.String encoding)  
      int write​(java.io.File outputFile, STErrorListener listener, java.lang.String encoding, int lineWidth)  
      int write​(java.io.File outputFile, STErrorListener listener, java.lang.String encoding, java.util.Locale locale, int lineWidth)  
      int write​(STWriter out)  
      int write​(STWriter out, java.util.Locale locale)  
      int write​(STWriter out, java.util.Locale locale, STErrorListener listener)  
      int write​(STWriter out, STErrorListener listener)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • EMPTY_ATTR

        public static final java.lang.Object EMPTY_ATTR
      • IMPLICIT_ARG_NAME

        public static final java.lang.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:
        Constant Field Values
      • impl

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

        protected java.lang.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()}
          
    • Constructor Detail

      • ST

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

        public ST​(java.lang.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​(java.lang.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,
                  java.lang.String template)
    • Method Detail

      • add

        public ST add​(java.lang.String name,
                      java.lang.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​(java.lang.String aggrSpec,
                          java.lang.Object... values)
        Split aggrName.{propName1,propName2} into list [propName1, propName2] and the aggrName. Spaces are allowed around ','.
      • remove

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

        protected void rawSetAttribute​(java.lang.String name,
                                       java.lang.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 java.lang.Object getAttribute​(java.lang.String name)
        Find an attribute in this template only.
      • getAttributes

        public java.util.Map<java.lang.String,​java.lang.Object> getAttributes()
      • convertToAttributeList

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

        public java.lang.String getName()
      • isAnonSubtemplate

        public boolean isAnonSubtemplate()
      • write

        public int write​(STWriter out)
                  throws java.io.IOException
        Throws:
        java.io.IOException
      • write

        public int write​(STWriter out,
                         java.util.Locale locale)
      • write

        public int write​(java.io.File outputFile,
                         STErrorListener listener)
                  throws java.io.IOException
        Throws:
        java.io.IOException
      • write

        public int write​(java.io.File outputFile,
                         STErrorListener listener,
                         java.lang.String encoding)
                  throws java.io.IOException
        Throws:
        java.io.IOException
      • write

        public int write​(java.io.File outputFile,
                         STErrorListener listener,
                         java.lang.String encoding,
                         int lineWidth)
                  throws java.io.IOException
        Throws:
        java.io.IOException
      • write

        public int write​(java.io.File outputFile,
                         STErrorListener listener,
                         java.lang.String encoding,
                         java.util.Locale locale,
                         int lineWidth)
                  throws java.io.IOException
        Throws:
        java.io.IOException
      • render

        public java.lang.String render()
      • render

        public java.lang.String render​(int lineWidth)
      • render

        public java.lang.String render​(java.util.Locale locale)
      • render

        public java.lang.String render​(java.util.Locale locale,
                                       int lineWidth)
      • inspect

        public STViz inspect()
      • inspect

        public STViz inspect​(int lineWidth)
      • inspect

        public STViz inspect​(java.util.Locale locale)
      • inspect

        public STViz inspect​(ErrorManager errMgr,
                             java.util.Locale locale,
                             int lineWidth)
      • getEvents

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

        public java.util.List<InterpEvent> getEvents​(int lineWidth)
      • getEvents

        public java.util.List<InterpEvent> getEvents​(java.util.Locale locale)
      • getEvents

        public java.util.List<InterpEvent> getEvents​(java.util.Locale locale,
                                                     int lineWidth)
      • toString

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

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

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