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  |
+------------------+--------------------+

Test Helpers

The compare/2 and equal?/1 functions can compare two ascii tables.

Compare/2 generates a matrix from two ascii tables indicating which cells are equal and which are different. You can provide an optional list of comparators associated with a column. 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?/1 takes the matrix generated by compare and returns a boolean indicating if original ascii tables are, well, equal.

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, "~> 0.3.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_no_header(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.