.. _csvtable:

CSV Table
=========

:Directive Type: "csvtable"
:Doctree Element: table
:Directive Arguments: 1, optional (table title).
:Directive Options: Possible.
:Directive Content: A CSV (comma-separated values) table.

The "csvtable" directive is used to create a table from CSV
(comma-separated values) data.  CSV is a common data format generated
by spreadsheet applications and commercial databases.

Example::

    .. csvtable:: Frozen Delights!
       :headers: "Treat", "Quantity", "Description"
       :widths: 15, 10, 30

       "Albatross", 2.99, "On a stick!"
       "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
       crunchy, now would it?"
       "Gannet Ripple", 1.99, "On a stick!"

Block markup and inline markup within cells is supported.  Line ends
are recognized within cells.

Working Limitations::

* Whitespace delimiters are supported only for external CSV files.

* There is no support for checking that the number of columns in each
  row is the same.  However, this directive supports CSV generators
  that do not insert "empty" entries at the end of short rows, by
  automatically adding empty entries.

  .. Add "strict" option to verify input?

* Due to limitations of the CSV parser, this directive is not Unicode
  compatible.  It may also have problems with ASCII NUL characters.
  Accordingly, CSV tables should be ASCII-printable safe.

  .. Test with Unicode; see if that's really so.  "encoding" option?

The following options are recognized:

``class`` : text
    Set a "class" attribute value on the table element.  See the
    class_ directive below.

``widths`` : integer [, integer...]
    A comma-separated list of relative column widths.  The default is
    equal-width columns (100%/#columns).

``header-rows`` : integer
    The number of rows of CSV data to use in the table header.
    Defaults to 0.

``header`` : CSV data
    Supplemental data for the table header, added independently of and
    before any ``header-rows`` from the main CSV data.  Must use the
    same CSV format as the main CSV data.

``file`` | ``url`` : path
    Path or URL to CSV file.

``delim`` : char | "tab" | "space"
    A one-character string used to separate fields.  Defaults to ``,``
    (comma).  May be specified as a Unicode code point; see the
    unicode_ directive for syntax details.

``quote`` : char
    A one-character string used to quote elements containing the
    delimiter or which start with the quote character.  Defaults to
    ``"`` (quote).  May be specified as a Unicode code point; see the
    unicode_ directive for syntax details.

``keepspace`` : flag
    Treat whitespace immediately following the delimiter as
    significant.  The default is to ignore such whitespace.

``escape`` : char
    A one-character string used to escape the delimiter or quote
    characters.  May be specified as a Unicode code point; see the
    unicode_ directive for syntax details.  Used when the delimiter is
    used in an unquoted field, or when quote characters are used
    within a field.  The default is to double-up the character,
    e.g. "He said, ""Hi!"""

    .. Add another possible value, "double", to explicitly indicate
       the default case?
