Add XMLSerialize: version and explicit XML declaration

* Explicit XML declaration (SQL/XML:2023, X078)

This patch adds the options INCLUDING XMLDECLARATION and
EXCLUDING XMLDECLARATION to XMLSERIALIZE, allowing users
to explicitly control the presence of the XML declaration
(e.g., <?xml version="1.0" encoding="UTF-8"?>) in the
serialized output of XML values. If neither option is
specified, the output includes the declaration only if the
input XML value already contained one.

* Version support (SQL/XML:2023, X076)

The VERSION option allows specifying the version string
to use in the XML declaration. If specified, the version
must conform to the lexical rules of the XML standard,
e.g., '1.0' or '1.1'. If omitted or NULL, version '1.0'
is assumed.

In DOCUMENT mode, the version string is validated by
libxml2’s `xmlNewDoc()`, which will raise an error for
invalid versions and a warning for unsupported ones.
No validation is performed in CONTENT mode. This option
has no effect unless INCLUDING XMLDECLARATION is also
specified or the input XML value already contains a
declaration.

Examples:

SELECT xmlserialize(
         DOCUMENT xmlval AS text
         VERSION '1.0'
         INCLUDING XMLDECLARATION);

SELECT xmlserialize(
         DOCUMENT xmlval AS text
         EXCLUDING XMLDECLARATION);

This patch also includes regression tests and documentation.

Author: jimjonesbr

doc/src/sgml/datatype.sgml

@@ -4518,7 +4518,10 @@ xml '<foo>bar</foo>'
     <type>xml</type>, uses the function
     <function>xmlserialize</function>:<indexterm><primary>xmlserialize</primary></indexterm>
 <synopsis>
-XMLSERIALIZE ( { DOCUMENT | CONTENT } <replaceable>value</replaceable> AS <replaceable>type</replaceable> [ [ NO ] INDENT ] )
+XMLSERIALIZE ( { DOCUMENT | CONTENT } <replaceable>value</replaceable> AS <replaceable>type</replaceable>
+     [ VERSION <replaceable>xmlversion</replaceable> ]
+     [ INCLUDING XMLDECLARATION | EXCLUDING XMLDECLARATION ]
+     [ [ NO ] INDENT ] )
 </synopsis>
     <replaceable>type</replaceable> can be
     <type>character</type>, <type>character varying</type>, or
