Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
no edit summary
This page is part of the [[XQuery|XQuery Portal]].
Serialization parameters define how XQuery items and XML nodes will be ''serialized'' (i.e., returned to the client or an API, usually in textual form). The official parameters are defined in the [httphttps://www.w3.org/TR/xslt-xquery-serialization-31 W3C XQuery Serialization 3.1] document. In BaseX, they can be specified by:
* including them included in the [[XQuery_3.0#Serialization|prolog of the XQuery expression]];* specifying them specified in the XQuery functions [[File_Module#file:write({{Function|File|file:write()]] or [[XQuery_3.0#Functions|fn:serialize()]]. The serialization parameters are specified as** children of an }}, {{CodeFunction|Database|<outputdb:serialization-parameters/>export}} element, as defined for the [httphttps://www.w3.org/TR/xpath-functions-3031/#func-serialize fn:serialize()] function, or as);** map, which contains all key/value pairs: <code>map { "method": "xml", "cdata-section-elements": "div", ... }</code>specified in [[REST#Parameters|REST query parameters]];* using the {{Code|-s}} flag of the BaseX specified in [[Command-Line OptionsRESTXQ#BaseX StandaloneOutput|command-lineRESTXQ output annotations]] clients;* setting set via the {{Option|SERIALIZER}} option before running a query;* setting set via the {{Option|EXPORTER}} option before exporting a database; or* setting them as supplied with the {{Code|-s}} flag of the BaseX [[RESTCommand-Line Options#ParametersBaseX Standalone|RESTcommand-line]] clients. The namespace for serialization parameters is statically bound to the {{Code|output}} prefix. This means that it need not (but may) be declared in the query parametersprolog: <syntaxhighlight lang="xquery">declare namespace output = 'http://www.w3.org/2010/xslt-xquery-serialization';declare option output:method 'text';<xml>Hi there</xml></syntaxhighlight>
Due to the wide range of ways how parameters can be supplied, we deliberately ignored one rule of the specification, which requires non-official features to be defined in a non-null namespace URI. In the following, we will indicate which features are specific to our implementation.
| {{Code|encoding}}
| Encoding to be used for outputting the data.
| ''[httphttps://docs.oracle.com/javase/78/docs/technotes/guides/intl/encoding.doc.html all encodings supported by Java]''
| {{Code|UTF-8}}
|- valign="top"
|- valign="top"
| {{Code|parameter-document}}
| Parses the value as XML document with additional serialization parameters (see the [httphttps://www.w3.org/TR/xslt-xquery-serialization-31/#serparams-in-xdm-instance Serialization Specification] for more details).
|
|
| Inserts a {{Code|meta}} content-type element into the head element if the result is output as HTML<br />Example: <code><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"></head></code>. The head element must already exist or nothing will be added. Any existing {{Code|meta}} content-type elements will be removed.
| {{Code|yes}}, {{Code|no}}
| {{Version|9.2}}: {{Code|yes}}
|}
The {{Code|csv}} and {{Code|json}} parameters are supplied with a list of options. Option names and values are combined with <code>=</code>, several options are separated by <code>,</code>:
<pre classsyntaxhighlight lang="brush:xquery">(: The output namespace declaration is optional, because it is statically declared in BaseX) :)declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
declare option output:method "csv";
declare option output:csv "header=yes, separator=semicolon";
</record>
</csv>
</presyntaxhighlight>
If {{Code|fn:serialize}} is called, output-specific parameters can be supplied via nested options:
<pre classsyntaxhighlight lang="brush:xquery">
serialize(
<csv>
}
)
</presyntaxhighlight>
'''Result''':
<pre classsyntaxhighlight lang="brush:xml">
Name;City
John;Newton
Jack;Oldtown
</presyntaxhighlight>
=Character mappings=
Character maps allow a specific character in the instance of the data model to be replaced with a specified string of characters during serialization. The string that is substituted is output "as is," and the serializer performs no checks that the resulting document is well-formed. This may only occur in documents parsed with {{Code|parameter-document}}. If a character is mapped, then it is not subjected to XML or HTML escaping. For details refer to section [https://www.w3.org/TR/2015/CR-xslt-xquery-serialization-31-20151217/#character-maps 11 Character maps] in the [httphttps://www.w3.org/TR/xslt-xquery-serialization-31 W3C XQuery Serialization 3.1] document
This example maps the Unicode U+00A0 NO-BREAK SPACE as &#160; (without the serialization parameter, the Unicode character would be output):
'''Example query''':
<pre classsyntaxhighlight lang="brush:xquery">
declare option output:parameter-document "map.xml";
<x>&#xA0;</x>
</presyntaxhighlight>
'''Example parameter-document''':
<pre classsyntaxhighlight lang="brush:xml">
<serialization-parameters
xmlns="http://www.w3.org/2010/xslt-xquery-serialization">
</use-character-maps>
</serialization-parameters>
</presyntaxhighlight>
=Changelog=
* Added: official {{Code|item-separator}} and {{Code|html-version}} parameter.
* Updated: <code>method=html5</code> removed; serializers updated with the [httphttps://www.w3.org/TR/2013/WD-xslt-xquery-serialization-30-20130108/ latest version of the specification], using <code>method=html</code> and <code>version=5.0</code>.
;Version 7.2
