Skip to content

Latest commit

 

History

History
187 lines (128 loc) · 4.86 KB

README.md

File metadata and controls

187 lines (128 loc) · 4.86 KB
Raw

Tests

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.

Installation

Add this line to your application's Gemfile:

gem 'legitable'

And then execute:

$ bundle

Or install it yourself as:

$ gem install legitable

Usage

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

Right-aligned columns

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

Changing up the look

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

Formatting columns

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

Markdown Style

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

Caveats

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

Development

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.

Contributing

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

License

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