Tableware

Tableware is a tiny gem for making it easier to define data in a text table. Table rows are parsed into either arrays or hashes.

For example:

stats = ' Hero        |    Value     |  Hours Played
          ------------------------------------------
          Phara       |       10     |      22
          Mercy       |        9     |      11
          Winston     |        3     |       2        '

Tableware.arrays(stats)
 # => [
        ['Phara', '10', '22'],
        ['Mercy', '9', '11'],
        ['Winston', '3', '2']
      ]

Tableware.hashes(stats)
  #=> [
        { hero: 'Phara', value: '10', hours_played: 22 },
        { hero: 'Mercy', value: '9', hours_played: 11 },
        { hero: 'Winston', value: '3', hours_played: 2 }
      ]

Writing test data or a matrix of permissions in a big hash or nested array is fine, but it can be a pain to format and work with, especially for larger data sets or with items of very different lengths.

Tableware lets you use a more human friendly format so that you can more easily scan and understand the data.

The downside is that everything is treated as a string, so you may need to do some .to_iing to convert things back into the type you're expecting. However, this is a one-time cost and optimising for reading code is a good idea.

This isn't always going to be better than defining your data in another format, but it is another option. Or perhaps you just like Cucumber scenario outlines and want something similar in rspec!

Focus a single row

You can focus a single row, to help with debugging, by prepending a line with >. For example:

words = '  Foo | Bar
         > Yay | Woo
           Zip | Zap '

Tableware.arrays(words)
  #=> [ ['Yay', 'Woo'] ]

Focus multiple rows

Running multiple rows cannot be achieved with prepending >. Instead, use Enum#select (or reject) to decide which lines to process. For the the previous example, you could achieve the same result using select as follows:

words = '  Foo | Bar
           Yay | Woo
           Zip | Zap '

Tableware.arrays(words).select{ |row| row.first == 'Yay' }
  #=> [ ['Yay', 'Woo'] ]

This gem has been created as a quick experiment to see if or how often this feature could be useful. If you find it useful, please like it or better yet, extend it!

Installation

Add this line to your application's Gemfile:

gem 'tableware'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tableware

Usage

Tableware accepts text tables following these rules:

• Columns delimited by the | character
• Header row is optional but if specified, it must be followed by a line of - or = characters
• Start and end | characters on a row are optional; | A | B | is the same as A | B

Tableware provides two main methods for getting your data back out of the table:

1. Tableware.arrays returns an array of arrays
2. Tableware.hashes returns an array of hashes, where the keys come from the headings row

Both of these can be seen in use in the example at the top of this README.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/AdamWhittingham/tableware. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.