Doc: improve description of allowed spellings for Boolean input.

tglsfdc · tglsfdc · commit df88137a398b · 2019-06-12T22:54:46.000-04:00
datatype.sgml failed to explain that boolin() accepts any unique prefix of the basic input strings. Indeed it was actively misleading because it called out a few minimal prefixes without mentioning that there were more valid inputs. I also felt that it wasn't doing anybody any favors by conflating SQL key words, valid Boolean input, and string literals containing valid Boolean input. Rewrite in hopes of reducing the confusion. Per bug #15836 from Yuming Wang, as diagnosed by David Johnston. Back-patch to supported branches. Discussion: https://postgr.es/m/15836-656fab055735f511@postgresql.org
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
@@ -2885,37 +2885,36 @@ SELECT EXTRACT(days from '80 hours'::interval);
    </table>
 
    <para>
-    Valid literal values for the <quote>true</quote> state are:
+    Boolean constants can be represented in SQL queries by the SQL
+    key words <literal>TRUE</literal>, <literal>FALSE</literal>,
+    and <literal>NULL</literal>.
+   </para>
+
+   <para>
+    The datatype input function for type <type>boolean</type> accepts these
+    string representations for the <quote>true</quote> state:
     <simplelist>
-     <member><literal>TRUE</literal></member>
-     <member><literal>'t'</literal></member>
-     <member><literal>'true'</literal></member>
-     <member><literal>'y'</literal></member>
-     <member><literal>'yes'</literal></member>
-     <member><literal>'on'</literal></member>
-     <member><literal>'1'</literal></member>
+     <member><literal>true</literal></member>
+     <member><literal>yes</literal></member>
+     <member><literal>on</literal></member>
+     <member><literal>1</literal></member>
     </simplelist>
-    For the <quote>false</quote> state, the following values can be
-    used:
+    and these representations for the <quote>false</quote> state:
     <simplelist>
-     <member><literal>FALSE</literal></member>
-     <member><literal>'f'</literal></member>
-     <member><literal>'false'</literal></member>
-     <member><literal>'n'</literal></member>
-     <member><literal>'no'</literal></member>
-     <member><literal>'off'</literal></member>
-     <member><literal>'0'</literal></member>
+     <member><literal>false</literal></member>
+     <member><literal>no</literal></member>
+     <member><literal>off</literal></member>
+     <member><literal>0</literal></member>
     </simplelist>
+    Unique prefixes of these strings are also accepted, for
+    example <literal>t</literal> or <literal>n</literal>.
     Leading or trailing whitespace is ignored, and case does not matter.
-    The key words
-    <literal>TRUE</literal> and <literal>FALSE</literal> are the preferred
-    (<acronym>SQL</acronym>-compliant) usage.
    </para>
 
    <para>
-    <xref linkend="datatype-boolean-example"> shows that
-    <type>boolean</type> values are output using the letters
-    <literal>t</literal> and <literal>f</literal>.
+    The datatype output function for type <type>boolean</type> always emits
+    either <literal>t</literal> or <literal>f</literal>, as shown in
+    <xref linkend="datatype-boolean-example">.
    </para>
 
    <example id="datatype-boolean-example">
@@ -2937,6 +2936,27 @@ SELECT * FROM test1 WHERE a;
  t | sic est
 </programlisting>
    </example>
+
+   <para>
+    The key words <literal>TRUE</literal> and <literal>FALSE</literal> are
+    the preferred (<acronym>SQL</acronym>-compliant) method for writing
+    Boolean constants in SQL queries.  But you can also use the string
+    representations by following the generic string-literal constant syntax
+    described in <xref linkend="sql-syntax-constants-generic">, for
+    example <literal>'yes'::boolean</literal>.
+   </para>
+
+   <para>
+    Note that the parser automatically understands
+    that <literal>TRUE</literal> and <literal>FALSE</literal> are of
+    type <type>boolean</type>, but this is not so
+    for <literal>NULL</literal> because that can have any type.
+    So in some contexts you might have to cast <literal>NULL</literal>
+    to <type>boolean</type> explicitly, for
+    example <literal>NULL::boolean</literal>.  Conversely, the cast can be
+    omitted from a string-literal Boolean value in contexts where the parser
+    can deduce that the literal must be of type <type>boolean</type>.
+   </para>
   </sect1>
 
   <sect1 id="datatype-enum">
