Legitable

Tables are easier to read. Legitable makes it easy to display plain text output in tabular form.

Given a normal series of hash objects as rows (where "normal" means that all hashes have the same keys), the first row's keys will be taken as the table's column headers; deviations in subsequent hashes will be ignored.

Add this line to your application's Gemfile:

gem 'legitable'

And then execute:

$ bundle

Or install it yourself as:

$ gem install legitable

First, require it:

require 'legitable'

Then, create a table object:

table = Legitable::Table.new

Now add some rows:

table << { name: 'joss whedon', phone: '444-555-1212' }
table << { name: 'jj abrams', phone: '333-555-1212' }

And then you can display it:

puts table.to_s

NAME        | PHONE       
--------------------------
joss whedon | 444-555-1212
jj abrams   | 333-555-1212

Some data, such as numbers, look better aligned to the right instead of to the left:

table = Legitable::Table.new(alignment: { bytes: :right })

table << { bytes: 12, file: 'foo.zip' }
table << { bytes: 1200, file: 'bar.zip' }
table << { bytes: 12000000, file: 'baz.zip' }

Which makes the numbers much easier to read:

   BYTES | FILE   
------------------
      12 | foo.zip
    1200 | bar.zip
12000000 | baz.zip

Some aspects of the table are configurable, such as the column delimiter (which defaults to " | ") and the character used as a header row separator (which defaults to "-").

table = Legitable::Table.new(delimiter: '  ', separator: '=')

Which would give us this:

NAME         PHONE       
=========================
joss whedon  444-555-1212
jj abrams    333-555-1212

Sometimes the raw data as it comes in isn't exactly what you want to display. So you can define formatters:

title = Legitable::Table.new do
  formatting :name do |value|
    "_#{value.titleize}_"
  end
end

Which, of course, improves the display of the names column:

NAME          | PHONE       
----------------------------
_Joss Whedon_ | 444-555-1212
_JJ Abrams_   | 333-555-1212

And, of course, you can do something similar for the column headings:

table = Legitable::Table.new do
  formatting_headers do |header|
    header.capitalize
  end
end

Which makes the headers a little nicer:

Name        | Phone       
--------------------------
joss whedon | 444-555-1212
jj abrams   | 333-555-1212

Sometimes your tables end up in a markdown document. Legitable is nice for plain text viewing, but the default table style is not quite legit as a markdown table. You can fix that with the markdown style:

table = Legitable::Table.new(style: :markdown)

The result is very similar, but adds the delimiter to the header separator, which causes it to render properly as markdown:

NAME        | PHONE       
------------|-------------
joss whedon | 444-555-1212
jj abrams   | 333-555-1212

It should be obvious that this utility pulls in all rows, and then displays them taking into account the widest values when determining the appropriate column width. Accordingly, all rows to be processed will be in memory as long as the table object exists. So this isn't a good tool for formatting a terrabyte of tabular data.

The focus is on display of data. Think of a Legitable::Table as a page of data. If you have multiple pages of data, you'd probably want to repeat the headers anyway at some point, so it makes sense to just create a new table after every n rows.

This puts me in mind of some ideas for the future:

• ability to "flush" all rows so that the table's formatting can be re-used and re-loaded.
• ability to fix the width of a column and to word wrap within that width in order to control the overall width of the table.
• ANSI color support

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/joelhelbling/legitable.

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