Tabular

Tabular is a reader for data in ascii table format and test helpers to facilitate testing with ascii tables.

Reader

The reader allows you to read string data formatted like this:

+------------------+--------------------+
| name             | dob                |
+------------------+--------------------+
| Malcolm Reynolds | September 20, 2468 |
| Zoe Washburne    | February 15, 2484  |
+------------------+--------------------+

You can add row separators so that column values can wrap over multiple rows. This helps you manage the width of tables.

+-----------+--------------+
| name      | dob          |
+-----------+--------------+
| Malcolm   | September 20,|
| Reynolds  | 2468         |
+-----------+--------------+
| Zoe       | February 15, |
| Washburne | 2484         |
+-----------+--------------+

Wrapped cells are folded--the two tables produce the same results.

Test Helpers

The compare, equal?, and assert_equal functions compare two ascii tables.

compare generates a matrix from two ascii tables indicating which cells are equal *and which are different. You can provide an optional list of per column comparators. When *a comparator is provided for a column it will be used to compare the values of the cells *for that column. See test_support_test.exs for examples that include comparators.

equal? takes the matrix generated by compare and returns a boolean indicating if *original ascii tables are, well, equal.

assert_equal asserts that the results generated from compare indicate the tables *are equal, and, if not, generates a failure message showing the table with differences *marked.

In Ascii Tables For Clearer Testing I discuss using ascii tables to improve comprehension of software tests.

Installation

The package can be installed by adding tabular to your list of dependencies in mix.exs:

def deps do
  [
    {:tabular, "~> 1.0"}
  ]
end

Usage

Rows are returned as either lists of lists or lists of maps.

+-----------------------+------------------------------+-----------------------------------+
| **Ascii Table Value** | **Returned Value**           | **Notes**                         |
+-----------------------+------------------------------+-----------------------------------+
| Malcolm Reynolds      | "Malcolm Reynolds"           | Most values returned as string    |
+-----------------------+------------------------------+-----------------------------------+
| 123                   | "123"                        | including numbers                 |
+-----------------------+------------------------------+-----------------------------------+
| wrapped strings are   | "wrapped strings are folded" | Similar to yaml, wrapped          |
| folded                |                              | strings are folded with a single  |
|                       |                              | space replacing the new line      |
+-----------------------+------------------------------+-----------------------------------+
|                       | ""                           | an empty string is returned for   | 
|                       |                              | blank cells                       |
+-----------------------+------------------------------+-----------------------------------+
| nil                   | nil                          | nil, true, and false are          |
|                       |                              | special values                    |
+-----------------------+------------------------------+-----------------------------------+
| true                  | true                         |                                   |
+-----------------------+------------------------------+-----------------------------------+
| false                 | false                        |                                   |
+-----------------------+------------------------------+-----------------------------------+
| :foo                  | :foo                         | Values beginning with a colon are |
|                       |                              | returned as atoms                 |
+-----------------------+------------------------------+-----------------------------------+

Reading a String

  Tabular.to_list_of_lists(table)
  |> Enum.each(fn [col1, col2, col3] = row ->
    # use row or column data here...
  end

More examples can be found in the Examples of Testing With ASCII Tables repo.

The docs can be found at https://hexdocs.pm/tabular.

License

Blue Oak Model license. Please see LICENSE for details.