text-table

= text-table {}[https://rubygems.org/gems/text-table] {}[http://travis-ci.org/aptinio/text-table] {}[https://codeclimate.com/github/aptinio/text-table]

A feature-rich, easy-to-use plain text table formatter.

== Introduction

Allows you to easily create and format plain text tables, useful when working with the terminal or when you want to quickly print formatted tables to a dot-matrix printer.

Text::Table is compatible with Ruby 1.8.6, 1.8.7 and 1.9.1 and includes a comprehensive test suite.

== Install

gem install text-table

== Examples

require 'text-table'

table = Text::Table.new
table.head = ['A', 'B']
table.rows = [['a1', 'b1']]
table.rows << ['a2', 'b2']

table.to_s

#    +----+----+
#    | A  | B  |
#    +----+----+
#    | a1 | b1 |
#    | a2 | b2 |
#    +----+----+

You can also pass an options hash when instantiating a Text::Table:

table = Text::Table.new(:head => ['A', 'B'], :rows => [['a1', 'b1'], ['a2', 'b2']])

== Calling the to_table Method

Just call the to_table method (or to_text_table if the former is already defined) on Arrays (and other Enumerables).

array = [
  ['Student', 'Mid-Terms', 'Finals'],
  ['Sam', 94, 93],
  ['Jane', 92, 99],
  ['Average', 93, 96]
]

puts array.to_table

#    +---------+-----------+--------+
#    | Student | Mid-Terms | Finals |
#    | Sam     | 94        | 93     |
#    | Jane    | 92        | 99     |
#    | Average | 93        | 96     |
#    +---------+-----------+--------+

You could specify that the first row is the table heading.

puts array.to_table(:first_row_is_head => true)

#    +---------+-----------+--------+
#    | Student | Mid-Terms | Finals |
#    +---------+-----------+--------+
#    | Sam     | 94        | 93     |
#    | Jane    | 92        | 99     |
#    | Average | 93        | 96     |
#    +---------+-----------+--------+

You could also specify that the last row is the table footer.

puts array.to_table(:first_row_is_head => true, :last_row_is_foot => true)

#    +---------+-----------+--------+
#    | Student | Mid-Terms | Finals |
#    +---------+-----------+--------+
#    | Sam     | 94        | 93     |
#    | Jane    | 92        | 99     |
#    +---------+-----------+--------+
#    | Average | 93        | 96     |
#    +---------+-----------+--------+

== Aligning Cells and Spanning Columns

Alignment and column span can be specified by passing a cell as a Hash object.

The acceptable aligments are :left, :center and :right.

Cells and footers are aligned to the left by default, while headers are centered by default.

table = Text::Table.new
table.head = ['Heading A', 'Heading B']
table.rows << ['a1', 'b1']
table.rows << ['a2', {:value => 'b2', :align => :right}]
table.rows << ['a3', 'b3']
table.rows << [{:value => 'a4', :colspan => 2, :align => :center}]

puts table

#    +-----------+-----------+
#    | Heading A | Heading B |
#    +-----------+-----------+
#    | a1        | b1        |
#    | a2        |        b2 |
#    | a3        | b3        |
#    |          a4           |
#    +-----------+-----------+

There's also an easy way to align columns:

table = Text::Table.new :rows => [%w(a bb), %w(aa bbb), %w(aaa b)]
puts table

#    +-----+-----+
#    | a   | bb  |
#    | aa  | bbb |
#    | aaa | b   |
#    +-----+-----+

table.align_column 2, :right

#    +-----+-----+
#    | a   |  bb |
#    | aa  | bbb |
#    | aaa |   b |
#    +-----+-----+

Note that headers, spanned cells and cells with explicit alignments are not affected by align_column.

== Adding a Separator

You can add a separator by inserting :separator symbols between the rows.

Text::Table.new :rows => [
  ['a', 'b'],
  ['c', 'd'],
  :separator,
  ['e', 'f'],
  :separator,
  ['g', 'h']
]

#    +---+---+
#    | a | b |
#    | c | d |
#    +---+---+
#    | e | f |
#    +---+---+
#    | g | h |
#    +---+---+

== Other Options

Cell padding and table boundaries can be modified.

Text::Table.new :rows => [['a', 'b'], ['c', 'd']],
                :horizontal_padding    => 3,
                :vertical_boundary     => '=',
                :horizontal_boundary   => ':',
                :boundary_intersection => 'O'

#    O=======O=======O
#    :   a   :   b   :
#    :   c   :   d   :
#    O=======O=======O

== Special Thanks

This project was inspired by visionmedia's terminal-table, and to a lesser-extent, by prawn, ruport and hirb. I've decided to start a new project, primarily as an exercise, and to be able to model-out the classes differently. Thanks to the authors and contributors of these projects.

== Contributors

• Claudio Bustos (clbustos[http://github.com/clbustos])

  • Fix Ruby 1.9 warnings on shadowed outer local variables

• Kaoru Maeda (mad-p[https://github.com/mad-p])

  • Fixed performance issue with large number of rows

== Copyright

Copyright (c) 2009 Aaron Tinio. See LICENSE for details.