@@ -4528,13 +4531,77 @@ XMLSERIALIZE ( { DOCUMENT | CONTENT } <replaceable>value</replaceable> AS <repla
     you to simply cast the value.
    </para>
 
+   <para>
+     The <literal>VERSION</literal> option sets the version string
+     used in the XML declaration. If specified, the value of
+     <replaceable>xmlversion</replaceable> must conform to the lexical
+     rules of the XML standard: it must be a string of the form
+     <literal>'1.'</literal> followed by one or more digits (e.g.,
+     <literal>'1.0'</literal>, <literal>'1.1'</literal>). Versions other
+     than 1.x (e.g., <literal>'2.0'</literal>) are not valid in
+     <literal>DOCUMENT</literal> mode and will result in an error. This format
+     is defined in section 2.8,
+     <ulink url="https://www.w3.org/TR/xml/#sec-prolog-dtd">"Prolog and Document Type Declaration"</ulink>,
+     of the XML standard. If the <literal>VERSION</literal> option is omitted or specified as
+     <literal>NULL</literal>, version <literal>1.0</literal> is used by default.
+
+     In <literal>CONTENT</literal> mode, no validation is performed on the version,
+     and it is emitted as specified if an XML declaration is requested.
+   </para>
+
+    <para>
+     The <literal>INCLUDING XMLDECLARATION</literal> and
+     <literal>EXCLUDING XMLDECLARATION</literal> options control
+     whether the serialized output includes an XML declaration such as
+     <literal>&lt;?xml version="1.0" encoding="UTF-8"?&gt;</literal>.
+     If neither option is specified, the presence of the declaration in
+     the output depends on whether the input <replaceable>value</replaceable>
+     originally contained one.
+
+     The <literal>INCLUDING XMLDECLARATION</literal> option is allowed in both
+     <literal>DOCUMENT</literal> and <literal>CONTENT</literal> modes. In
+     <literal>CONTENT</literal> mode, no structural validation is performed,
+     and the declaration is emitted according to the specified options,
+     even if it would not normally be considered valid by the XML specification.
+   </para>
+
    <para>
     The <literal>INDENT</literal> option causes the result to be
     pretty-printed, while <literal>NO INDENT</literal> (which is the
     default) just emits the original input string.  Casting to a character
     type likewise produces the original string.
    </para>
 
+   <para>
+Examples:
+   </para>
+<screen><![CDATA[
+SELECT
+  xmlserialize(
+    DOCUMENT xmlelement(name foo, xmlelement(name bar,42)) AS text
+    VERSION '1.0'
+    INCLUDING XMLDECLARATION
+    INDENT);
+
+             xmlserialize
+---------------------------------------
+ <?xml version="1.0" encoding="UTF8"?>+
+ <foo>                                +
+   <bar>42</bar>                      +
+ </foo>
+(1 row)
+
+SELECT
+  xmlserialize(
+    DOCUMENT '<?xml version="1.0" encoding="UTF-8"?><foo><bar>42</bar></foo>' AS text
+    EXCLUDING XMLDECLARATION);
+
+       xmlserialize
+--------------------------
+ <foo><bar>42</bar></foo>
+(1 row)
+]]></screen>
+
    <para>
     When a character string value is cast to or from type
     <type>xml</type> without going through <type>XMLPARSE</type> or

src/backend/catalog/sql_features.txt

@@ -665,9 +665,9 @@ X072	XMLSerialize: character string serialization			YES
 X073	XMLSerialize: binary string serialization and CONTENT option			NO	
 X074	XMLSerialize: binary string serialization and DOCUMENT option			NO	
 X075	XMLSerialize: binary string serialization			NO	
-X076	XMLSerialize: VERSION			NO	
+X076	XMLSerialize: VERSION			YES	
 X077	XMLSerialize: explicit ENCODING option			NO	
-X078	XMLSerialize: explicit XML declaration			NO	
+X078	XMLSerialize: explicit XML declaration			YES	
 X080	Namespaces in XML publishing			NO	
 X081	Query-level XML namespace declarations			NO	
 X082	XML namespace declarations in DML			NO	

src/backend/executor/execExprInterp.c

@@ -4621,7 +4621,9 @@ ExecEvalXmlExpr(ExprState *state, ExprEvalStep *op)
 				*op->resvalue =
 					PointerGetDatum(xmltotext_with_options(DatumGetXmlP(value),
 														   xexpr->xmloption,
-														   xexpr->indent));
+														   xexpr->indent,
+														   xexpr->xmldeclaration,
+														   xexpr->version));
 				*op->resnull = false;
 			}
 			break;

src/backend/parser/gram.y

@@ -626,6 +626,8 @@ static Node *makeRecursiveViewSelect(char *relname, List *aliases, Node *query);
 %type <defelt>	xmltable_column_option_el
 %type <list>	xml_namespace_list
 %type <target>	xml_namespace_el
+%type <ival> 	opt_xml_declaration_option
+%type <str>		opt_xml_declaration_version xmlserialize_version
 
 %type <node>	func_application func_expr_common_subexpr
 %type <node>	func_expr func_expr_windowless
@@ -794,8 +796,8 @@ static Node *makeRecursiveViewSelect(char *relname, List *aliases, Node *query);
 
 	WHEN WHERE WHITESPACE_P WINDOW WITH WITHIN WITHOUT WORK WRAPPER WRITE
 
-	XML_P XMLATTRIBUTES XMLCONCAT XMLELEMENT XMLEXISTS XMLFOREST XMLNAMESPACES
-	XMLPARSE XMLPI XMLROOT XMLSERIALIZE XMLTABLE
+	XML_P XMLATTRIBUTES XMLCONCAT XMLDECLARATION XMLELEMENT XMLEXISTS XMLFOREST
+	XMLNAMESPACES XMLPARSE XMLPI XMLROOT XMLSERIALIZE XMLTABLE
 
 	YEAR_P YES_P
 
