FreeMarker字符串內建函數

這些內建函數做用於表達式左側的字符串值。 若是左側值是數字或日期/時間/日期-時間或布爾類型(從 2.3.20 版本開始)， 根據當前的number-, date/time/date-time- 和 boolean-format設置， 那麼它會自動被轉成字符串值(當使用${...} 插入這些值時，應用的都是同樣的格式程序)。

boolean

字符串轉爲布爾值。字符串必須是 true 或 false (大小寫敏感！)，或者必須是由 boolean_format 設置的特定格式。

若是字符串不是適當的格式，那麼當訪問該內建函數時， 就會發成錯誤終止模板處理。

cap_first

字符串中的首單詞的首字母大寫。 關於"單詞"的準確意義，能夠參考 word_list 內建函數。 例如：

${"  green mouse"?cap_first}
${"GreEN mouse"?cap_first}
${"- green mouse"?cap_first}

將會輸出：

Green mouse
GreEN mouse
- green mouse

In the case of "- green mouse", the first word is the -.

capitalize

字符串中全部單詞的首字母大寫。 關於"單詞"的準確意義，能夠參考 word_list 內建函數。例如：

${"  green  mouse"?capitalize}
${"GreEN mouse"?capitalize}

將會輸出：

Green Mouse
Green Mouse

chop_linebreak

在末尾沒有 換行符 的字符串， 那麼能夠換行，不然不改變字符串。

contains

Note:

這個內建函數從 FreeMarker 2.3.1 版本開始可用。 在2.3版本中是沒有的。

若是函數中的參數指定的子串出如今源字符串中， 那麼返回true。好比：

<#if "piceous"?contains("ice")>It contains "ice"</#if>

將會輸出

It contains "ice"

date, time, datetime

字符串轉換成日期值，時間或日期-時間值。須要一個由 date_format， time_format 和 datetime_format 設置指定的格式。 若是字符串不是適當的格式，那麼當訪問該內建函數時， 就會發生錯誤停止模板的處理。

<#-- The date_format, time_format and datetime_format settings must match this format! -->
<#assign someDate = "Oct 25, 1995"?date>
<#assign someTime = "3:05:30 PM"?time>
<#assign someDatetime = "Oct 25, 1995 03:05:00 PM"?datetime>

<#-- Changing the setting value changes the expected format: -->
<#setting datetime_format="iso">
<#assign someDatetime = "1995-10-25T15:05"?datetime>

也能夠指定明確的格式，好比 ?datetime.format 或 ?datetime["format"] (因爲歷史緣由，也能夠是 ?datetime("format"))， 它們與 ?date 和 ?time是相同的。 對於格式化值的語法和意義，能夠參考 date_format, time_format 和 datetime_format 設置 的可能的值。 好比：

<#-- Parsing XML Schema xs:date, xs:time and xs:dateTime values: -->
<#assign someDate = "1995-10-25"?date.xs>
<#assign someTime = "15:05:30"?time.xs>
<#assign someDatetime = "1995-10-25T15:05:00"?datetime.xs>

<#-- Parsing ISO 8601 (both extended and basic formats): -->
<#assign someDatetime = "1995-10-25T15:05"?datetime.iso>
<#assign someDatetime = "19951025T1505"?datetime.iso>

<#-- Parsing with SimpleDateFormat patterns: -->
<#assign someDate = "10/25/1995"?date("MM/dd/yyyy")>
<#assign someTime = "15:05:30"?time("HH:mm:ss")>
<#assign someDatetime = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")>

避免誤解，左側值無需是字符串文本。好比，當從XML結點 (此處的全部值都是未被解析的字符串)讀取數據，那麼就須要這樣來作order.confirmDate?date.xs，將字符串轉化成真實的日期。

固然，格式也能夠是一個變量，好比： "..."?datetime[myFormat]。

ends_with

返回是否這個字符串以參數中指定的子串結尾。 好比 "ahead"?ends_with("head") 返回布爾值 true。"head"?ends_with("head") 也返回 true。

ensure_ends_with

Note:

該內建函數從 FreeMarker 2.3.21 版本開始可用

若是字符串沒有以第一個參數指定的子串結尾， 那麼就會將它加到字符串後面，不然返回原字符串。好比， "foo"?ensure_ends_with("/") 和 "foo/"?ensure_ends_with("/") 返回 "foo/"。

