Common Template Engine

一. 语法规则:
整个模板语言只有一个语法规则：
$指令名{参数表达式}
(注：指令名或参数表达式均可以为空，但不可以同时为空，参数表达式为空时，大括号可省)

二. 特殊符转义:
(1) 使用 \$ 转义，输出非指令 $ 符
如：“\${name}”输出“${name}”
(2) 使用 \\ 取消转义，输出非转义 \ 符
如：“\\${name}”输出“\value”
“\\\${name}”等价于“\\”+“\${name}”的组合，输出“\” + “${name}”，即“\${name}”
“\\\\${name}”等价于“\\”+“\\”+“${name}”的组合，输出“\” + “\” + “value”，即“\\value”
(注：这里的“\”都是指紧挨在“$”前的“\”，未紧挨在“$”前的任意“\”均不作任何处理，以避免模板中到处使用双斜杠)

三. 特殊指令:
(1) 行注释: 忽略其后同一行的内容 (注: 可注释不合法的指令内容)
运行期不保留: (注: 编译后即抛弃)
$# line comment ...
运行期保留: (注: 可通过Visitor访问到)
$## line comment ...
(2) 多行块注释: 忽略其包含的内容 (注: 可注释不合法的指令内容，自身不可嵌套，但可嵌套行注释和不解释块等)
运行期不保留: (注: 编译后即抛弃)
$*
    block comment ...
*$
运行期保留: (注: 可通过Visitor访问到)
$**
    block comment ...
*$
(3) 不解释块: 将其包含的内容作为纯文本输出 (注: 可包含不合法的指令内容，自身不可嵌套，但可嵌套行注释和块注释等)
$!
    no parse, eg: $if ...
!$
(4) 通用结束指令:
$end

四. 标准指令:
(1) 输出指令:
表达式结果输出: (注：指令名为空的指令)
${user.name}
${user.coins + 100}
国际化信息输出:
$msg{"home.title"}
$msg{"home.title", arg0, arg1}
块指令：(注：用于注释版语法外套)
表达式结果输出：忽略指令内部块内容
$out{user.name} James $end
 James 
 112 
国际化信息输出：将内部块内容作为默认值
$message{"key", arg0, arg1} default value $end
$message{"home.title"} welcome $end
 welcome 
(2) 条件指令:
$if{user.name == "james"} (注：可以判断空对象，$if{user}等价于$if{user != null})
    ...
$elseif{ user.name == "kent"}
    ...
$else
    ...
$end
(3) 迭代指令:
定义循环显示项:
$cycle{color: ("red", "blue", "green")}
迭代集合或数组:
$for{user : users}
    从循环显示项中取值 (注：cycle变量每次next取值时向后滚动，到最后一个值时将循环到第一个值)
    ${color.next} ${color.value} ${color.index}
    中断循环 (注：条件判定与指令合并，以避免冗长的语句：$if {for.count > 5} $break $end)
    $break{for.count > 5}
    继续循环
    $continue{user.name == null}
    状态
    (注：for变量(非关键字)持有循环过程的状态，多级嵌套循环时，可以用super.for.index获取上级循环的状态)
    ${for.index} ${for.count} ${for.size} ${for.first} ${for.middle} ${for.last} ${for.odd} ${for.even}
    (注：index从0开始，count从1开始，也就是count = index + 1)
    取值
    ${user.name}
$forelse (注：仿$if ... $else ...语法，以避免多重判断语句，当循环集合为空时执行)
    have no users...
