You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2017/03/15 21:19:23 UTC
[26/51] [partial] incubator-freemarker-site git commit: 2.3.26-voting
docs, removed nightly
http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/a4004324/builds/2.3.26-nightly/ref_builtins_string.html
----------------------------------------------------------------------
diff --git a/builds/2.3.26-nightly/ref_builtins_string.html b/builds/2.3.26-nightly/ref_builtins_string.html
deleted file mode 100644
index 6ebdd42..0000000
--- a/builds/2.3.26-nightly/ref_builtins_string.html
+++ /dev/null
@@ -1,2374 +0,0 @@
-<!doctype html>
-<!-- Generated by FreeMarker/Docgen from DocBook -->
-<html lang="en" class="page-type-section">
-<head prefix="og: http://ogp.me/ns#">
-<meta charset="utf-8">
-<title>Built-ins for strings - Apache FreeMarker Manual</title>
-<meta http-equiv="X-UA-Compatible" content="IE=edge">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-<meta name="format-detection" content="telephone=no">
-<meta property="og:site_name" content="Apache FreeMarker Manual">
-<meta property="og:title" content="Built-ins for strings">
-<meta property="og:locale" content="en_US">
-<meta property="og:url" content="http://freemarker.org/docs/ref_builtins_string.html">
-<link rel="canonical" href="http://freemarker.org/docs/ref_builtins_string.html">
-<link rel="icon" href="favicon.png" type="image/png">
-<link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono">
-<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1489402528979">
-<script>
-(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
-(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
-m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
-})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
-ga('create', 'UA-55420501-1', 'auto');
-ga('send', 'pageview');
-</script>
-</head>
-<body itemscope itemtype="https://schema.org/Code">
- <meta itemprop="url" content="http://freemarker.org/docs/">
- <meta itemprop="name" content="Apache FreeMarker Manual">
-
- <!--[if lte IE 9]>
- <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
- <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org" role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker">
-</a><ul class="tabs"><li><a href="http://freemarker.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="searc
h-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">Apache FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref.html"><span itemprop="name">Template Language Reference</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_builtins.html"><span itemprop="name">Built-in Reference</span></a></li><li class="step-3"
itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_builtins_string.html"><span itemprop="name">Built-ins for strings</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div> <div class="main-content site-width">
- <div class="content-wrapper">
- <div id="table-of-contents-wrapper" class="col-left">
- <script>var breadcrumb = ["Apache FreeMarker Manual","Template Language Reference","Built-in Reference","Built-ins for strings"];</script>
- <script src="toc.js?1489402528979"></script>
- <script src="docgen-resources/main.min.js?1489402528979"></script>
- </div>
-<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="ref_builtins_alphaidx.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_builtins_number.html"><span>Next</span></a></div><div class="title-wrapper">
-<h1 class="content-header header-section1" id="ref_builtins_string" itemprop="headline">Built-ins for strings</h1>
-</div></div><div class="page-menu">
-<div class="page-menu-title">Page Contents</div>
-<ul><li><a class="page-menu-link" href="#ref_builtin_boolean" data-menu-target="ref_builtin_boolean">boolean</a></li><li><a class="page-menu-link" href="#ref_builtin_cap_first" data-menu-target="ref_builtin_cap_first">cap_first</a></li><li><a class="page-menu-link" href="#ref_builtin_capitalize" data-menu-target="ref_builtin_capitalize">capitalize</a></li><li><a class="page-menu-link" href="#ref_builtin_chop_linebreak" data-menu-target="ref_builtin_chop_linebreak">chop_linebreak</a></li><li><a class="page-menu-link" href="#ref_builtin_contains" data-menu-target="ref_builtin_contains">contains</a></li><li><a class="page-menu-link" href="#ref_builtin_string_date" data-menu-target="ref_builtin_string_date">date, time, datetime</a></li><li><a class="page-menu-link" href="#ref_builtin_ends_with" data-menu-target="ref_builtin_ends_with">ends_with</a></li><li><a class="page-menu-link" href="#ref_builtin_ensure_ends_with" data-menu-target="ref_builtin_ensure_ends_with">ensure_ends_with</a><
/li><li><a class="page-menu-link" href="#ref_builtin_ensure_starts_with" data-menu-target="ref_builtin_ensure_starts_with">ensure_starts_with</a></li><li><a class="page-menu-link" href="#ref_builtin_esc" data-menu-target="ref_builtin_esc">esc</a></li><li><a class="page-menu-link" href="#ref_builtin_groups" data-menu-target="ref_builtin_groups">groups</a></li><li><a class="page-menu-link" href="#ref_builtin_html" data-menu-target="ref_builtin_html">html (deprecated)</a></li><li><a class="page-menu-link" href="#ref_builtin_index_of" data-menu-target="ref_builtin_index_of">index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_j_string" data-menu-target="ref_builtin_j_string">j_string</a></li><li><a class="page-menu-link" href="#ref_builtin_js_string" data-menu-target="ref_builtin_js_string">js_string</a></li><li><a class="page-menu-link" href="#ref_builtin_json_string" data-menu-target="ref_builtin_json_string">json_string</a></li><li><a class="page-menu-link" href="#ref_bu
iltin_keep_after" data-menu-target="ref_builtin_keep_after">keep_after</a></li><li><a class="page-menu-link" href="#ref_builtin_keep_after_last" data-menu-target="ref_builtin_keep_after_last">keep_after_last</a></li><li><a class="page-menu-link" href="#ref_builtin_keep_before" data-menu-target="ref_builtin_keep_before">keep_before</a></li><li><a class="page-menu-link" href="#ref_builtin_keep_before_last" data-menu-target="ref_builtin_keep_before_last">keep_before_last</a></li><li><a class="page-menu-link" href="#ref_builtin_last_index_of" data-menu-target="ref_builtin_last_index_of">last_index_of</a></li><li><a class="page-menu-link" href="#ref_builtin_left_pad" data-menu-target="ref_builtin_left_pad">left_pad</a></li><li><a class="page-menu-link" href="#ref_builtin_length" data-menu-target="ref_builtin_length">length</a></li><li><a class="page-menu-link" href="#ref_builtin_lower_case" data-menu-target="ref_builtin_lower_case">lower_case</a></li><li><a class="page-menu-link" href="#
ref_builtin_matches" data-menu-target="ref_builtin_matches">matches</a></li><li><a class="page-menu-link" href="#ref_builtin_no_esc" data-menu-target="ref_builtin_no_esc">no_esc</a></li><li><a class="page-menu-link" href="#ref_builtin_number" data-menu-target="ref_builtin_number">number</a></li><li><a class="page-menu-link" href="#ref_builtin_replace" data-menu-target="ref_builtin_replace">replace</a></li><li><a class="page-menu-link" href="#ref_builtin_right_pad" data-menu-target="ref_builtin_right_pad">right_pad</a></li><li><a class="page-menu-link" href="#ref_builtin_remove_beginning" data-menu-target="ref_builtin_remove_beginning">remove_beginning</a></li><li><a class="page-menu-link" href="#ref_builtin_remove_ending" data-menu-target="ref_builtin_remove_ending">remove_ending</a></li><li><a class="page-menu-link" href="#ref_builtin_rtf" data-menu-target="ref_builtin_rtf">rtf (deprecated)</a></li><li><a class="page-menu-link" href="#ref_builtin_split" data-menu-target="ref_builti
n_split">split</a></li><li><a class="page-menu-link" href="#ref_builtin_starts_with" data-menu-target="ref_builtin_starts_with">starts_with</a></li><li><a class="page-menu-link" href="#ref_builtin_string_for_string" data-menu-target="ref_builtin_string_for_string">string (when used with a string value)</a></li><li><a class="page-menu-link" href="#ref_builtin_substring" data-menu-target="ref_builtin_substring">substring (deprecated)</a></li><li><a class="page-menu-link" href="#ref_builtin_trim" data-menu-target="ref_builtin_trim">trim</a></li><li><a class="page-menu-link" href="#ref_builtin_uncap_first" data-menu-target="ref_builtin_uncap_first">uncap_first</a></li><li><a class="page-menu-link" href="#ref_builtin_upper_case" data-menu-target="ref_builtin_upper_case">upper_case</a></li><li><a class="page-menu-link" href="#ref_builtin_url" data-menu-target="ref_builtin_url">url</a></li><li><a class="page-menu-link" href="#ref_builtin_url_path" data-menu-target="ref_builtin_url_path">ur
l_path</a></li><li><a class="page-menu-link" href="#ref_builtin_word_list" data-menu-target="ref_builtin_word_list">word_list</a></li><li><a class="page-menu-link" href="#ref_builtin_xhtml" data-menu-target="ref_builtin_xhtml">xhtml (deprecated)</a></li><li><a class="page-menu-link" href="#ref_builtin_xml" data-menu-target="ref_builtin_xml">xml (deprecated)</a></li><li><a class="page-menu-link" href="#ref_builtin_string_flags" data-menu-target="ref_builtin_string_flags">Common flags</a></li></ul> </div><p>These built-ins act on a string left-value. However, if the
- left-value is number or date/time/date-time or boolean (since 2.3.20),
- it will automatically converted to string according the current
- number-, date/time/date-time- and boolean-format settings (which are
- the same formatters that are applied when inserting such values with
- <code class="inline-code">${<em class="code-color">...</em>}</code>).</p>
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_boolean">boolean</h2>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <p>The string converted to boolean value. The string must be
- <code class="inline-code">true</code> or <code class="inline-code">false</code> (case
- sensitive!), or must be in the format specified by the
- <code class="inline-code">boolean_format</code> setting.</p>
-
- <p>If the string is not in the appropriate format, an error will
- abort template processing when you try to access this
- built-in.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_cap_first">cap_first</h2>
-
-
-
-
- <p>The string with the very first word of the string capitalized.
- For the precise meaning of "word" see the <a href="#ref_builtin_word_list">word_list built-in</a>.
- Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${" green mouse"?cap_first}
-${"GreEN mouse"?cap_first}
-${"- green mouse"?cap_first}</pre></div>
-
- <p>The output:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output"> Green mouse
-GreEN mouse
-- green mouse</pre></div>
-
- <p>In the case of <code class="inline-code">"- green mouse"</code>, the first
- word is the <code class="inline-code">-</code>.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_capitalize">capitalize</h2>
-
-
-
-
- <p>The string with all words capitalized. For the precise meaning
- of "word" see the <a href="#ref_builtin_word_list">word_list built-in</a>.
- Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${" green mouse"?capitalize}
-${"GreEN mouse"?capitalize}</pre></div>
-
- <p>The output:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output"> Green Mouse
-Green Mouse</pre></div>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_chop_linebreak">chop_linebreak</h2>
-
-
-
-
- <p>The string without the <a href="gloss.html#gloss.lineBreak">line-break</a> at its very end if there
- was a line-break, otherwise the unchanged string.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_contains">contains</h2>
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.1. It
- doesn't exist in 2.3.</p>
- </div>
-
-
- <p>Returns if the substring specified as the parameter to this
- built-in occurrs in the string. For example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#if "piceous"?contains("ice")>It contains "ice"</#if></pre></div>
-
- <p>This will output:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">It contains "ice"</pre></div>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_string_date">date, time, datetime</h2>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <p>The string value converted to a date, time, or date-time
- value. It will expect the format specified by the <a href="ref_directive_setting.html#topic.dateTimeFormatSettings"><code>date_format</code>,
- <code>time_format</code> and
- <code>datetime_format</code> settings</a>. If the string is
- not in the appropriate format, an error will abort template
- processing when you try to access this built-in.</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#-- 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></pre></div>
-
- <p>You can also specify the format explicitly like
- <code class="inline-code">?datetime.<em class="code-color">format</em></code> (and
- hence also as
- <code class="inline-code">?datetime["<em class="code-color">format</em>"]</code>)
- or
- <code class="inline-code">?datetime("<em class="code-color">format</em>")</code>;
- these three forms do the same. The format can be specified similarly
- with <code class="inline-code">?date</code> and <code class="inline-code">?time</code> too. For
- the syntax and meaning of format values see the possible values of
- the <a href="ref_directive_setting.html#topic.dateTimeFormatSettings"><code>date_format</code>,
- <code>time_format</code> and
- <code>datetime_format</code> settings</a>. Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#-- 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")>
-
-<#-- Parsing with custom date formats: -->
-<#assign someDatetime = "October/25/1995 03:05 PM"?datetime.@worklog></pre></div>
-
- <p>To prevent misunderstandings, the left-hand value need not be
- a string literal. For example, when you read data from XML DOM (from
- where all values come as unparsed strings), you may do things like
- <code class="inline-code">order.confirmDate?date.xs</code> to convert the string
- value to a real date.</p>
-
- <p>Of course, the format also can be a variable, like in
- <code class="inline-code">"<em class="code-color">...</em>"?datetime(myFormat)</code>.</p>
-
- <p>Note that since 2.3.24, these built-ins can also be called
- with 0 arguments, like <code class="inline-code">?date()</code>. It's almost the
- same as just writing <code class="inline-code">?date</code>. The difference is
- highly technical and rarely matters: <code class="inline-code">?date()</code> and
- such returns exactly the same Java object that the date parser
- (<code class="inline-code">freemarker.core.TemplateDateFormat</code>
- implementation) returns, while <code class="inline-code">?date</code> without the
- <code class="inline-code">()</code> returns a tricky wrapper value that's a date
- and a method and hash on the same time.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_ends_with">ends_with</h2>
-
-
-
-
- <p>Returns whether this string ends with the substring specified
- in the parameter. For example
- <code class="inline-code">"ahead"?ends_with("head")</code> returns boolean
- <code class="inline-code">true</code>. Also,
- <code class="inline-code">"head"?ends_with("head")</code> will return
- <code class="inline-code">true</code>.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_ensure_ends_with">ensure_ends_with</h2>
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.21.</p>
- </div>
-
-
- <p>If the string doesn't end with the substring specified as the
- 1st parameter, it adds it after the string, otherwise it returns the
- original string. For example, both
- <code class="inline-code">"foo"?ensure_ends_with("/")</code> and
- <code class="inline-code">"foo/"?ensure_ends_with("/")</code> returns
- <code class="inline-code">"foo/"</code>.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_ensure_starts_with">ensure_starts_with</h2>
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.21.</p>
- </div>
-
-
- <p>If the string doesn't start with the substring specified as
- the 1st parameter, it adds it before the string, otherwise it
- returns the original string. For example, both
- <code class="inline-code">"foo"?ensure_starts_with("/")</code> and
- <code class="inline-code">"/foo"?ensure_starts_with("/")</code> returns
- <code class="inline-code">"/foo"</code>.</p>
-
- <p>If you specify two parameters, then the 1st parameter is
- interpreted as a Java regular expression, and if it doesn't match
- the beginning of the string, then the string specified as the 2nd
- parameter is added before the string. For example
- <code class="inline-code">someURL?ensure_starts_with("[a-zA-Z]+://",
- "http://")</code> will check if the string starts with something
- that matches <code class="inline-code">"[a-zA-Z]+://"</code> (note that no
- <code class="inline-code">^</code> is needed), and if it doesn't, it prepends
- <code class="inline-code">"http://"</code>.</p>
-
- <p>This method also accepts a 3rd <a href="#ref_builtin_string_flags">flags parameter</a>. As
- calling with 2 parameters implies <code class="inline-code">"r"</code> there
- (i.e., regular expression mode), you rarely need this. One notable
- case is when you don't want the 1st parameter to be interpreted as a
- regular expression, only as plain text, but you want the comparison
- to be case-insensitive, in which case you would use
- <code class="inline-code">"i"</code> as the 3rd parameter.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_esc">esc</h2>
-
-
- <p></p>
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.24.</p>
- </div>
-
-
- <p>Escapes the value with the current <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_outputformat">output format</a>,
- and prevents the <a href="dgui_misc_autoescaping.html">auto-escaping</a> of the
- returned value (to avoid double escaping). Because of auto-escaping,
- you usually only need this where auto-escaping was disabled:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#ftl output_format="HTML" <strong>auto_esc=false</strong>>
-<#assign s = "R&D">
-${s}
-${s?esc}</pre></div>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">R&D
-R&amp;D</pre></div>
-
- <p>In templates, where auto-escaping is on, using it is
- redundant:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#ftl output_format="HTML">
-<#assign s = "R&D">
-${s}
-${s?esc} <#-- ?esc is redundant here --></pre></div>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">R&amp;D
-R&amp;D</pre></div>
-
- <p>This built-in works by converting the string value to a <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
- value</a>, by escaping the string with the current output format,
- and using the result as the markup. The resulting markup output
- value belongs to the current output format at the point of the
- invocation.</p>
-
- <p>This built-in can also be applied on markup output values,
- which it will bypass without change, as far as the input markup
- output value belongs to the current output format. If it doesn't,
- then the markup has to be converted to the current output format,
- which currently (as of 2.3.24) will be only successful if that value
- was created by escaping plain text (usually, with
- <code class="inline-code">?esc</code>).</p>
-
- <p>This built-in can't be used where the current output format is
- a <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_nonmarkupof">non-markup
- output format</a>. An attempt to do so will cause a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>.</p>
-
- <p>This built-in is not related to the deprecated <a href="ref_directive_escape.html"><code>escape</code> and
- <code>noescape</code> directives</a>. In fact, the parser
- will prevent using them on the same place, to prevent
- confusion.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_groups">groups</h2>
-
-
-
-
- <p>This is used only with the result of the
- <code class="inline-code">matches</code> built-in. See <a href="#ref_builtin_matches">there...</a></p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_html">html (deprecated)</h2>
-
-
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is <em>deprecated</em> by the
- <a href="dgui_misc_autoescaping.html">auto-escaping
- mechanism</a> introduced in 2.3.24. To prevent double escaping
- and confusion in general, using this built-in on places where
- auto-escaping is active is a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>. To help
- migration, this built-in silently bypasses HTML <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
- values</a> without changing them.</p>
- </div>
-
-
- <p>The string as HTML markup. That is, the string with
- all:</p>
-
- <ul>
- <li>
- <code class="inline-code"><</code> replaced with
- <code class="inline-code">&lt;</code>
- </li>
-
- <li>
- <code class="inline-code">></code> replaced with
- <code class="inline-code">&gt;</code>
- </li>
-
- <li>
- <code class="inline-code">&</code> replaced with
- <code class="inline-code">&amp;</code>
- </li>
-
- <li>
- <code class="inline-code">"</code> replaced with
- <code class="inline-code">&quot;</code>
- </li>
-
- <li>
- <code class="inline-code">'</code> is replaced with
- <code class="inline-code">&#39;</code> <em>if</em> the
- programmers has <a href="pgui_config_incompatible_improvements.html#pgui_config_incompatible_improvements_how_to_set">set
- the <code>incompatible_improvements</code> setting</a>
- to 2.3.24 or higher (also if it's set to 2.3.20 or higher and
- you are outside a string literal). Otherwise
- <code class="inline-code">'</code> won't be replaced, so you must use
- quotation mark (<code class="inline-code">"</code>, not <code class="inline-code">'</code>)
- to quote attribute values where you want to insert a value
- safely.
- </li>
- </ul>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><input type=text name=user value=<strong>"</strong>${user?html}<strong>"</strong>></pre></div>
-
- <div class="callout warning">
- <strong class="callout-label">Warning!</strong>
-
- <p>When inserting the value of an attribute, always quote it,
- or else it can be exploited by attackers! This is WRONG:
- <code class="inline-code"><input name="user" value=${user?xhtml}></code>.
- This is good: <code class="inline-code"><input name="user"
- value="${user?xhtml}"></code>.</p>
- </div>
-
-
- <p>Note that in HTML pages usually you want to use this built-in
- for all interpolations. You can spare a lot of typing and lessen the
- chances of accidental mistakes by using the <a href="ref_directive_escape.html"><code>escape</code>
- directive</a>.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_index_of">index_of</h2>
-
-
-
-
- <p>Returns the index within this string of the first occurrence
- of the specified substring. For example,
- <code class="inline-code">"abcabc"?index_of("bc")</code> will return 1 (don't
- forget that the index of the first character is 0). Also, you can
- specify the index to start the search from:
- <code class="inline-code">"abcabc"?index_of("bc", 2)</code> will return 4. There
- is no restriction on the numerical value of the second parameter: if
- it is negative, it has the same effect as if it were zero, and if it
- is greater than the length of this string, it has the same effect as
- if it were equal to the length of this string. Decimal values will
- be truncated to integers.</p>
-
- <p>If the 1st parameter does not occur as a substring in this
- string (starting from the given index, if you use the second
- parameter), then it returns -1.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_j_string">j_string</h2>
-
-
-
-
- <p>Escapes the string with the escaping rules of Java language
- string literals, so it's safe to insert the value into a string
- literal. Note that it will <em>not</em> add quotation
- marks around the inserted value; you meant to use this
- <em>inside</em> the string literal.</p>
-
- <p>All characters under <a href="gloss.html#gloss.UCS">UCS</a> code
- point 0x20 will be escaped. When they have no dedicated escape
- sequence in the Java language (like <code class="inline-code">\n</code>,
- <code class="inline-code">\t</code>, etc.), they will be replaced with a UNICODE
- escape
- (<code class="inline-code">\u<em class="code-color">XXXX</em></code>).</p>
-
- <p>Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#assign beanName = 'The "foo" bean.'>
-String BEAN_NAME = "${beanName?j_string}";</pre></div>
-
- <p>will output:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">String BEAN_NAME = "The \"foo\" bean.";</pre></div>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_js_string">js_string</h2>
-
-
-
-
- <p>Escapes the string with the escaping rules of JavaScript
- language string literals, so it's safe to insert the value into a
- string literal. Note that it will <em>not</em> add
- quotation marks around the inserted value; you meant to use this
- <em>inside</em> the string literal.</p>
-
- <div class="callout warning">
- <strong class="callout-label">Warning!</strong>
-
- <p>When inserting into a JavaScript string literal that's
- inside a HTML attribute, you also must escape the value with HTML
- escaping. Thus, of you don't have <a href="pgui_config_outputformatsautoesc.html">automatic HTML
- escaping</a>, this is WRONG: <code class="inline-code"><p
- onclick="alert('${message?js_string}')"></code>, and this is
- good: <code class="inline-code"><p
- onclick="alert('${message?js_string?html}')"></code>.</p>
- </div>
-
-
- <p>Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#assign user = "Big Joe's \"right hand\"">
-<script>
- alert("Welcome ${user?js_string}!");
-</script></pre></div>
-
- <p>will output:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output"><script>
- alert("Welcome Big Joe\'s \"right hand\"!");
-</script></pre></div>
-
- <p>The exact escaping rules are:</p>
-
- <ul>
- <li>
- <p><code class="inline-code">"</code> is escaped as
- <code class="inline-code">\"</code></p>
- </li>
-
- <li>
- <p><code class="inline-code">'</code> is escaped as
- <code class="inline-code">\'</code></p>
- </li>
-
- <li>
- <p><code class="inline-code">\</code> is escaped as
- <code class="inline-code">\\</code></p>
- </li>
-
- <li>
- <p><code class="inline-code">/</code> is escaped as <code class="inline-code">\/</code>
- if the <code class="inline-code">/</code> is directly after
- <code class="inline-code"><</code> in the escaped string, or if it's at the
- beginning of the escaped string</p>
- </li>
-
- <li>
- <p><code class="inline-code">></code> is escaped as
- <code class="inline-code">\></code> if the <code class="inline-code">></code> is
- directly after <code class="inline-code">]]</code> or <code class="inline-code">--</code> in
- the escaped string, or if it's at the beginning of the escaped
- string, or if there's only a <code class="inline-code">]</code> or
- <code class="inline-code">-</code> before it at the beginning of the escaped
- string</p>
- </li>
-
- <li>
- <p><code class="inline-code"><</code> is escaped as
- <code class="inline-code">\u003C</code> if it's followed by
- <code class="inline-code">?</code> or <code class="inline-code">!</code> in the escaped
- string, or if it's at the end of the escaped string</p>
- </li>
-
- <li>
- <p>Control characters in <a href="gloss.html#gloss.UCS">UCS</a>
- code point ranges U+0000...U+001f and U+007f...U+009f are
- escaped as <code class="inline-code">\r</code>, <code class="inline-code">\n</code>, etc.,
- or as <code class="inline-code">\x<em class="code-color">XX</em></code> where
- there's no special escape for them in JavaScript.</p>
- </li>
-
- <li>
- <p>Control characters with <a href="gloss.html#gloss.UCS">UCS</a> code point U+2028 (Line
- separator) and U+2029 (Paragraph separator) are escaped as
- <code class="inline-code">\u<em class="code-color">XXXX</em></code>, as they
- are source code line-breaks in ECMAScript.</p>
- </li>
- </ul>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_json_string">json_string</h2>
-
-
-
-
- <p>Escapes the string with the escaping rules of JSON language
- string literals, so it's safe to insert the value into a string
- literal. Note that it will <em>not</em> add quotation
- marks around the inserted value; you meant to use this
- <em>inside</em> the string literal.</p>
-
- <p>This will not escape <code class="inline-code">'</code> characters, since
- JSON strings must be quoted with <code class="inline-code">"</code>.</p>
-
- <p>The escaping rules are almost identical to those <a href="#ref_builtin_j_string">documented for
- <code>js_string</code></a>. The differences are that
- <code class="inline-code">'</code> is not escaped at all, that > is escaped as
- \u003E (not as \>), and that
- <code class="inline-code">\u<em class="code-color">XXXX</em></code> escapes are
- used instead of <code class="inline-code">\x<em class="code-color">XX</em></code>
- escapes.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_keep_after">keep_after</h2>
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.21.</p>
- </div>
-
-
- <p>Removes the part of the string that is not after the first
- occurrence of the given substring. For example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${"abcdefgh"?keep_after("de")}</pre></div>
-
- <p>will print</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">fgh</pre></div>
-
- <p>If the parameter string is not found, it will return an empty
- string. If the parameter string is a 0-length string, it will return
- the original string unchanged.</p>
-
- <p>This method accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its
- 2nd parameter:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${"foo : bar"?keep_after(r"\s*:\s*", "r")}</pre></div>
-
- <p>will print</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">bar</pre></div>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_keep_after_last">keep_after_last</h2>
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.22.</p>
- </div>
-
-
- <p>Same as <a href="#ref_builtin_keep_after"><code>keep_after</code></a>,
- but keeps the part after the last occurrence of the parameter,
- rather than after the first. Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${"foo.bar.txt"?keep_after_last(".")}</pre></div>
-
- <p>will print</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">txt</pre></div>
-
- <p>while with <code class="inline-code">keep_after</code> you would get
- <code class="inline-code">bar.txt</code>.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_keep_before">keep_before</h2>
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.21.</p>
- </div>
-
-
- <p>Removes the part of the string that starts with the given
- substring. For example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${"abcdef"?keep_before("de")}</pre></div>
-
- <p>will print</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">abc</pre></div>
-
- <p>If the parameter string is not found, it will return the
- original string unchanged. If the parameter string is a 0-length
- string, it will return an empty string.</p>
-
- <p>This method accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its
- 2nd parameter:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${"foo : bar"?keep_before(r"\s*:\s*", "r")}</pre></div>
-
- <p>will print</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">foo</pre></div>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_keep_before_last">keep_before_last</h2>
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.22.</p>
- </div>
-
-
- <p>Same as <a href="#ref_builtin_keep_before"><code>keep_before</code></a>,
- but keeps the part before the last occurrence of the parameter,
- rather than after the first. Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${"foo.bar.txt"?keep_after_last(".")}</pre></div>
-
- <p>will print</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">foo.bar</pre></div>
-
- <p>while with <code class="inline-code">keep_before</code> you would get
- <code class="inline-code">foo</code>.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_last_index_of">last_index_of</h2>
-
-
-
-
- <p>Returns the index within this string of the last (rightmost)
- occurrence of the specified substring. It returns the index of the
- first (leftmost) character of the substring. For example:
- <code class="inline-code">"abcabc"?last_index_of("ab")</code> will return 3. Also,
- you can specify the index to start the search from. For example,
- <code class="inline-code">"abcabc"?last_index_of("ab", 2)</code> will return 0.
- Note that the second parameter indicates the maximum index of the
- start of the substring. There is no restriction on the numerical
- value of the second parameter: if it is negative, it has the same
- effect as if it were zero, and if it is greater than the length of
- this string, it has the same effect as if it were equal to the
- length of this string. Decimal values will be truncated to
- inegers.</p>
-
- <p>If the 1st parameter does not occur as a substring in this
- string (before the given index, if you use the second parameter),
- then it returns -1.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_left_pad">left_pad</h2>
-
-
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.1.</p>
- </div>
-
-
- <p>If it's used with 1 parameter, then it inserts spaces on the
- beginning of the string until it reaches the length that is
- specified as the parameter. If the string is already as long or
- longer than the specified length, then it does nothing. For example,
- this:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">[${""?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)}]</pre></div>
-
- <p>will output this:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">[ ]
-[ a]
-[ ab]
-[ abc]
-[ abcd]
-[abcde]
-[abcdef]
-[abcdefg]
-[abcdefgh]</pre></div>
-
- <p>If it's used with 2 parameters, then the 1st parameter means
- the same as if you were using the built-in with only 1 parameter,
- and the second parameter specifies what to insert instead of space
- characters. For example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">[${""?left_pad(5, "-")}]
-[${"a"?left_pad(5, "-")}]
-[${"ab"?left_pad(5, "-")}]
-[${"abc"?left_pad(5, "-")}]
-[${"abcd"?left_pad(5, "-")}]
-[${"abcde"?left_pad(5, "-")}]</pre></div>
-
- <p>will output this:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">[-----]
-[----a]
-[---ab]
-[--abc]
-[-abcd]
-[abcde]</pre></div>
-
- <p>The 2nd parameter can be a string whose length is greater than
- 1. Then the string will be inserted periodically, for
- example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">[${""?left_pad(8, ".oO")}]
-[${"a"?left_pad(8, ".oO")}]
-[${"ab"?left_pad(8, ".oO")}]
-[${"abc"?left_pad(8, ".oO")}]
-[${"abcd"?left_pad(8, ".oO")}]</pre></div>
-
- <p>will output this:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">[.oO.oO.o]
-[.oO.oO.a]
-[.oO.oOab]
-[.oO.oabc]
-[.oO.abcd]</pre></div>
-
- <p>The 2nd parameter must be a string value, and it must be at
- least 1 character long.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_length">length</h2>
-
-
-
-
- <p>The number of characters in the string.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_lower_case">lower_case</h2>
-
-
-
-
- <p>The lower case version of the string. For example
- <code class="inline-code">"GrEeN MoUsE"?lower_case</code> will be <code class="inline-code">"green
- mouse"</code>.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_matches">matches</h2>
-
-
-
-
- <p>This is a "power user" built-in. Ignore it if you
- don't know <a href="gloss.html#gloss.regularExpression">regular
- expressions</a>.</p>
-
- <p>This built-in determines if the string exactly matches the
- pattern. Also, it returns the list of matching sub-strings. The
- return value is a multi-type value:</p>
-
- <ul>
- <li>
- <p>Boolean: <code class="inline-code">true</code>, if it the entire string
- matches the pattern, otherwise <code class="inline-code">false</code>. For
- example, <code class="inline-code">"fooo"?matches('fo*')</code> is
- <code class="inline-code">true</code>, but
- <code class="inline-code">"fooo�bar"?matches('fo*')</code> is
- <code class="inline-code">false</code>.</p>
- </li>
-
- <li>
- <p>Sequence: the list of matched substrings of the string.
- Possibly a 0 length sequence.</p>
- </li>
- </ul>
-
- <p>For example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#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></pre></div>
-
- <p>will print:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">Matches.
-
-Does not match.
-Matching sub-strings:
-- foo
-- fyo</pre></div>
-
- <p>If the regular expression contains groups (parentheses), then
- you can access them with the <code class="inline-code">groups</code>
- built-in:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#-- 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></pre></div>
-
- <p>This will print:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output"> First name: John
- Second name: Doe
-
- - "aa/rx;" is "a" per "a/rx"
- - " ab/r;" is " " per "ab/r"</pre></div>
-
- <p>Notes regarding the behavior of the <code class="inline-code">groups</code>
- built-in:</p>
-
- <ul>
- <li>
- <p>It works both with substring matches and with the result
- of entire string matching (as it was shown in the above
- example)</p>
- </li>
-
- <li>
- <p>The first item in the sequence that
- <code class="inline-code">groups</code> returns is the whole substring matched
- by the regular expression. Hence, the index of the first
- explicit regular expression group (with other words, of the
- first <code class="inline-code">(<em class="code-color">...</em>)</code> in the
- regular expression) is 1, and not 0. Also, because of this, the
- size of the sequence is one more than the number of explicit
- regular expression groups.</p>
- </li>
-
- <li>
- <p>The size of the sequence returned by
- <code class="inline-code">groups</code> only depends on the number of explicit
- groups in the regular expression, and so it will be the same
- (non-0) even if there was no match found for the regular
- expression. Attempting to access an item of the sequence (as in
- <code class="inline-code">res?groups[1]</code>) when there was match will
- cause an error. Thus, before accessing the groups, you should
- always check if there was any match (as in <code class="inline-code"><#if
- res><em class="code-color">access the groups
- here</em></#if></code>).</p>
- </li>
-
- <li>
- <p>When there's a match for the regular expression, but not
- for a certain explicit group inside the regular expression, then
- for that group the sequence will contain a 0 length string. So
- accessing a group that matches nothing is safe, as far as the
- containing regular expression has matched something.</p>
- </li>
- </ul>
-
- <p><code class="inline-code">matches</code> accepts an optional 2nd parameter,
- the <a href="#ref_builtin_string_flags">flags</a>. Note that
- it doesn't support flag <code class="inline-code">f</code>, and ignores the
- <code class="inline-code">r</code> flag.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_no_esc">no_esc</h2>
-
-
- <p></p>
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.24.</p>
- </div>
-
-
- <p>Prevents the <a href="dgui_misc_autoescaping.html">auto-escaping</a> of a value.
- For example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#ftl output_format="HTML">
-<#assign s = "<b>Test</b>">
-${s}
-${s?no_esc}</pre></div>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">&lt;b&gt;Test&lt;/b&gt;
-<b>Test</b></pre></div>
-
- <p>This works by converting the string value to a <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
- value</a>, which uses the string as the markup as is, and belongs
- to the current <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_outputformat">output format</a>
- at the point of the invocation.</p>
-
- <p>This built-in can also be applied on markup output values,
- which it will bypass without change, as far as the input markup
- output value belongs to current output format. If it doesn't, then
- the markup has to be converted to the current output format, which
- currently (as of 2.3.24) will be only successful if that value was
- created by escaping plain text (usually, with
- <code class="inline-code">?esc</code>).</p>
-
- <p>This built-in can't be used where the current output format is
- a <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_nonmarkupof">non-markup
- output format</a>. An attempt to do so will cause a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>.</p>
-
- <p>This built-in is not related to the deprecated <a href="ref_directive_escape.html"><code>escape</code> and
- <code>noescape</code> directives</a>. In fact, the parser
- will prevent using them on the same place, to prevent
- confusion.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_number">number</h2>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <p>The string converted to numerical value. The number must be in
- "computer language" format. That is, it must be in the
- locale independent form, where the decimal separator is dot, and
- there's no grouping.</p>
-
- <p>This built-in recognizes numbers in the format that the
- FreeMarker template language uses. In additionally, it recognizes
- scientific notation (e.g. <code class="inline-code">"1.23E6"</code>,
- <code class="inline-code">"1.5e-8"</code>). Since FreeMarker 2.3.21, it also
- recognizes all XML Schema number formats, like
- <code class="inline-code">NaN</code>, <code class="inline-code">INF</code>,
- <code class="inline-code">-INF</code>, plus the Java-native formats
- <code class="inline-code">Infinity</code> and <code class="inline-code">-Infinity</code>.</p>
-
- <p>If the string is not in the appropriate format, an error will
- abort template processing when you try to access this
- built-in.</p>
-
- <p><span class="marked-for-programmers">In fact, the string is parsed by
- the <code class="inline-code">toNumber</code> method of the current
- <code class="inline-code">arithmetic_engine</code>, which is configuration
- setting. However, that method should behave similarly as described
- above.</span></p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_replace">replace</h2>
-
-
-
-
- <p>It is used to replace all occurrences of a string in the
- original string with another string. It does not deal with word
- boundaries. For example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${"this is a car acarus"?replace("car", "bulldozer")}</pre></div>
-
- <p>will print:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">this is a bulldozer abulldozerus</pre></div>
-
- <p>The replacing occurs in left-to-right order. This means that
- this:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${"aaaaa"?replace("aaa", "X")}</pre></div>
-
- <p>will print:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">Xaa</pre></div>
-
- <p>If the 1st parameter is an empty string, then all occurrences
- of the empty string will be replaced, like
- <code class="inline-code">"foo"?replace("","|")</code> will evaluate to
- <code class="inline-code">"|f|o|o|"</code>.</p>
-
- <p><code class="inline-code">replace</code> accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its
- 3rd parameter.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_right_pad">right_pad</h2>
-
-
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.1. It
- doesn't exist in 2.3.</p>
- </div>
-
-
- <p>This is the same as <a href="#ref_builtin_left_pad"><code>left_pad</code></a>,
- but it inserts the characters at the end of the string instead of
- the beginning of the string.</p>
-
- <p>Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">[${""?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")}]</pre></div>
-
- <p>This will output this:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">[ ]
-[a ]
-[ab ]
-[abc ]
-[abcd ]
-[abcde]
-[abcdef]
-[abcdefg]
-[abcdefgh]
-
-[.oO.oO.o]
-[aoO.oO.o]
-[abO.oO.o]
-[abc.oO.o]
-[abcdoO.o]</pre></div>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_remove_beginning">remove_beginning</h2>
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.21.</p>
- </div>
-
-
- <p>Removes the parameter substring from the beginning of the
- string, or returns the original string if it doesn't start with the
- parameter substring. For example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${"abcdef"?remove_beginning("abc")}
-${"foobar"?remove_beginning("abc")}</pre></div>
-
- <p>will print:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">def
-foobar</pre></div>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_remove_ending">remove_ending</h2>
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.21.</p>
- </div>
-
-
- <p>Removes the parameter substring from the ending of the string,
- or returns the original string if it doesn't end with the parameter
- substring. For example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">${"abcdef"?remove_ending("def")}
-${"foobar"?remove_ending("def")}</pre></div>
-
- <p>will print:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">abc
-foobar</pre></div>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_rtf">rtf (deprecated)</h2>
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is <em>deprecated</em> by the
- <a href="dgui_misc_autoescaping.html">auto-escaping
- mechanism</a> introduced in 2.3.24. To prevent double escaping
- and confusion in general, using this built-in on places where
- auto-escaping is active is a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>. To help
- migration, this built-in silently bypasses RTF <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
- values</a> without changing them.</p>
- </div>
-
-
-
-
-
-
- <p>The string as Rich text (RTF text). That is, the string with
- all:</p>
-
- <ul>
- <li>
- <p><code class="inline-code">\</code> replaced with
- <code class="inline-code">\\</code></p>
- </li>
-
- <li>
- <p><code class="inline-code">{</code> replaced with
- <code class="inline-code">\{</code></p>
- </li>
-
- <li>
- <p><code class="inline-code">}</code> replaced with
- <code class="inline-code">\}</code></p>
- </li>
- </ul>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_split">split</h2>
-
-
-
-
- <p>It is used to split a string into a sequence of strings along
- the occurrences of another string. For example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#list "someMOOtestMOOtext"?split("MOO") as x>
-- ${x}
-</#list></pre></div>
-
- <p>will print:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">- some
-- test
-- text</pre></div>
-
- <p>Note that it is assumed that all occurrences of the separator
- is before a new item (except with <code class="inline-code">"r"</code> flag - see
- later), thus:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#list "some,,test,text,"?split(",") as x>
-- "${x}"
-</#list></pre></div>
-
- <p>will print:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">- "some"
-- ""
-- "test"
-- "text"
-- ""</pre></div>
-
- <p><code class="inline-code">split</code> accepts an optional <a href="#ref_builtin_string_flags">flags parameter</a>, as its
- 2nd parameter. There's a historical glitch with the
- <code class="inline-code">r</code> (regular expression) flag; it removes the empty
- elements from the end of the resulting list, so with
- <code class="inline-code">?split(",", "r")</code> in the last example the last
- <code class="inline-code">""</code> would be missing from the output.</p>
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>To check if a strings ends with something and append it
- otherwise, use <a href="#ref_builtin_ensure_ends_with">the
- <code>ensure_ends_with</code> built-in</a>.</p>
- </div>
-
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_starts_with">starts_with</h2>
-
-
-
-
- <p>Returns if this string starts with the specified substring.
- For example <code class="inline-code">"redirect"?starts_with("red")</code> returns
- boolean <code class="inline-code">true</code>. Also,
- <code class="inline-code">"red"?starts_with("red")</code> will return
- <code class="inline-code">true</code>.</p>
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>To check if a strings starts with something and prepend it
- otherwise, use <a href="#ref_builtin_ensure_starts_with">the
- <code>ensure_starts_with</code> built-in</a>.</p>
- </div>
-
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_string_for_string">string (when used with a string value)</h2>
-
-
- <p>Does nothing, just returns the string as-is. The exception is
- that if the value is a multi-type value (e.g. it is both string and
- sequence at the same time), then the resulting value will be only a
- simple string, not a multi-type value. This can be utilized to
- prevent the artifacts of multi-typing.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_substring">substring (deprecated)</h2>
-
-
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is deprecated since FreeMarker 2.3.21 by <a href="dgui_template_exp.html#dgui_template_exp_stringop_slice">slicing
- expressions</a>, like
- <code class="inline-code"><em class="code-color">str</em>[<em class="code-color">from</em>..<<em class="code-color">toExclusive</em>]</code>,
- <code class="inline-code"><em class="code-color">str</em>[<em class="code-color">from</em>..]</code>,
- and
- <code class="inline-code"><em class="code-color">str</em>[<em class="code-color">from</em>..*<em class="code-color">maxLength</em>]</code>.</p>
-
- <p>A warning if you are processing XML: Since slicing
- expressions work both for sequences and strings, and since XML
- nodes are typically both sequences and strings at the same time,
- there the equivalent expression is
- <code class="inline-code"><em class="code-color">someXmlNode</em>?string[<em class="code-color">from</em>..<<em class="code-color">toExclusive</em>]</code>
- and
- <code class="inline-code"><em class="code-color">exp</em>?string[<em class="code-color">from</em>..]</code>,
- as without <code class="inline-code">?string</code> it would slice the node
- sequence instead of the text value of the node.</p>
- </div>
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>Some of the typical use-cases of string slicing is covered
- by convenient built-ins: <a href="#ref_builtin_remove_beginning"><code>remove_beginning</code></a>,
- <a href="#ref_builtin_remove_ending"><code>remove_ending</code></a>,
- <a href="#ref_builtin_keep_before"><code>keep_before</code></a>,
- <a href="#ref_builtin_keep_after"><code>keep_after</code></a>,
- <a href="#ref_builtin_keep_before_last"><code>keep_before_last</code></a>,
- <a href="#ref_builtin_keep_after_last"><code>keep_after_last</code></a></p>
- </div>
-
-
- <p>Synopsis:
- <code class="inline-code"><em class="code-color">exp</em>?substring(<em class="code-color">from</em>,
- <em class="code-color">toExclusive</em>)</code>, also callable as
- <code class="inline-code"><em class="code-color">exp</em>?substring(<em class="code-color">from</em>)</code></p>
-
- <p>A substring of the string.
- <code class="inline-code"><em class="code-color">from</em></code> is the index of
- the first character. It must be a number that is at least 0 and less
- than or equal with
- <code class="inline-code"><em class="code-color">toExclusive</em></code>, or else
- an error will abort the template processing. The
- <code class="inline-code"><em class="code-color">toExclusive</em></code> is the
- index of the character position after the last character of the
- substring, or with other words, it is one greater than the index of
- the last character. It must be a number that is at least 0 and less
- than or equal to the length of the string, or else an error will
- abort the template processing. If the
- <code class="inline-code"><em class="code-color">toExclusive</em></code> is
- omitted, then it defaults to the length of the string. If a
- parameter is a number that is not an integer, only the integer part
- of the number will be used.</p>
-
- <p>Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">- ${'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)}</pre></div>
-
- <p>The output:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">- abc
-- bc
-- c
--
-
--
-- a
-- ab
-- abc
-
-- a
-- b
-- c</pre></div>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_trim">trim</h2>
-
-
-
-
- <p>The string without leading and trailing white-space.
- Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template">(${" green mouse "?trim})</pre></div>
-
- <p>The output:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">(green mouse)</pre></div>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_uncap_first">uncap_first</h2>
-
-
-
-
- <p>The opposite of <a href="#ref_builtin_cap_first"><code>cap_first</code></a>.
- The string with the very first word of the string
- un-capitalized.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_upper_case">upper_case</h2>
-
-
-
-
- <p>The upper case version of the string. For example
- <code class="inline-code">"GrEeN MoUsE"</code> will be <code class="inline-code">"GREEN
- MOUSE"</code>.</p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_url">url</h2>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.1. It
- doesn't exist in 2.3.</p>
- </div>
-
-
- <p>The string after URL escaping. This means that all
- non-US-ASCII and reserved URL characters will be escaped with
- <code class="inline-code">%<em class="code-color">XX</em></code>. For
- example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#assign x = 'a/b c'>
-${x?url}</pre></div>
-
- <p>The output will be (assuming that the charset used for the
- escaping is an US-ASCII compatible charset):</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">a%2Fb%20c</pre></div>
-
- <p>Note that it escapes <em>all</em> reserved URL
- characters (<code class="inline-code">/</code>, <code class="inline-code">=</code>,
- <code class="inline-code">&</code>, ...etc), so this encoding can be used for
- encoding query parameter values, for example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><a href="foo.cgi?x=${x?url}&y=${y?url}">Click here...</a></pre></div>
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>Above no HTML encoding (<code class="inline-code">?html</code>) was
- needed, because URL escaping escapes all reserved HTML characters
- anyway. But watch: always quote the attribute value, and always
- with normal quotation mark (<code class="inline-code">"</code>), never with
- apostrophe quotation mark (<code class="inline-code">'</code>), because
- apostrophe quotation mark is not escaped by the URL
- escaping.</p>
- </div>
-
-
- <p>To do URL escaping a <a href="gloss.html#gloss.charset">charset</a> must be chosen that will be
- used for calculating the escaped parts
- (<code class="inline-code">%<em class="code-color">XX</em></code>). 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 (<span class="marked-for-programmers">programmers: see
- more below...</span>). If you are a more technical minded user,
- then you may want to know that the charset used is specified by the
- <code class="inline-code">url_escaping_charset</code> setting, that can be set in
- template execution time (or, preferably, earlier by the
- programmers). For example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#--
- 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: -->
-<strong><#setting url_escaping_charset="UTF-8"></strong>
-
-<#-- This will surely use UTF-8 charset -->
-<a href="bar.cgi?x=${x?url}">bar</a></pre></div>
-
- <p>Furthermore, you can explicitly specify a charset for a single
- URL escaping as the parameter to the built-in:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><a href="foo.cgi?x=${x?url<strong>('ISO-8895-2')</strong>}">foo</a></pre></div>
-
- <p><span class="marked-for-programmers">If the <code class="inline-code">url</code> built-in has no
- parameter, then it will use the charset specified as the value of
- the <code class="inline-code">url_escaping_charset</code> setting. This setting
- should be set by the software that encloses FreeMarker (e.g. a Web
- application framework), because it is not set
- (<code class="inline-code">null</code>) by default. If it is not set, then
- FreeMarker falls back using the value of the
- <code class="inline-code">output_encoding</code> setting, which is also not set by
- default, so it is again the task of the enclosing software. If the
- <code class="inline-code">output_encoding</code> setting is not set either, then
- the parameterless <code class="inline-code">url</code> built-in can't be executed,
- and it will cause execution time error. Of course, the
- <code class="inline-code">url</code> built-in with parameter always
- works.</span></p>
-
- <p><span class="marked-for-programmers">It's possible to set
- <code class="inline-code">url_escaping_charset</code> in the template with the
- <code class="inline-code">setting</code> directive, but it is bad practice, at
- least in true MVC applications. The
- <code class="inline-code">output_encoding</code> setting can't be set with the
- <code class="inline-code">setting</code> directive, so that's surely the task of
- the enclosing software. You may find more information regarding this
- <a href="pgui_misc_charset.html">here...</a></span></p>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_url_path">url_path</h2>
-
-
-
-
-
-
-
-
-
-
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is available since FreeMarker 2.3.21.</p>
- </div>
-
-
- <p>This is the same as <a href="#ref_builtin_url">the
- <code>url</code> built-in</a>, except that it doesn't
- escape slash (<code class="inline-code">/</code>) characters. This meant to be
- used for converting paths (like paths coming from the OS or some
- content repository) that use slash (not backslash!) to a path the
- can be inserted into an URL. The most common reason why this
- conversion is needed is that folder names or file names might
- contain non-US-ASCII letters ("national"
- characters).</p>
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>Just like with <a href="#ref_builtin_url">the
- <code>url</code> built-in</a>, the desired URL escaping
- charset (or as a fall back, the output encoding) must be set in
- the FreeMarker configuration settings, or else the built-in will
- give error. Or, you you have to specify the charset like
- <code class="inline-code">somePath?url_path('utf-8')</code>.</p>
- </div>
-
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_word_list">word_list</h2>
-
-
-
-
- <p>A sequence that contains all words of the string in the order
- as they appear in the string. Words are continual character
- sequences that contain any character but <a href="gloss.html#gloss.whiteSpace">white-space</a>. Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#assign words = " a bcd, . 1-2-3"?word_list>
-<#list words as word>[${word}]</#list></pre></div>
-
- <p>will output:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">[a][bcd,][.][1-2-3]</pre></div>
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_xhtml">xhtml (deprecated)</h2>
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is <em>deprecated</em> by the
- <a href="dgui_misc_autoescaping.html">auto-escaping
- mechanism</a> introduced in 2.3.24. To prevent double escaping
- and confusion in general, using this built-in on places where
- auto-escaping is active is a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>. To help
- migration, this built-in silently bypasses HTML <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
- values</a> without changing them.</p>
- </div>
-
-
-
-
-
-
- <p>The string as XHTML text. That is, the string with all:</p>
-
- <ul>
- <li>
- <code class="inline-code"><</code> replaced with
- <code class="inline-code">&lt;</code>
- </li>
-
- <li>
- <code class="inline-code">></code> replaced with
- <code class="inline-code">&gt;</code>
- </li>
-
- <li>
- <code class="inline-code">&</code> replaced with
- <code class="inline-code">&amp;</code>
- </li>
-
- <li>
- <code class="inline-code">"</code> replaced with
- <code class="inline-code">&quot;</code>
- </li>
-
- <li>
- <code class="inline-code">'</code> replaced with
- <code class="inline-code">&#39;</code>
- </li>
- </ul>
-
- <p>The only difference between this built-in and the
- <code class="inline-code">xml</code> built-in is that the <code class="inline-code">xhtml</code>
- built-in escapes <code class="inline-code">'</code> as
- <code class="inline-code">&#39;</code> instead of as
- <code class="inline-code">&apos;</code>, because some older browsers don't
- know <code class="inline-code">&apos;</code>.</p>
-
- <div class="callout warning">
- <strong class="callout-label">Warning!</strong>
-
- <p>When inserting the value of an attribute, always quote it,
- or else it can be exploited by attacker! This is WRONG:
- <code class="inline-code"><input name="user" value=${user?xhtml}/></code>.
- These are good: <code class="inline-code"><input name="user"
- value="${user?xhtml}"/></code>, <code class="inline-code"><input
- name="user" value='${user?xhtml}'/></code>.</p>
- </div>
-
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_xml">xml (deprecated)</h2>
-
-
- <div class="callout note">
- <strong class="callout-label">Note:</strong>
-
- <p>This built-in is <em>deprecated</em> by the
- <a href="dgui_misc_autoescaping.html">auto-escaping
- mechanism</a> introduced in 2.3.24. To prevent double escaping
- and confusion in general, using this built-in on places where
- auto-escaping is active is a <a href="gloss.html#gloss.parseTimeError">parse-time error</a>. To help
- migration, this built-in silently bypasses XML and HTML <a href="dgui_misc_autoescaping.html#dgui_misc_autoescaping_movalues">markup output
- values</a> without changing them.</p>
- </div>
-
-
-
-
-
-
- <p>The string as XML text. That is, the string with all:</p>
-
- <ul>
- <li>
- <code class="inline-code"><</code> replaced with
- <code class="inline-code">&lt;</code>
- </li>
-
- <li>
- <code class="inline-code">></code> replaced with
- <code class="inline-code">&gt;</code>
- </li>
-
- <li>
- <code class="inline-code">&</code> replaced with
- <code class="inline-code">&amp;</code>
- </li>
-
- <li>
- <code class="inline-code">"</code> replaced with
- <code class="inline-code">&quot;</code>
- </li>
-
- <li>
- <code class="inline-code">'</code> replaced with
- <code class="inline-code">&apos;</code>
- </li>
- </ul>
-
- <div class="callout warning">
- <strong class="callout-label">Warning!</strong>
-
- <p>When inserting the value of an attribute, always quote it,
- or else it can be exploited by attackers! This is WRONG:
- <code class="inline-code"><input name="user" value=${user?xml}/></code>.
- These are good: <code class="inline-code"><input name="user"
- value="${user?xml}"/></code>, <code class="inline-code"><input name="user"
- value='${user?xml}'/></code>.</p>
- </div>
-
-
-
-
-
-
-<h2 class="content-header header-section2" id="ref_builtin_string_flags">Common flags</h2>
-
-
- <p>Many string built-ins accept an optional string parameter, the
- so called "flags". In this string, each letter
- influences a certain aspect of the behavior of the built-in. For
- example, letter <code class="inline-code">i</code> means that the built-in should
- not differentiate the lower and upper-case variation of the same
- letter. The order of the letters in the flags string is not
- significant.</p>
-
- <p>This is the complete list of letters (flags):</p>
-
- <ul>
- <li>
- <p><code class="inline-code">i</code>: Case insensitive: do not
- differentiate the lower and upper-case variation of the same
- letter.</p>
- </li>
-
- <li>
- <p><code class="inline-code">f</code>: First only. That is,
- replace/find/etc. only the first occurrence of something.</p>
- </li>
-
- <li>
- <p> <code class="inline-code">r</code>: The substring to find is a
- <a href="gloss.html#gloss.regularExpression">regular
- expression</a>. FreeMarker uses the variation of regular
- expressions described at <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html</a>
- (note that the presence of some pattern features depends on the
- Java version used).</p>
- </li>
-
- <li>
- <p><code class="inline-code">m</code>: Multi-line mode for regular
- expressions. In multi-line mode the expressions
- <code class="inline-code">^</code> and <code class="inline-code">$</code> match just after
- or just before, respectively, a line terminator or the end of
- the string. By default these expressions only match at the
- beginning and the end of the entire string. Note that
- <code class="inline-code">^</code> and <code class="inline-code">$</code> doesn't match the
- line-break character itself.</p>
- </li>
-
- <li>
- <p><code class="inline-code">s</code>: Enables dot-all mode for regular
- expressions (same as Perl singe-line mode). In dot-all mode, the
- expression <code class="inline-code">.</code> matches any character, including
- a line terminator. By default this expression does not match
- line terminators.</p>
- </li>
-
- <li>
- <p><code class="inline-code">c</code>: Permits whitespace and comments in
- regular expressions.</p>
- </li>
- </ul>
-
- <p>Example:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-template"><#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')}</pre></div>
-
- <p>This outputs this:</p>
-
-
-
-<div class="code-wrapper"><pre class="code-block code-output">foo bAr XYar
-i: foo XYr XYar
-if: foo XYr baar
-r: foo XYAr XYr
-ri: foo XYr XYr
-rif: foo XYr baar</pre></div>
-
- <p>
<TRUNCATED>