freemarker-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ddek...@apache.org
Subject [18/32] incubator-freemarker git commit: FREEMARKER-16: Fixed incorrect js_string and json_string documentation.
Date Sat, 26 Mar 2016 15:41:32 GMT
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
Commit: da3b1a6811a3db1dff276b840c0147718bc9c4ea
Parents: 6b51f59
Author: ddekany <ddekany@apache.org>
Authored: Mon Mar 14 14:52:35 2016 +0100
Committer: ddekany <ddekany@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 = "&lt;/${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>&gt;</literal> as <literal>\&gt;</literal>
(to
-          avoid <literal>&lt;/script&gt;</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>&lt;p
+            escaping. Thus, of you don't have <link
+            linkend="pgui_config_outputformatsautoesc">automatic HTML
+            escaping</link>, this is WRONG: <literal>&lt;p
             onclick="alert('${message?js_string}')"&gt;</literal>, and this is
             good: <literal>&lt;p
             onclick="alert('${message?js_string?html}')"&gt;</literal>.</para>
@@ -13362,6 +13351,65 @@ String BEAN_NAME = "${beanName?j_string}";</programlisting>
           <programlisting role="output">&lt;script&gt;
   alert("Welcome Big Joe\'s \"right hand\"!");
 &lt;/script&gt;</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>&lt;</literal> in the escaped string, or if it's at
the
+              beginning of the escaped string</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>&gt;</literal> is escaped as
+              <literal>\&gt;</literal> if the <literal>&gt;</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>&lt;</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>&lt;</literal>, to avoid <literal>&lt;/script&gt;</literal>
-          and such. It will also escape the <literal>&gt;</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 &gt; is escaped
as
+          \u003E (not as \&gt;), 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">


Mime
View raw message