= 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