ST condensed -- File syntax

File types

There are three file types in the StringTemplate world:

xxx.st - File containing single StringTemplate text. Body only, no argument declarations.
- Could be just a single file, or could be located within a group directory and thus be involved in some group functionality such as referencing other named templates, or vice versa.
- Name of template is name of file (minus the ".st" extension)
xxx.stg - StringTemplateGroup file. Contains definitions of multiple named templates, including formal argument declarations.
xxx.sti - Defines an "interface" for StringTemplateGroups. A StringTemplateGroup can declare that that it implements a particular interface, in which case it must provide implementations (actual template definitions) for the templates declared in the interface file.

Template file format

Filename pattern: *.st

Just interleaved literal text and expressions. The contents of the file are just the body of the template text, no template name, no arguments.

Name: <personname>
Address: <addr>
Phone: <phonenum>

Here, the template uses <...> as expression delimiters. This is the exact same format as your program could supply in a string when calling one of the StringTemplate constructors.

Template Group file format

Filename pattern: *.stg

This format is more elaborate. Example:

group mygroup;

// My nice template group file

// A simple template
sometemplate(anarg) ::= <<
Look, here's my input: <anarg>
blah blah
>>

// can also use " " around the template if it's one line
anothertemplate(arg2) ::= "blah blah <arg2> blah"

MyMap ::= [
"mon":"Monday",
"tue":"Tuesday",
"wed":"Wednesday",
default:"null"
]

Template group file syntax

Statement type	Syntax	Comment
group		Place at beginning of string template group file to name the group, and also indicate inheritance or implements
	group gname;	Simple case. Conventionally, gname should match the name of the template group file (minus .stg extension). The actual StringTemplateGroup object's Name field adopts the name provided by this group statement, even if different from the filename. If other templates refer to this one (as in inheritance) then it's this gname that's valid.
	group gname: supergroupname;	Group gname inherits from supergroupname
	group gname implements intfname;	Group gname implements the interface specified in intfname. Implements can also be placed after supergroupname.
template definition	tmpname() ::= "template text"	Basic form of template specification
	tempname() := << template text >>	Basic form of template specification using <<...>> to enclose multiple lines of template text
	tmpname(arg1, arg2) ::= "..."	Declare formal arguments inside the parens. (<<...>> can be used instead of "...")
	tmpname(arg1="blah") ::= "..."	Optionally provide a default value for an argument (<<...>> can be used instead of "...")
	newname::=oldname	Make newname an alternative name for the template oldname. Might also work for maps?
Inheritance	Override an inherited template	In the sub group file, just create a new definition of the template using the syntax above.
Region override	@tmpname.rgnname() ::= "sometext"	Override a region just like overriding a template, except use the qualified name of the region in place of the template name. Although there are parens, there will never be formal arguments. (<<...>> can be used instead of "...")
map	mapname ::= [ "name1":"val1", "name2":"val2", default:"err" ]	-- The last row can use default as the name (no quotes) to specify what to return when an expression invokes the map with a key that is not in the map. -- You can use the word key (no quotes) as a value to indicate that the map should just return the same value as was supplied. This is most useful in combination with the default name.

Template Group interface file format

Filename pattern: *.sti

This format is almost identical to the string-template group file (*.stg) format, but omits the bodies (texts) of templates.

interface myinterface;

// My nice template group interface

sometemplate(anarg);

anothertemplate(arg2);

Template group interface file syntax

Statement type	Syntax	Comment
interface		Place at beginning of string-template group interface file to name the interface
	group gname;	Simple case. Conventionally, gname should match the name of the template group file (minus .stg extension). The actual StringTemplateGroup object's Name field adopts the name provided by this group statement, even if different from the filename. If other templates refer to this one (as in inheritance) then it's this gname that's valid.
	tmpname(arg1, arg2);	Specify a template that is required to be implemented. (Note the semicolon at the end.)
	optional tmpname(arg1, arg2);	This form (with the keyword "optional") is used specify a template that can be implemented but is not required.

Next: ST condensed -- API annotated