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 2015/09/24 22:21:39 UTC
[06/12] incubator-freemarker git commit: (Documentation
fixes/improvements related to format strings and @)
(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 <dd...@apache.org>
Authored: Fri Sep 18 23:57:02 2015 +0200
Committer: ddekany <dd...@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>
<#-- 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")></programlisting>
+<#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></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"><#assign x = 1.234>
${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"><#-- Predefined format names: -->
+
+${openingTime?string.short}
${openingTime?string.medium}
${openingTime?string.long}
${openingTime?string.full}
@@ -15188,18 +15207,19 @@ ${lastUpdated?string.medium_short} <#-- medium date, short time -->
${lastUpdated?string.xs}
${lastUpdated?string.iso}
+<#-- <link linkend="pgui_config_custom_formats">Programmer-defined formats</link> (starts with @ + letter): -->
+${lastUpdated?string.@lastMod}
+
+<#-- More advanced ISO 8601-related formats: -->
+${lastUpdated?string.iso_m_u}
+${lastUpdated?string.xs_ms_nz}
+
<#-- SimpleDateFormat patterns: -->
${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} <#-- Same as ${lastUpdated?string["yyyy"]} -->
-
-<#-- Advanced ISO 8601-related formats: -->
-${lastUpdated?string.iso_m_u}
-${lastUpdated?string.xs_ms_nz}
-
-<#-- <link linkend="pgui_config_custom_formats">Programmer-defined formats</link> (start with @): -->
-${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}
<#setting locale="en_US">