freemarker-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ddek...@apache.org
Subject [06/12] incubator-freemarker git commit: (Documentation fixes/improvements related to format strings and @)
Date Thu, 24 Sep 2015 20:21:39 GMT
(Documentation fixes/improvements related to format strings and @)


Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/9c2b9c87
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/9c2b9c87
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/9c2b9c87

Branch: refs/heads/2.3
Commit: 9c2b9c871aeb80d5c3fbe595b65e79fc363af06f
Parents: 8e7c80a
Author: ddekany <ddekany@apache.org>
Authored: Fri Sep 18 23:57:02 2015 +0200
Committer: ddekany <ddekany@apache.org>
Committed: Fri Sep 18 23:57:02 2015 +0200

----------------------------------------------------------------------
 src/main/java/freemarker/core/Configurable.java |  26 ++---
 src/manual/book.xml                             | 113 ++++++++++++-------
 2 files changed, 85 insertions(+), 54 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/9c2b9c87/src/main/java/freemarker/core/Configurable.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/Configurable.java b/src/main/java/freemarker/core/Configurable.java
index 4ad0a2e..e7b9a99 100644
--- a/src/main/java/freemarker/core/Configurable.java
+++ b/src/main/java/freemarker/core/Configurable.java
@@ -726,10 +726,10 @@ public class Configurable {
      *       rounding mode, and {@code _} as the group separator. See more about "extended
Java decimal format" in the
      *       FreeMarker Manual.
      *       </li>
-     *   <li>If the string starts with {@code @} character then it's interpreted as
a custom number format, but only if
-     *       either {@link Configuration#getIncompatibleImprovements()} is at least 2.3.24,
or there's any custom
-     *       formats defined (even if custom date/time/dateTime format). The format of a
such string is
-     *       <code>"@<i>name</i>"</code> or <code>"@<i>name</i>
<i>parameters</i>"</code>, where
+     *   <li>If the string starts with {@code @} character followed by a letter then
it's interpreted as a custom number
+     *       format, but only if either {@link Configuration#getIncompatibleImprovements()}
is at least 2.3.24, or
+     *       there's any custom formats defined (even if custom date/time/dateTime format).
The format of a such string
+     *       is <code>"@<i>name</i>"</code> or <code>"@<i>name</i>
<i>parameters</i>"</code>, where
      *       <code><i>name</i></code> is the key in the {@link Map}
set by {@link #setCustomNumberFormats(Map)}, and
      *       <code><i>parameters</i></code> is parsed by the custom
{@link TemplateNumberFormat}.
      *   </li>
@@ -772,10 +772,10 @@ public class Configurable {
     /**
      * Associates names with formatter factories, which then can be referred by the {@link
#setNumberFormat(String)
      * number_format} setting with values starting with <code>@<i>name</i></code>.
Beware, if you specify any custom
-     * formats here, an initial {@code @} will have special meaning in number/date/time/datetime
format strings, even if
-     * {@link Configuration#getIncompatibleImprovements() incompatible_improvements} is less
than 2.3.24 (starting with
-     * {@link Configuration#getIncompatibleImprovements() incompatible_improvements} 2.3.24
{@code @} always has special
-     * meaning).
+     * formats here, an initial {@code @} followed by a letter will have special meaning
in number/date/time/datetime
+     * format strings, even if {@link Configuration#getIncompatibleImprovements() incompatible_improvements}
is less
+     * than 2.3.24 (starting with {@link Configuration#getIncompatibleImprovements() incompatible_improvements}
2.3.24
+     * {@code @} always has special meaning).
      * 
      * @param customNumberFormats
      *            Can't be {@code null}. The name must start with an UNICODE letter, and
can only contain UNICODE
@@ -1102,7 +1102,7 @@ public class Configurable {
      *       them with {@code _}, like {@code "short_medium"}. ({@code "medium"} means
      *       {@code "medium_medium"} for date-time values.)
      *       
-     *   <li><p>Anything that starts with {@code "@"} is interpreted as a custom
+     *   <li><p>Anything that starts with {@code "@"} followed by a letter is
interpreted as a custom
      *       date/time/dateTime format, but only if either {@link Configuration#getIncompatibleImprovements()}
      *       is at least 2.3.24, or there's any custom formats defined (even if custom number
format). The format of
      *       such string is <code>"@<i>name</i>"</code> or <code>"@<i>name</i>
<i>parameters</i>"</code>, where
@@ -1148,10 +1148,10 @@ public class Configurable {
      * Associates names with formatter factories, which then can be referred by the {@link
#setDateTimeFormat(String)
      * date_format}, {@link #setDateTimeFormat(String) time_format}, and {@link #setDateTimeFormat(String)
      * datetime_format} settings with values starting with <code>@<i>name</i></code>.
Beware, if you specify any custom
-     * formats here, an initial {@code @} will have special meaning in number/date/time/datetime
format strings, even if
-     * {@link Configuration#getIncompatibleImprovements() incompatible_improvements} is less
than 2.3.24 (starting with
-     * {@link Configuration#getIncompatibleImprovements() incompatible_improvements} 2.3.24
{@code @} always has special
-     * meaning).
+     * formats here, an initial {@code @} followed by a letter will have special meaning
in number/date/time/datetime
+     * format strings, even if {@link Configuration#getIncompatibleImprovements() incompatible_improvements}
is less
+     * than 2.3.24 (starting with {@link Configuration#getIncompatibleImprovements() incompatible_improvements}
2.3.24
+     * {@code @} always has special meaning).
      *
      * @param customDateFormats
      *            Can't be {@code null}. The name must start with an UNICODE letter, and
can only contain UNICODE

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/9c2b9c87/src/manual/book.xml
----------------------------------------------------------------------
diff --git a/src/manual/book.xml b/src/manual/book.xml
index 0506f18..fe7ab96 100644
--- a/src/manual/book.xml
+++ b/src/manual/book.xml
@@ -12314,7 +12314,10 @@ Green Mouse</programlisting>
 &lt;#-- Parsing with SimpleDateFormat patterns: --&gt;
 &lt;#assign someDate = "10/25/1995"?date("MM/dd/yyyy")&gt;
 &lt;#assign someTime = "15:05:30"?time("HH:mm:ss")&gt;
-&lt;#assign someDatetime = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")&gt;</programlisting>
+&lt;#assign someDatetime = "1995-10-25 03:05 PM"?datetime("yyyy-MM-dd hh:mm a")&gt;
+
+&lt;#-- Parsing with custom date formats: --&gt;
+&lt;#assign someDatetime = "October/25/1995 03:05 PM"?datetime.@worklog&gt;</programlisting>
 
           <para>To prevent misunderstandings, the left-hand value need not be
           a string literal. For example, when you read data from XML DOM (from
@@ -14468,11 +14471,25 @@ $42.00
 
           <para>since the default number format was set to "currency".</para>
 
-          <para>Beside the three predefined formats, you can use arbitrary
-          number format patterns written in <link
+          <para>You can also refer to named custom formats that were defined
+          when configuring FreeMarker (programmers <link
+          linkend="pgui_config_custom_formats">see more here</link>),
+          like:</para>
+
+          <programlisting>${x?strong.@price}
+${x?strong.@weight}</programlisting>
+
+          <para>where the custom format names were <quote>price</quote>
and
+          <quote>weight</quote>. Note that hence the templates can just refer
+          to the application-domain meaning, and the exact format can be
+          specified outside the templates, on a single central place.</para>
+
+          <para>Beside named formats, you can specify number format patterns
+          directly, using the <link
           xlink:href="http://docs.oracle.com/javase/7/docs/api/java/text/DecimalFormat.html">Java
           decimal number format syntax</link> (with some FreeMarker-specific
-          extensions; see later):</para>
+          extensions; <link linkend="topic.extendedJavaDecimalFormat">see
+          later</link>):</para>
 
           <programlisting role="template">&lt;#assign x = 1.234&gt;
 ${x?string["0"]}
@@ -15166,7 +15183,9 @@ The usual variations are supported:
           <literal>java.sql.Timestamp</literal> or
           <literal>java.util.Date</literal> then this:</para>
 
-          <programlisting role="template">${openingTime?string.short}
+          <programlisting role="template">&lt;#-- Predefined format names: --&gt;
+
+${openingTime?string.short}
 ${openingTime?string.medium}
 ${openingTime?string.long}
 ${openingTime?string.full}
@@ -15188,18 +15207,19 @@ ${lastUpdated?string.medium_short} &lt;#-- medium date, short
time --&gt;
 ${lastUpdated?string.xs}
 ${lastUpdated?string.iso}
 
+&lt;#-- <link linkend="pgui_config_custom_formats">Programmer-defined formats</link>
(starts with @ + letter): --&gt;
+${lastUpdated?string.@lastMod}
+
+&lt;#-- More advanced ISO 8601-related formats: --&gt;
+${lastUpdated?string.iso_m_u}
+${lastUpdated?string.xs_ms_nz}
+
 &lt;#-- SimpleDateFormat patterns: --&gt;
 ${lastUpdated?string["dd.MM.yyyy, HH:mm"]}
 ${lastUpdated?string["EEEE, MMMM dd, yyyy, hh:mm a '('zzz')'"]}
 ${lastUpdated?string["EEE, MMM d, ''yy"]}
 ${lastUpdated?string.yyyy} &lt;#-- Same as ${lastUpdated?string["yyyy"]} --&gt;
-
-&lt;#-- Advanced ISO 8601-related formats: --&gt;
-${lastUpdated?string.iso_m_u}
-${lastUpdated?string.xs_ms_nz}
-
-&lt;#-- <link linkend="pgui_config_custom_formats">Programmer-defined formats</link>
(start with @): --&gt;
-${lastUpdated?string.@file} (or however it was configured)</programlisting>
+</programlisting>
 
           <para>will print something like this:</para>
 
@@ -15225,15 +15245,20 @@ Feb 8, 2003 9:24 PM
 2007-02-20T13:45:09-08:00
 2007-02-20T13:45:09-08:00
 
-08.04.2003 21:24
-Tuesday, April 08, 2003, 09:24 PM (PDT)
-Tue, Apr 8, '03
-2003
+Apr/20/2007 13:45
 
 2007-02-20T21:45Z
 2007-02-20T13:45:09.000
 
-2007-02-20 13 (or however it was configured)</programlisting>
+08.04.2003 21:24
+Tuesday, April 08, 2003, 09:24 PM (PDT)
+Tue, Apr 8, '03
+2003</programlisting>
+
+          <para>Note that with custom formats like in
+          <literal>lastUpdated?string.@lastMod</literal> above, templates can
+          just refer to the application-domain meaning, and the exact format
+          can be specified outside the templates, on a central place.</para>
 
           <warning>
             <para>Unfortunately, because of the limitations of the Java
@@ -20572,18 +20597,22 @@ ${"'{}"}
                 </listitem>
 
                 <listitem>
-                  <para>Values starting with <literal>@</literal> refer
to a
-                  <link linkend="pgui_config_custom_formats">custom
-                  format</link>, but only if either <link
+                  <para>Values starting with <literal>@</literal> that's
also
+                  followed by a letter, refer to a <link
+                  linkend="pgui_config_custom_formats">custom format</link>.
+                  For example, <literal>"@price"</literal> refers to the
+                  custom format registered with the <literal>"price"</literal>
+                  name. The custom format name is possibly followed by space
+                  or <literal>_</literal> and then format parameters, whose
+                  interpretation depends on the custom format. For backward
+                  compatibility, the initial <literal>@</literal> only has
+                  this new meaning if either <link
                   linkend="pgui_config_incompatible_improvements_how_to_set">the
                   <literal>incompatible_improvements</literal> setting</link>
-                  is at least 2.3.24, or there are some custom formats
-                  defined. For example, <literal>"@price"</literal> refers to
-                  the custom format registered with the
-                  <literal>"price"</literal> name. The custom format name is
-                  possibly followed by space or <literal>_</literal> and then
-                  format parameters, whose interpretation depends on the
-                  custom format.</para>
+                  is at least 2.3.24, or there's any custom formats defined.
+                  When the initial <literal>@</literal> isn't followed by a
+                  letter (any UNICODE letter), it's never treated as a
+                  reference to a custom format.</para>
                 </listitem>
               </itemizedlist>
             </listitem>
@@ -20832,20 +20861,22 @@ ${"'{}"}
                 </listitem>
 
                 <listitem>
-                  <para>Values starting with <literal>@</literal> refer
to a
-                  <link linkend="pgui_config_custom_formats">custom
-                  format</link>, like <literal>"@departure"</literal> refers
-                  to the custom format registered with the
-                  <literal>"departure"</literal> name. The format name is
-                  possibly followed by space or <literal>_</literal> and then
-                  format parameters, whose interpretation depends on the
-                  custom format. For backward compatibility, the initial
-                  <literal>@</literal> only has this new meaning if either
-                  <link
+                  <para>Values starting with <literal>@</literal> that's
also
+                  followed by a letter, refer to a <link
+                  linkend="pgui_config_custom_formats">custom format</link>,
+                  like <literal>"@worklog"</literal> refers to the custom
+                  format registered with the <literal>"worklog"</literal>
+                  name. The format name is possibly followed by space or
+                  <literal>_</literal> and then format parameters, whose
+                  interpretation depends on the custom format. For backward
+                  compatibility, the initial <literal>@</literal> only has
+                  this new meaning if either <link
                   linkend="pgui_config_incompatible_improvements_how_to_set">the
                   <literal>incompatible_improvements</literal> setting</link>
-                  is at least 2.3.24, or there's any custom formats
-                  defined.</para>
+                  is at least 2.3.24, or there's any custom formats defined.
+                  When the initial <literal>@</literal> isn't followed by a
+                  letter (any UNICODE letter), it's never treated as a
+                  reference to a custom format.</para>
                 </listitem>
               </itemizedlist>
             </listitem>
@@ -20930,8 +20961,8 @@ ${"'{}"}
             </listitem>
           </itemizedlist>
 
-          <para>Example: Assume that the initial locale of template is de_DE
-          (German). Then this:</para>
+          <para>Example: Assume that the initial locale of template is
+          <literal>de_DE</literal> (German). Then this:</para>
 
           <programlisting role="template">${1.2}
 &lt;#setting locale="en_US"&gt;


Mime
View raw message