= Terminal Table

== Description

Terminal Table is a fast and simple, yet feature rich ASCII table generator written in Ruby.

== Installation

  $ gem install terminal-table

== Usage

=== Basics

To use Terminal Table:

  require 'terminal-table'

To generate a table, provide an array of arrays (which are interpreted as rows):

  rows = []
  rows << ['One', 1]
  rows << ['Two', 2]
  rows << ['Three', 3]
  table = Terminal::Table.new :rows => rows

  # > puts table
  #
  # +-------+---+
  # | One   | 1 |
  # | Two   | 2 |
  # | Three | 3 |
  # +-------+---+


The constructor can also be given a block which is either yielded the Table object or instance evaluated:

  table = Terminal::Table.new do |t|
    t.rows = rows
  end

  table = Terminal::Table.new do
    self.rows = rows
  end

Adding rows one by one:

  table = Terminal::Table.new do |t|
    t << ['One', 1]
    t.add_row ['Two', 2]
  end

To add separators between rows:

  table = Terminal::Table.new do |t|
    t << ['One', 1]
    t << :separator
    t.add_row ['Two', 2]
    t.add_separator
    t.add_row ['Three', 3]
  end

  # > puts table
  #
  # +-------+---+
  # | One   | 1 |
  # +-------+---+
  # | Two   | 2 |
  # +-------+---+
  # | Three | 3 |
  # +-------+---+

Cells can handle multiline content:

  table = Terminal::Table.new do |t|
    t << ['One', 1]
    t << :separator
    t.add_row ["Two\nDouble", 2]
    t.add_separator
    t.add_row ['Three', 3]
  end

  # > puts table
  #
  # +--------+---+
  # | One    | 1 |
  # +--------+---+
  # | Two    | 2 |
  # | Double |   |
  # +--------+---+
  # | Three  | 3 |
  # +--------+---+

=== Head

To add a head to the table:

  table = Terminal::Table.new :headings => ['Word', 'Number'], :rows => rows

  # > puts table
  #
  # +-------+--------+
  # | Word  | Number |
  # +-------+--------+
  # | One   | 1      |
  # | Two   | 2      |
  # | Three | 3      |
  # +-------+--------+

=== Title

To add a title to the table:

  table = Terminal::Table.new :title => "Cheatsheet", :headings => ['Word', 'Number'], :rows => rows

  # > puts table
  #
  # +------------+--------+
  # |     Cheatsheet      |
  # +------------+--------+
  # | Word       | Number |
  # +------------+--------+
  # | One        | 1      |
  # | Two        | 2      |
  # | Three      | 3      |
  # +------------+--------+

=== Alignment

To align the second column to the right:

  table.align_column(1, :right)

  # > puts table
  #
  # +-------+--------+
  # | Word  | Number |
  # +-------+--------+
  # | One   |      1 |
  # | Two   |      2 |
  # | Three |      3 |
  # +-------+--------+

To align an individual cell, you specify the cell value in a hash along the alignment:

  table << ["Four", {:value => 4.0, :alignment => :center}]

  # > puts table
  #
  # +-------+--------+
  # | Word  | Number |
  # +-------+--------+
  # | One   |      1 |
  # | Two   |      2 |
  # | Three |      3 |
  # | Four  |  4.0   |
  # +-------+--------+

=== Style

To specify style options:

  table = Terminal::Table.new :headings => ['Word', 'Number'], :rows => rows, :style => {:width => 80}

  # > puts table
  #
  # +--------------------------------------+---------------------------------------+
  # | Word                                 | Number                                |
  # +--------------------------------------+---------------------------------------+
  # | One                                  | 1                                     |
  # | Two                                  | 2                                     |
  # | Three                                | 3                                     |
  # +--------------------------------------+---------------------------------------+

And change styles on the fly:

  table.style = {:width => 40, :padding_left => 3, :border_x => "=", :border_i => "x"}

  # > puts table
  #
  # x====================x=================x
  # |               Cheatsheet             |
  # x====================x=================x
  # |   Word             |   Number        |
  # x====================x=================x
  # |   One              |   1             |
  # |   Two              |   2             |
  # |   Three            |   3             |
  # x====================x=================x

You can also use styles to add a separator after every row:

  table = Terminal::Table.new do |t|
    t.add_row [1, 'One']
    t.add_row [2, 'Two']
    t.add_row [3, 'Three']
    t.style = {:all_separators => true}
  end

  # > puts table
  #
  # +---+-------+
  # | 1 | One   |
  # +---+-------+
  # | 2 | Two   |
  # +---+-------+
  # | 3 | Three |
  # +---+-------+

You can also use styles to disable top and bottom borders of the table

  table = Terminal::Table.new do |t|
    t.headings = ['id', 'name']
    t.rows = [[1, 'One'], [2, 'Two'], [3, 'Three']]
    t.style = { :border_top => false, :border_bottom => false }
  end

  # > puts table
  # | id | name  |
  # +----+-------+
  # | 1  | One   |
  # | 2  | Two   |
  # | 3  | Three |

To change the default style options:

  Terminal::Table::Style.defaults = {:width => 80}

All Table objects created afterwards will inherit these defaults.

=== Constructor options and setter methods

Valid options for the constructor are :rows, :headings, :style and :title - and all options can also be set on the created table object by their setter method:

  table = Terminal::Table.new
  table.title = "Cheatsheet"
  table.headings = ['Word', 'Number']
  table.rows = rows
  table.style = {:width => 40}

== More examples

For more examples, please see the examples/examples.rb file included in the source distribution.

== Author

TJ Holowaychuk <tj@vision-media.ca>