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 2016/03/14 14:53:14 UTC
[1/2] incubator-freemarker git commit: FREEMARKER-16: Fixed incorrect
js_string and json_string documentation.
Repository: incubator-freemarker
Updated Branches:
refs/heads/2.3.24-gae-stabilization 6b51f59d5 -> a925da5da
FREEMARKER-16: Fixed incorrect js_string and json_string documentation.
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/da3b1a68
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/da3b1a68
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/da3b1a68
Branch: refs/heads/2.3.24-gae-stabilization
Commit: da3b1a6811a3db1dff276b840c0147718bc9c4ea
Parents: 6b51f59
Author: ddekany <dd...@apache.org>
Authored: Mon Mar 14 14:52:35 2016 +0100
Committer: ddekany <dd...@apache.org>
Committed: Mon Mar 14 14:52:35 2016 +0100
----------------------------------------------------------------------
.../freemarker/template/utility/StringUtil.java | 8 +-
src/manual/en_US/book.xml | 100 +++++++++++++------
2 files changed, 76 insertions(+), 32 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/da3b1a68/src/main/java/freemarker/template/utility/StringUtil.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/template/utility/StringUtil.java b/src/main/java/freemarker/template/utility/StringUtil.java
index 58d5ffb..88811f4 100644
--- a/src/main/java/freemarker/template/utility/StringUtil.java
+++ b/src/main/java/freemarker/template/utility/StringUtil.java
@@ -1331,12 +1331,12 @@ public class StringUtil {
* output. Note that for JSON, the quotation marks must be {@code "}, not {@code '}, because JSON doesn't escape
* {@code '}.
*
- * <p>The escaping rules guarantee that if the inside
- * of the literal is from one or more touching sections of strings escaped with this, no character sequence will
- * occur that closes the string literal or has special meaning in HTML/XML that can terminate the script section.
+ * <p>The escaping rules guarantee that if the inside of the JavaScript/JSON string literal is from one or more
+ * touching pieces that were escaped with this, no character sequence can occur that closes the
+ * JavaScript/JSON string literal, or has a meaning in HTML/XML that causes the HTML script section to be closed.
* (If, however, the escaped section is preceded by or followed by strings from other sources, this can't be
* guaranteed in some rare cases. Like <tt>x = "</${a?js_string}"</tt> might closes the "script"
- * element if {@code a} is is {@code "script>"}.)
+ * element if {@code a} is {@code "script>"}.)
*
* The escaped characters are:
*
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/da3b1a68/src/manual/en_US/book.xml
----------------------------------------------------------------------
diff --git a/src/manual/en_US/book.xml b/src/manual/en_US/book.xml
index c47f5d9..770418e 100644
--- a/src/manual/en_US/book.xml
+++ b/src/manual/en_US/book.xml
@@ -13328,23 +13328,12 @@ String BEAN_NAME = "${beanName?j_string}";</programlisting>
quotation marks around the inserted value; you meant to use this
<emphasis>inside</emphasis> the string literal.</para>
- <para>Both quotation mark (<literal>"</literal>) and
- apostrophe-quoate (<literal>'</literal>) are escaped. It also
- escapes <literal>></literal> as <literal>\></literal> (to
- avoid <literal></script></literal>).</para>
-
- <para>All characters under <link linkend="gloss.UCS">UCS</link> code
- point 0x20 will be escaped. When they have no dedicated escape
- sequence in JavaScript (like <literal>\n</literal>,
- <literal>\t</literal>, etc.), they will be replaced with a UNICODE
- escape
- (<literal>\u<replaceable>XXXX</replaceable></literal>).</para>
-
<warning>
<para>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 automatic HTML escaping, this is
- WRONG: <literal><p
+ escaping. Thus, of you don't have <link
+ linkend="pgui_config_outputformatsautoesc">automatic HTML
+ escaping</link>, this is WRONG: <literal><p
onclick="alert('${message?js_string}')"></literal>, and this is
good: <literal><p
onclick="alert('${message?js_string?html}')"></literal>.</para>
@@ -13362,6 +13351,65 @@ String BEAN_NAME = "${beanName?j_string}";</programlisting>
<programlisting role="output"><script>
alert("Welcome Big Joe\'s \"right hand\"!");
</script></programlisting>
+
+ <para>The exact escaping rules are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>"</literal> is escaped as
+ <literal>\"</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>'</literal> is escaped as
+ <literal>\'</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>\</literal> is escaped as
+ <literal>\\</literal></para>
+ </listitem>
+
+ <listitem>
+ <para><literal>/</literal> is escaped as <literal>\/</literal>
+ if the <literal>/</literal> is directly after
+ <literal><</literal> in the escaped string, or if it's at the
+ beginning of the escaped string</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>></literal> is escaped as
+ <literal>\></literal> if the <literal>></literal> is
+ directly after <literal>]]</literal> or <literal>--</literal> in
+ the escaped string, or if it's at the beginning of the escaped
+ string, or if there's only a <literal>]</literal> or
+ <literal>-</literal> before it at the beginning of the escaped
+ string</para>
+ </listitem>
+
+ <listitem>
+ <para><literal><</literal> is escaped as
+ <literal>\u003C</literal> if it's followed by
+ <literal>?</literal> or <literal>!</literal> in the escaped
+ string, or if it's at the end of the escaped string</para>
+ </listitem>
+
+ <listitem>
+ <para>Control characters in <link linkend="gloss.UCS">UCS</link>
+ code point ranges U+0000
U+001f and U+007f
U+009f are escaped as
+ <literal>\r</literal>, <literal>\n</literal>, etc., or as
+ <literal>\x<replaceable>XX</replaceable></literal> where there's
+ no special escape for them in JavaScript.</para>
+ </listitem>
+
+ <listitem>
+ <para>Control characters with <link
+ linkend="gloss.UCS">UCS</link> code point U+2028 (Line
+ separator) and U+2029 (Paragraph separator) are escaped as
+ <literal>\u<replaceable>XXXX</replaceable></literal>, as they
+ are source code line-breaks in ECMAScript.</para>
+ </listitem>
+ </itemizedlist>
</section>
<section xml:id="ref_builtin_json_string">
@@ -13378,20 +13426,16 @@ String BEAN_NAME = "${beanName?j_string}";</programlisting>
<emphasis>inside</emphasis> the string literal.</para>
<para>This will not escape <literal>'</literal> characters, since
- JSON strings must be quoted with <literal>"</literal>. It will,
- however escape the <literal>/</literal> (slash) characters as
- <literal>\/</literal> where they occur directly after a
- <literal><</literal>, to avoid <literal></script></literal>
- and such. It will also escape the <literal>></literal> characters
- as <literal>\u003E</literal> where they occur directly after
- <literal>]]</literal>, to avoid exiting an XML
- <literal>CDATA</literal> section.</para>
-
- <para>All characters under <link linkend="gloss.UCS">UCS</link> code
- point 0x20 will be escaped. When they have no dedicated escape
- sequence in JSON (like <literal>\n</literal>, <literal>\t</literal>,
- etc.), they will be replaced with a UNICODE escape
- (<literal>\u<replaceable>XXXX</replaceable></literal>).</para>
+ JSON strings must be quoted with <literal>"</literal>.</para>
+
+ <para>The escaping rules are almost identical to those <link
+ linkend="ref_builtin_j_string">documented for
+ <literal>js_string</literal></link>. The differences are that
+ <literal>'</literal> is not escaped at all, that > is escaped as
+ \u003E (not as \>), and that
+ <literal>\u<replaceable>XXXX</replaceable></literal> escapes are
+ used instead of <literal>\x<replaceable>XX</replaceable></literal>
+ escapes.</para>
</section>
<section xml:id="ref_builtin_keep_after">
[2/2] incubator-freemarker git commit: (JavaDoc typos)
Posted by dd...@apache.org.
(JavaDoc typos)
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/a925da5d
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/a925da5d
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/a925da5d
Branch: refs/heads/2.3.24-gae-stabilization
Commit: a925da5dafec3db731bf41a75e755c42a3de00fb
Parents: da3b1a6
Author: ddekany <dd...@apache.org>
Authored: Mon Mar 14 14:52:58 2016 +0100
Committer: ddekany <dd...@apache.org>
Committed: Mon Mar 14 14:52:58 2016 +0100
----------------------------------------------------------------------
src/main/java/freemarker/core/TemplateConfiguration.java | 4 ++--
src/main/java/freemarker/template/DefaultObjectWrapper.java | 2 +-
2 files changed, 3 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/a925da5d/src/main/java/freemarker/core/TemplateConfiguration.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/TemplateConfiguration.java b/src/main/java/freemarker/core/TemplateConfiguration.java
index 2c89d01..50ebc8f 100644
--- a/src/main/java/freemarker/core/TemplateConfiguration.java
+++ b/src/main/java/freemarker/core/TemplateConfiguration.java
@@ -38,11 +38,11 @@ import freemarker.template.utility.NullArgumentException;
* <p>
* Note on the {@code locale} setting: When used with the standard template loading/caching mechanism (
* {@link Configuration#getTemplate(String)} and its overloads), localized lookup happens before the {@code locale}
- * specified here could have effect. The {@code locale} will be only set in the template that the localized looks has
+ * specified here could have effect. The {@code locale} will be only set in the template that the localized lookup has
* already found.
*
* <p>
- * Note on encoding setting {@code encoding}: See {@link #setEncoding(String)}.
+ * Note on the encoding setting {@code encoding}: See {@link #setEncoding(String)}.
*
* <p>
* Note that the result value of the reader methods (getter and "is" methods) is usually not useful unless the value of
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/a925da5d/src/main/java/freemarker/template/DefaultObjectWrapper.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/template/DefaultObjectWrapper.java b/src/main/java/freemarker/template/DefaultObjectWrapper.java
index bda6f32..8753ebb 100644
--- a/src/main/java/freemarker/template/DefaultObjectWrapper.java
+++ b/src/main/java/freemarker/template/DefaultObjectWrapper.java
@@ -226,7 +226,7 @@ public class DefaultObjectWrapper extends freemarker.ext.beans.BeansWrapper {
}
/**
- * Called for an object that aren't considered to be of a "basic" Java type, like for an application specific type,
+ * Called for an object that isn't considered to be of a "basic" Java type, like for an application specific type,
* or for a W3C DOM node. In its default implementation, W3C {@link Node}-s will be wrapped as {@link NodeModel}-s
* (allows DOM tree traversal), Jython objects will be delegated to the {@code JythonWrapper}, others will be
* wrapped using {@link BeansWrapper#wrap(Object)}.