StringTemplate 4 Documentation

StringTemplate is designed around the principle of strict model-view separation. Its primary goal is to ensure that the specification of business logic and computation (the model) is completely separated from the specification of how that text is presented or formatted (the view).

Key characteristics of this approach include:

• No Side-Effects: StringTemplate does not allow assignments or imperative programming features (like setting variables or arbitrary arithmetic) within templates. This prevents templates from becoming complex, unmaintainable programs.
• Push Method vs. Pull Method: Unlike many template engines that use a 'pull' method (where the template invokes model methods on demand), StringTemplate uses a push method. All attributes must be computed and pushed into the template before rendering. This eliminates 'order-of-computation' dependencies and prevents bugs where moving a template reference causes null pointer exceptions or missing data.

When using wrap, you can use the anchor option to ensure that all wrapped lines align with the left edge of the expression. This is useful for creating clean, indented code structures like arrays or function arguments.

How it works

• anchor: When present, StringTemplate lines up all wrapped lines with the left edge of the expression.
• Indentation vs. Anchor: If both an indentation (from the template context) and an anchor are present, StringTemplate uses whichever is larger.
• Anchoring to a specific position: Since anchor only works relative to the expression, if you need to anchor to a position to the left of the expression (e.g., to include leading literals in the alignment), wrap the literals and the expression together in an anonymous template <{...}> and apply the anchor to that wrapper.

Example: Aligned Array

// Standard wrap (not aligned)
array(values) ::= <<
int[] a = { <values; wrap, separator=","> };
>>

// Aligned wrap using anchor
array(values) ::= <<
int[] a = { <values; wrap, anchor, separator=","> };
>>

// Anchoring including leading literals via anonymous template
data(a) ::= <<
int[] a = { <{1,9,2,<values; wrap, separator=",">}; anchor> };
>>

StringTemplate provides several ways to organize and load templates:

1. STGroupDir: Loads templates from a directory. Each .st file in the directory is treated as a template source. This is useful for keeping templates in separate files.
2. STGroupFile: Loads a single file (typically with a .stg extension) that contains a collection of template definitions. This acts like a single unit or archive of templates.
3. STRawGroupDir: A variation of STGroupDir used when you want to keep only the template text in your files without formal parameter definitions (e.g., <type> <name>; instead of decl(type, name) ::= "<type> <name>;"). This is often preferred by designers working on HTML or graphics.

To use these, you create an STGroup object, use getInstanceOf(name) to retrieve a specific template instance, and then proceed with add() and render() as usual.

// Using STGroupDir
STGroup group = new STGroupDir("/tmp");
ST st = group.getInstanceOf("decl");
st.add("type", "int");
st.add("name", "x");
st.add("value", 0);
String result = st.render();

// Using STGroupFile
STGroup group = new STGroupFile("/tmp/test.stg");
ST st = group.getInstanceOf("decl");
// ... same as above

StringTemplate uses a lazy evaluation model to decouple the order of attribute computation from the order of text emission.

In many template engines, the order in which attributes are referenced in the template dictates the order in which the model must compute them. This can create 'dependency hazards' where an attribute $a_i$ depends on $a_j$, and changing the template order causes crashes or incorrect output.

StringTemplate avoids this by:

1. Decoupling Controller from View: The controller (your code) can compute attributes in any order convenient for your data structures.
2. Buffering Attributes: Attributes are stored in built-in attribute tables rather than being immediately evaluated.
3. Bottom-up Recursive Evaluation: Evaluation is delayed until the controller explicitly renders the root template instance. This invocation performs a bottom-up recursive evaluation of all sub-templates before evaluating the root template itself.

This allows you to assemble complex templates without worrying about the specific order in which their referenced attributes are computed or rendered.