ensure_starts_with

Note:

該內建函數從 FreeMarker 2.3.21 版本開始可用

若是字符串沒有以第一個參數指定的子串開頭， 那麼就會將它加到字符串開頭，不然返回原字符串。好比， "foo"?ensure_starts_with("/") 和 "/foo"?ensure_starts_with("/") 返回 "/foo"。

若是指定兩個參數，那麼第一個參數就被解釋成Java正則表達式， 若是它不匹配字符串的開頭，那麼第二個參數指定的字符串就會添加到字符串開頭。 好比 someURL?ensure_starts_with("[a-zA-Z]+://", "http://") 就會檢查若是字符串是否以 "[a-zA-Z]+://" 開頭 (請注意，不須要 ^)，若是不是的話，就添加 "http://"。

該方法也接受第三個標誌位參數。由於調用兩個參數暗指 "r"(也就是正則表達式模式)，那麼就須要第三個參數了。 值得注意的一點是當不須要第一參數被解釋成正則表達式，而只是普通文本， 可是又想讓比較是大小寫敏感的，那麼此時就須要使用 "i" 做爲第三個參數。

groups

這個函數只做用於內建函數 matches 的結果。

html

字符串按照HTML標記輸出。也就是說，下面字符串將會被替代：

• < 替換爲 <
• > 替換爲 >
• & 替換爲 &
• " 替換爲 "
• 若是程序員設置了FreeMarker(將 incompatible_improvements 設置爲 2.3.20 或更高；)，那麼 ' 被替換爲'。

