sandbox/dpriest/csvtable/csvtable.txt

   1 .. _csvtable:
   2
   3 CSV Table
   4 =========
   5
   6 :Directive Type: "csvtable"
   7 :Doctree Element: table
   8 :Directive Arguments: 1, optional (table title).
   9 :Directive Options: Possible.
  10 :Directive Content: A CSV (comma-separated values) table.
  11
  12 The "csvtable" directive is used to create a table from CSV
  13 (comma-separated values) data.  CSV is a common data format generated
  14 by spreadsheet applications and commercial databases.
  15
  16 Example::
  17
  18     .. csvtable:: Frozen Delights!
  19        :headers: "Treat", "Quantity", "Description"
  20        :widths: 15, 10, 30
  21
  22        "Albatross", 2.99, "On a stick!"
  23        "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
  24        crunchy, now would it?"
  25        "Gannet Ripple", 1.99, "On a stick!"
  26
  27 Block markup and inline markup within cells is supported.  Line ends
  28 are recognized within cells.
  29
  30 Working Limitations::
  31
  32 * Whitespace delimiters are supported only for external CSV files.
  33
  34 * There is no support for checking that the number of columns in each
  35   row is the same.  However, this directive supports CSV generators
  36   that do not insert "empty" entries at the end of short rows, by
  37   automatically adding empty entries.
  38
  39   .. Add "strict" option to verify input?
  40
  41 * Due to limitations of the CSV parser, this directive is not Unicode
  42   compatible.  It may also have problems with ASCII NUL characters.
  43   Accordingly, CSV tables should be ASCII-printable safe.
  44
  45   .. Test with Unicode; see if that's really so.  "encoding" option?
  46
  47 The following options are recognized:
  48
  49 ``class`` : text
  50     Set a "class" attribute value on the table element.  See the
  51     class_ directive below.
  52
  53 ``widths`` : integer [, integer...]
  54     A comma-separated list of relative column widths.  The default is
  55     equal-width columns (100%/#columns).
  56
  57 ``header-rows`` : integer
  58     The number of rows of CSV data to use in the table header.
  59     Defaults to 0.
  60
  61 ``header`` : CSV data
  62     Supplemental data for the table header, added independently of and
  63     before any ``header-rows`` from the main CSV data.  Must use the
  64     same CSV format as the main CSV data.
  65
  66 ``file`` | ``url`` : path
  67     Path or URL to CSV file.
  68
  69 ``delim`` : char | "tab" | "space"
  70     A one-character string used to separate fields.  Defaults to ``,``
  71     (comma).  May be specified as a Unicode code point; see the
  72     unicode_ directive for syntax details.
  73
  74 ``quote`` : char
  75     A one-character string used to quote elements containing the
  76     delimiter or which start with the quote character.  Defaults to
  77     ``"`` (quote).  May be specified as a Unicode code point; see the
  78     unicode_ directive for syntax details.
  79
  80 ``keepspace`` : flag
  81     Treat whitespace immediately following the delimiter as
  82     significant.  The default is to ignore such whitespace.
  83
  84 ``escape`` : char
  85     A one-character string used to escape the delimiter or quote
  86     characters.  May be specified as a Unicode code point; see the
  87     unicode_ directive for syntax details.  Used when the delimiter is
  88     used in an unquoted field, or when quote characters are used
  89     within a field.  The default is to double-up the character,
  90     e.g. "He said, ""Hi!"""
  91
  92     .. Add another possible value, "double", to explicitly indicate
  93        the default case?