');
template.render({source: '
Hello World!
'});
```
当然，如果你觉得这样非常麻烦，那么你也可以修改转义函数：
```js
import { setEscapeFunction } from './ij2tpl';
// 使其原封不动的返回
setEscapFunction(v => v);
```
不过这样会影响到整个 IJ2TPL.js 的模板。如果你有多个模板，我们一般
是不建议你这样做的。
### If-Else 段落
```html
{?valid}
数据合法。
{*valid}
哎呀，好像出错了？
{/valid}
```
If-Else段落是一种语法糖。它可以将同一个变量的If段落和Not段落合并
成一个段落。两个分支之间使用“{*xxx}”格式分隔开。
题外话：为什么没有Not-Else段落呢？
> 是无法实现吗？不是的。虽然没有实际去写过，但就从实现上来说并不难。
> 我当初在设计时考虑到这样的语法会相对难理解，至少我不喜欢这样的语法。
> 加之我们的语法主要以符号为主，如果再增加上这样一种取反语法，那对于
> 用户来说，可读性降低了可不是一点两点……
### 函数类型（Lambda）
```ts
function toHumanReadableSize(size: number): string {
var i = 0,
dataUnits = ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB', 'BiB', 'NiB', 'DiB'];
while (size >= 1024)
i++, size /= 1024;
return String(size.toFixed(2)) + dataUnits[i];
}
import { Context, Name } from './ij2tpl';
/* 你可以理解为这是一个属性 getter，与其他格式化器相同 */
function humanReadableSize(context: Context) {
const name: Name = ['downloadedSize', null, null];
let downloadedSize = context.resolve(name);
return toHumanReadableSize(downloadedSize);
}
```
```html
已下载 {humanReadableSize}
```
函数类型指的是通过上下文查找到的变量是可调用类型的格式化器。
一般而言我们是不需要使用到函数类型的。但是如果你遇到了足够复杂的场景，
如我们需要验证某个值的范围是否正常，然后再决定是否渲染时，函数类型就
显得非常重要了。
函数类型中的函数会接受一个`Context`变量，你可以通过这个变量查找你想要的值。
如最上面我们见到的示例一样。
我们可以看到在上面的源码里我们还导入了一个叫做`Name`的类型，这个
类型是从`v0.1.0`时引入的。
```ts
import { Context, Name } from './ij2tpl';
```
其源码定义是：
```ts
// NAME NAMES FILTERS IS_ACTION
export type Name = [string, string[] | null, string[] | null, boolean];
```
因为篇幅原因，我不打算做过多的解释。我们只需要关心前两个元素的类型。
其中`NAME`表示的是一个格式化器的全名，如`"obj.key1.key2"`。后面的`NAMES`表示的是分隔
以后的名字，如`["obj", "key1", "key2"]`。如果名称不包含属性，那么后面的`NAMES`属性则
需要设置为`null`。
```js
// 包含属性
let name1: Name = ['name.lastName', ['name', 'lastName']];
// 不包含属性
let name2: Name = ['name', null];
```
这样设计的原因是为了优化查找速度。但相对的也给开发者造成了一定程度的不便。
**注意**：这里的函数类型会缓存结果，如果这不是你想要的效果，那么你可以考虑下面的过滤器。
### 定制 前缀 与 后缀 （分隔符）
```js
IJ2TPL.parse('Hello <%name%>', '<%', '%>');
```
```ts
let template = IJ2TPL.parse('Hello ${name}', '${', '}');
template.render({name: 'urain39'}); // -> 'Hello urain39'
```
此处应该没有什么特别需要讲解的，所以就举一两个简单的例子一笔带过了。
> 前缀可以是特殊字符，如上面讲到过的“#”，但是后缀不能是特殊字符。
> 因为这样会让词法分析函数产生误解，让结果不可预料。
### 片段模板（v0.1.0+）
```html
{? xxxEnabled }
{@partial_template}
{/ xxxEnabled }
```
```js
let renderer = IJ2TPL.parse(` {@partial_template}`),
renderer2 = IJ2TPL.parse(source2);
let partialMap = {
partial_template: renderer2
};
renderer.render(data, partialMap);
```
片段模板是指在模板中以“{@xxx}”形式引入的另一个模板。
`Renderer.render`方法接受两个参数，其中除了必要的视图数据`data`外，
还有一个可选的叫做`partialMap`的参数。这个参数的类型是`IMap
`。
```ts
public render(data: IMap, partialMap?: IMap): string {
return this.renderTree(
this.treeRoot, new Context(data, null), partialMap
);
```
也就是说我们只需要将被引用的模板作为`Map`传给`Renderer.render`方法即可。
有意思的是，如果我们将模板本身作为参数传入给`Render.render`，那么我们甚至
可以实现递归渲染，参考：https://stackoverflow.com/questions/13408425/mustache-js-recursion
从`v0.1.3`开始，IJ2TPL.js 和 Mustache.js 一样，已经支持缩进片段模板了。
片段模板将会以“{@xxx}”标签的缩进为准，将渲染后的片段模板以行为单位重新进行缩进。
**关于缩进的小问题**
> 目前我们的缩进检测机制还有些小问题，会误认为上一个字符标签的空白部分是一个
> 单独行的开始部分，即缩进。因此我建议片段模板最好还是单行使用为好。不过不用
> 担心，稍后的版本中我会改进这个问题。
### 过滤器 与 动作（Action）（v0.1.0+）
```html
Hello { name | no-f-word }
```
```js
IJ2TPL.setFilterMap({
'no-f-word': function(word) {
return word.replace('fuck', '****');
}
});
```
这和许多框架中的过滤器或是Unix Shell中的管道是一样的。
不过需要注意一点，IJ2TPL.js 中的过滤器是闭包保存的，一旦加载后
则是多个引用共享一个变量。我不保证所谓的安全克隆后的对象的安全性。
新版的过滤器增加了一个可选的参数项`context`，使用方法和上面的函数
类型是一样的，这里也就不赘述了。
*动作*与过滤器基本是一样的, 但是其并不会查找字段(因为“没名字”)
```html
{- 简单的例子 -}
{| report}
```
```js
IJ2TPL.setFilterMap({
report: function(_, context) {
let debugEnabled = context.resolve(['debugEnabled', null]);
if (debugEnabled) {
console.log('debugEnabled = true');
}
return '';
}
});
IJ2TPL.parse('{|report}').render({
debugEnabled: true
});
```
还记得我们上面提过的函数类型吗？这里的*动作*类型就类似于函数类型。
只不过它并不会缓存结果，适合对数据实时性要求比较高的场合使用。
但是需要注意`context`的实现上仍然是缓存结果的，也就说本质上缓存
结果这个功能是由`context`来完成的，详情可以参考`Context`的源码。
### 函数类型 与 动作类型 的不同点
|比较|函数类型|动作类型|
|:---:|:----:|:------:|
| 实时 | No | Yes |
| 安全 | Yes | No |
| 效率 | Yes | No |
| 易用 | Yes | No |
这两个功能各有优缺点，上图只是一个简单的比较，不能随便下定论。
简单而言，函数类型会在单页渲染时缓存第一次的结果，后面的渲染都是引用。
而动作类型会对每一次渲染重新求值，相对来说更实时一些。
### 嵌套段落
```html
{?valid}
{-}你的得分：
{?scores}
{-}得分：{.}
{/scores}
{/valid}
```
段落相当于是一个子模板，如果模板中能够定义模板，那么段落中
能定义新的段落吗？答案是当然可以，这就是所谓的嵌套。
**注意**：上面我们提到过了，每个段落相当于新的环境，所以在编写
模板时一定要注意名字是否写对了，然后再使用。
> If段落将会判断变量的真假，然后再将其作为新的上下文对段落进行渲染
下面是一个稍复杂的示例：
```js
let template = IJ2TPL.parse(`\
{?settings}
{?account}
{?username}{username}{/username}
{?password}{password}{/password}
{/account}
{/settings}
`);
template.render({
settings: {
account: {
username: "urain39",
password: "123"
}
}
});
```
这个功能有点类似于`with`语法，写起来会更便捷。
如果你真的运行了上面的代码，那么你会发现上面的渲染结果并非
你想的那样，这是为什么呢？
```js
template.render(data) // -> 'urain39123'
```
其实这是因为我们的`tokenize`函数会将段落标签的换行符和缩进都
忽略掉造成的。所以上面的模板应该改成：
```ij2
{?settings}
{?account}
{?username}
{username}
{/username}
{?password}
{password}
{/password}
{/account}
{/settings}
```
```js
template.render(data) // -> '\t\t\turain39\n\t\t\t123\n'
```
### 自递归模板（v0.1.3+）
自递归模板是从`v0.1.3`引入的新概念，其主要功能是让模板支持
递归渲染。
在上面我们给出了一个 Mustache.js 递归的实现，这个功能在 IJ2TPL.js
中被简化为你可以使用“@&”表示引用自身：
```ts
let template = IJ2TPL.parse(`\
{?contents}
{-}类型：{type}
{-}名称：{name}
{-}{@&}
{/contents}
`);
let data = {
"contents": [
{
"type": "file",
"name": "file1",
"contents": null
},
{
"type": "directory",
"name": "directory1",
"contents": [
{
"type": "file",
"name": "file2",
"contents": null
}
]
}
]
};
expected(template.render(data), `\
类型：file
名称：file1
类型：directory
名称：directory1
类型：file
名称：file2
`);
```
但是如你所见，我们在渲染时必须规定数据中含有一个“null”作为递归的
终结符号，这或许对我们引用第三方数据来说非常不便。
为了应对这种复杂的情况，我们也增加一种相对独立的递归形式“@^”：
```js
let template = IJ2TPL.parse(`\
{?contents}
类型：{type}
名称：{name}
{@^}
{/contents}
`);
let data = {
"contents": [
{
"type": "file",
"name": "file1"
},
{
"type": "directory",
"name": "directory1",
"contents": [
{
"type": "file",
"name": "file2"
}
]
}
]
};
expected(template.render(data), `\
类型：file
名称：file1
类型：directory
名称：directory1
类型：file
名称：file2
`);
```
这样我们就省去了手动加上`null`终结递归的操作了。
这部分的代码：
```ts
if (value === '&') { // Recursive render with parents
buffer += this.renderTree(this.treeRoot, context, partialMap)
.replace(BEGINNING_RE, `${indentation}$&`);
} else if (value === '^') { // Recursive render without parents
buffer += this.renderTree(this.treeRoot, new Context(context.data, null), partialMap)
.replace(BEGINNING_RE, `${indentation}$&`);
```
你可以看见，这里我们其实是将`context`的数据重新包装了一次，然后将其`parent`设置为`null`。
这样设计我们就不会将上层作用域的变量与当前作用域的变量搞混了。
**实战：递归树形结构渲染**
```ij2
{{?contents.length}} {{- ul标签只需要插入一次 }}
{{?contents}} {{- 判断是否有子节点 }}
{{-}}- {{name}}
{{-}}{{@^}}
{{/contents}}
{{/contents.length}}
```
`{{?contents.length}}`这样的用法是为了保证最外层的`ul`标签只插入一次。
还记得我们上面学过的吗？数组始终是会被遍历的，那样的话就不是我们想要的结果了。
## 关于调试
抱歉，我没有考虑到这一点。 为了改进令牌化(tokenizing)速度，我将位置信息移除了。
不过你依然可以从错误信息中猜测是哪里出了问题，它会告诉你段落的名字与类型。
## 还未实现
- ~~函数类型(已在 v0.0.2-dev 支持)~~
- ~~子模板(Partial Section)~~
- ~~格式化管道(又叫做过滤器)~~
## 关于自述文件
写错了 / 不能理解？请帮助我改进！
你只需在我的项目主页打开一个新的 issue 或者 PR ，我会尽可能的回复的 :)
上次更新: 2021-01-04