StringTemplate是一个模板引擎。模板引擎现在有很多，比如FreeMarker，比如velocity。ST有啥特别的呢？这就不提ST的兄弟项目Antlr了。Antlr是ANother Tool for Language Recognition的缩写，意思是另一个语法分析器。Antlr被大量用来开发DSL或者是分析现有语言。而作为ST的兄弟项目的ST，他的应用领域和Antlr一样，专注于语言分析之后的代码/文档生成。相较于普通的后端模板引擎，ST更加强大，也更加复杂一些。

Hello World

让我们来写一个简单的例子来体验ST的功能：

添加依赖：

1
2
3
4
5
<dependency>
    <groupId>org.antlr</groupId>
    <artifactId>ST4</artifactId>
    <version>4.0.8</version>
</dependency>

编写例子：

1
2
3
4
5
6
7
public class Hello {
    public static void main(String[] args) {
        ST hello = new ST("Hello <name>");
        hello.add("name","World");
        System.out.println(hello.render());
    }
}

输出：

1
Hello World

StringTemplate的基本语法

StringTemplate是基于MVC思想设计的。其中View是使用ST语法编写的模板，Model是Antlr解析语法后的数据或者是其他的自定义数据，Controller就是ST类，他吧数据传递给模板，并可以渲染输出。

本质上，ST的语法很简单，分为两个部分：文本和属性表达式(attribute expressions)。文本部分会被原样输出。属性表达式会被求值后输出。默认属性表达式使用尖括号包围，当然这个是可以自定义的，比如如果你要生成HTML代码，用尖括号就非常麻烦了，可以改用%。比如上面的例子中的模板：

1
Hello, <name>

这里有一个属性表达式，<name>，通过.add("name","World")设置属性的值后，<name>就被替换为了World，所以合起来的输出是Hello World。

模板组（Groups of templates）

在说更多的ST语法之前，先说说ST的模板组。代码生成是具有复杂逻辑的，一般不会在一个模板中搞定，而是分解为多个小的模板，然后拼装起来。就算是网页模板引擎，也会支持引入子模板这样的功能。ST的模板更加强大，可以有输入参数，写起来和编程语言很类似。一个模板组里可以定义多个模板，只有在同一个模板组里的模板才可以互相调用。

看代码：

1
2
3
4
5
6
STGroup stGroup = new STGroup();
stGroup.defineTemplate("thing","name","<name>");
stGroup.defineTemplate("say","name","Hello <thing(name)>");
ST st = stGroup.getInstanceOf("say");
st.add("name","World");
System.out.println(st.render());

定义了一个模板组stGroup，其中定义了两个模板。defineTemplate需要三个参数，分别是模板名称，模板参数，模板内容。代码中我们定义了两个模板，say和thing。这两个模板都需要一个name参数，并且say模板调用了thing模板。

然后我们拿到say模板的实例，传入参数，并渲染，得到输出Hello World。

从文件中读入模板组

在代码中定义模板真是很费劲的，所以一般都是把模板定义在文件中，在代码中载入：

1
2
3
// file /tmp/test.stg
decl(type, name, value) ::= "<type> <name><init(value)>;"
init(v) ::= "<if(v)> = <v><endif>"

stg是模板组文件，其中可以定义多个模板，每个模板的格式是：模板名称(模板参数) ::= "模板内容"

如果模板的内容有多行，可以这么写：

1
2
3
4
message(message) ::= <<
line1
line2
>>

在代码中载入模板：

1
2
3
4
5
6
STGroup group = new STGroupFile("/tmp/test.stg");
ST st = group.getInstanceOf("decl");
st.add("type", "int");
st.add("name", "x");
st.add("value", 0);
String result = st.render(); // yields "int x = 0;"

向模板赋值

传递数组

可以通过ST实例向模板传递参数。

1
2
3
4
5
say(name) ::= "hello, <name>"

st.add("name", "mushan");

// 输出： hello, mushan

如果多次add同一个参数的值，是不会覆盖的，而是追加，也就是每个参数其实是一个数组：

1
2
3
4
5
6
say(name) ::= "hello, <name>"

st.add("name", "mushan");
st.add("name","willing");

// 输出： hello, mushanwilling

我们还可以控制多个值的输出格式：

1
2
3
4
5
6
say(name) ::= "hello, <name;separator=\",\">"

st.add("name", "mushan");
st.add("name","willing");

// 输出： hello, mushan,willing

还可以使用模板来处理每一个元素：

1
2
3
4
5
6
7
say(name) ::= "hello, <name:bracket();separator=\",\">"
bracket(x) ::= "(<x>)"

st.add("name", "mushan");
st.add("name","willing");

// 输出： hello, (mushan),(willing)

是不是非常灵活😁。但，其实还可以很灵活，比如我们这里定义了一个bracket模板，但其实功能很小，能不能像编程语言一样，弄个一个匿名函数呢？可以！那就是匿名模板：

1
2
3
4
5
6
say(name) ::= "hello, <name:{x|[<x>]};separator=\",\">"

st.add("name", "mushan");
st.add("name","willing");

// 输出： hello, [mushan],[willing]

传递对象

除了上面的例子中简单的字符串和数字外，ST还支持向模板传递自定义的类作为数据。比如我们定义一个User类：

1
2
3
4
5
6
7
8
9
public static class User {
    public int id; // template can directly access via u.id
    private String name; // template can't access this
    public User(int id, String name) { this.id = id; this.name = name; }
    public boolean isManager() { return true; } // u.manager
    public boolean hasParkingSpot() { return true; } // u.parkingSpot
    public String getName() { return name; } // u.name
    public String toString() { return id+":"+name; } // u
}

注释的部分就是如何在模板中访问User类实例属性的方法。属性的范围是比较简单的，方法的访问有一套映射关系，比如对于o.p，st会在类上尝试访问getP(), isP(), hasP()，如果都不存在，则会报错。

1
2
3
ST st = new ST("<b>$u.id$</b>: $u.name$", '$', '$');
st.add("u", new User(999, "parrt"));
String result = st.render(); // "<b>999</b>: parrt"

可以看到在ST模板中使用Java类是非常简单的。但是和js中直接使用json相比，Java中定义一个类，只是为了传递数据就定义一个类是非常繁琐的，还好，ST为我们提供了一种简便的方法来传递对象性质的信息：

1
2
3
4
5
6
7
introduction(person) ::= "I'm <person.name>, I'm <person.age> years old."

st = stGroupFile.getInstanceOf("introduction");
st.addAggr("person.{name,age}","mushan",18);
System.out.println(st.render());

// 输出： I'm mushan, I'm 18 years old.

StringTemplate模板语

ST模板的语法很丰富，可以实现复杂逻辑，以处理复杂的代码生成需求。上面我提到的语法是最常用的语法，全面的模板语法可以参考stringtemplate4/cheatsheet.md

参考资料