Google Git
Sign in
apache / freemarker-docgen / f6eb79676240e0fa3a9154cdb825da28220fc9b9 / . / legacy-tests / build / test / 1 / ref_builtins_expert.html
blob: 0733a26d73748815a3a5baa55173bfc019ff4901 [file] [log] [blame]
<!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>Seldom used and expert built-ins - 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="FreeMarker Manual">
<meta property="og:title" content="Seldom used and expert built-ins">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://example.com/ref_builtins_expert.html">
<link rel="canonical" href="http://example.com/ref_builtins_expert.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1594338519184">
</head>
<body itemscope itemtype="https://schema.org/Code">
<meta itemprop="url" content="http://example.com/">
<meta itemprop="name" content="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://example.com" role="banner"> <img itemprop="image" src="logo.png" alt="My Logo">
</a></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">FreeMarker Manual</a><div class="navigation-header"></div></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">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">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_expert.html"><span itemprop="name">Seldom used and expert built-ins</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="ref.html">Reference</a></li><li><a href="app_faq.html">FAQ</a></li><li><a href="preface.html#test_target">Bőregér</a></li><li><a href="api/index.html">API</a></li><li><a href="../index.html">Home</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 = ["FreeMarker Manual","Reference","Built-in Reference","Seldom used and expert built-ins"];</script>
<script src="toc.js?1594338519184"></script>
<script src="docgen-resources/main.min.js?1594338519184"></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_node.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directives.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="ref_builtins_expert" itemprop="headline">Seldom used and expert built-ins</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_numType" data-menu-target="ref_builtin_numType">byte, double, float, int, long, short</a></li><li><a class="page-menu-link" href="#ref_builtin_eval" data-menu-target="ref_builtin_eval">eval</a></li><li><a class="page-menu-link" href="#ref_builtin_has_content" data-menu-target="ref_builtin_has_content">has_content</a></li><li><a class="page-menu-link" href="#ref_builtin_interpret" data-menu-target="ref_builtin_interpret">interpret</a></li><li><a class="page-menu-link" href="#ref_builtin_isType" data-menu-target="ref_builtin_isType">is_...</a></li><li><a class="page-menu-link" href="#ref_builtin_namespace" data-menu-target="ref_builtin_namespace">namespace</a></li><li><a class="page-menu-link" href="#ref_builtin_new" data-menu-target="ref_builtin_new">new</a></li></ul> </div><p>These are the built-ins that normally you should not use, but in
exceptional situations (debugging, advanced macros) they can be
useful. If you need to use these in your normal page templates, you
may revisit the data-model so you don&#39;t need to use these.</p>
<h2 class="content-header header-section2" id="ref_builtin_numType">byte, double, float, int, long, short</h2>
<p>Returns a <code class="inline-code">SimpleNumber</code> which contains the
same value as the original variable, but uses
<code class="inline-code">java.lang.<em class="code-color">Type</em></code> for the
internal representation of the value. This is useful if a method is
overloaded, or if a <code class="inline-code">TemplateModel</code> unwrapper has
problem with automatically choosing the suitable
<code class="inline-code">java.lang.*</code> type. Note that since version 2.3.9
the unwrapper has been improved substantially, so you will hardly
ever need to use these built-ins, except for resolving ambiguity in
overloaded method invocation.</p>
<h2 class="content-header header-section2" id="ref_builtin_eval">eval</h2>
<p>This built-in evaluates a string as an FTL expression. For
example <code class="inline-code">&quot;1+2&quot;?eval</code> returns number 3.</p>
<h2 class="content-header header-section2" id="ref_builtin_has_content">has_content</h2>
<p>It is <code class="inline-code">true</code> if the variable exists (and
isn&#39;t Java <code class="inline-code">null</code>) and is not ``empty&#39;&#39;, otherwise
it is <code class="inline-code">false</code>. The meaning of ``empty&#39;&#39; depends on
the concrete case. This follows intuitive common-sense ideas. The
following are empty: a string with 0 length, sequence or hash with
no subvariables, a collection which has passed the last element. If
the value is not a string or sequence or hash or collection, then it
counts as non-empty if it&#39;s a number or a date or a boolean (e.g.
<code class="inline-code">0</code> and <code class="inline-code">false</code> are not empty),
otherwise it counts as empty. Note that when your data-model
implements multiple template model interfaces you may get unexpected
results. However, when in doubt you can use always use
<code class="inline-code">expr!?size &gt; 0</code> or <code class="inline-code">expr!?length &gt;
0</code> instead of <code class="inline-code">expr?has_content</code>.</p>
<p>This buit-in is exceptional in that you can use the
parentheses trick like with the <a href="dgui_template_exp.html#dgui_template_exp_missing_default">default value
operator</a>. That is, you can write both
<code class="inline-code">product.color?has_content</code> and
<code class="inline-code">(product.color)?has_content</code>. The first doesn&#39;t
handle the case when <code class="inline-code">product</code> is missing, the last
does.</p>
<h2 class="content-header header-section2" id="ref_builtin_interpret">interpret</h2>
<p>This built-in interprets a string as a FTL template, and
returns an user-defined directive that - when applied to any block -
executes the template just as if it was included at that point.
Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign x=[&quot;a&quot;, &quot;b&quot;, &quot;c&quot;]&gt;
&lt;#assign templateSource = r&quot;&lt;#list x as y&gt;${y}&lt;/#list&gt;&quot;&gt;
&lt;#-- Note: That r was needed so that the ${y} is not interpreted above --&gt;
&lt;#assign inlineTemplate = templateSource?interpret&gt;
&lt;@inlineTemplate /&gt;</pre></div>
<p>The output:</p>
<div class="code-wrapper"><pre class="code-block code-output">abc</pre></div>
<p>As you can see, <code class="inline-code">inlineTemplate</code> is a
user-defined directive that, when executed, runs the template that
was generated on-the-fly using the
<code class="inline-code">interpret</code>.</p>
<p>You can also apply this built-in to a two-element sequence. In
this case the first element of the sequence is the template source,
and the second element is a name for the inline template. It can be
useful to give an explicit name to the inline template for debugging
purposes. So, you could have written:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#assign inlineTemplate = [templateSource, &quot;myInlineTemplate&quot;]?interpret&gt;</pre></div>
<p>as well in the above template. Note that giving the inline
template a name has no immediate effect - it is only useful as an
extra bit of information if you get an error report.</p>
<h2 class="content-header header-section2" id="ref_builtin_isType">is_...</h2>
<p>These built-ins check the type of a variable, and returns
<code class="inline-code">true</code> or <code class="inline-code">false</code> depending on the
type. The list of
<code class="inline-code">is_<em class="code-color">...</em></code>
built-ins:</p>
<div class="table-responsive">
<table class="table">
<thead>
<tr>
<th>Built-in</th>
<th>Returns <code class="inline-code">true</code> if the value is a ...</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="inline-code">is_string</code></td>
<td>string</td>
</tr>
<tr>
<td><code class="inline-code">is_number</code></td>
<td>number</td>
</tr>
<tr>
<td><code class="inline-code">is_boolean</code></td>
<td>boolean</td>
</tr>
<tr>
<td><code class="inline-code">is_date</code></td>
<td>date (all types: date-only, time-only and date-time)</td>
</tr>
<tr>
<td><code class="inline-code">is_method</code></td>
<td>method</td>
</tr>
<tr>
<td><code class="inline-code">is_transform</code></td>
<td>transform</td>
</tr>
<tr>
<td><code class="inline-code">is_macro</code></td>
<td>macro</td>
</tr>
<tr>
<td><code class="inline-code">is_hash</code></td>
<td>hash</td>
</tr>
<tr>
<td><code class="inline-code">is_hash_ex</code></td>
<td>extended hash (i.e. supports <code class="inline-code">?keys</code> and
<code class="inline-code">?values</code>)</td>
</tr>
<tr>
<td><code class="inline-code">is_sequence</code></td>
<td>sequence</td>
</tr>
<tr>
<td><code class="inline-code">is_collection</code></td>
<td>collection</td>
</tr>
<tr>
<td><code class="inline-code">is_enumerable</code></td>
<td>sequence or collection</td>
</tr>
<tr>
<td><code class="inline-code">is_indexable</code></td>
<td>sequence</td>
</tr>
<tr>
<td><code class="inline-code">is_directive</code></td>
<td>Whatever kind of directive (for example a macro, <span class="marked-for-programmers">or
<code class="inline-code">TemplateDirectiveModel</code>,
<code class="inline-code">TemplateTransformModel</code>, etc.</span>)</td>
</tr>
<tr>
<td><code class="inline-code">is_node</code></td>
<td>node</td>
</tr>
</tbody>
</table>
</div>
<h2 class="content-header header-section2" id="ref_builtin_namespace">namespace</h2>
<p>This built-in returns the namespace (i.e. the ``gate&#39;&#39; hash to
the namespace) associated with a macro variable. You can use it with
macros only.</p>
<h2 class="content-header header-section2" id="ref_builtin_new">new</h2>
<p>This is to create a variable of a certain
<code class="inline-code">TemplateModel</code> implementation.</p>
<p>On the left side of <code class="inline-code">?</code> you specify a string,
the full-qualified class name of a <code class="inline-code">TemplateModel</code>
implementation. The result is a method variable that calls the
constructor, and returns the new variable.</p>
<p>Example:</p>
<div class="code-wrapper"><pre class="code-block code-template">&lt;#-- Creates an user-defined directive be calling the parameterless constructor of the class --&gt;
&lt;#assign word_wrapp = &quot;com.acmee.freemarker.WordWrapperDirective&quot;?new()&gt;
&lt;#-- Creates an user-defined directive be calling the constructor with one numerical argument --&gt;
&lt;#assign word_wrapp_narrow = &quot;com.acmee.freemarker.WordWrapperDirective&quot;?new(40)&gt;</pre></div>
<p>For more information about how the constructor parameters are
unwrapped and how overloaded constructor is chosen, read: <a href="pgui_misc_beanwrapper.html">Programmer&#39;s Guide/Miscellaneous/Bean wrapper</a></p>
<div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_builtins_node.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directives.html"><span>Next</span></a></div></div></div></div> </div>
</div>
<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"></div><div class="col-right"><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated">
Last generated:
<time itemprop="dateModified" datetime="2020-07-09T23:48:39Z" title="Thursday, July 9, 2020 11:48:39 PM GMT">2020-07-09 23:48:39 GMT</time> </p>
<p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2020
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a> </p>
</div></div></div></body>
</html>