Difference between revisions of "Serialization"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replace - "{{Mono|" to "{{Code|")
Line 6: Line 6:
 
* by including them in the [[XQuery_3.0#Serialization|prolog of the XQuery expression]],
 
* by including them in the [[XQuery_3.0#Serialization|prolog of the XQuery expression]],
 
* by specifying them in the XQuery functions [[File_Module#file:write|file:write()]] or [[XQuery_3.0#Functions|fn:serialize()]],
 
* by specifying them in the XQuery functions [[File_Module#file:write|file:write()]] or [[XQuery_3.0#Functions|fn:serialize()]],
−
* by using the <code>-s</code> flag of the BaseX [[Startup_Options#BaseX|command-line]] clients,
+
* by using the {{Code|-s}} flag of the BaseX [[Startup_Options#BaseX|command-line]] clients,
 
* by setting the [[Options#SERIALIZER|SERIALIZER]] option before running a query,
 
* by setting the [[Options#SERIALIZER|SERIALIZER]] option before running a query,
 
* by setting the [[Options#EXPORTER|EXPORTER]] option before exporting a database, or
 
* by setting the [[Options#EXPORTER|EXPORTER]] option before exporting a database, or
Line 23: Line 23:
 
! Examples
 
! Examples
 
|- valign="top"
 
|- valign="top"
−
| <code>method</code>
+
| {{Code|method}}
 
| Specifies the serialization method:
 
| Specifies the serialization method:
−
* <code>xml</code>, <code>xhtml</code>, <code>html</code>, and <code>text</code> are adopted from the official specification.
+
* {{Code|xml}}, {{Code|xhtml}}, {{Code|html}}, and {{Code|text}} are adopted from the official specification.
−
* <code>html5</code> is specific to BaseX and can be used to output query results as [http://en.wikipedia.org/wiki/Html5 HTML5].
+
* {{Code|html5}} is specific to BaseX and can be used to output query results as [http://en.wikipedia.org/wiki/Html5 HTML5].
−
* <code>json</code> and <code>jsonml</code> are specific to BaseX and can be used to output XML nodes in the JSON format (see the [[JSON Module]] for more details).
+
* {{Code|json}} and {{Code|jsonml}} are specific to BaseX and can be used to output XML nodes in the JSON format (see the [[JSON Module]] for more details).
−
* <code>raw</code> is BaseX-specific as well: Binary data types are output in their ''raw'' form, i.e., without modifications. For all other types, the items’ string values are returned. No indentation takes place, and and no characters are encoded via entities.
+
* {{Code|raw}} is BaseX-specific as well: Binary data types are output in their ''raw'' form, i.e., without modifications. For all other types, the items’ string values are returned. No indentation takes place, and and no characters are encoded via entities.
−
| <code>xml</code>, <code>xhtml</code>, <code>html</code>, <code>text</code>, <code>html5</code>, <code>json</code>, <code>jsonml</code>, <code>raw</code>
+
| {{Code|xml}}, {{Code|xhtml}}, {{Code|html}}, {{Code|text}}, {{Code|html5}}, {{Code|json}}, {{Code|jsonml}}, {{Code|raw}}
−
| <code>xml</code>
+
| {{Code|xml}}
 
| <code>method=xml</code>
 
| <code>method=xml</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>version</code>
+
| {{Code|version}}
 
| Specifies the version of the serializer.
 
| Specifies the version of the serializer.
−
| <code>xml/xhtml</code>: <code>1.0</code>, <code>1.1</code><br/><code>html</code>: <code>4.0</code>, <code>4.01</code><br/>
+
| {{Code|xml/xhtml}}: {{Code|1.0}}, {{Code|1.1}}<br/>{{Code|html}}: {{Code|4.0}}, {{Code|4.01}}<br/>
−
| <code>1.0</code>
+
| {{Code|1.0}}
 
| <code>version=1.0</code>
 
| <code>version=1.0</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>encoding</code>
+
| {{Code|encoding}}
 
| Encoding to be used for outputting the data.
 
| Encoding to be used for outputting the data.
 
| ''all encodings supported by Java''
 
| ''all encodings supported by Java''
−
| <code>UTF-8</code>
+
| {{Code|UTF-8}}
 
| <code>encoding=US-ASCII</code>
 
| <code>encoding=US-ASCII</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>indent</code>
+
| {{Code|indent}}
 
| Adjusts whitespaces to make the output better readable.
 
| Adjusts whitespaces to make the output better readable.
−
| <code>yes</code>, <code>no</code>
+
| {{Code|yes}}, {{Code|no}}
−
| <code>yes</code>
+
| {{Code|yes}}
 
| <code>indent=no</code>
 
| <code>indent=no</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>cdata-section-elements</code>
+
| {{Code|cdata-section-elements}}
−
| List of elements to be output as CDATA, separated by whitespaces.<br />Example: <code>&lt;text&gt;&lt;![CDATA[ &lt;&gt; ]]&gt;&lt;/text&gt;</code>
+
| List of elements to be output as CDATA, separated by whitespaces.<br />Example: {{Code|&lt;text&gt;&lt;![CDATA[ &lt;&gt; ]]&gt;&lt;/text&gt;}}
 
|  
 
|  
 
|  
 
|  
 
| <code>cdata-section-elements=text</code>
 
| <code>cdata-section-elements=text</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>omit-xml-declaration</code>
+
| {{Code|omit-xml-declaration}}
 
| Omits the XML declaration, which is serialized before the actual query result<br />Example: <code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;</code>
 
| Omits the XML declaration, which is serialized before the actual query result<br />Example: <code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;</code>
−
| <code>yes</code>, <code>no</code>
+
| {{Code|yes}}, {{Code|no}}
−
| <code>yes</code>
+
| {{Code|yes}}
 
| <code>omit-xml-declaration=no</code>
 
| <code>omit-xml-declaration=no</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>standalone</code>
+
| {{Code|standalone}}
 
| Prints or omits the "standalone" attribute in the XML declaration.
 
| Prints or omits the "standalone" attribute in the XML declaration.
−
| <code>yes</code>, <code>no</code>, <code>omit</code>
+
| {{Code|yes}}, {{Code|no}}, {{Code|omit}}
−
| <code>omit</code>
+
| {{Code|omit}}
 
| <code>standalone=yes</code>
 
| <code>standalone=yes</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>doctype-system</code>
+
| {{Code|doctype-system}}
−
| Introduces the output with a document type declaration and the given system identifier.<br />Example: <code>&lt;!DOCTYPE x SYSTEM "entities.dtd"&gt;</code>
+
| Introduces the output with a document type declaration and the given system identifier.<br />Example: {{Code|&lt;!DOCTYPE x SYSTEM "entities.dtd"&gt;}}
 
|
 
|
 
|
 
|
 
| <code>doctype-system=entities.dtd</code>
 
| <code>doctype-system=entities.dtd</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>doctype-public</code>
+
| {{Code|doctype-public}}
−
| If <code>doctype-system</code> is specified, adds a public identifier.<br />Example: <code>&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"&gt;</code>
+
| If {{Code|doctype-system}} is specified, adds a public identifier.<br />Example: {{Code|&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "<nowiki>http://www.w3.org/TR/html4/strict.dtd</nowiki>"&gt;}}
 
|  
 
|  
 
|
 
|
 
| <code>doctype-public=-//W3C//DTD HTML 4.01//EN,<br />doctype-system=http://www.w3.org/TR/html4/strict.dtd</code>
 
| <code>doctype-public=-//W3C//DTD HTML 4.01//EN,<br />doctype-system=http://www.w3.org/TR/html4/strict.dtd</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>undeclare-prefixes</code>
+
| {{Code|undeclare-prefixes}}
 
| Undeclares prefixes in XML 1.1.
 
| Undeclares prefixes in XML 1.1.
−
| <code>yes</code>, <code>no</code>
+
| {{Code|yes}}, {{Code|no}}
−
| <code>no</code>
+
| {{Code|no}}
 
| <code>undeclare-prefixes=yes</code>
 
| <code>undeclare-prefixes=yes</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>normalization-form</code>
+
| {{Code|normalization-form}}
−
| Specifies a normalization form. BaseX supports Form C (<code>NFC</code>).
+
| Specifies a normalization form. BaseX supports Form C ({{Code|NFC}}).
−
| <code>NFC</code>, <code>none</code>
+
| {{Code|NFC}}, {{Code|none}}
−
| <code>NFC</code>
+
| {{Code|NFC}}
 
| <code>normalization-form=none</code>
 
| <code>normalization-form=none</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>media-type</code>
+
| {{Code|media-type}}
 
| Specifies the media type.
 
| Specifies the media type.
 
|  
 
|  
−
| <code>application/xml</code>
+
| {{Code|application/xml}}
 
| <code>media-type=text/plain</code>
 
| <code>media-type=text/plain</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>use-character-maps</code>
+
| {{Code|use-character-maps}}
 
| Defines character mappings (not supported).
 
| Defines character mappings (not supported).
 
|  
 
|  
Line 105: Line 105:
 
|
 
|
 
|- valign="top"
 
|- valign="top"
−
| <code>byte-order-mark</code>
+
| {{Code|byte-order-mark}}
 
| Prints a byte-order-mark before starting serialization.
 
| Prints a byte-order-mark before starting serialization.
−
| <code>yes</code>, <code>no</code>
+
| {{Code|yes}}, {{Code|no}}
−
| <code>no</code>
+
| {{Code|no}}
 
| <code>byte-order-mark=yes</code>
 
| <code>byte-order-mark=yes</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>escape-uri-attributes</code>
+
| {{Code|escape-uri-attributes}}
 
| Escapes URI information in certain HTML attributes<br />Example: <code>&lt;a&nbsp;href="%C3%A4%C3%B6%C3%BC"&gt;äöü&lt;a&gt;</code>
 
| Escapes URI information in certain HTML attributes<br />Example: <code>&lt;a&nbsp;href="%C3%A4%C3%B6%C3%BC"&gt;äöü&lt;a&gt;</code>
−
| <code>yes</code>, <code>no</code>
+
| {{Code|yes}}, {{Code|no}}
−
| <code>no</code>
+
| {{Code|no}}
 
| <code>escape-uri-attributes=yes, method=html</code>
 
| <code>escape-uri-attributes=yes, method=html</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>include-content-type</code>
+
| {{Code|include-content-type}}
−
| Includes a <code>meta</code> content-type element if the result is output as HTML<br />Example: <code>&lt;head&gt;&lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8"&gt;&lt;/head&gt;</code>
+
| Includes a {{Code|meta}} content-type element if the result is output as HTML<br />Example: <code>&lt;head&gt;&lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8"&gt;&lt;/head&gt;</code>
−
| <code>yes</code>, <code>no</code>
+
| {{Code|yes}}, {{Code|no}}
−
| <code>no</code>
+
| {{Code|no}}
 
| <code>include-content-type=yes, method=html</code>
 
| <code>include-content-type=yes, method=html</code>
 
|}
 
|}
Line 134: Line 134:
 
! Examples
 
! Examples
 
|- valign="top"
 
|- valign="top"
−
| <code>format</code>
+
| {{Code|format}}
 
| Turns output formatting on/off, including the conversion of special characters to entities and insertion of item separators. This flag can be turned off to simplify the handling of plain-text results.
 
| Turns output formatting on/off, including the conversion of special characters to entities and insertion of item separators. This flag can be turned off to simplify the handling of plain-text results.
−
| <code>yes</code>, <code>no</code>
+
| {{Code|yes}}, {{Code|no}}
−
| <code>yes</code>
+
| {{Code|yes}}
 
| <code>format=no</code>
 
| <code>format=no</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>tabulator</code>
+
| {{Code|tabulator}}
−
| Uses tab characters (<code>\t</code>) for indenting elements.
+
| Uses tab characters ({{Code|\t}}) for indenting elements.
−
| <code>yes</code>, <code>no</code>
+
| {{Code|yes}}, {{Code|no}}
−
| <code>no</code>
+
| {{Code|no}}
 
| <code>tabulator=yes</code>
 
| <code>tabulator=yes</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>indents</code>
+
| {{Code|indents}}
 
| Specifies the number of characters to be indented.
 
| Specifies the number of characters to be indented.
 
| ''positive number''
 
| ''positive number''
−
| <code>2</code>
+
| {{Code|2}}
 
| <code>indents=1, tabulator=yes</code>
 
| <code>indents=1, tabulator=yes</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>wrap-prefix</code>,<br /><code>wrap-uri</code>
+
| {{Code|wrap-prefix}},<br />{{Code|wrap-uri}}
 
| Specifies a prefix and/or URI for wrapping the query results.
 
| Specifies a prefix and/or URI for wrapping the query results.
 
|  
 
|  
Line 158: Line 158:
 
| <code>wrap-prefix=rest, wrap-uri=http://basex.org/rest</code>
 
| <code>wrap-prefix=rest, wrap-uri=http://basex.org/rest</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>newline</code>
+
| {{Code|newline}}
 
| Specifies the type of newline to be used as end-of-line marker.  
 
| Specifies the type of newline to be used as end-of-line marker.  
−
| <code>\n</code>, <code>\r\n</code>, <code>\r</code>
+
| {{Code|\n}}, {{Code|\r\n}}, {{Code|\r}}
 
| ''system dependent''
 
| ''system dependent''
 
| <code>newline=\r\n</code>
 
| <code>newline=\r\n</code>
 
|- valign="top"
 
|- valign="top"
−
| <code>separator</code>
+
| {{Code|separator}}
 
| Determines the string to be used as item separator. {{Mark|Introduced with Version 7.2}}
 
| Determines the string to be used as item separator. {{Mark|Introduced with Version 7.2}}
 
| ''arbitrary strings''
 
| ''arbitrary strings''

Revision as of 23:43, 26 May 2012

This page is part of the XQuery Portal. Serialization parameters define how XQuery items and XML nodes are textually output, i.e., serialized. (For input see Parsers.) They have been formalized in the W3C XQuery Serialization 3.0 document. In BaseX, they can be specified in several ways:

Parameters

The following table gives a brief summary of all serialization parameters recognized by BaseX. For details, please refer to official specification.

Parameter Description Allowed Default Examples
method Specifies the serialization method:
  • xml, xhtml, html, and text are adopted from the official specification.
  • html5 is specific to BaseX and can be used to output query results as HTML5.
  • json and jsonml are specific to BaseX and can be used to output XML nodes in the JSON format (see the JSON Module for more details).
  • raw is BaseX-specific as well: Binary data types are output in their raw form, i.e., without modifications. For all other types, the items’ string values are returned. No indentation takes place, and and no characters are encoded via entities.
 xml, xhtml, html, text, html5, json, jsonml, raw xml method=xml
version Specifies the version of the serializer. xml/xhtml: 1.0, 1.1
html: 4.0, 4.01
 1.0 version=1.0
encoding Encoding to be used for outputting the data. all encodings supported by Java UTF-8 encoding=US-ASCII
indent Adjusts whitespaces to make the output better readable. yes, no yes indent=no
cdata-section-elements List of elements to be output as CDATA, separated by whitespaces.
Example: <text><![CDATA[ <> ]]></text> 		cdata-section-elements=text
omit-xml-declaration Omits the XML declaration, which is serialized before the actual query result
Example: <?xml version="1.0" encoding="UTF-8"?> 		yes, no yes omit-xml-declaration=no
standalone Prints or omits the "standalone" attribute in the XML declaration. yes, no, omit omit standalone=yes
doctype-system Introduces the output with a document type declaration and the given system identifier.
Example: <!DOCTYPE x SYSTEM "entities.dtd"> 		doctype-system=entities.dtd
doctype-public If doctype-system is specified, adds a public identifier.
Example: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 		doctype-public=-//W3C//DTD HTML 4.01//EN,
doctype-system=http://www.w3.org/TR/html4/strict.dtd
undeclare-prefixes Undeclares prefixes in XML 1.1. yes, no no undeclare-prefixes=yes
normalization-form Specifies a normalization form. BaseX supports Form C (NFC). NFC, none NFC normalization-form=none
media-type Specifies the media type. application/xml media-type=text/plain
use-character-maps Defines character mappings (not supported).
byte-order-mark Prints a byte-order-mark before starting serialization. yes, no no byte-order-mark=yes
escape-uri-attributes Escapes URI information in certain HTML attributes
Example: <a href="%C3%A4%C3%B6%C3%BC">äöü<a> 		yes, no no escape-uri-attributes=yes, method=html
include-content-type Includes a meta content-type element if the result is output as HTML
Example: <head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"></head> 		yes, no no include-content-type=yes, method=html

BaseX provides some additional, implementation-specific serialization parameters:

Parameter Description Allowed Default Examples
format Turns output formatting on/off, including the conversion of special characters to entities and insertion of item separators. This flag can be turned off to simplify the handling of plain-text results. yes, no yes format=no
tabulator Uses tab characters (\t) for indenting elements. yes, no no tabulator=yes
indents Specifies the number of characters to be indented. positive number 2 indents=1, tabulator=yes
wrap-prefix,
wrap-uri 		Specifies a prefix and/or URI for wrapping the query results. wrap-prefix=rest, wrap-uri=http://basex.org/rest
newline Specifies the type of newline to be used as end-of-line marker. \n, \r\n, \r system dependent newline=\r\n
separator Determines the string to be used as item separator. Template:Mark arbitrary strings single space separator=\n

Changelog

Version 7.2

  • Added: separator parameter

Version 7.1

  • Added: newline parameter

Version 7.0

  • Added: Serialization parameters added to REST API; JSON/JsonML/raw methods
Retrieved from "http://docs.basex.org/index.php?title=Serialization&oldid=7299"