smarty4j的一些新特性

项目地址：[url]http://ordinary.googlecode.com[/url]
以下功能均是与标准smarty manual的不同之处，不影响原有的使用

1.扩展的break,continue函数，加上参数允许指定跳出多少层，在不特别指定的情况下只跳出一层，如

{foreach from=$values item="item" key="key"}
  {$key}:{$item}
  {if $key>10}{break}{/if}
{/foreach}

当values是Map时，{$key}表示键值；当values是List时，{$key}表示序号，从0开始，在有多层循环的时候，可以使用{break 2}跳出2层循环

2.扩展的assign函数，支持delimiter参数，可以直接定义一个数组，delimiter表示分隔符，例如

{assign var="list" values="1,2,3,4,5,6" delimiter=","}

3.扩展的bytes函数，允许向字节流中输出一个变量，使用时，必须merge的参数是OutputStream，否则会失败，一般用于向Socket进行特殊输出。例如

{bytes $array}

4.扩展的date_format函数，支持将long，date或者字符串代表的日期转换成标准日期类型，对于字符串日期，使用from参数定义输入字符串的格式，使用to参数定义输出字符串的格式，格式代表的意义参见jdk中java.text.SimpleDateFormat类的说明，使用locale与timezone参数指定国别与时区，例如

{date_format date="2008/12/12" from="yyyy/MM/dd" to="MM/dd/yyyy"}

5.扩展的macro函数，与include不同的是，macro表示直接在当前位置展开一段smarty语法的文本，这段文本本身可以是不完整的smarty语法

6.扩展的b2s变量调节器，能将一个字节数组变为字符串，例如

{$barray|b2s}

7.扩展的truncate变量调节器，在截取字符时，会换算非ASCII字符，一个非ASCII字符长度计算为两个ASCII字符

8.扩展的block函数，用于优化，smarty4j在编译过程中，会自动优化被多次出现的变量，前提是这一个区块中没有出现数据的回写操作，例如一个区块中有assign函数，这个区块就不会优化，默认情况下整个文档是一个最大的区块，如果反复出现对一个变量的操作，例如

...
{$items.data[0]}
...
{$items.data[1]}
...
{$items.data[2]}
...

可以写为

{assign var="data" values=$items.data}
{block}
...
{$data[0]}
...
{$data[1]}
...
{$data[2]}
...
{/block}

这样可以将后面的操作人为的划分出一个区块，而这个区块内没有回写数据进入容器的操作，$data变量将进行缓存，性能会有明显的提升

9.高速的条件短路算法，在实现短路算法时，smarty4j引擎会自动计算哪些代码块是可以越过的，加快条件判断的执行速度

10.允许重新定义左右边界符，例如重定义为<!--与-->，这样，smarty4j的代码不会影响整个文档在浏览器中的阅读效果，使用Engine.setLeftDelimiter与Engine.setRightDelimiter方法可以重新设置，之后使用

<!--foreach from=$values item="item"-->
...
<!--/foreach-->

即可

11.新增行函数，继承org.lilystudio.smarty4j.statement.AbstractLineFunction；新增区块函数，继承org.lilystudio.smarty4j.statement.AbstractBlockFunction；新增变量调节器，继承org.lilystudio.smarty4j.statement.AbstractCustomModifier；都是通过设置parameter这个属性来定义默认的参数格式
单行函数的例子：

public class $repeat extends AbstractLineFunction {
  @SuppressWarnings("unused")
  private static Parameter[] parameters = {
      new Parameter("value", Parameter.STROBJECT), // 第一个参数名字叫value，是一个字符串对象
      new Parameter("count", Parameter.INTOBJECT) }; // 第二个参数名字叫count，是一个整数对象

  @Override
  public void execute(Context context, Writer writer, Object[] values) //values就是参数表
      throws Exception {
    StringBuilder s = new StringBuilder();
    String value = (String) values[0]; // 参数value
    int count = (Integer) values[1]; // 参数count
    for (int i = 0; i < count; i++) {
      s.append(value);
    }
    writer.write(s.toString());
  }

  @Override
  public boolean isSimpleNode() {
    return true;
  }
}

{repeat value=$text count=3}

即可以调用
区块函数的例子：

public class $strip extends AbstractBlockFunction {

  @Override
  public Writer start(Context context, Writer writer, Object[] values) {
    return new StringWriter();
  }

  @Override
  public void end(Context context, Writer writer, Object[] values,
      Writer childWriter) throws Exception {
    StringBuilder buffer = new StringBuilder();
    String text = childWriter.toString();
    int len = text.length();
    int start = 0;
    out: while (true) {
      while (true) {
        if (start >= len) {
          break out;
        }
        char c = text.charAt(start);
        if (!Character.isWhitespace(c)) {
          break;
        }
        start++;
      }
      int i = text.indexOf('\n', start);
      if (i < 0) {
        break;
      }
      int end = i - 1;
      while (true) {
        char c = text.charAt(end);
        if (!Character.isWhitespace(c)) {
          buffer.append(text.substring(start, end + 1));
          start = i;
          break;
        }
        end--;
      }
    }
    buffer.append(text.substring(start));
    writer.write(buffer.toString());
  }
}

其中start的返回值是表示区块内部的处理使用的Writer对象，这里生成了一个新的StringWriter来拦截中间的输出，这个对象稍后会在end中被访问，即childWriter这个值。
变量调节器的例子：

public class $cat extends AbstractCustomModifier {

  @SuppressWarnings("unused")
  private static Object[] parameters = { "" }; // 第一个参数是字符串类型，默认是空字符串

  @Override
  protected Object execute(Object var, Object[] values) {
    if (((String) values[0]).length() > 0) {
      return var.toString() + values[0];
    } else {
      return var.toString();
    }
  }
}

{"Psychics predict world didn't end"|cat:" yesterday."}

即可使用
需要注意的是，默认的函数都应该位于org.lilystudio.smarty4j.statement.function包下，以$开头；默认的变量调节器都应该位于org.lilystudio.smarty4j.statement.modifier包下，同样以$开头。需要自定义包的位置，参见Engine内的说明