$end
特殊迭代举例：
a. 简单次数迭代：$for{10}，迭代10次，不产生迭代项数据，但可以用状态信息${for.index}等
b. 数字序列迭代：$for{num : 1..9}，$for{num : -2..5}，$for{num : 5..-2}
c. 子集合迭代：$for{item : list[0..2]}，迭代list中索引号从0到2的元素(包含边界)
d. 过滤迭代：$for{item : list[=> item != 'xxx']}，过滤掉"xxx"项，参见"=>"操作符使用
e. 排序迭代：$for{item : list orderby ("+property1", "-property2")}，$for{book : books orderby "+price"} 将books内的元素按price属性值升序排列后再迭代 (参见orderby操作符使用)
f. 非空选择迭代：$for{item : list1 || list2 || list3}，从左至右选第一个非空的集合进行迭代
g. 并行迭代：$for{item1 : list1, item2 : list2}, $for{i : (1..10), user : users}，多个集合并行取next值，以最长的集合作为结束，短集合自动补null值
(4) 变量指令:
声明局部变量: (注：通常用于隐藏上级同名变量)
$var{name = "james"}
给最近区域的变量赋值: (注：若直到根区域均未找到相应变量，则在当前区域创建局部变量)
$set{name = "james"} (注：不能修改即有数据模型状态，也就是不能使用像：$set{user.name = "james"}的层级设值方式，以遵守模板无副作用契约，避免引入业务逻辑)
如果变量为空或未定义，则给其赋初始值:
$init{name = "guest"}
(5) 包含指令:
内嵌其它模板: (注：被内嵌的文件可以访问当前上下文的变量，不可以传参)
$embed{"common.ctl"}
$embed{"common.ctl", "UTF-8"}
内嵌其它模板的一部分: (注：#后为zone的名称, 参见$zone指令)
$embed{"common.ctl#zone"}
包含其它模板的输出: (注：只包含输出，被包含的文件在新的上下文中执行，不能访问当前上下文的变量，可以传参)
$include{"common.ctl"}
$include{"common.ctl", "UTF-8"}
$include{"common.ctl", (param1: "value1", param2: "value2")}
$include{"common.ctl", "UTF-8", (param1: "value1", param2: "value2")}
包含其它模板的一部分: (注：#后为zone的名称, 参见$zone指令)
$include{"common.ctl#zone"}
显示文件的内容: (注：不解析其内容)
$display{"article.txt"}
$display{"article.txt", "UTF-8"}
(6) 块指令:
Block块定义: (注: Block块在定义的位置不显示, 需通过show指令显示, 可以多次调用显示)
$block{"myblock"}
    ...
$end
显示Block块:
$show{"myblock"}
(7) 宏指令:
宏定义:
$macro{"mymacro"}
    ...
$end
$macro{"mymacro_block"} (注：以"_block"结尾的指令表示块指令，可以通过inner指令回调其内部块)
    ...
    回调调用者的内部块
    $inner{param3: "value3"}
$end
导入模板文件作为宏:
$import{mymacro : "mymacro.ctl"}
$import{mymacro_block : "mymacro.ctl"}
导入模板文件中的宏作为宏: (注：#号后面是宏的名称, 参见$macro指令)
$import{mymacro : "mymacro.ctl#mymacro"}
使用Block块作为宏:
$using{mymacro : "myblock"}
$using{mymacro_block : "myblock"}
宏调用方式: (注：宏调用在新的上下文中执行，不能访问当前上下文的变量，可以传参)
$mymacro{param1: "value1", param2: "value2"}
$mymacro_block{param1: "value1", param2: "value2"} (注：以"_block"结尾的指令表示块指令)
    ...
$end
(8) 继承指令: (注：通常用于布局layout) 示例>>
模板块区域定义: (注：在父模板中)
$zone{"myzone"}
    ...
$end
继承模板: (注：在子模板中)
$extends{"super.ctl"}
    覆盖父模板块:
    $overzone{"myzone"}
        调用父模板块:
        $superzone
        ...
    $end
$end
(9) 动态指令:
动态执行模板:
$exec{templateString}
动态表达式求值:
$eval{expressionString}
(10) 过滤指令:
输出过滤指令: (注：只过滤动态内容，不过滤文本块)
$filter{x => "<b>" + x.escapeHtml + "</b>"} (注：缺省名称为value，如：$filter{=> value.escapeHtml})
    ...
$end
输出全过滤指令: (注：过滤所有输出，包括文本块)
$filterAll{x => x.escapeHtml} (注：缺省名称为value，如：$filterAll{=> value.escapeHtml})
    ...
$end
压缩空格: (注: 将多个连续的空白符压成一个空格)
$compress
    ...
$end
转义特殊符:
$escape{"html", "js", "url", "base64"}
    ...
$end
(11) 调试指令:
停止页面解析：
$stop
性能监测，记录其内部块的运行时间，并将时间存入全局的变量中:
$time{"xxx_time"}
    ...
$end
above block spend time: ${xxx_time} ms
调试日志：
$log{"debug messages..."}
$log{debug: "debug messages..."}
$log{info: "info messages..."}
$log{warn: "warn messages..."}
$log{error: "error messages..."}

五. 变量区间:
页面内的每一个块指令(如$if,$for等)都会创建相应的LocalContext, 变量取值时逐级向上查找,
如果当前LocalContext中的变量与上级变量重名，可以使用super关键字跳到上级取值，如：${super.var}
Web应用中变量查找顺序：页面内, root, model, request, parameter, header, session, cookie, application, global
可以用context["区域名"]在指定范围内查找，如：${context["session"].loginUser}
另外，也可以用context["指令名"]查找最近的某个块指令区域内的变量，如：${context["for"].xxx} ${context["if"].xxx}

六. Html语法扩展
(1)  注释指令
(2) <table ct:if="users != null && users.size > 0">...<table> 属性指令, (暂只能用于if, for, out)

七. 举例:
(1) 标准指令:
<html>
    <body>
        $if{users != null && users.size > 0}
        <table border="1">
            $for{user : users}
            <tr>
                <td>${for.index + 1}</td>
                <td>${user.name}</td>
                <td>${user.coins}</td>
            </tr>
            $end
        </table>
        $end
    </body>
</html>

(2) 注释版语法外套:
<html>
    <body>
        
        <table border="1">
            
            <tr>
                <td>1</td>
                <td>james</td>
                <td>2.00</td>
            </tr>
            
        </table>
        
    </body>
</html>

(3) 属性版语法外套:
<html>
    <body>
        <table ct:if="users != null && users.size > 0" border="1">
            <tr ct:for="user : users">
                <td><span ct:out="for.index + 1">1</span></td>
                <td><span ct:out="user.name">james</span></td>
                <td><span ct:out="user.coins">2.00</span></td>
            </tr>
        </table>
    </body>
</html>