README.md

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:

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

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][2]
for examples that include comparators.

[2]: https://github.com/kellyfelkins/tabular/blob/master/test/test_support_test.exs

**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][1] I discuss using ascii tables to improve comprehension
of software tests.

[1]: https://punctuatedproductivity.wordpress.com/2016/02/02/ascii-tables-for-clearer-testing/

Installation
------------

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

```elixir
def deps do
  [
    {:tabular, "~> 0.3.0"}
  ]
end
```

Usage
-----

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

<pre>
+-----------------------+------------------------------+-----------------------------------+
| **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                 |
+-----------------------+------------------------------+-----------------------------------+
</pre>

**Reading a String**

```elixir
  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](https://github.com/kellyfelkins/examples_of_testing_with_ascii_tables).

The docs can be found at [https://hexdocs.pm/tabular](https://hexdocs.pm/tabular).

## License

Blue Oak Model license. Please see [LICENSE][license] for details.

[LICENSE]: https://github.com/kellyfelkins/tabular/blob/master/LICENSE.md