| Syntax | Description |
|---|---|
| Attributes | |
| <attrname> | Insert the string value of the attribute named attrname |
| <attrname> | If attrname is an attribute with multiple values, then insert the
concatenation of these strings. |
| <attrname; separator=expr> | (Semicolon: delimiter before specifying options.) If attrname is an attribute with multiple values, then insert the concatenation of these strings separated by separator. |
| <attrname; format=expr> | When invoking a StringTemplate equipped with a FormatRenderer, the tempate
expression can pass a string argument to it (here expr), using the options part of the overall
expression. Multiple options can be provide, separated by comma, example: <attrname; format="toUpper",separator=" and "> |
| <attrname.propname> |
Dot = select property of attribute Tells StringTemplate to look for property called propname on the variable that was supplied for attrname, and insert its string value here. |
| <attrname.(expr)> | (expr) = indirection Same as <attrname.propname>, except first evaluate expr to calculate propname. |
| <[attrname1,attrname2]> | Square brackets: Make a list that combines the single or multiple values of attributes attrname1 and attrname2. Such a list can be used wherever a multi-valued attrname can be used, in the syntax below. |
| Invoke template | |
| <tmpname()> | ( ) means this is a template. Invoke template named tmpname, without args. Insert resulting string. |
| <tmpname(argname=expr, argname=expr)> | Invoke template named tmpname, with arguments. Insert resulting string.
-- argname refers to an argument of the called template (which in turn should match some attrname in an expression in the called template's text. -- expr can be any expression that makes sense in the context of the enclosing (ie: current) template. Note that an expression does not need to be delimited if it's inside an expression. So: Correct: <mytemplate(somearg=someattr)> Incorrect: <mytemplate(somearg=<someattr>)> |
| <tmpname(...)> | Elipses (three periods). The "..." syntax in the argument list says that template tmpname should obtain all argument values from the same-named values in the current template. (This overcomes the normal behavior of <tmpname()>, where any declared arguments of tmpname block tmpname's expressions from seeing the same-named values in the calling template.) Note: This is the only place in StringTemplate expressions that "..." is used as actual syntax. Elsewhere in this documentation, "..." stands for additional items that you fill in as you wish. |
| <tmpname(argname1=expr,...)> | Similar to preceding, but here a value for argument argname1 is provided explicitly, and the remaining arguments are "passed through". |
| In the following: Use args to represent argname=expr,argname2=expr2... (optionally empty) | |
| <(expr)(args)> | Template invocation, but first evaluate expr to calculate tmpname template name |
| Invoke template and apply it to an attribute | In the following expressions, a template is applied to an attribute. Where the attribute has multiple values, the template is invoked multiple times, each time with the next value from attribute. The final result is the list of output strings catenated together into a single string. |
| <i>, <i0> and <it> | Each time the template is applied, the value of the attribute for this iteration is made available in the invoked template through the built-in expression <it>. The invoked template can see the number of the iteration in the built-in expressions <i> (counting from 1) and <i0> (counting from zero). |
| <attrname:tmpname(args)> |
Colon: apply template to attribute. If the attribute has multiple values, invoke template tmpname once for each value. Within template tempname, the value of attrname
can be obtained using <it>. Special shorthand case: If template tmpname declares exactly one formal argument, and that template is invoked without arguments like this: <attrname:tmpname()> then StringTemplate will assign the attribute value to both <it> and that single argument. |
| <attrname:(expr)(args)> | Same as preceding, but first evaluate (expr) to calculate name of template. Eg: This could obtain template name from an attribute. |
| <attrname:tmpname(args); null="xxx"> | Semicolon: delimiter beginning one or more options. Here the option is the null option which provides a string (or expression) to return if attribute attrname is null. (Default result would be null string.) |
| <attrname:tmp1name(args):tmp2name(args)... | Colon. Apply each template in sequence left to right. In the leftmost template, the value of the attribute can be accessed using <it>. Each successive template can use <it> to access the result so far. If the attribute has multiple values, then each template passes a multi-value result to the next template, and finally to the result of this expression where it is catenated into a single string. |
| Define a subtemplate on-the-spot in an expression ("anonymous" template) and possibly apply it to an attribute | |
| <...{tmptext}...> | Braces: define template, returning a string. In general, an on-the-spot ("anonymous") template can be placed anywhere that an expression can appear: in this article, substituting for (expr). |
| <attrname:{tmptext}> | Invoke the "anonymous" template defined by tmptext to attribute attrname. If the attribute is multivalued, then invoke tmptext once for each value. Within tmptext, use <i>, <i0> and <it> as described above. |
| <{attrname:{argname | tmptext}> | Invoke anonymous template (defined by tmptext) for each value of multi-valued attribute attrname. On each invocation, the value of attribute attrname is given to argname. Expressions within tmptext can refer to that value either using <argname> or <it>. |
| <attrname,attrname2:{argname,argname2 | tmptext} > | "Parallel list iteration". Similar to the preceding, except two (or more)
attributes are used for input, whose values on each iteration are given to the corresponding
arguments: attrname-->argname, attrname2-->argname2, and so on. This syntax can be extended to three or more attributes and
arguments. Having multiple arguments, this syntax does not define an <it> attribute. (However, if the surrounding context has an <it> attribute then it can be accessed within tmptext). |
| <attrname:tmp1name(),tmp2name()...etc | Comma: Apply only one template from the list of templates, alternatingly for the multi values of attrname. First iteration invokes template tmp1name, second iteration invokes template temp2name and so on, wrapping around as many times as needed. |
| Operators | |
| <first(attrname)> | Returns the first (or only) element in this multi-valued attribute |
| <last(attrname)> | Returns the last (or only) element in this multi-valued attribute |
| <rest(attrname)> | All but the first element of attribute attrname. Returns nothing if <attr> a
single valued. You can combine operations to say things like: first(rest(names)) to get second element. |
| <trunc(attrname)> | All but the last element of attribute attrname. |
| <strip(attrname)> | Returns all elements that are non-null in attribute attrname. |
| <length(attrname)> | Returns count of of elements in attribute attrname. Use length(strip(list)) to
get count on non-null elements. (Note: this length function does NOT return the character-count length of a string.) |
| <...expr1+expr2...> | Plus: catenate two strings. Terence says he prefers the alternative of using a
subtemplate: <...{<expr1><expr2>}...> |
| Escapes | |
| \$ or \< | Whichever delimiter the template is using, if the template needs to use that character literally it can be escaped to avoid incorrect parsing. |
| <\ >, <\n>, <\t>, <\r> | These expressions can be used for space, newline, tab and carriage-return. More than one of these can appear in a single <...> expression. |
| <\uXXXX> | This expression can place a specific unicode character into the template. Example: <\u1234>. More than one of these can appear in a single <...> expression. |
| Comment | |
| <! lorem !> or $! lorem !$ | Comments, ignored by StringTemplate. |
| ______________________________________ | |
Labels:
None