Package org.stringtemplate.v4

Class STGroup

java.lang.Object
org.stringtemplate.v4.STGroup
Direct Known Subclasses:
STGroupDir, STGroupFile, STGroupString
public class STGroup extends Object
A directory or directory tree of .st template files and/or group files. Individual template files contain formal template definitions. In a sense, it's like a single group file broken into multiple files, one for each template. ST v3 had just the pure template inside, not the template name and header. Name inside must match filename (minus suffix).

  • Field Details

    • GROUP_FILE_EXTENSION

      public static final String GROUP_FILE_EXTENSION

    • TEMPLATE_FILE_EXTENSION

      public static final String TEMPLATE_FILE_EXTENSION

    • RESERVED_CHARACTERS

      private static final boolean[] RESERVED_CHARACTERS

    • DICT_KEY

      public static final String DICT_KEY
      When we use key as a value in a dictionary, this is how we signify.
      See Also:

    • DEFAULT_KEY

      public static final String DEFAULT_KEY
      See Also:

    • encoding

      public String encoding
      The encoding to use for loading files. Defaults to UTF-8.

    • imports

      protected final List<STGroup> imports
      Every group can import templates/dictionaries from other groups. The list must be synchronized (see importTemplates(org.stringtemplate.v4.STGroup)).

    • importsToClearOnUnload

      protected final List<STGroup> importsToClearOnUnload

    • delimiterStartChar

      public char delimiterStartChar

    • delimiterStopChar

      public char delimiterStopChar

    • templates

      protected Map<String,CompiledST> templates
      Maps template name to CompiledST object. This map is synchronized.

    • dictionaries

      protected Map<String,Map<String,Object>> dictionaries
      Maps dictionary names to Map objects representing the dictionaries defined by the user like typeInitMap ::= ["int":"0"].

    • renderers

      protected Map<Class<?>,AttributeRenderer<?>> renderers
      A dictionary that allows people to register a renderer for a particular kind of object for any template evaluated relative to this group. For example, a date should be formatted differently depending on the locale. You can set Date.class to an object whose toString(Object) method properly formats a Date attribute according to locale. Or you can have a different renderer object for each locale.

      Order of addition is recorded and matters. If more than one renderer works for an object, the first registered has priority.

      Renderer associated with type t works for object o if

        t.isAssignableFrom(o.getClass()) // would assignment t = o work?
      So it works if o is subclass or implements t.

      This structure is synchronized.

    • adaptors

      protected final Map<Class<?>,ModelAdaptor<?>> adaptors
      A dictionary that allows people to register a model adaptor for a particular kind of object (subclass or implementation). Applies for any template evaluated relative to this group.

      ST initializes with model adaptors that know how to pull properties out of Objects, Maps, and STs.

      The last one you register gets priority; do least to most specific.

    • NOT_FOUND_ST

      protected static final CompiledST NOT_FOUND_ST
      Used to indicate that the template doesn't exist. Prevents duplicate group file loads and unnecessary file checks.

    • DEFAULT_ERR_MGR

      public static final ErrorManager DEFAULT_ERR_MGR

    • verbose

      public static boolean verbose
      Watch loading of groups and templates.

    • trackCreationEvents

      public static boolean trackCreationEvents
      For debugging with STViz. Records where in code an ST was created and where code added attributes.

    • iterateAcrossValues

      public boolean iterateAcrossValues
      v3 compatibility; used to iterate across Map.values() instead of v4's default Map.keySet(). But to convert ANTLR templates, it's too hard to find without static typing in templates.

    • defaultGroup

      public static STGroup defaultGroup

    • errMgr

      public ErrorManager errMgr
      The ErrorManager for entire group; all compilations and executions. This gets copied to parsers, walkers, and interpreters.

  • Constructor Details

    • STGroup

      public STGroup()

    • STGroup

      public STGroup(char delimiterStartChar, char delimiterStopChar)

  • Method Details

    • getInstanceOf

      public ST getInstanceOf(String name)
      The primary means of getting an instance of a template from this group. Names must be absolute, fully-qualified names like /a/b.

    • getEmbeddedInstanceOf

      protected ST getEmbeddedInstanceOf(Interpreter interp, InstanceScope scope, String name)

    • createSingleton

      public ST createSingleton(org.antlr.runtime.Token templateToken)
      Create singleton template for use with dictionary values.

    • isDefined

      public boolean isDefined(String name)
      Is this template defined in this group or from this group below? Names must be absolute, fully-qualified names like /a/b.

    • lookupTemplate

      public CompiledST lookupTemplate(String name)
      Look up a fully-qualified name.

    • unload

      public void unload()
      Unload all templates, dictionaries and import relationships, but leave renderers and adaptors. This essentially forces the next call to getInstanceOf(java.lang.String) to reload templates. Call unload() on each group in the imports list, and remove all elements in importsToClearOnUnload from imports.

    • load

      protected CompiledST load(String name)
      Load st from disk if directory or load whole group file if .stg file (then return just one template). name is fully-qualified.

    • load

      public void load()
      Force a load if it makes sense for the group.

    • isReservedCharacter

      public static boolean isReservedCharacter(char c)
      Determines if a specified character may be used as a user-specified delimiter.
      Parameters:
      c - The character
      Returns:
      true if the character is reserved by the StringTemplate language; otherwise, false if the character may be used as a delimiter.
      Since:
      4.0.9

    • lookupImportedTemplate

      protected CompiledST lookupImportedTemplate(String name)

    • rawGetTemplate

      public CompiledST rawGetTemplate(String name)

    • rawGetDictionary

      public Map<String,Object> rawGetDictionary(String name)

    • isDictionary

      public boolean isDictionary(String name)

    • defineTemplate

      public CompiledST defineTemplate(String templateName, String template)
      for testing

    • defineTemplate

      public CompiledST defineTemplate(String name, String argsS, String template)
      for testing

    • defineTemplate

      public CompiledST defineTemplate(String fullyQualifiedTemplateName, org.antlr.runtime.Token nameT, List<FormalArgument> args, String template, org.antlr.runtime.Token templateToken)

    • defineTemplateAlias

      public CompiledST defineTemplateAlias(org.antlr.runtime.Token aliasT, org.antlr.runtime.Token targetT)
      Make name and alias for target. Replace any previous definition of name.

    • defineRegion

      public CompiledST defineRegion(String enclosingTemplateName, org.antlr.runtime.Token regionT, String template, org.antlr.runtime.Token templateToken)

    • defineTemplateOrRegion

      public void defineTemplateOrRegion(String fullyQualifiedTemplateName, String regionSurroundingTemplateName, org.antlr.runtime.Token templateToken, String template, org.antlr.runtime.Token nameToken, List<FormalArgument> args)

    • rawDefineTemplate

      public void rawDefineTemplate(String name, CompiledST code, org.antlr.runtime.Token defT)

    • undefineTemplate

      public void undefineTemplate(String name)

    • compile

      public CompiledST compile(String srcName, String name, List<FormalArgument> args, String template, org.antlr.runtime.Token templateToken)
      Compile a template.

    • getMangledRegionName

      public static String getMangledRegionName(String enclosingTemplateName, String name)
      The "foo" of t() ::= "<@foo()>" is mangled to "/region__/t__foo"

    • getUnMangledTemplateName

      public static String getUnMangledTemplateName(String mangledName)
      Return "t.foo" from "/region__/t__foo"

    • defineDictionary

      public void defineDictionary(String name, Map<String,Object> mapping)
      Define a map for this group.

      Not thread safe...do not keep adding these while you reference them.

    • importTemplates

      public void importTemplates(STGroup g)
      Make this group import templates/dictionaries from g.

      On unload imported templates are unloaded but stay in the imports list.

    • importTemplates

      public void importTemplates(org.antlr.runtime.Token fileNameToken)
      Import template files, directories, and group files. Priority is given to templates defined in the current group; this, in effect, provides inheritance. Polymorphism is in effect so that if an inherited template references template t() then we search for t() in the subgroup first.

      Templates are loaded on-demand from import dirs. Imported groups are loaded on-demand when searching for a template.

      The listener of this group is passed to the import group so errors found while loading imported element are sent to listener of this group.

      On unload imported templates are unloaded and removed from the imports list.

      This method is called when processing import statements specified in group files. Use importTemplates(STGroup) to import templates 'programmatically'.

    • importTemplates

      protected void importTemplates(STGroup g, boolean clearOnUnload)

    • getImportedGroups

      public List<STGroup> getImportedGroups()

    • loadGroupFile

      public void loadGroupFile(String prefix, String fileName)
      Load a group file with full path fileName; it's relative to root by prefix.

    • loadAbsoluteTemplateFile

      public CompiledST loadAbsoluteTemplateFile(String fileName)
      Load template file into this group using absolute fileName.

    • loadTemplateFile

      public CompiledST loadTemplateFile(String prefix, String unqualifiedFileName, org.antlr.runtime.CharStream templateStream)
      Load template stream into this group. unqualifiedFileName is "a.st". The prefix is path from group root to unqualifiedFileName like "/subdir" if file is in /subdir/a.st.

    • registerModelAdaptor

      public <T> void registerModelAdaptor(Class<T> attributeType, ModelAdaptor<? super T> adaptor)
      Add an adaptor for a kind of object so ST knows how to pull properties from them. Add adaptors in increasing order of specificity. ST adds Object, Map, ST, and Aggregate model adaptors for you first. Adaptors you add have priority over default adaptors.

      If an adaptor for type T already exists, it is replaced by the adaptor argument.

      This must invalidate cache entries, so set your adaptors up before calling ST.render() for efficiency.

    • getModelAdaptor

      public <T> ModelAdaptor<? super T> getModelAdaptor(Class<T> attributeType)

    • registerRenderer

      public <T> void registerRenderer(Class<T> attributeType, AttributeRenderer<? super T> r)
      Register a renderer for all objects of a particular "kind" for all templates evaluated relative to this group. Use r to render if object in question is an instance of attributeType. Recursively set renderer into all import groups.

    • registerRenderer

      public <T> void registerRenderer(Class<T> attributeType, AttributeRenderer<? super T> r, boolean recursive)

    • getAttributeRenderer

      public <T> AttributeRenderer<? super T> getAttributeRenderer(Class<T> attributeType)
      Get renderer for class T associated with this group.

      For non-imported groups and object-to-render of class T, use renderer (if any) registered for T. For imports, any renderer set on import group is ignored even when using an imported template. You should set the renderer on the main group you use (or all to be sure). I look at import groups as "helpers" that should give me templates and nothing else. If you have multiple renderers for String, say, then just make uber combined renderer with more specific format names.

    • createStringTemplate

      public ST createStringTemplate(CompiledST impl)

    • createStringTemplateInternally

      public ST createStringTemplateInternally(CompiledST impl)
      Differentiate so we can avoid having creation events for regions, map operations, and other implicit "new ST" events during rendering.

    • createStringTemplateInternally

      public ST createStringTemplateInternally(ST proto)

    • getName

      public String getName()

    • getFileName

      public String getFileName()

    • getRootDirURL

      public URL getRootDirURL()
      Return root dir if this is group dir; return dir containing group file if this is group file. This is derived from original incoming dir or filename. If it was absolute, this should come back as full absolute path. If only a URL is available, return URL of one dir up.

    • getURL

      public URL getURL(String fileName)

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • show

      public String show()

    • getListener

      public STErrorListener getListener()

    • setListener

      public void setListener(STErrorListener listener)

    • getTemplateNames

      public Set<String> getTemplateNames()