Changes

This [[Module Library|XQuery Module]] contains a single function to parse CSV input. [httphttps://en.wikipedia.org/wiki/Comma-separated_values CSV] (comma-separated values) is a popular representation for tabular data, exported e. g. from Excel.

All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/csv</nowiki></code> namespace, which is statically bound to the {{Code|csv}} prefix.<br/>All errors are assigned to the <code><nowiki>http://basex.org/errors</nowiki></code> namespace, which is statically bound to the {{Code|bxerr}} prefix.

==ConversionFormats==

If the {{Code|direct}} or {{Code|attributes}} format is chosen, a CSV string is converted to XML as follows:

* The resulting XML document has a {{Code|<csv>}} root element.* Rows are represented via {{Code|<record>}} elements.* Fields are represented via {{Code|<entry>}} elements. The value of a field is represented as text node.* If the {{Code|header}} option is set to {{Code|true}}, the first text line is parsed as table header, and the {{Code|<entry>}} elements are replaced with the field names:** Empty names are represented by a single underscore ({{Code|_}}), and characters that are not valid in element names are replaced with underscores or (when invalid as first character of an element name) prefixed with an underscore.** If the {{Code|laxformat}} option is set to {{Code|falsedirect}}, invalid characters will be rewritten to an underscore and the character’s four-digit Unicodefield names are encoded, as described in the [[Conversion Module#Keys|Conversion Module]], and underscores will be represented used as two underscores ({{Code|__}}). The resulting element names may be less readable, but can always be converted back to the original field names.* If * Otherwise, if {{Code|format}} is set to {{Code|attributes}}, the field names will be stored in name attributes.

With the {{MarkCode|Introduced with Version 9.0xquery}}format, CSV records are converted to a sequence of arrays:

CSV * The resulting value will be a map with a {{Code|records can be converted to }} entry and an optional {{Code|names}} entry.* Records are organized as a plain sequence of arrays:. An array contains the entries of a single record.* The {{Code|names}} entry contains an array with the column names. It is generated if the {{Code|header}} option is set to {{Code|true}}.

* The resulting value will be a CSV map with a {{Code|records}} and an optional {{Code|names}} key.* Records are organized as a sequence of arrays. A single array contains the entries of a single record.* The column names will be available if {{Code|header}} option is set to {{Code|true}}. The resulting data can e.g. be accessed as follows:

* <code>$csv?records?(2)</code> returns all entries of the 2nd field (column)

<pre classlang="brush:'xquery"'>

The resulting representation consumes less memory than XML-based formats, and values can be directly accessed without conversion. Thus, it is recommendable for very large inputs and for efficient ad-hoc processing. Before {{Version|9.0}}, a {{Code|map}} format was available, which was now replaced with the more flexible and light-weight {{Code|xquery}} format.

In the following table, all available options are listed. The Excel column indicates what are the preferred lists recommended options for data that is to be imported, processed with Excel or has been exported from ExcelOpen/Libre Office.

! width="140" | Option! width="50%" | Description

| ''parse'', ''serialize''| {{Code|semicolon}}or {{Code|comma}}, depending on the region

| Specifies the format of the XML for converting CSV data:<br/>* With {{Code|direct}} conversion, field names are represented as element names* With {{Code|attributes}} conversion, field names are stored in {{Code([[#Conversion Formats|name}} attributes* With {{Code|xquery}} conversion, the input is converted to an XQuery mapsee above]]).| {{Code|direct}}, {{Code|attributes}}, {{Code|mapxquery}}

| Specifies if a [[Conversion Module#Keys|lax approach is conversion rules]] are used to convert QNames to JSON names.

* Serialization: If the option is enabled, the value will be wrapped with quotesif it contains characters that might be treated as control characters. A quote character in the value will be encoded according to the rules of the {{Code|backslashes}} option.

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|csv:parse|$input as xs:string|document-node(element(csv))}}<br/pre>{{Func|csv:parse|( $input value as xs:string?, $options as map(xs*)? :string, item(= map { }))|as item()}}?</pre>|-valign="top"

|Converts the CSV data specified by {{Code|$inputvalue}} to an XML document or a mapXQuery value. The {{Code|$options}} argument can be used to control the way the input is converted.|-valign="top"

|{{Error|BXCS0001parse|#Errors}} the specified input cannot be parsedas CSV document.

|-valign="top"| width='120' | '''SignaturesSignature'''|{{Func|csv:serialize|$input as node()|xs:string}}<br/pre>{{Func|csv:serialize|( $input as nodeitem()?, $options as map(xs*)? :string, item(= map { }))|as xs:string}}</pre>|-valign="top"

|Serializes the node specified by {{Code|$input}} as CSV data, and returns using the result as specified {{Code|xs:string$options}}, and returns the result as string. Items Values can also be serialized as JSON if CSV with the standard [[Serialization|Serialization Parameter]] feature of XQuery:* The parameter {{Code|method}} is needs to be set to {{Code|csv}}.<br/>The , and* the options presented in this article need to be assigned to the {{Code|$optionscsv}} argument can be used to control the way the input is serializedparameter.|-valign="top"

|{{Error|BXCS0002serialize|#Errors}} the input cannot be serialized.

<pre classlang="brush:xml">

<pre classlang="brush:'xquery"'>

<pre classlang="brush:xml">

<pre classlang="brush:'xquery"'>

<pre classlang="brush:'xquery"'>

let $data csv := csv:parse($text, $options)

let $records := $data?csv('records') for $name at $pos in $data?csv('names')?*

<pre classlang="brush:'xquery"'>

|-valign="top"|{{Code|BXCS0001parse}}

|-valign="top"|{{Code|BXCS0002serialize}}

* Updated: [[#csv:parse{{Function||csv:parse]] }} now returns a document node instead of an element, or an XQuery map if {{Code|format}} is set to {{Code|map}}.