@@ -16200,14 +16202,16 @@ func_expr_common_subexpr:
 					$$ = makeXmlExpr(IS_XMLROOT, NULL, NIL,
 									 list_make3($3, $5, $6), @1);
 				}
-			| XMLSERIALIZE '(' document_or_content a_expr AS SimpleTypename xml_indent_option ')'
+			| XMLSERIALIZE '(' document_or_content a_expr AS SimpleTypename opt_xml_declaration_version opt_xml_declaration_option xml_indent_option ')'
 				{
 					XmlSerialize *n = makeNode(XmlSerialize);
 
 					n->xmloption = $3;
 					n->expr = $4;
 					n->typeName = $6;
-					n->indent = $7;
+					n->version = $7;
+					n->xmldeclaration = $8;
+					n->indent = $9;
 					n->location = @1;
 					$$ = (Node *) n;
 				}
@@ -16432,6 +16436,21 @@ xml_indent_option: INDENT							{ $$ = true; }
 			| /*EMPTY*/								{ $$ = false; }
 		;
 
+xmlserialize_version:
+			VERSION_P Sconst		{ $$ = $2; }
+		|	VERSION_P NULL_P		{ $$ = NULL; }
+		;
+
+opt_xml_declaration_version:
+			xmlserialize_version	{ $$ = $1; }
+			| /*EMPTY*/				{ $$ = NULL; }
+		;
+
+opt_xml_declaration_option: INCLUDING XMLDECLARATION	{ $$ = XMLSERIALIZE_INCLUDING_XMLDECLARATION; }
+			| EXCLUDING XMLDECLARATION					{ $$ = XMLSERIALIZE_EXCLUDING_XMLDECLARATION; }
+			| /*EMPTY*/									{ $$ = XMLSERIALIZE_NO_XMLDECLARATION_OPTION; }
+		;
+
 xml_whitespace_option: PRESERVE WHITESPACE_P		{ $$ = true; }
 			| STRIP_P WHITESPACE_P					{ $$ = false; }
 			| /*EMPTY*/								{ $$ = false; }
@@ -18126,6 +18145,7 @@ unreserved_keyword:
 			| WRAPPER
 			| WRITE
 			| XML_P
+			| XMLDECLARATION
 			| YEAR_P
 			| YES_P
 			| ZONE
@@ -18784,6 +18804,7 @@ bare_label_keyword:
 			| XML_P
 			| XMLATTRIBUTES
 			| XMLCONCAT
+			| XMLDECLARATION
 			| XMLELEMENT
 			| XMLEXISTS
 			| XMLFOREST

src/backend/parser/parse_expr.c

@@ -2502,6 +2502,8 @@ transformXmlSerialize(ParseState *pstate, XmlSerialize *xs)
 
 	xexpr->xmloption = xs->xmloption;
 	xexpr->indent = xs->indent;
+	xexpr->version = xs->version;
+	xexpr->xmldeclaration = xs->xmldeclaration;
 	xexpr->location = xs->location;
 	/* We actually only need these to be able to parse back the expression. */
 	xexpr->type = targetType;

src/backend/utils/adt/ruleutils.c

@@ -10232,6 +10232,15 @@ get_rule_expr(Node *node, deparse_context *context,
 					appendStringInfo(buf, " AS %s",
 									 format_type_with_typemod(xexpr->type,
 															  xexpr->typmod));
+
+					if (xexpr->version)
+						appendStringInfo(buf, " VERSION '%s'", xexpr->version);
+
+					if (xexpr->xmldeclaration == XMLSERIALIZE_INCLUDING_XMLDECLARATION)
+						appendStringInfoString(buf, " INCLUDING XMLDECLARATION");
+					else if (xexpr->xmldeclaration == XMLSERIALIZE_EXCLUDING_XMLDECLARATION)
+						appendStringInfoString(buf, " EXCLUDING XMLDECLARATION");
+
 					if (xexpr->indent)
 						appendStringInfoString(buf, " INDENT");
 					else