summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBruce Momjian2007-01-30 22:29:40 +0000
committerBruce Momjian2007-01-30 22:29:40 +0000
commitc422008204951a63613d6ea2172397e32738e57c (patch)
tree32b12d76716509debf69014e6bab53f380c58217
parent199d4f56d196356891a07922be2fc0194cf582e0 (diff)
Update documentation for backslashes to mention escape string syntax
more, and standard_conforming_strings less, because in the future non-E strings will not treat backslashes specially. Also use E'' strings where backslashes are used in examples. (The existing examples would have drawn warnings.) Backpatch to 8.2.X.
-rw-r--r--doc/src/sgml/array.sgml16
-rw-r--r--doc/src/sgml/datatype.sgml44
-rw-r--r--doc/src/sgml/func.sgml48
-rw-r--r--doc/src/sgml/libpq.sgml4
-rw-r--r--doc/src/sgml/plperl.sgml8
-rw-r--r--doc/src/sgml/plpgsql.sgml10
-rw-r--r--doc/src/sgml/pltcl.sgml10
-rw-r--r--doc/src/sgml/rowtypes.sgml5
-rw-r--r--doc/src/sgml/xfunc.sgml6
9 files changed, 73 insertions, 78 deletions
diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index 35dbf6e5cf..cdd5529915 100644
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -597,17 +597,17 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
</para>
<para>
- As shown previously, when writing an array value you may write double
+ As shown previously, when writing an array value you can write double
quotes around any individual array element. You <emphasis>must</> do so
if the element value would otherwise confuse the array-value parser.
For example, elements containing curly braces, commas (or whatever the
delimiter character is), double quotes, backslashes, or leading or trailing
whitespace must be double-quoted. Empty strings and strings matching the
word <literal>NULL</> must be quoted, too. To put a double quote or
- backslash in a
- quoted array element value, precede it with a backslash. Alternatively, you
- can use backslash-escaping to protect all data characters that would
- otherwise be taken as array syntax.
+ backslash in a quoted array element value, use escape string syntax
+ and precede it with a backslash. Alternatively, you can use
+ backslash-escaping to protect all data characters that would otherwise
+ be taken as array syntax.
</para>
<para>
@@ -625,16 +625,16 @@ SELECT f1[1][-2][3] AS e1, f1[1][-1][5] AS e2
backslashes you need. For example, to insert a <type>text</> array
value containing a backslash and a double quote, you'd need to write
<programlisting>
-INSERT ... VALUES ('{"\\\\","\\""}');
+INSERT ... VALUES (E'{"\\\\","\\""}');
</programlisting>
- The string-literal processor removes one level of backslashes, so that
+ The escape string processor removes one level of backslashes, so that
what arrives at the array-value parser looks like <literal>{"\\","\""}</>.
In turn, the strings fed to the <type>text</> data type's input routine
become <literal>\</> and <literal>"</> respectively. (If we were working
with a data type whose input routine also treated backslashes specially,
<type>bytea</> for example, we might need as many as eight backslashes
in the command to get one backslash into the stored array element.)
- Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) may be
+ Dollar quoting (see <xref linkend="sql-syntax-dollar-quoting">) can be
used to avoid the need to double backslashes.
</para>
</note>
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 623a4b34fa..04ba4f8108 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1152,11 +1152,9 @@ SELECT b, char_length(b) FROM test2;
of a string literal in an <acronym>SQL</acronym> statement. In
general, to escape an octet, it is converted into the three-digit
octal number equivalent of its decimal octet value, and preceded
- by two backslashes (or one backslash if
- <varname>standard_conforming_strings</> is <literal>off</>).
- <xref linkend="datatype-binary-sqlesc"> shows the characters
- that must be escaped, and gives the alternate escape sequences
- where applicable.
+ by two backslashes. <xref linkend="datatype-binary-sqlesc">
+ shows the characters that must be escaped, and gives the alternate
+ escape sequences where applicable.
</para>
<table id="datatype-binary-sqlesc">
@@ -1176,32 +1174,32 @@ SELECT b, char_length(b) FROM test2;
<row>
<entry>0</entry>
<entry>zero octet</entry>
- <entry><literal>'\\000'</literal></entry>
- <entry><literal>SELECT '\\000'::bytea;</literal></entry>
+ <entry><literal>E'\\000'</literal></entry>
+ <entry><literal>SELECT E'\\000'::bytea;</literal></entry>
<entry><literal>\000</literal></entry>
</row>
<row>
<entry>39</entry>
<entry>single quote</entry>
- <entry><literal>'\''</literal> or <literal>'\\047'</literal></entry>
- <entry><literal>SELECT '\''::bytea;</literal></entry>
+ <entry><literal>''''</literal> or <literal>E'\\047'</literal></entry>
+ <entry><literal>SELECT E'\''::bytea;</literal></entry>
<entry><literal>'</literal></entry>
</row>
<row>
<entry>92</entry>
<entry>backslash</entry>
- <entry><literal>'\\\\'</literal> or <literal>'\\134'</literal></entry>
- <entry><literal>SELECT '\\\\'::bytea;</literal></entry>
+ <entry><literal>E'\\\\'</literal> or <literal>E'\\134'</literal></entry>
+ <entry><literal>SELECT E'\\\\'::bytea;</literal></entry>
<entry><literal>\\</literal></entry>
</row>
<row>
<entry>0 to 31 and 127 to 255</entry>
<entry><quote>non-printable</quote> octets</entry>
- <entry><literal>'\\<replaceable>xxx'</></literal> (octal value)</entry>
- <entry><literal>SELECT '\\001'::bytea;</literal></entry>
+ <entry><literal>E'\\<replaceable>xxx'</></literal> (octal value)</entry>
+ <entry><literal>SELECT E'\\001'::bytea;</literal></entry>
<entry><literal>\001</literal></entry>
</row>
@@ -1224,18 +1222,18 @@ SELECT b, char_length(b) FROM test2;
string written as a string literal must pass through two parse
phases in the <productname>PostgreSQL</productname> server.
The first backslash of each pair is interpreted as an escape
- character by the string-literal parser (assuming
- <varname>standard_conforming_strings</> is <literal>off</>)
- and is therefore consumed, leaving the second backslash of the
- pair. The remaining backslash is then recognized by the
+ character by the string-literal parser (assuming escape string
+ syntax is used) and is therefore consumed, leaving the second backslash of the
+ pair. (Dollar-quoted strings can be used to avoid this level
+ of escaping.) The remaining backslash is then recognized by the
<type>bytea</type> input function as starting either a three
digit octal value or escaping another backslash. For example,
- a string literal passed to the server as <literal>'\\001'</literal>
+ a string literal passed to the server as <literal>E'\\001'</literal>
becomes <literal>\001</literal> after passing through the
- string-literal parser. The <literal>\001</literal> is then sent
+ escape string parser. The <literal>\001</literal> is then sent
to the <type>bytea</type> input function, where it is converted
to a single octet with a decimal value of 1. Note that the
- apostrophe character is not treated specially by <type>bytea</type>,
+ single-quote character is not treated specially by <type>bytea</type>,
so it follows the normal rules for string literals. (See also
<xref linkend="sql-syntax-strings">.)
</para>
@@ -1269,7 +1267,7 @@ SELECT b, char_length(b) FROM test2;
<entry>92</entry>
<entry>backslash</entry>
<entry><literal>\\</literal></entry>
- <entry><literal>SELECT '\\134'::bytea;</literal></entry>
+ <entry><literal>SELECT E'\\134'::bytea;</literal></entry>
<entry><literal>\\</literal></entry>
</row>
@@ -1277,7 +1275,7 @@ SELECT b, char_length(b) FROM test2;
<entry>0 to 31 and 127 to 255</entry>
<entry><quote>non-printable</quote> octets</entry>
<entry><literal>\<replaceable>xxx</></literal> (octal value)</entry>
- <entry><literal>SELECT '\\001'::bytea;</literal></entry>
+ <entry><literal>SELECT E'\\001'::bytea;</literal></entry>
<entry><literal>\001</literal></entry>
</row>
@@ -1285,7 +1283,7 @@ SELECT b, char_length(b) FROM test2;
<entry>32 to 126</entry>
<entry><quote>printable</quote> octets</entry>
<entry>client character set representation</entry>
- <entry><literal>SELECT '\\176'::bytea;</literal></entry>
+ <entry><literal>SELECT E'\\176'::bytea;</literal></entry>
<entry><literal>~</literal></entry>
</row>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6a7682c3f9..5ac4974e56 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1339,7 +1339,7 @@
Encode binary data to <acronym>ASCII</acronym>-only representation. Supported
types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
</entry>
- <entry><literal>encode( '123\\000\\001', 'base64')</literal></entry>
+ <entry><literal>encode( E'123\\000\\001', 'base64')</literal></entry>
<entry><literal>MTIzAAE=</literal></entry>
</row>
@@ -1439,7 +1439,7 @@
<entry>
Return the given string suitably quoted to be used as a string literal
in an <acronym>SQL</acronym> statement string.
- Embedded quotes and backslashes are properly doubled.
+ Embedded single-quotes and backslashes are properly doubled.
</entry>
<entry><literal>quote_literal( 'O\'Reilly')</literal></entry>
<entry><literal>'O''Reilly'</literal></entry>
@@ -2393,7 +2393,7 @@
<secondary>concatenation</secondary>
</indexterm>
</entry>
- <entry><literal>'\\\\Post'::bytea || '\\047gres\\000'::bytea</literal></entry>
+ <entry><literal>E'\\\\Post'::bytea || E'\\047gres\\000'::bytea</literal></entry>
<entry><literal>\\Post'gres\000</literal></entry>
</row>
@@ -2406,7 +2406,7 @@
<primary>get_bit</primary>
</indexterm>
</entry>
- <entry><literal>get_bit('Th\\000omas'::bytea, 45)</literal></entry>
+ <entry><literal>get_bit(E'Th\\000omas'::bytea, 45)</literal></entry>
<entry><literal>1</literal></entry>
</row>
@@ -2419,7 +2419,7 @@
<primary>get_byte</primary>
</indexterm>
</entry>
- <entry><literal>get_byte('Th\\000omas'::bytea, 4)</literal></entry>
+ <entry><literal>get_byte(E'Th\\000omas'::bytea, 4)</literal></entry>
<entry><literal>109</literal></entry>
</row>
@@ -2427,7 +2427,7 @@
<entry><literal><function>octet_length</function>(<parameter>string</parameter>)</literal></entry>
<entry><type>int</type></entry>
<entry>Number of bytes in binary string</entry>
- <entry><literal>octet_length( 'jo\\000se'::bytea)</literal></entry>
+ <entry><literal>octet_length( E'jo\\000se'::bytea)</literal></entry>
<entry><literal>5</literal></entry>
</row>
@@ -2435,7 +2435,7 @@
<entry><literal><function>position</function>(<parameter>substring</parameter> in <parameter>string</parameter>)</literal></entry>
<entry><type>int</type></entry>
<entry>Location of specified substring</entry>
- <entry><literal>position('\\000om'::bytea in 'Th\\000omas'::bytea)</literal></entry>
+ <entry><literal>position(E'\\000om'::bytea in E'Th\\000omas'::bytea)</literal></entry>
<entry><literal>3</literal></entry>
</row>
@@ -2449,7 +2449,7 @@
<primary>set_bit</primary>
</indexterm>
</entry>
- <entry><literal>set_bit('Th\\000omas'::bytea, 45, 0)</literal></entry>
+ <entry><literal>set_bit(E'Th\\000omas'::bytea, 45, 0)</literal></entry>
<entry><literal>Th\000omAs</literal></entry>
</row>
@@ -2463,7 +2463,7 @@
<primary>set_byte</primary>
</indexterm>
</entry>
- <entry><literal>set_byte('Th\\000omas'::bytea, 4, 64)</literal></entry>
+ <entry><literal>set_byte(E'Th\\000omas'::bytea, 4, 64)</literal></entry>
<entry><literal>Th\000o@as</literal></entry>
</row>
@@ -2476,7 +2476,7 @@
<primary>substring</primary>
</indexterm>
</entry>
- <entry><literal>substring('Th\\000omas'::bytea from 2 for 3)</literal></entry>
+ <entry><literal>substring(E'Th\\000omas'::bytea from 2 for 3)</literal></entry>
<entry><literal>h\000o</literal></entry>
</row>
@@ -2492,7 +2492,7 @@
<parameter>bytes</parameter> from the start
and end of <parameter>string</parameter>
</entry>
- <entry><literal>trim('\\000'::bytea from '\\000Tom\\000'::bytea)</literal></entry>
+ <entry><literal>trim(E'\\000'::bytea from E'\\000Tom\\000'::bytea)</literal></entry>
<entry><literal>Tom</literal></entry>
</row>
</tbody>
@@ -2530,7 +2530,7 @@
in <parameter>bytes</parameter> from the start and end of
<parameter>string</parameter>
</entry>
- <entry><literal>btrim('\\000trim\\000'::bytea, '\\000'::bytea)</literal></entry>
+ <entry><literal>btrim(E'\\000trim\\000'::bytea, E'\\000'::bytea)</literal></entry>
<entry><literal>trim</literal></entry>
</row>
@@ -2544,7 +2544,7 @@
Decode binary string from <parameter>string</parameter> previously
encoded with <function>encode</>. Parameter type is same as in <function>encode</>.
</entry>
- <entry><literal>decode('123\\000456', 'escape')</literal></entry>
+ <entry><literal>decode(E'123\\000456', 'escape')</literal></entry>
<entry><literal>123\000456</literal></entry>
</row>
@@ -2558,7 +2558,7 @@
Encode binary string to <acronym>ASCII</acronym>-only representation. Supported
types are: <literal>base64</>, <literal>hex</>, <literal>escape</>.
</entry>
- <entry><literal>encode('123\\000456'::bytea, 'escape')</literal></entry>
+ <entry><literal>encode(E'123\\000456'::bytea, 'escape')</literal></entry>
<entry><literal>123\000456</literal></entry>
</row>
@@ -2577,7 +2577,7 @@
<see>binary strings, length</see>
</indexterm>
</entry>
- <entry><literal>length('jo\\000se'::bytea)</literal></entry>
+ <entry><literal>length(E'jo\\000se'::bytea)</literal></entry>
<entry><literal>5</literal></entry>
</row>
@@ -2588,7 +2588,7 @@
Calculates the MD5 hash of <parameter>string</parameter>,
returning the result in hexadecimal
</entry>
- <entry><literal>md5('Th\\000omas'::bytea)</literal></entry>
+ <entry><literal>md5(E'Th\\000omas'::bytea)</literal></entry>
<entry><literal>8ab2d3c9689aaf18 b4958c334c82d8b1</literal></entry>
</row>
</tbody>
@@ -2812,7 +2812,8 @@ cast(-44 as bit(12)) <lineannotation>111111010100</lineannotation>
<para>
Note that the backslash already has a special meaning in string
literals, so to write a pattern constant that contains a backslash
- you must write two backslashes in an SQL statement. Thus, writing a pattern
+ you must write two backslashes in an SQL statement (assuming escape
+ string syntax is used). Thus, writing a pattern
that actually matches a literal backslash means writing four backslashes
in the statement. You can avoid this by selecting a different escape
character with <literal>ESCAPE</literal>; then a backslash is not special
@@ -3106,7 +3107,7 @@ substring('foobar' from 'o(.)b') <lineannotation>o</lineannotation>
substring matching the entire pattern should be inserted. Write
<literal>\\</> if you need to put a literal backslash in the replacement
text. (As always, remember to double backslashes written in literal
- constant strings.)
+ constant strings, assuming escape string syntax is used.)
The <replaceable>flags</> parameter is an optional text
string containing zero or more single-letter flags that change the
function's behavior. Flag <literal>i</> specifies case-insensitive
@@ -3121,7 +3122,7 @@ regexp_replace('foobarbaz', 'b..', 'X')
<lineannotation>fooXbaz</lineannotation>
regexp_replace('foobarbaz', 'b..', 'X', 'g')
<lineannotation>fooXX</lineannotation>
-regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g')
+regexp_replace('foobarbaz', 'b(..)', E'X\\1Y', 'g')
<lineannotation>fooXarYXazY</lineannotation>
</programlisting>
</para>
@@ -3283,7 +3284,8 @@ regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g')
Remember that the backslash (<literal>\</literal>) already has a special
meaning in <productname>PostgreSQL</> string literals.
To write a pattern constant that contains a backslash,
- you must write two backslashes in the statement.
+ you must write two backslashes in the statement, assuming escape
+ string syntax is used.
</para>
</note>
@@ -3594,7 +3596,7 @@ regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g')
Keep in mind that an escape's leading <literal>\</> will need to be
doubled when entering the pattern as an SQL string constant. For example:
<programlisting>
-'123' ~ '^\\d{3}' <lineannotation>true</lineannotation>
+'123' ~ E'^\\d{3}' <lineannotation>true</lineannotation>
</programlisting>
</para>
</note>
@@ -4756,10 +4758,10 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})');
<listitem>
<para>
If you want to have a double quote in the output you must
- precede it with a backslash, for example <literal>'\\"YYYY
+ precede it with a backslash, for example <literal>E'\\"YYYY
Month\\"'</literal>. <!-- "" font-lock sanity :-) -->
(Two backslashes are necessary because the backslash already
- has a special meaning in a string constant.)
+ has a special meaning when using the escape string syntax.)
</para>
</listitem>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index decfb28f4d..28762dcf07 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -916,7 +916,7 @@ in a numeric form that is much easier to compare against.
<para>
If no value for <literal>standard_conforming_strings</> is reported,
-applications may assume it is <literal>false</>, that is, backslashes
+applications may assume it is <literal>off</>, that is, backslashes
are treated as escapes in string literals. Also, the presence of this
parameter may be taken as an indication that the escape string syntax
(<literal>E'...'</>) is accepted.
@@ -2494,7 +2494,7 @@ unsigned char *PQescapeByteaConn(PGconn *conn,
of a <type>bytea</type> literal in an <acronym>SQL</acronym>
statement. In general, to escape a byte, it is converted into the
three digit octal number equal to the octet value, and preceded by
- one or two backslashes. The single quote (<literal>'</>) and backslash
+ usually two backslashes. The single quote (<literal>'</>) and backslash
(<literal>\</>) characters have special alternative escape
sequences. See <xref linkend="datatype-binary"> for more
information. <function>PQescapeByteaConn</function> performs this
diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml
index 198580de87..0436c73150 100644
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -80,10 +80,10 @@ $$ LANGUAGE plperl;
the function body to be written as a string constant. It is usually
most convenient to use dollar quoting (see <xref
linkend="sql-syntax-dollar-quoting">) for the string constant.
- If you choose to use regular single-quoted string constant syntax,
- you must escape single quote marks (<literal>'</>) and backslashes
- (<literal>\</>) used in the body of the function, typically by
- doubling them (see <xref linkend="sql-syntax-strings">).
+ If you choose to use escape string syntax <literal>E''</>,
+ you must double the single quote marks (<literal>'</>) and backslashes
+ (<literal>\</>) used in the body of the function
+ (see <xref linkend="sql-syntax-strings">).
</para>
<para>
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 0387c70142..accaf398db 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -288,7 +288,8 @@ $$ LANGUAGE plpgsql;
<command>CREATE FUNCTION</command> as a string literal. If you
write the string literal in the ordinary way with surrounding
single quotes, then any single quotes inside the function body
- must be doubled; likewise any backslashes must be doubled.
+ must be doubled; likewise any backslashes must be doubled (assuming
+ escape string syntax is used).
Doubling quotes is at best tedious, and in more complicated cases
the code can become downright incomprehensible, because you can
easily find yourself needing half a dozen or more adjacent quote marks.
@@ -434,13 +435,6 @@ a_output := a_output || $$ if v_$$ || referrer_keys.kind || $$ like '$$
</varlistentry>
</variablelist>
- <para>
- A variant approach is to escape quotation marks in the function body
- with a backslash rather than by doubling them. With this method
- you'll find yourself writing things like <literal>\'\'</> instead
- of <literal>''''</>. Some find this easier to keep track of, some
- do not.
- </para>
</sect2>
</sect1>
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index 4509863cdc..a96c337cd8 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -387,11 +387,11 @@ CREATE FUNCTION t1_count(integer, integer) RETURNS integer AS $$
$$ LANGUAGE pltcl;
</programlisting>
- We need backslashes inside the query string given to
- <function>spi_prepare</> to ensure that the
- <literal>$<replaceable>n</replaceable></> markers will be passed
- through to <function>spi_prepare</> as-is, and not replaced by Tcl
- variable substitution.
+ We need backslashes inside the query string given to
+ <function>spi_prepare</> to ensure that the
+ <literal>$<replaceable>n</replaceable></> markers will be passed
+ through to <function>spi_prepare</> as-is, and not replaced by Tcl
+ variable substitution.
</para>
</listitem>
diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml
index 1ba5c43faa..349b3e43a2 100644
--- a/doc/src/sgml/rowtypes.sgml
+++ b/doc/src/sgml/rowtypes.sgml
@@ -294,11 +294,12 @@ INSERT INTO mytab (complex_col.r, complex_col.i) VALUES(1.1, 2.2);
<para>
Remember that what you write in an SQL command will first be interpreted
as a string literal, and then as a composite. This doubles the number of
- backslashes you need. For example, to insert a <type>text</> field
+ backslashes you need (assuming escape string syntax is used).
+ For example, to insert a <type>text</> field
containing a double quote and a backslash in a composite
value, you'd need to write
<programlisting>
-INSERT ... VALUES ('("\\"\\\\")');
+INSERT ... VALUES (E'("\\"\\\\")');
</programlisting>
The string-literal processor removes one level of backslashes, so that
what arrives at the composite-value parser looks like
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 8934a10f51..cea8869f06 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -147,9 +147,9 @@ SELECT clean_emp();
most convenient to use dollar quoting (see <xref
linkend="sql-syntax-dollar-quoting">) for the string constant.
If you choose to use regular single-quoted string constant syntax,
- you must escape single quote marks (<literal>'</>) and backslashes
- (<literal>\</>) used in the body of the function, typically by
- doubling them (see <xref linkend="sql-syntax-strings">).
+ you must double single quote marks (<literal>'</>) and backslashes
+ (<literal>\</>) (assuming escape string syntax) in the body of
+ the function (see <xref linkend="sql-syntax-strings">).
</para>
<para>