This page is an examination of the existing page: Setting the expression delimiters. Please help by leaving comments confirming or disputing what I think this page intends, especially the red blobs. (Or you can outright edit this page if you like.)
I wanted to improve this article to avoid the ambiguity in the phrasing "a template uses a particular delimiter". Part of the issue is whether "template" refers to a StringTemplate object, or to the text of a template.
As far as I understand it, the author of a template text chooses to write it using a particular choice of expression delimiter. Independently, the programmer employing a StringTemplate object sets it to recognize a particular expression delimiter. Obviously these choices should be coordinated.
So below is the complete article (on the left) and my clarifications/questions on the right...
| What existing article says |
What I think it probably means |
|
|---|---|---|
| 1 |
By default, expressions in a template are delimited by dollar signs: $...$. | This claim seems not always true. So how about: You can choose whether your template text uses dollar signs $...$ or by angle brackets <...> to delimit expressions. Depending on how the StringTemplate object is created, it defaults to recognizing one or the other, a choice which can be overriden by your program code. |
| 2 |
This works great for the most common case of HTML generation because the attribute expressions are clearly highlighted in the text. Sometimes, with other formats like SQL statement generation, you may want to change the template expression delimiters to avoid a conflict and to make the expressions stand out. This works great for the most common case of HTML generation because the attribute expressions are clearly highlighted in the text. Sometimes, with other formats like SQL statement generation, you may want to change the template expression delimiters to avoid a conflict and to make the expressions stand out. |
You would choose which delimiter to use based on the main language of the template text within which these expressions are surrounded. Within a template containing HTML, the $...$ choice avoids conflicts with HTML's own angle-bracket tags. Within some other language, using <...> may avoid conflicts with the language's own use of "$", or may simply stand out better visually. Not mentioned on this page, but perhaps covered elsewhere:
|
| 3 |
The start and stop strings are limited to either $...$ or <...> (unless you build your own lexical analyzer to break apart templates into chunks). | The dollar and angle-bracket delimiters are the two alternatives recognized by StringTemplate. If necessary, you could write your own lexical analyzer for StringTemplate to use other delimiters. |
| 4 |
group file templates use <...> delimiters by default (in v2.2 $...$ was the default delimiter). | A StringTemplateGroup object defaults to recognizing <...> expression delimiters when reading from a template-group file/stream. It can be set to recognize $...$ instead if desired. (Is <...> StringTemplateGroups default always, or only when reading from a stream/file? See comment on example below). |
| 5 |
Templates created with the StringTemplate object constructor still use $...$ by default. | A StringTemplate object defaults to recognizing $...$ expression delimiters. |
| 6 |
To specify that StringTemplate should use a specific delimiter you must create a StringTemplateGroup | There is no way to set a StringTemplate by itself to recognize angle-bracket delimiters, you can only do this by creating it as a member of a StringTemplateGroup, which allows a choice of delimiter. Except this appears not to be true, since there's a constructor for StringTemplate which takes a lexer. |
| 7 |
(Example code, see below) |
OK, but if StringTemplateGroup defaults to <...>, why does the code have to explicitly set the AngleBracketTemplateLexer.class? |
| Java | |
|---|---|
| C# | (omitted for brevity) |
| Python | (omitted for brevity) |
| 10 |
All templates created through the group or in anyway associated with the group will assume your the angle bracket delimiters. | If a StringTemplate is a part (child? member?) of a StringTemplate Group, it honors the delimiter setting of the group. (Which might be $...$, but in this example it's <...> ). (What other way is this sentence referring to in which a StringTemplate can be associated with a StringTemplateGroup, that impacts on delimiter recognition? Ah -- possibly templates created within template text.) |
| 11 |
It's smart to be consistent across all files of similar type such as "all HTML templates use $...$" and "all SQL templates use <...>". | Having determined which delimiter is the better one for a particular surrounding language, you will reduce confusion by using this delimiter consistently for all templates that use that language. |
GW's Comments
Part of my tentativeness in thinking I understand this ought-to-be-trivial topic is this:
It doesn't seem quite right that the choice of which expression delimiter to recognize is divorced from the actual template text itself which is obviously committed to a particular delimiter. So, naively, I would have expected there to be some syntax at the beginning of the template text itself saying "I'm using <..>, so, Mr StringTemplate, that's what you have to recognize".
Correspondingly, StringTemplate(Group) would have no need for a delimiter setting. Or they might have a setting which says "in the absence of an override from syntax within the template, assume this delimiter".
Which all makes me think I missed something.
Comments?