[FreeMarker] Built-ins for strings

원문 : http://freemarker.sourceforge.net/docs/ref_builtins_string.html

• substring

FreeMarker 2.3.7 부터 지원

exp?substring(from, toExclusive) 또는 exp?substring(from) 의 형태로 사용

string의 substring. from 은 첫 문자의 인덱스입니다. from 은 0 이상이고, toExclusive 보다 작거나 같아야 합니다. toExclusive 는 부분 문자열의 다음 문자의 인덱스입니다. toExclusive 는 0 이상이고, 문자열 길이보다 작거나 같아야 합니다. toExclusive 를 생략하면 문자열의 길이로 설정됩니다. 정수가 아닌 숫자를 from 이나 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

 

• cap_first

첫 번째 word 의 첫 문자가 대문자인 문자열. word 의 정확한 의미는 word_list built-in 에서 볼 수 있습니다.

예

${"  green mouse"?cap_first}

${"GreEN mouse"?cap_first}

${"- green mouse"?cap_first}

결과

  Green mouse

GreEN mouse

- green mouse

• upcap_first

cap_first 의 반대. 첫 word 의 첫 문자가 소문자인 문자열.

• capitalize

모든 word의 첫 문자가 대문자인 문자열. word 의 정확한 의미는 word_list built-in 에서 볼 수 있습니다.

예

${"  green  mouse"?capitalize}

${"GreEN mouse"?capitalize}  

결과

  Green Mouse

Green Mouse

• chop_linebreak

끝에 line_break 가 없는 문자열.

• date, time, datetime

date 값으로 변환된 문자열. 형식에 대한 파라미터를 명시하는 것을 추천합니다.

예

<#assign test1 = "10/25/1995"?date("MM/dd/yyyy")>

<#assign test2 = "15:05:30"?time("HH:mm:ss")>

<#assign test3 = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")>

${test1}

${test2}

${test3}

결과

Oct 25, 1995

3:05:30 PM

Oct 25, 1995 3:05:00 PM

date 가 date_format, time_format, datetime_format 설정에 따라 변환되었다는 것을 유의하십시오. (date 를 string 으로 변환하는 것에 대한 자세한 정보는 string built-in for dates, date interpolations 에서 볼 수 있습니다.) string 을 date 로 변환할 때 사용한 형식은 중요하지 않습니다.

기본 date/time/datetime 형식이 무엇일지 알고 있다면 형식 파라미터를 사용할 필요가 없습니다.

<#assign test1 = "Oct 25, 1995"?date>

<#assign test2 = "3:05:30 PM"?time>

<#assign test3 = "Oct 25, 1995 03:05:00 PM"?datetime>

${test1}

${test2}

${test3}  

• ends_with

문자열이 특정 문자열로 끝나면 true 를 반환합니다. 예를 들어 "redhead"?ends_with("head")는 boolean true 를 반환합니다. "head"?ends_with("head") 역시 true 를 반환합니다.

• html

html 문자열. 즉, < 는 &lt; 로, > 는 &gt; 로, & 는 &amp; 로, " 는 &quot; 로 치환된 문자열.

안전하게 속성 값을 삽입하고자 한다면, HTML 에서 속성 값을 큰 따옴표로 둘러싸야 한다는 것에 유의하십시오.

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

일반적으로 많은 타이핑을 없애고, escape directive 를 사용함으로써 발생할 수 있는 실수의 가능성을 줄이기 위해, HTML 에서 모든 것에 이  built-in 을 사용하고 싶을 것입니다.

• groups

matches built-in 의 결과에만 사용됩니다.

• index_of

특정 문자열이 처음 나타나는 인덱스를 반환합니다. 예를 들어, "abcabc"?index_of("bc") 는 1을 반환합니다. (첫 문자의 인덱스가 0 입을 잊지 마십시오.) 검색을 시작할 인덱스를 지정할 수도 있습니다. "abcabc"?index_of("bc", 2) 는 4를 반환합니다. 두 번째 파라미터의 숫자는 제한이 없습니다. 두 번째 파라미터가 0 보다 작으면, 두 번째 파라미터가 0일 때와 같은 결과를 반환합니다. 두 번째 파라미터가 문자열의 길이보다 크면, 두 번째 파라미터가 문자열의 길이일 때와 같은 결과를 반환합니다. 파라미터가 소수면, 내림한 정수를 사용하여 결과를 반환합니다.

문자열에 첫 번째 파라미터가 존재하지 않으면 -1 을 반환합니다.

• j_string

Java 언어의 문자열 escaping 규칙에 따라 문자열을 수정합니다. 게다가 Java 언어에 해당하는 escape sequence 가 없는 모든 문자(UCS code point 0x20) 는 UNICODE escape (\uXXXX) 으로 변경됩니다..