請注意，若是想安全地插入一個屬性， 必須在HTML模板中使用引號標記(是 "，而不是 ')爲屬性值加引號：

<input type=text name=user value="${user?html}">

請注意，在HTML頁面中，一般想對全部插值使用這個內建函數。 因此可使用 escape 指令 來節約不少輸入，減小偶然錯誤的機會。

index_of

返回第一次字符串中出現子串時的索引位置。 例如 "abcabc"?index_of("bc") 將會返回1 (不要忘了第一個字符的索引是0)。並且，你能夠指定開始搜索的索引位置： "abcabc"?index_of("bc", 2) 將會返回4。 這對第二個參數的數值沒有限制：若是它是負數，那就和是0是相同效果了， 若是它比字符串的長度還大，那麼就和它是字符串長度那個數值是一個效果。 小數會被切成整數。

若是第一個參數做爲子串沒有在該字符串中出現時 (若是你使用了第二個參數，那麼就從給定的序列開始)，那麼就返回-1。

j_string

根據Java語言字符串轉義規則來轉義字符串， 因此它很安全的將值插入到字符串類型中。要注意它 不會 在被插入的值的兩側添加引號； 你須要在字符串值 內部 來使用。

全部 UCS 編碼下指向0x20的字符會被轉義。 當它們在Java語言中(好比\n，\t等) 沒有專門的轉義序列時，將會被用UNICODE進行轉義替換 (\uXXXX)。

例如：

<#assign beanName = 'The "foo" bean.'>
String BEAN_NAME = "${beanName?j_string}";

將會輸出：

String BEAN_NAME = "The \"foo\" bean.";

js_string

根據JavaScript語言字符串轉義規則來轉義字符串， 因此它很安全的將值插入到字符串類型中。要注意， 它不會在被插入的值兩側添加引號； 你須要在字符串值 內部 來使用。

引號(")和單引號(')要被轉義。 從 FreeMarker 2.3.1 開始，也要將 > 轉義爲 \>(爲了不 </script>)。

全部在 UCS 編碼下指向0x20的字符將會被轉義。 當它們在JavaScript中沒有專用的轉義序列時 (好比 \n，\t 等)， 它們會被UNICODE字符代替(\uXXXX)。

例如：

<#assign user = "Big Joe's \"right hand\"">
<script>
  alert("Welcome ${user?js_string}!");
</script>

將會輸出：

<script>
  alert("Welcome Big Joe\'s \"right hand\"!");
</script>

json_string

根據JSON語言的字符串規則來轉義字符串， 因此在字符串中插入值是安全的。 要注意它 不會 在被插入的值兩側添加引號； 你須要在字符串值 內部 來使用。

這不會轉義 ' 字符，由於JSON字符串必須使用 " 來括起來。它會在 < 以後直接出現的 /(斜槓)字符轉義爲 \/， 來避免 </script> 等。 它也會在 ]] 以後轉義 > 字符爲 \u003E，來避免退出XML的 CDATA 段。

全部在 UCS 編碼下指向0x20的字符會被轉義。 當在JSON中沒有專用的轉義序列時 (好比 \n，\t 等)， 它們會被UNICODE字符代替(\uXXXX)。

keep_after

Note:

該內建函數從 FreeMarker 2.3.21 版本開始可用。

移除字符串中的一部份內容，該部分是給定子串第一次出現以前的部分。 好比：

${"abcdefgh"?keep_after("de")}

將會輸出

fgh

若是參數字符串沒有找到，它會返回空串。若是參數是長度爲0的字符串， 它會返回源字符串，不會改變。

該方法接受可選的 標誌位參數，做爲它的第二個參數：

${"foo : bar"?keep_after(r"\s*:\s*", "r")}

將會輸出

bar

keep_after_last

Note:

該內建函數從 FreeMarker 2.3.22 版本開始可用。

和 keep_after 相同， 可是它會保留參數最後一次出現後的部分，而不是第一次。好比：

${"foo.bar.txt"?keep_after_last(".")}

將會輸出

txt

若使用 keep_after 則會獲得 bar.txt。

keep_before

Note:

該內建函數從 FreeMarker 2.3.21 版本開始可用。

移除字符串的一部分，該部分是從給定子串開始的部分。 好比：

${"abcdef"?keep_before("de")}

將會輸出

abc

若是參數字符串沒有找到，它會返回源字符串，不會改變。 若是參數是長度爲0的字符串，它會返回空串。

該方法接受可選的 標誌位參數，做爲它的第二個參數：

${"foo : bar"?keep_before(r"\s*:\s*", "r")}

將會輸出

foo

keep_before_last

Note:

該內建函數從 FreeMarker 2.3.22 版本開始可用。

和 keep_before 相同， 可是保留參數最後一次出現以前的部分，而不是第一次出現以前。好比：

${"foo.bar.txt"?keep_after_last(".")}

將會輸出

foo.bar

若使用 keep_before 則會獲得 foo。

last_index_of

返回最後一次(最右邊)字符串中出現子串時的索引位置。 它返回子串第一個(最左邊)字符所在位置的索引。例如： "abcabc"?last_index_of("ab")：將會返回3。 並且能夠指定開始搜索的索引。例如， "abcabc"?last_index_of("ab", 2)，將會返回0。 要注意第二個參數暗示了子串開始的最大索引。對第二個參數的數值沒有限制： 若是它是負數，那麼效果和是零的同樣，若是它比字符串的長度還大， 那麼就和它是字符串長度那個數值是一個效果。小數會被切成整數。

若是第一個參數做爲子串沒有在該字符串中出現時 (若是你使用了第二個參數，那麼就從給定的序列開始)，那麼就返回-1。

left_pad

Note:

該內建函數從 FreeMarker 2.3.1 版本開始可用。

若是它僅僅用1個參數，那麼它將在字符串的開始插入空白， 直到整個串的長度達到參數指定的值。 若是字符串的長度達到指定數值或者比指定的長度還長， 那麼就什麼都不作了。好比這樣：

[${""?left_pad(5)}]
[${"a"?left_pad(5)}]
[${"ab"?left_pad(5)}]
[${"abc"?left_pad(5)}]
[${"abcd"?left_pad(5)}]
[${"abcde"?left_pad(5)}]
[${"abcdef"?left_pad(5)}]
[${"abcdefg"?left_pad(5)}]
[${"abcdefgh"?left_pad(5)}]

將會輸出：

[     ]
[    a]
[   ab]
[  abc]
[ abcd]
[abcde]
[abcdef]
[abcdefg]
[abcdefgh]

若是使用了兩個參數，那麼第一個參數表示的含義和你使用一個參數時的相同， 第二個參數指定用什麼東西來代替空白字符。好比：

[${""?left_pad(5, "-")}]
[${"a"?left_pad(5, "-")}]
[${"ab"?left_pad(5, "-")}]
[${"abc"?left_pad(5, "-")}]
[${"abcd"?left_pad(5, "-")}]
[${"abcde"?left_pad(5, "-")}]

將會輸出：

[-----]
[----a]
[---ab]
[--abc]
[-abcd]
[abcde]

第二個參數也能夠是個長度比1大的字符串。 那麼這個字符串會週期性的插入，好比：

[${""?left_pad(8, ".oO")}]
[${"a"?left_pad(8, ".oO")}]
[${"ab"?left_pad(8, ".oO")}]
[${"abc"?left_pad(8, ".oO")}]
[${"abcd"?left_pad(8, ".oO")}]

將會輸出：

[.oO.oO.o]
[.oO.oO.a]
[.oO.oOab]
[.oO.oabc]
[.oO.abcd]

第二個參數必須是個字符串值，並且至少有一個字符。

length

字符串中字符的數量。

lower_case

字符串的小寫形式。好比 "GrEeN MoUsE"?lower_case 將會是 "green mouse"。

matches

這是一個"超級用戶"函數。若是不懂 正則表達式，就忽略它吧。

該內建函數決定了字符串是否精確匹配模式。並且，它會返回匹配子串的列表。 返回值是多類型值：

• 布爾值：若是字符串總體匹配了模式，就是 true， 不然就是 false。好比："fooo"?matches('fo*') 就是 true，可是 "fooo bar"?matches('fo*') 是 false。

• 序列：字符串匹配的子串的列表。頗有多是長度爲0的序列。

好比：

<#if "fxo"?matches("f.?o")>Matches.<#else>Does not match.</#if>

<#assign res = "foo bar fyo"?matches("f.?o")>
<#if res>Matches.<#else>Does not match.</#if>
Matching sub-strings:
<#list res as m>
- ${m}
</#list>

將會輸出：

Matches.

Does not match.
Matching sub-strings:
- foo
- fyo

若是正則表達式包含分組(圓括號)，那麼可使用 groups 內建函數來訪問它們：

<#-- Entire input match -->
<#assign res = "John Doe"?matches(r"(\w+) (\w+)")>
<#if res> <#-- Must not try to access groups if there was no match! -->
  First name: ${res?groups[1]}
  Second name: ${res?groups[2]}
</#if>

<#-- Subtring matches -->
<#assign res = "aa/rx; ab/r;"?matches("(.+?)/*(.+?);")>
<#list res as m>
  - "${m}" is "${m?groups[1]}" per "${m?groups[2]}"
</#list>

將會輸出：

First name: John
  Second name: Doe

  - "aa/rx;" is "a" per "a/rx"
  - " ab/r;" is " " per "ab/r"

請注意，上面的 groups 對子串匹配和整個字符串匹配的結果都起做用。

matches 接受可選的第二參數， 標誌位。請注意， 它不支持標誌 f，也會忽略 r 標誌。

number

字符串轉化爲數字格式。這個數字必須是 "計算機語言" 格式。也就是說， 它必須是本地化獨立的形式，小數的分隔符就是一個點，沒有分組。

該內建函數識別FreeMarker模板語言使用的數字格式。此外， 它也識別科學記數法(好比 "1.23E6"，"1.5e-8") 從 FreeMarker 2.3.21 版本開始，它也識別全部XML Schema數字格式，好比 NaN，INF，-INF， 還有Java本地格式Infinity 和 -Infinity。

若是字符串不是適當的格式，當嘗試訪問該內建函數時就會發生錯誤， 並停止模板執行。

實際上，字符串是由當前 arithmetic_engine 的 toNumber 方法解析的，這是能夠配置的設置項。不過該方法應該和上面描述的行爲類似。

replace

在源字符串中，用另一個字符串來替換原字符串中出現它的部分。 它不處理詞的邊界。好比：

${"this is a car acarus"?replace("car", "bulldozer")}

將會輸出：

this is a bulldozer abulldozerus

替換是從左向右執行的。這就意味着：

${"aaaaa"?replace("aaa", "X")}

將會輸出：

Xaa

若是第一個參數是空字符串，那麼全部的空字符串將會被替換， 好比 "foo"?replace("","|")，就會獲得 "|f|o|o|"。

replace 接受可選的 標誌位參數，做爲它的第三參數。

right_pad

Note:

該內建函數從 FreeMarker 2.3.1 版本開始可用。 在2.3版本中是沒有的。

它和 left_pad 相同， 可是它從末尾開始插入字符而不是從開頭。

好比：

[${""?right_pad(5)}]
[${"a"?right_pad(5)}]
[${"ab"?right_pad(5)}]
[${"abc"?right_pad(5)}]
[${"abcd"?right_pad(5)}]
[${"abcde"?right_pad(5)}]
[${"abcdef"?right_pad(5)}]
[${"abcdefg"?right_pad(5)}]
[${"abcdefgh"?right_pad(5)}]

[${""?right_pad(8, ".oO")}]
[${"a"?right_pad(8, ".oO")}]
[${"ab"?right_pad(8, ".oO")}]
[${"abc"?right_pad(8, ".oO")}]
[${"abcd"?right_pad(8, ".oO")}]

將會輸出：

[     ]
[a    ]
[ab   ]
[abc  ]
[abcd ]
[abcde]
[abcdef]
[abcdefg]
[abcdefgh]

[.oO.oO.o]
[aoO.oO.o]
[abO.oO.o]
[abc.oO.o]
[abcdoO.o]

remove_beginning

Note:

該內建函數從 FreeMarker 2.3.21 版本開始可用。

從字符串的開頭移除參數中的子串，若是它不以參數中的子串開頭， 那麼就或者返回原字符串。好比：

${"abcdef"?remove_beginning("abc")}
${"foobar"?remove_beginning("abc")}

將會輸出：

def
foobar

remove_ending

Note:

該內建函數從 FreeMarker 2.3.21 版本開始可用。

從字符串的結尾移除參數中的子串，若是它不以參數中的子串結尾， 那麼就或者返回原字符串。好比：

${"abcdef"?remove_ending("def")}
${"foobar"?remove_ending("def")}

將會輸出：

abc
foobar

rtf

字符串做爲富文本(RTF 文本)，也就是說，下列字符串：

• \ 替換爲 \\

• { 替換爲 \{

• } 替換爲 \}

split

它被用來根據另一個字符串的出現將原字符串分割成字符串序列。 好比：

<#list "someMOOtestMOOtext"?split("MOO") as x>
- ${x}
</#list>

將會輸出：

- some
- test
- text

請注意，假設全部的分隔符都在新項以前出現 (除了使用 "r" 標誌 - 後面詳細介紹) 所以：

<#list "some,,test,text,"?split(",") as x>
- "${x}"
</#list>

將會輸出：

- "some"
- ""
- "test"
- "text"
- ""

split 接受可選的 標誌位參數， 做爲它的第二個參數。因爲歷史使用 r (正則表達式)標誌的差錯；它會從結果列表中移除空元素， 因此在最後示例中使用 ?split(",", "r")， "" 會從輸出中消失。

Note:

要檢查一個字符串是否以...結尾或者要附加它， 使用 ensure_ends_with 內建函數。

starts_with

若是字符串以指定的子字符串開頭，那麼返回true。 好比 "redirect"?starts_with("red") 返回布爾值 true，並且 "red"?starts_with("red") 也返回 true。

Note:

要檢查一個字符串是否以...開頭或者要在前面附加它， 使用 ensure_starts_with 內建函數。

string (當被用做是字符串值時)

什麼也不作，僅僅返回和其內容一致的字符串。例外的是， 若是值是一個多類型的值(好比同時有字符串和序列兩種)， 那麼結果就只是一個簡單的字符串，而不是多類型的值。 這能夠被用來防止人爲多輸入。

substring (已廢棄)

Note:

從 FreeMarker 2.3.21 版本開始，該內建函數被廢棄，由 字符串切分 替代，好比 str[from..<toExclusive]， str[from..], 和 str[from..*maxLength]。

若是處理XML那麼有一點警示：由於分割表達式做用於序列和字符串， 並且XML結點一般既是序列又是字符串，那麼相等的表達式是 someXmlNode?string[from..<toExclusive] 和 exp?string[from..]， 由於沒有 ?string 它會分割結點序列而不是結點的字符串值。

Note:

一些典型的字符串分割的用例已經由一些內建函數方便地實現： remove_beginning，remove_ending， keep_before， keep_after， keep_before_last，keep_after_last

概要： exp?substring(from, toExclusive)，也可使用 exp?substring(from) 調用。

字符串的子串 from 是第一個字符的索引。 它必須是數字，最小是0而且小於或等於 toExclusive， 不然就會發生錯誤而且停止模板處理。toExclusive 是子串最後一個字符以後的字符位置索引，換句話說，它比最後一個字符的索引大1。 它必須是一個數字，最小是0而且小於或等於字符串的長度， 不然就會發生錯誤而且停止模板處理。若是 toExclusive 被忽略了， 那麼默認就是字符串的長度。若是參數是數字但不是整數， 那麼只有數字中的整數部分會被使用。

例如：

- ${'abc'?substring(0)}
- ${'abc'?substring(1)}
- ${'abc'?substring(2)}
- ${'abc'?substring(3)}

- ${'abc'?substring(0, 0)}
- ${'abc'?substring(0, 1)}
- ${'abc'?substring(0, 2)}
- ${'abc'?substring(0, 3)}

- ${'abc'?substring(0, 1)}
- ${'abc'?substring(1, 2)}
- ${'abc'?substring(2, 3)}

將會輸出：

- abc
- bc
- c
-

-
- a
- ab
- abc

- a
- b
- c

trim

去掉字符串首尾的空格。例如：

(${"  green mouse  "?trim})

將會輸出：

(green mouse)

uncap_first

和 cap_first 相反。 字符串中全部單詞的首字母小寫。

upper_case

字符串的大寫形式。好比 "GrEeN MoUsE" 將會是 "GREEN MOUSE".

url

Note:

該內建函數從 FreeMarker 2.3.1 版本開始可用。 在2.3版本中是沒有的。

在URL以後的字符串進行轉義。這意味着， 全部非US-ASCII的字符和保留的URL字符將會被 %XX 形式轉義。例如：

<#assign x = 'a/b c'>
${x?url}

將會輸出(假設用來轉義的字符集是US-ASCII兼容的字符集)：

a%2Fb%20c

請注意，它會轉義 全部 保留的URL字符 (/， =， &，等...)， 因此編碼能夠被用來對查詢參數的值進行，好比：

<a href="foo.cgi?x=${x?url}&y=${y?url}">Click here...</a>

Note:

上面的沒有HTML編碼(?html)是須要的， 由於URL轉義全部保留的HTML編碼。可是要當心：一般引用的屬性值， 用普通引號(")包括，而不是單引號 (')，由於單引號是不被URL轉義的。

爲了進行URL轉義，必需要選擇 字符集，它被用來計算被轉義的部分 (%XX)。 若是你是HTML頁面設計者，並且你不懂這個，不要擔憂： 程序員應該配置 FreeMarker，則它默認使用恰當的字符集 (程序員應該多看看下面的內容...)。 若是你是一個比較熱衷於技術的人，那麼你也許想知道被 url_escaping_charset 設置的指定字符集， 它能夠在模板的執行時間設置(或者，更好的是，由程序員以前設置好)。例如：

<#--
  This will use the charset specified by the programmers
  before the template execution has started.
-->
<a href="foo.cgi?x=${x?url}">foo</a>

<#-- Use UTF-8 charset for URL escaping from now: -->
<#setting url_escaping_charset="UTF-8">

<#-- This will surely use UTF-8 charset -->
<a href="bar.cgi?x=${x?url}">bar</a>

此外，你能夠明確地指定一個爲單獨URL轉義的字符集，做爲內建函數的參數：

<a href="foo.cgi?x=${x?url('ISO-8895-2')}">foo</a>

若是內建函數 url 沒有參數， 那麼它會使用由 url_escaping_charset 設置的字符集。 這個設置應該被軟件設置，包括 FreeMarker(好比Web應用框架)， 由於它默認不會被設置(null)。 若是它沒有被設置，那麼 FreeMarker 退回使用 output_encoding 的設置，這個也會被默認設置，因此它也是又軟件設置的。 若是 output_encoding 也沒有被設置， 那麼沒有參數的內建函數 url 將不會被執行， 並且它會引發運行時錯誤。固然，有參數的 url 函數將會執行。

用 setting 指令在模板中設置 url_escaping_charset 是可能的。 至少在真實的MVC應用中，這是一個很差的實踐行爲。output_encoding 不能由 setting 指令來設置，因此它應該是軟件的工做。 

url_path

Note:

該內建函數從 FreeMarker 2.3.21 版本開始可用。

它和 url 內建函數 相同，只是它不轉義斜槓 (/)字符。這就是意味着用來轉義使用了斜槓(不是反斜槓！)的路徑 (好比操做系統或一些內容倉庫的路徑)，轉義以後它們能夠插入到URL中。 須要該轉義的經常使用緣由是文件夾名稱或文件名稱可能含有非US-ASCII字母 ("國家" 標準符號)。

Note:

和 the url 內建函數 類似，但願的URL轉義字符 (或者後退，輸出編碼)必需要在 FreeMarker的配置設置項中設置， 不然內建函數就會報錯。或者能夠指定字符集，好比 somePath?url_path('utf-8')。

word_list

包含字符串中全部單詞的序列，順序爲出如今字符串中的順序。 單詞是不間斷的字符序列，包含了任意字符，可是沒有 空白。例如：

<#assign words = "   a bcd, .   1-2-3"?word_list>
<#list words as word>[${word}]</#list>

將會輸出：

[a][bcd,][.][1-2-3]

xhtml

字符串做爲XHTML格式文本，下面這些：

• < 替換爲 <
• > 替換爲 >
• & 替換爲 &
• " 替換爲 "
• ' 替換爲 '

該內建函數和 xml 內建函數的惟一不一樣是 xhtml內建函數轉義 ' 爲 '，而不是 '， 由於一些老版本的瀏覽器不能正確解釋 '。

xml

字符串做爲XML格式文本，下面這些：

• < 替換爲 <
• > 替換爲 >
• & 替換爲 &
• " 替換爲 "
• ' 替換爲 '

通用標誌

不少字符串內建函數接受可選的字符串參數， 它們被稱爲"標誌"。在這個字符串中，每一個字母影響內建函數一個特定方面的行爲。 好比，字母 i 說明內建函數不該該區別相同字母的小寫和大寫變化。 標誌字符串中的字母順序是不重要的。

下面是字母(標誌)的完整列表：

• i：大小寫敏感： 不區別相同字母的小寫和大寫變化。

• f：只是第一個。也就是說， 替換/查找/等...，只是第一個出現的地方。

• r：查找的子串是 正則表達式。 FreeMarker 使用的正則表達式變量能夠在 http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html 中找到(請注意，一些模式規則特性的出現基於所使用的Java版本)。

• m：正則表達式的多行模式。在多行正則表達式 ^ 和 $ 僅僅匹配以後或以前， 各自匹配行終止符或字符串結尾。默認狀況下，這些表達式僅僅匹配完整字符串的開頭和結尾。 請注意，^ 和 $ 不匹配換行符字符自己。

• s：開啓正則表達式的dot-all模式 (和Perl的單行模式相同)。在dot-all模式下，表達式 . 匹配任意字符串，包含行終止符。 默認狀況下，該表達式不匹配行終止符。

• c： 容許正則表達式中的空白和註釋。

例如：

<#assign s = 'foo bAr baar'>
${s?replace('ba', 'XY')}
i: ${s?replace('ba', 'XY', 'i')}
if: ${s?replace('ba', 'XY', 'if')}
r: ${s?replace('ba*', 'XY', 'r')}
ri: ${s?replace('ba*', 'XY', 'ri')}
rif: ${s?replace('ba*', 'XY', 'rif')}

將會輸出：

foo bAr XYar
i: foo XYr XYar
if: foo XYr baar
r: foo XYAr XYr
ri: foo XYr XYr
rif: foo XYr baar

下表是支持使用這些通用標誌的內建函數：

內建函數	i (忽略大小寫)	r (正則表達式)	m (多行模式)	s (dot-all模式)	c (空白和註釋)	f (僅第一個)
replace	是	是	僅 r	僅 r	僅 r	是
split	是	是	僅 r	僅 r	僅 r	否
matches	是	忽略	是	是	是	否
keep_after	是	是	是	是	是	忽略
keep_after_last	是	是	是	是	是	忽略
keep_before	是	是	是	是	是	忽略
keep_before_last	是	是	是	是	是	忽略
ensure_starts_with	是	忽略	是	是	是	忽略