FreeMaker一篇通
前言
Freemaker是一个强大的模板引擎,相比velocity而言,其强大的过程调用、递归和闭包回调功能让freemaker可以完成几乎所有我们所想的功能。从个人看法而言,freemaker完全有能力作为MDA的代码辅助生成工具。
本文试图越过传统的概念性介绍,通过一组例子直接把读者带入到Freemaker应用的较高层阶。
正文
大家看文章标题就应该知道,我想用一篇文章,把大家从对freemaker的陌生直接带入到比较深入的境界,所以不想说一些基础性的东西,如果大家不习惯我的表达方法,大可通过google去找习惯于自己阅读方式的相关文章。
我用过velocity,最近才用freemaker,才知道我以前的选择是错了,因为velocity不支持过程的调用,所以我为velocity增加了很多的东西,写了很多代码,而且脚本也累赘得要命。freemaker首先吸引我的是它强大的过程调用和递归处理能力,其次则是xml风格的语法结构有着明显的边界,不象velocity要注意段落之间要留空格。所以我建议大家直接使用Freemaker,虽然freemaker没有.net版本,我想不嵌入程序中使用的话,freemaker是绝对的首选。(题外话,谁有兴趣移植一个NFreeMaker?)
在使用之前我们先要设置运行环境,在使用Freemaker的时候,我们需要下载相关的程序:
freemaker: http://freemarker.sourceforge.net/
fmpp: http://fmpp.sourceforge.net/
其中fmpp是一个freemaker的辅助工具,有了它,我们可以实现更多的功能。以下例子必须fmpp辅助。
这里我们首先提出问题。大家看如下的一个xml文件,虽然freemaker的能力不仅在于处理xml文件,但是用xml作为例子更直观一些:
< types xmlns:xsi ="http://www.w3.org/2001/XMLSchema-instance" xmlns ="urn:DruleForm-Lite.xsd" >
< type name ="Type1" >
< labels >
< label lang ="zh-CN" value ="投保单" />
</ labels >
< field name ="Field11" type ="Float" lbound ="1" ubound ="1" >
< labels >
< label lang ="zh-CN" value ="投保单ID" />
</ labels >
</ field >
< field name ="Field12" type ="String" lbound ="1" ubound ="*" />
< field name ="Field13" type ="Integer" lbound ="1" ubound ="*" />
< field name ="Field14" type ="Type2" lbound ="1" ubound ="*" >
< type name ="Type2" >
< field name ="Field21" type ="String" lbound ="1" ubound ="*" />
< field name ="Field22" type ="Integer" lbound ="1" ubound ="*" />
</ type >
</ field >
< field name ="Field15" type ="InsuranceProduct" lbound ="1" ubound ="*" />
< type >
< type name ="Type3" >
< field name ="Field31" type ="Type1" lbound ="1" ubound ="*" />
</ type >
</ types >
[代码1]
我们的任务是把这个文件转化为相应的C#代码。大家先看转换模板的代码:
2 < #-- 定义xml namespace,以便在以下代码中使用,注意,ftl指令必须使用单独的行 -- >
3 < @pp .setOutputEncoding encoding ="gb2312" /> < #-- 使用fmpp提供的函数来设置输出编码 -- >
4
5 < #recurse doc > < #-- 根入口,代码1部分的xml存放在变量doc中,doc变量的填充由fmpp根据config.fmpp中的配置进行 -- >
6
7 < #macro "ns:types" > < #-- xslt风格的匹配处理入口 -- >
8 < #recurse > < #-- 直接进行types节点内的匹配 -- >
9 </ #macro >
10
11 < #macro "ns:type" > < #-- 匹配type节点 -- >
12 class ${.node.@name} < #-- 其中.node是保留字,表示当前节点,引用的@name是xslt风格 -- >
13 {
14 < #recurse > < #-- 继续匹配 -- >
15 }
16 </ #macro >
17
18 < #macro "ns:field" >
19 public ${.node.@type} ${.node.@name};
20 </ #macro >
21
22 < #macro @element > < #-- 所有没有定义匹配的节点到这里处理 -- >
23 </ #macro >
24
25
[代码2]
我们使用的配置文件设置如下:
outputRoot: out
logFile: log.fmpp
modes: [
copy(common/**/*.* , resource/*.*)
execute(*.ftl)
ignore(templates/*.* , .project , **/*.xml , xml/*.* , *.js)
]
removeExtensions: ftl
sourceEncoding: gb2312
data: {
doc: xml(freemaker.xml)
}
[代码3]
然后我们在dos模式下运行指令:
E:/work/blogs/freemaker>f:/download/freemaker/fmpp/bin/fmpp
最后的输出结果是这样的,存放在文件out/freemaker.中:
{
public Float Field11;
public String Field12;
public Integer Field13;
public Type2 Field14;
public Float Field15;
}
class Type3
{
public Type1 Field31;
}
[代码4]
先来解释一下freemaker的基本语法了,
<# ... > 中存放所有freemaker的内容,之外的内容全部原样输出。
<@ ... /> 是函数调用
两个定界符内的内容中,第一个符号表示指令或者函数名,其后的跟随参数。freemaker提供的控制包括如下:
<#if condition><#elseif condition><#else></#if> 条件判断
<#list hash_or_seq as var></#list> 遍历hash表或者collection(freemaker称作sequence)的成员
<#macro name param1 param2 ... ><#nested param></#macro> 宏,无返回参数
<#function name param1 param2><#return val></#function>函数,有返回参数
var?member_function(...) 用函数对var进行转换,freemaker称为build-ins。实际内部实现类似member_function(var, ...)
stringA[M .. N] 取子字符串,类似substring(stringA, M, N)
{key:value, key2:value2 ...} 直接定义一个hash表
[item0, item1, item2 ...] 直接定义一个序列
hash0[key0] 存取hash表中key对应的元素
seq0[5] 存取序列指定下标的元素
<@function1 param0 param1 ... /> 调用函数function1
<@macro0 param0 param1 ; nest_param0 nest_param1 ...> nest_body </@macro> 调用宏,并处理宏的嵌套
<#assign var = value > 定义变量并初始化
<#local var = value> 在 macro 或者 function 中定义局部变量并初始化
<#global var = value > 定义全局变量并初始化
${var} 输出并替换为表达式的值
<#visit xmlnode> 调用macro匹配xmlnode本身及其子节点
<#recurse xmlnode> 调用macro匹配xmlnode的子节点
[表1]
大家仔细对比xml文件,发现少了什么吗?对了,少了一个Type2定义,我们把代码2中的ns:type匹配(第11行)修改一下:
public ${.node.@type} ${.node.@name};
< #recurse > < #-- 深入处理子节点 -- >
</ #macro >
[代码5]
结果输出文件中的内容就变为如下:
{
public Float Field11;
public String Field12;
public Integer Field13;
public Type2 Field14;
class Type2
{
public String Field21;
public Integer Field22;
}
public Float Field15;
}
class Type3
{
public Type1 Field31;
}
[代码6]
如果各位有意向把Type2提到跟Type1和Type3同一级别的位置,那么我们要继续修改代码了。把代码2的 <#recurse doc>行(第5行)修改成如下:
< #recurse doc > < #-- 根入口,代码1部分的xml存放在变量doc中,doc变量的填充由fmpp根据config.fmpp中的配置进行 -- >
< #if inner_types?size gt 0 > < #-- 如果存放有类型 -- >
< #list inner_types?values as node > < #-- 遍历哈西表的值 -- >
< #visit node > < #-- 激活相应的macro处理,类似于xslt的apply-template。大家把visit改成recurse看一下不同的效果 -- >
</ #list >
</ #if >
[代码7]
同时把macro ns:field(第18行)修改成如下:
public ${.node.@type} ${.node.@name};
< #if .node["ns:type"]?has_content > < #-- 如果当前节点下存在type节点 -- >
< #local t = .node["ns:type"] >
< @pp .set hash =inner_types key ="${t.@name}" value =t /> < #-- 哈西表中增加内容,key为嵌套类型的name属性,value为该类型节点 -- >
</ #if >
</ #macro >
[代码8]
运行得到输出文件类似这样:
{
public Float Field11;
public String Field12;
public Integer Field13;
public Type2 Field14;
public Float Field15;
}
class Type3
{
public Type1 Field31;
}
class Type2
{
public String Field21;
public Integer Field22;
}
[代码9]
大家比较一下,看看我们修改的地方出现了哪些效果?然后记得大家要做另外2件事情,
1。把第一行修改成为<#ftl ns_prefixes={"D": "urn:DruleForm-Lite.xsd"}> ,然后把所有的 <#macro "ns:type"> 修改成<#macro type>,把所有的.node["ns:type"]修改成 .node.type,看看能不能运行?是不是觉得简单方便些了?记住,第一行的那个D表示是default namespace的意思哦。
2。在第二行插入<#compress>,在最后一行添加</#compress>。再运行一下看看结果有什么不同?
一个例子下来,大家基本对freemaker有了一些感觉了,为了纠正大家认为freemaker就是一个xml处理工具的误解,我们再来做一个简单的实验。这次我们要做的是一个正常的编程题目,做一个100以内的Fibonacci数列的程序。程序如下:
< #list 1 .. 10 as n >
${n} = ${fibo(n)}
</ #list >
< #compress >
< #function fibo n >
< #if n lte 1 >
< #return 1 >
< #elseif n = 2>
<#return 1 >
< #else >
< #return fibo(n-1) + fibo(n-2) >
</ #if >
</ #function >
</ #compress >
[代码10]
这个例子里边有一些问题需要注意,大家看我的 #if n lte 1 这一行,为什么我这么写?因为常规的大于小于号和xml的节点有冲突,为了避免问题,所以用 gt(>) gte(>=) lt(<) lte(<=) 来代表。
另外,复杂的字符串处理如何来做?就留作家庭作业吧,大家记得取substr的方法是 str[first .. last] 就可以了。如下的例子可能会给你一点提示:
< #assign mid = (str?length + 1)/2-1 >
< #list mid .. 0 as cnt >
${str[(mid - cnt) .. (mid + cnt)]?left_pad(mid*2)}
</ #list >
[代码11]
最后,说一下非常有用的macro的nested指令,没有它,也许freemaker会失去大部分的魅力。我个人认为这也是freemaker全面超越velocity的地方。大家先看一下代码:
< @macro0 ; index >
${msg} ${index}
</ @macro0 >
< #macro macro0 >
< #list 0 .. 10 as number >
< #nested number >
</ #list >
</ #macro >
[代码12]
这段代码的作用就是一个闭包(closure)。我们用java的匿名类实现相同的功能就是这样:
{
public void call(int index);
}
void Main()
{
String msg = "hello";
macro0(
new ICallback()
{
public void call(int index)
{
System.out.println(msg + index.toString());
}
}
);
}
void macro0(ICallback callback)
{
for(int i = 0; i < 10; ++i)
{
callback.call(i);
}
}
这下清楚了吧!
Feedback
# re: FreeMaker一篇通 回复
2005-11-29 09:13 by CavingdeepFreeMaker在我看过了这篇文章后知道了它与Velocity的实现方式属同一类,即都是通过自创模板语言然后自行解析来实现的。这类实现方式的优点是控制比较细腻,缺点是如果每次运行同一模板都解析影响速度,实现难度大(等于bug多难维护),因为需要写一个模板语言的parser,其次语法受限,只能做自创模板语言范围内的操作(可能也是一个优点),这样一来不能利用平台优势,比如创建函数时。
其实与其说FreeMaker与Velocity相似倒不如说FreeMaker是XSLT 2.0的另一种实现(不过绝对没有XSLT 2.0强,差的远呢)。FreeMaker的语法也并不是特别有亲和力,如果让我在XSLT与FreeMaker之间选择我一定选XSLT。:)
我们回过头来再看DCG,DCG在实现方式上与.NET阵营的CodeSmith属于同一类,即都是与平台绑定的,也就是,模板的动态部分为与其绑定的平台语言,比如C#或者VB,如果移植到Java下的话绑定的平台就是Java。DCG与CodeSmith都是通过标签语言的形式(如ASP或者XML式的标签都可以)来区分模板中的静态文字与动态内容,这样做实现起来很简单(bug相对较少易维护),切可以充分利用平台资源,如函数等都是直接通过平台语言定义实现,可以选择的语法既是绑定平台语言的语法,在使用上极其容易上手,在维护、功能等方面也绝对不会输给XSLT一类的模板语法,况且像DCG一类的模板语法也是可以扩展的,像FreeMaker的list这种语法也是可以选择性的支持的,只是有没有必要的问题,因为用.NET直接写个for好了,没有必要写个特殊的语法。
最后,DCG在核心能力上要比CodeSmith强(尤其是新的DTL模板语法),只是目前外包装做的还不多,不过今后是一定会做的,DCG 2.0已经是Beta1了,目前经过一段时间的使用还是很稳定的,有兴趣的朋友可以下来试试,DCG的license是LGPL,请见一下链接:
http://cavingdeep.cnblogs.com/category/37494.html
FreeMaker和xslt不能等价,处理xml只是它的部分功能而已。freemaker和velocity是同一级别的东西。都可以作为模板解释引擎嵌入到我们的应用程序里去的。比如我们可以用伪代码演示一下如何嵌入freemaker或者velocity到我们的程序中(真实代码要自己写了):
void MyMain()
{
TemplateEngine engine = new FreeMakerEngine();// new VelocityEngine();
engine.loadConfig("config.cfg");
Object exportObject1 = new MyExportedClass1();
Object exportObject2 = new MyExportedClass2();
Object exportObject3 = new MyExportedClass3();
engine.importObject("obj1", exportObject1);
engine.importObject("obj2", exportObject2);
engine.importObject("obj3", exportObject3);
engine.loadTemplate("template.tpl");
engine.Run();
}
我们的template.tpl可能是如下的样子:
test obj1: ${obj1.Name}
test add: ${obj2.Value + obj3.Value}
<#list obj3.Items as item>
${item_index} = ${item.Name}
</#list>
这下明白了吧。codesmith不能为我所用,但是freemaker和velocity是可以的。因为velocity的主要目的是为了替代jsp产生html页面,所以他的野心比freemaker要小。不过Freemaker确实是codesmith之类的强大竞争者。
# re: FreeMaker一篇通 回复
2005-11-29 13:16 by Cavingdeep这个我自然知道,XSLT当然也可以的啊,只不过它只转换XML罢了。任何模板引擎都是以差不多的方式传参的。:) FreeMaker从语法上看起来的确要比Velocity强,不过本质上与Velocity没什么区别,调用方式都差不多。说是CodeSmith强大的竞争者也不为言过。不过从使用习惯等角度来看,DCG更是CodeSmith的竞争者。^_^
这里附上一段DCG作为嵌入式引擎的代码:
void Main() {
using (ITemplate template = new Template(fileName, Encoding.Default)) {
string arg1 = "Arg1";
MyObj arg2 = new MyObj();
Console.WriteLine(template.Transform(false, arg1, arg2));
}
}
而模板则可以是:
<%@ parameter
name:string;
obj:MyObj;
%>
Arg1 is <%=name%>
Arg2 is <%=obj.ToString()%>
<%
foreach (Item item in obj.Items) {
<%!
Item <%=item.Index%> is <%item.Name=%>.
!%>
}
%>