예

<#assign beanName = 'The "foo" bean.'>

String BEAN_NAME = "${beanName?j_string}";

결과

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

• js_string

JavaScript 언어 문자열 escaping 규칙에 따라 문자열을 변경합니다. 큰 따옴표(") 와 작은 따옴표(') 가 모두 변경됩니다. FreeMarker 2.3.1 부터 > 는 \> 로 치환됩니다. 게다가 JavaScript 에 escape sequence 가 없는 모든 문자 (UCS code point 0x20) 은 16진수 escape (\xXX) 로 치환됩니다. (물론, JavaScript 언어 문자열 syntax 에 따라 백슬래쉬(\) 도 변경되고, line-feed 는 \n 으로 치환됩니다. 등)

예

<#assign user = "Big Joe's \"right hand\"">

<script>

  alert("Welcome ${user?js_string}!");

</script>

결과

<script>

  alert("Welcome Big Joe\'s \"right hand\"!");

</script>

• last_index_of

문자열의 끝에서부터 검색했을 때, 특정 문자열의 인덱스를 반환합니다. 예를 들어, "abcabc"?last_index_of("ab") 는 3을 반환합니다. 검색을 시작할 인덱스를 지정할 수도 있습니다. 예를 들어, "abcabc"?last_index_of("ab", 2) 는 0을 반환합니다. ...

• length

문자열의 문자 개수

• lower_case

소문자로 이루어진 문자열

• left_pad

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]

파라미터가 2 개일 때, 첫 번째 파라미터는 앞에서 언급한 파라미터와 같은 역할을 합니다. 두 번째 파라미터는 문자열의 앞에 삽입할 문자 입니다.

예

