From bb3cce4ec9cc157a8dfc80b5b1770c2beac0a57e Mon Sep 17 00:00:00 2001
From: Bruce Momjian
Date: Sun, 26 Jun 2005 03:04:37 +0000
Subject: Add E'' syntax so eventually normal strings can treat backslashes
 literally.

Add GUC variables:

        "escape_string_warning" - warn about backslashes in non-E strings
        "escape_string_syntax" - supports E'' syntax?
        "standard_compliant_strings" - treats backslashes literally in ''

Update code to use E'' when escapes are used.
---
 doc/src/sgml/runtime.sgml | 57 ++++++++++++++++++++++++++++++++++++++++++++++-
 doc/src/sgml/syntax.sgml  | 23 +++++++++++++++----
 2 files changed, 75 insertions(+), 5 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 43334453921..3841b0dee2d 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.330 2005/06/21 04:02:30 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.331 2005/06/26 03:03:17 momjian Exp $
 -->
 
 <chapter Id="runtime">
@@ -3757,6 +3757,30 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-escape-string-warning" xreflabel="escape_string_warning">
+      <term><varname>escape_string_warning</varname> (<type>boolean</type>)</term>
+      <indexterm><primary>strings</><secondary>escape</></>
+      <indexterm>
+       <primary><varname>escape_string_warning</> configuration parameter</primary>
+      </indexterm>
+      <listitem>
+       <para>
+        When <literal>on</>, a warning is issued if a backslash
+        (<literal>\</>) appears in a ordinary, non-escape syntax
+        (<literal>''</>) string. To log the statement that generated the
+        warning, set <varname>log_min_error_statement</> to
+        <literal>error</>.  The default is off.
+       </para>
+       <para>
+        Escape string syntax (<literal>E''</>) should be used for
+        escapes, because in future versions of
+        <productname>PostgreSQL</productname> ordinary strings will have
+        the standard-compliant behavior of treating backslashes
+        literally.
+       </para>
+      </listitem>
+     </varlistentry>
+
      </variablelist>
     </sect3>
     <sect3 id="runtime-config-compatible-clients">
@@ -3964,6 +3988,37 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
       </listitem>
      </varlistentry>
 
+     <varlistentry id="guc-escape-string-syntax" xreflabel="escape_string_syntax">
+      <term><varname>escape_string_syntax</varname> (<type>boolean</type>)</term>
+      <indexterm><primary>strings</><secondary>escape</></>
+      <indexterm>
+       <primary><varname>escape_string_syntax</> configuration parameter</primary>
+      </indexterm>
+      <listitem>
+       <para>
+        Reports whether escape string syntax (<literal>E''</>) is
+        supported. This variable is used by applications that need to
+        determine if escape string syntax can be used in their code.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="guc-sql-standard-strings" xreflabel="standard_compliant_strings">
+      <term><varname>standard_compliant_strings</varname> (<type>boolean</type>)</term>
+      <indexterm><primary>strings</><secondary>escape</></>
+      <indexterm>
+       <primary><varname>standard_compliant_strings</> configuration parameter</primary>
+      </indexterm>
+      <listitem>
+       <para>
+        Reports whether ordinary, non-escape syntax strings
+        (<literal>''</>) treat backslashes literally, as specified in
+        the SQL standard. This variable is used by applications that
+        need to know how ordinary strings are processed`.
+       </para>
+      </listitem>
+     </varlistentry>
+
     </variablelist>
    </sect2>
 
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 45b6a80564b..3d8d457c561 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.100 2005/06/02 01:23:08 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/syntax.sgml,v 1.101 2005/06/26 03:03:21 momjian Exp $
 -->
 
 <chapter id="sql-syntax">
@@ -247,9 +247,10 @@ UPDATE "my_table" SET "a" = 5;
      write two adjacent single quotes, e.g.
      <literal>'Dianne''s horse'</literal>.
      <productname>PostgreSQL</productname> also allows single quotes
-     to be escaped with a backslash (<literal>\</literal>), so for
-     example the same string could be written
-     <literal>'Dianne\'s horse'</literal>.
+     to be escaped with a backslash (<literal>\'</literal>).  However,
+     future versions of <productname>PostgreSQL</productname> will not
+     support this so applications using this should convert to the 
+     standard-compliant method outlined above.
     </para>
 
     <para>
@@ -268,6 +269,20 @@ UPDATE "my_table" SET "a" = 5;
      include a backslash in a string constant, write two backslashes.
     </para>
 
+    <note>
+    <para>
+     While ordinary strings now support C-style backslash escapes,
+     future versions will generate warnings for such usage and
+     eventually treat backslashes as literal characters to be
+     standard-compliant. The proper way to specify escape processing is
+     to use the escape string syntax to indicate that escape
+     processing is desired. Escape string syntax is specified by placing
+     the the letter <literal>E</literal> (upper or lower case) before
+     the string, e.g. <literal>E'\041'</>. This method will work in all
+     future versions of <productname>PostgreSQL</productname>.
+    </para>
+    </note>
+
     <para>
      The character with the code zero cannot be in a string constant.
     </para>
-- 
cgit v1.2.3