min-velocity簡化 velocity ?模板引擎

min-velocity 是一個專為代碼生成而定制的簡化 velocity 模板引擎。

目標：

以 velocity 1.7 為基礎, 裁剪出適合用作代碼生成的模板引擎

裁剪：

• 沒有event機制

• 沒有macro

• 沒有stop

• 沒有evaluate

• 沒有define

• 沒有break

改動：

• requires jdk1.5+

• 默認情況下，不打印任何日志

• 默認采用classpath模板加載器而非文件系統(tǒng)模板加載器

• default I/O encoding changed to UTF-8(from iso-8859-1)

• 對于#set指令，默認允許設置null值

• 默認打開resource cache

• 去掉了parser pool

• #parse和#include標簽支持相對路徑

• 新增$ParseUtil.recParsing("xxx.vm").addParam("key", val)模板調用形式；相當于帶調用棧的#parse標簽，能用在當你需要每層遞歸的context都相互隔離的遞歸#parse的時候；也能支持相對路徑

• 可放置min-velocity.properties文件(可選)在classpath根路徑下，用于覆蓋velocity的各種默認屬性

• min-velocity.properties可使用default.static.util.mappings屬性配置默認的靜態(tài)工具類，這 些工具類將被默認放入模板context中，可配置多個，如：default.static.util.mappings = ClassUtils:org.apache.commons.lang.ClassUtils

• 設置'stream.reference.rendering'開關(true/false)，默認關閉; 開啟后，遇到reference是stream或reader的時候, 將讀取stream或reader中的內容做渲染而非簡單地toString渲染; 其中讀取stream或reader的buffer可通過'stream.reference.rendering.buffer.size'配置大小 (默認為1024個字符); 亦可通過'stream.reference.rendering.limit'選項設置能夠從流中讀取的最大字符數(shù)限制(默認為100000)

• 支持String模板渲染，即直接將模板內容以String形式傳入api進行渲染而不是只能選擇傳入一個模板路徑

• 新增index.out.of.bounds.exception.suppress選項，當設置為true時，模板中對數(shù)組或list進行的取值或設置操作將忽略index out of bounds異常

For English speakers, see below:

• No event mechanism

• No macro

• No '#stop'

• No '#evaluate'

• No '#define'

• No '#break'

• requires jdk1.5+

• By default no logs rather than log to velocity.log

• defaults to use classapth resource loader

• I/O encoding defaults to UTF-8

• #set directive defaults to allow null value

• resource cache on by default

• parser pool removed

• relative path support for #parse and #include directives

• $ParseUtil.recParsing("xxx.vm").addParam("key", val) template parsing util added. You can see it as a '#parse' directive with invocation stack frame,
  which could easily do recursive parsing with isolated context in each round of recursion. This also supports relative path.

• could place an optional 'min-velocity.properties' file in classpath root to configure velocity runtime.

• min-velocity could contain zero or more 'default.static.util.mappings' property configs to expose static utility classes in template contexts, for example: default.static.util.mappings = ClassUtils:org.apache.commons.lang.ClassUtils, with this config you can reference to org.apache.commons.lang.ClassUtils class with key 'ClassUtils' anywhere.

• stream/reader reference rendering supported. If you set 'stream.reference.rendering'(default false) to 'true', min-velocity will dump the contents of a stream/reader reference rather than just invoking 'toString' on them while rendering. And the stream/reader reading buffer size could be specified by configuration 'stream.reference.rendering.buffer.size', measured in number of characters(default 1024). And further more, the maximum number of characters read from a stream could be limited by configuration 'stream.reference.rendering.limit'(default 100000).

• String literal templates rendering supported. Just specify template contents in a in-memory-String value to render, other than always specify a template path.

• When 'index.out.of.bounds.exception.suppress' option is setting to be 'true'，any 'IndexOutOfBoundsException' will be ignored when accessing or setting elements of arrays and lists.

Maven Central Repo:

<dependency>
    <groupId>com.github.pfmiles</groupId>
    <artifactId>min-velocity</artifactId>
    <version>1.0</version>
</dependency>

代碼樣例參見單元測試：

package com.github.pfmiles.minvelocity;

import java.io.StringReader;
import java.io.StringWriter;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import junit.framework.TestCase;

import com.github.pfmiles.org.apache.velocity.Template;

public class TemplateUtilTest extends TestCase {

    public void testRenderStringTemp() {
        String templateString = "#foreach($i in $list)\n$i\n#end";
        Map<String, Object> ctxPojo = new HashMap<String, Object>();
        List<String> list = new ArrayList<String>();
        list.add("one");
        list.add("two");
        list.add("three");
        ctxPojo.put("list", list);
        StringWriter out = new StringWriter();
        TemplateUtil.renderString(templateString, ctxPojo, out);
        // System.out.println(out.toString());
        assertTrue("one\ntwo\nthree\n".equals(out.toString()));
    }

    public void testRenderTemplate() {
        Template temp = TemplateUtil.parseStringTemplate("#foreach($i in $list)\n$i\n#end");
        Map<String, Object> ctxPojo = new HashMap<String, Object>();
        List<String> list = new ArrayList<String>();
        list.add("one");
        list.add("two");
        list.add("three");
        ctxPojo.put("list", list);
        StringWriter out = new StringWriter();
        TemplateUtil.renderTemplate(temp, ctxPojo, out);
        // System.out.println(out.toString());
        assertTrue("one\ntwo\nthree\n".equals(out.toString()));
    }

    public void testRefRendering() {
        Template temp = TemplateUtil.parseStringTemplate("hello $ref world");
        Map<String, Object> ctxPojo = new HashMap<String, Object>();
        StringReader stream = new StringReader("1234567890");
        ctxPojo.put("ref", stream);
        StringWriter writer = new StringWriter();
        TemplateUtil.renderTemplate(temp, ctxPojo, writer);
        assertTrue("hello 1234567890 world".equals(writer.toString()));
    }
}