[${""?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] 

두 번째 파라미터는 문자열이 될 수도 있습니다. 그러면 문자열인 파라미터가 반복하여 삽입됩니다.

예

[${""?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]

두 번째 파라미터는 반드시 길이가 1 이상인 문자열이어야 합니다.

• right_pad

FreeMarker 2.3.1 부터 지원됩니다.

이 것은 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]

• contains

FreeMarker 2.3.1 부터 지원됩니다.

파라미터가 문자열에 있으면 true 를 리턴합니다.

예

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

결과

It contains "ice"

• matches

"power user" built-in 입니다. regular expression(정규식) 을 모르면 무시해 주세요.

FreeMarker 2.3.1 부터 지원됩니다.

Java 2 플랫폼 1.4 이상의 버전을 사용할 때만 동작합니다.

이 built-in 은 문자열이 패턴에 해당하는지 판단합니다. 그리고 해당하는 부분 문자열의 리스트를 반환합니다. 반환되는 값은 multi-type 값입니다.

Boolean: 문자열이 패턴과 정확하게 일치하면, true. 아니면, false. 예를 들어, "fooo?matches('fo*') 는 true 지만, "fooo bar"?matches('fo*') 는 false 입니다.

예

<#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 (괄호) 를 포함하면, groups built-in 으로 접근할 수 있습니다.

<#assign res = "aa/rx; ab/r;"?matches("(\\w[^/]+)/([^;]+);")>

<#list res as m>

- ${m} is ${m?groups[1]} per ${m?groups[2]}

</#list>  

결과

- aa/rx; is aa per rx

- ab/r; is ab per r

matches 는 생략 가능한 두 번째 파라미터 flags 를 허용합니다. 항상 정규식을 사용하기 때문에 flag r 은 지원되지 않는다는 것을 유의하십시오.

• number

숫자로 변환된 문자열. number 는 FTL 에서 직접 숫자를 명시했을 때와 같은 형식이어야 합니다. 즉, 숫자들 사이에 . 이 있는 locale independent form 이어야 한다는말입니다. 추가적으로 이 built-in 은 몇 가지 특정 표현을 인식합니다.(예: "1.23E6", "1.5e-8").

알려진 문제점: Java2 플랫폼 1.3 이전의 버전을 사용하면 이 built-in 은 숫자 앞의 + 와 과학적인 표현을 인식하지 못합니다.

• replace

문자열의 모든 특정 부분 문자열을 다른 문자열로 치환합니다. 단어를 다루지는 않습니다.

예

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

결과

this is a bulldozer abulldozerus

치환은 왼쪽에서 오른쪽으로 진행됩니다.

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

결과

Xaa 

첫 번째 파라미터가 길이가 0인 문자열이면, 문자와 문자 사이에 두 번째 파라미터가 삽입됩니다. 예를 들어, "foo"?replace("", "|") 는 "|f|o|o|" 입니다.

replace 는 생략가능한 세 번째 파라미터인 flags parameter 를 허용합니다.

• rtf

Rich text(RTF text) 인 문자열. 즉, \ 가 \\ 로 치환되고, { 가 \{ 로 치환되고, } 가 \} 로 치환되는 문자열.

• url

FreeMarker 2.3.1 부터 지원됩니다.

URL escaping 을 거친 문자열. 모든 US-ASCII 가 아닌 문자와 URL 예약어가 %xx 로 치환되는 것을 의미합니다.

예

<#assign x = 'a/b c'>

${x?url}

결과(US-ASCII compatible charset 을 사용했다고 가정)

a%2Fb%20c

Note that it escapes all reserved URL characters (/, =, &, ...etc), so this encoding can be used for encoding query parameter values, for example:

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

Note

Above no HTML encoding (?htm) was needed, because URL escaping escapes all reserved HTML characters anyway. But watch: always quote the attribute value, and always with normal quotation mark ("), never with apostrophe quotation mark ('), because apostrophe quotation mark is not escaped by the URL escaping.

To do URL escaping a charset must be chosen that will be used for calculating the escaped parts (%XX). If you are HTML page author and you don't really understand this, don't worry: the programmers should configure FreeMarker so that it uses the proper charset by default (programmers: see more below...). If you are a more technical minded user, then you may want to know that the charset used is specified by the url_escaping_charset setting, that can be set in template execution time (or, preferably, earlier by the programmers). For example:

	<#-- 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>

Furthermore, you can explicitly specify a charset for a single URL escaping as the parameter to the built-in:

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

If the url built-in has no parameter, then it will use the charset specified as the value of the url_escaping_charset setting. This setting should be set by the software that encloses FreeMarker (e.g. a Web application framework), because it is not set (null) by default. If it is not set, then FreeMarker falls back using the value of the output_encoding setting, which is also not set by default, so it is again the task of the enclosing software. If the output_encoding setting is not set either, then the parameterless url built-in can't be executed, and it will cause execution time error. Of course, the url built-in with parameter always works.

It's possible to set url_escaping_charset in the template with the setting directive, but it is bad practice, at least in true MVC applications. The output_encoding setting can't be set with the setting directive, so that's surely the task of the enclosing software. You may find more information regarding this here...

• split

한 문자열을 여러 문자열로 나눌 때 사용됩니다.

예

<#list "someMOOtestMOOtext"?split("MOO") as x>

- ${x}

</#list>

결과

- some

- test

- text

모든 분리자가 새로운 아이템 전에 사용된다고 가정하고 있다는 점에 유의하십시오.

<#list "some,,test,text,"?split(",") as x>

- "${x}"

</#list>

결과

- "some"

- ""

- "test"

- "text"

- ""

• starts_with

특정 문자열로 시작하면 true 를 반환합니다. 예를 들어, "redhead"?starts_with("red") 는 boolean true 를 반환합니다. "red"?starts_with("red") 도 true 를 반환합니다.

• string(when used with a string value)
  

아무 일도 하지 않고 현재의 문자열을 반환합니다. 예외는 값이 여러 가지 형태일 때 결과 값이 단순한 문자열이 된다는 것입니다. multi-typing 의 artifact 를 방지하기 위해 활용될 수 있습니다.

• trim

처음과 끝에 공백이 없는 문자열.

예

(${"  green mouse  "?trim})

결과

(green mouse)

• upper_case

대문자로만 이루어진 문자열. 예를 들어, "GrEen MoUsE" 는 "GREEN MOUSE" 가 됩니다.

• word_list

문자열의 모든 word 의 리스트. word 의 순서는 문자열에 나타나는 순서입니다. word 는 white-space 가 아닌 모든 문자의 연속입니다.

예

<#assign words = "   a bcd, .   1-2-3"?word_list>

<#list words as word>[${word}]</#list>

결과

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

• xhtml

XHTML 텍스트인 문자열. 즉, < 는 &lt; 로, < 는 &gt; 로, & 는 &amp; 로, " 는  &quot; 로, ' 는 &#39; 로, ' 는 &apos; 로 치환된 문자열.

이  built-in 과 xml built-in 의 차이는 xhtml built-in 은 ' 을 &apos; 대신  &#39 ;  로 치환하여 사용한다. 왜냐하면 오래된 몇 몇 브라우저는 &apos; 를 바르게 처리하지 못하기 때문이다.

• xml

XML 텍스트인 문자열. 즉, < 는 &lt; 로, < 는 &gt; 로, & 는 &amp; 로, " 는  &quot; 로, ' 는 &apos; 로, ' 는 &apos; 로 치환된 문자열.

• Common flags