gridtables

Parser for reStructuredText-style grid tables.

This package provides a parser for plain-text representations of tables, like the one given below.

+---------------------+-----------------------+
| Location            | Temperature 1961-1990 |
|                     | in degree Celsius     |
|                     +-------+-------+-------+
|                     | min   | mean  | max   |
+=====================+=======+=======+=======+
| Antarctica          | -89.2 | N/A   | 19.8  |
+---------------------+-------+-------+-------+
| Earth               | -89.2 | 14    | 56.7  |
+---------------------+-------+-------+-------+

Character widths

The tables are intended to look good when viewed in a monospace font. Therefore, wide and full-width characters, as those in East Asian scripts, are counted as two characters, while zero-width and combining characters are treated as if they have no width.

Column alignments

The parser re-implements a table extensions from John MacFarlane's pandoc, namely support for column-wide cell alignments. The alignment of cells is determined by placing colons in the row that separates the table head from the body, like so:

+------+--------+-------+
| left | center | right |
+:=====+:======:+======:+
| 1    | 2      | 3     |
+------+--------+-------+

The first line must be used for headless tables:

+:-----+:------:+------:+
| left | center | right |
+------+--------+-------+
| a 1  | b 2    | c 3   |
+------+--------+-------+

Table Foot

This library implements an extension that enables to create tables with table foots: If the last separator line is a part separator, i.e., if it consists of = instead of -, then all rows after the second-to-last part separator are treated as the table foot.

E.g., consider the following table:

+------+-------+
| Item | Price |
+======+=======+
| Eggs | 5£    |
+------+-------+
| Spam | 3£    |
+======+=======+
| Sum  | 8£    |
+======+=======+

Here, the last row, containing "Sum" and "8£", would be the table foot.

Algorithm

The cell tracing algorithm used in this package has been translated from the original Python implementation for reStructuredText. The parser has been placed in the public domain.

Usage

The usual way to use this package will be to use it as part of a parsec parser:

main :: IO ()
main = do
  let gt = T.unlines
           [ "+------+--------+-------+"
           , "| left | center | right |"
           , "+:=====+:======:+======:+"
           , "| 1    | 2      | 3     |"
           , "+------+--------+-------+"
           ]
  in print (runParser GT.gridTable () "table" gt)

Use traceLines :: [Text] -> Maybe (GridTable [Text]), if the table's raw lines have been retrieved in a different way.