2.0 RC1

Page Contents

FreeMarker 2.0 的第一个公共发行版是在 2002 年 3 月 18 日。以下是 Lazarus 发行版与 FreeMarker Classic 的最后一个稳定发行版相比所做的更改的摘要。

  • NOTA BENE *:

尽管进行了上述更改,但 Lazarus 发行版几乎与 FreeMarker Classic 完全向后兼容。我们相信,在 FreeMarker Classic 下可以使用的大多数现有代码和模板将在 Lazarus 下可以 continue 使用,而所做的改动最少。实际上,遗留模板代码被破坏的最常见情况是假设数字和字符串相等。请注意,在 FreeMarker 2、2 2 中不会产生“ 22”。字符串“ 1”和数字 1 是完全不同的动物,因此,如果任何代码依赖于布尔表达式(“ 1” == 1)为 true,则该代码将被破坏。可以通过以下方式设置“经典兼容模式”:可以设置Template.setClassCompatibility(),以便 Lazarus 模仿 FreeMarker Classic 的一些古怪行为。但是,任何依赖于 FreeMarker classic 的上述“功能”的代码都应该重新设计。您不太可能遇到上面列出的其他不兼容问题。如果您遇到其他任何异常情况,请务必告诉我们。

支持数值运算,包括算术运算和布尔运算,以及数值范围。

  • 标量现在可以是字符串或数字。 (在 FreeMarker Classic 中,所有标量都是字符串.)允许的基本运算分别是使用+-*/%运算符进行加,减,乘,除和模。提供具有整数和浮点数的任意精度算术。尽管我们的目标绝对是遵循最少惊讶的原则,但是为了向后兼容,+运算符仍用于字符串连接。如果lhs + rhs的左侧或右侧不是数字,我们将其解释为字符串连接。因此,在 FreeMarker 2 中,2 2 的计算结果为数字 4,而“ 2” 2 或 2“ 2”或“ 2”,“ 2”中的任何一个计算结果为字符串“ 22”。在 FreeMarker Classic 中,相当令人尴尬的是,以上所有内容(包括 2 2)都被评估为字符串“ 22”。尝试对非数字操作数使用除+以外的任何其他算术运算符,将引发异常。

  • 可以通过可选的#{....}语法使数值表达式的输出明确。如果大括号内的表达式的计算结果不是数值,则抛出异常。较早的${....}语法可以求值为数字或字符串。通常,如果出于逻辑原因,输出必须是数字,则最好使用#\ {}语法,因为它会添加额外的完整性检查。请注意,如果在模板中出现了字符序列“#{”,这真是个奇迹,那么您将必须使用变通方法来防止问题。 ( 指令是一种可能.)

  • 在此版本中,有一种工具可以指定小数点后显示的位数。以下代码指定显示小数点后至少 3 位,但不超过 6 位。这是可选的。仅当使用#\ {}语法时,此选项才可用。

#{foo + bar ; m3M6}

(请注意,以上只是权宜之计。将来的版本将朝着完全支持数字和货币格式的国际化和本地化迈进。

  • 可以通过比较运算符ltgtltegte在布尔表达式中使用数值表达式。在实践中最常使用 FreeMarker 的网络空间中,使用更自然的运算符,例如\ < and >往往会混淆面向 HTML 的编辑器。尝试使用这些运算符比较非数值表达式会导致抛出TemplateException。碰巧的是,如果您有名为“ lt”,“ gt”,“ lte”或“ gte”的变量,则必须更改其名称,因为它们现在是该语言中的关键字。

  • 支持数值范围。

<#list 1990..2001 as year>
  blah blah in the year ${year} blah
</#list>

..运算符的左侧和右侧必须为数字,否则将引发异常。它们也不必是 Literals 数字,但可以是更复杂的表达式,其计算结果为数字标量值。请注意,也可以编写一个值递减的范围:

<#list 2001..1990 as year>
  blah blah in the year ${year} blah blah
</#list>

API Changes

  • 添加了TemplateNumberModel接口和SimpleNumber实现以支持公开数值。

  • FreeMarker Classic 中的TemplateListModel API 存在一些设计问题,特别是在支持线程安全代码方面。不建议使用以下 API:TemplateCollectionModelTemplateSequenceModel。重构了SimpleList类以实现上述接口(并且矛盾的是,没有实现 TemplateListModel 接口.)应该重构使用不推荐使用的TemplateListModel的代码。

  • Attila Szegedi 的 Expose 软件包已成为 FreeMarker 发行版的组成部分,现在位于 freemarker.ext.*层次结构中。该软件包提供了用于将任意 Java 对象表示为模板模型,将 XML 文档表示为模板模型的高级模型,以及用于促进 FreeMarker 与 Servlet 和 Ant 集成的类。

  • 在 FreeMarker Classic 中,存在一些 Util 类,例如freemarker.template.utility.Addition etcetera,作为 FreeMarker 中缺乏数字运算的解决方法。这些已被删除,可能不会丢失。

  • 在 FreeMarker Classic 中,SimpleScalar对象是可变的,它具有setValue方法。这显然是设计错误。任何依赖于此的代码都必须重构。请注意,在此版本中,SimpleScalar和新引入的SimpleNumber都是不可变的且是最终的。

Syntactical Miscellany

  • 引入了 if-elseif-else 语法。 FreeMarker 经典版只有 if-else。这种结构(应该在本文作者的看来-Revusky)应该优先使用开关结构,因为对于大多数凡人来说,带有跌落的开关结构是一个众所周知的容易出错的结构。

  • 现在,您可以在一个\ <assign...>指令中进行多次分配。例如:<assign x = 1, y = price*items, message="foo">

  • 标量将不再被解释为\ <list...>或\ <#foreach...>块中的单项列表。如果您有依赖此功能的代码,则有一个简单的解决方法,因为您可以仅使用一个项目定义一个列表 Literals。

<assign y=[x]>
 and then...
 <list y as item>...</list>