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>
You can add row separators so that column values can wrap over multiple rows. This helps
you manage the width of tables.
<pre>
+-----------+--------------+
| name | dob |
+-----------+--------------+
| Malcolm | September 20,|
| Reynolds | 2468 |
+-----------+--------------+
| Zoe | February 15, |
| Washburne | 2484 |
+-----------+--------------+
</pre>
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][2] for examples that include comparators.
[2]: https://github.com/kellyfelkins/tabular/blob/master/test/test_support_test.exs
**`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][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, "~> 1.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
