Skip to content

Commit

Permalink
Fix examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@rrrene
rrrene committed Oct 20, 2011
2 parents fd09e19 + a509e4d commit 1b40f74
Showing 1 changed file with 212 additions and 132 deletions.
344 changes: 212 additions & 132 deletions README.rdoc
View file
@@ -1,140 +1,220 @@
= Terminal Table

Simple, feature rich ASCII table generator.

== Installation:

Install [Gemcutter](http://gemcutter.org) then execute:
$ sudo gem install terminal-table

== Features:

* Fast
* Simple
* Optional headings
* Alignment of columns, headings, or cells
* Supports arbitrary width
* Supports column span
* Supports multiline cell content
* Supports colorized cell content
* Easy modification of table strings (+, -, |)

== Examples:

require 'rubygems'
require 'terminal-table/import'

puts table(['a', 'b'], [1, 2], [3, 4], :separator, [4, 6])

v = table ['a', 'b']
v << [1, 2]
v << [3, 4]
v.add_separator
v << [4, 6]
puts t

user_table = table do |t|
t.headings = 'First Name', 'Last Name', 'Email'
t << ['TJ', 'Holowaychuk', 'tj@vision-media.ca']
t << ['Bob', 'Someone', 'bob@vision-media.ca']
t << ['Joe', 'Whatever', 'joe@vision-media.ca']
==

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

== Installation

Install [Gemcutter](http://gemcutter.org) then execute:

$ 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
puts user_table

user_table = table do
self.headings = 'First Name', 'Last Name', 'Email'
add_row ['TJ', 'Holowaychuk', { :value => 'tj@vision-media.ca', :alignment => :right }]
add_row ['Bob', 'Someone', 'bob@vision-media.ca']
add_row ['Joe', 'Whatever', 'joe@vision-media.ca']
align_column 1, :center

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

puts
user_table = table do
self.headings = ['First Name', 'Last Name', {:value => 'Phones', :colspan => 2, :alignment => :center}]
add_row ['Bob', 'Someone', '123', '456']
add_row ['TJ', 'Holowaychuk', {:value => "No phones", :colspan => 2, :alignment => :center}]
add_row ['Joe', 'Whatever', '4324', '343242']

Adding rows one by one:

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

rows = []
rows << ['Lines', 100]
rows << ['Comments', 20]
rows << ['Ruby', 70]
rows << ['JavaScript', 30]
puts table([nil, 'Lines'], *rows)

rows = []
rows << ['Lines', 100]
rows << ['Comments', 20]
rows << ['Ruby', 70]
rows << ['JavaScript', 30]
puts table(nil, *rows)

== Results:

+---+---+
| a | b |
+---+---+
| 1 | 2 |
| 3 | 4 |
+---+---+
| 4 | 6 |
+---+---+


+---+---+
| a | b |
+---+---+
| 1 | 2 |
| 3 | 4 |
+---+---+
| 4 | 6 |
+---+---+

+------------+-------------+---------------------+
| First Name | Last Name | Email |
+------------+-------------+---------------------+
| TJ | Holowaychuk | tj@vision-media.ca |
| Bob | Someone | bob@vision-media.ca |
| Joe | Whatever | joe@vision-media.ca |
+------------+-------------+---------------------+

+------------+-----------------------------+---------------------+
| First Name | Last Name | Email |
+------------+-----------------------------+---------------------+
| TJ | Holowaychuk | tj@vision-media.ca |
| Bob | Someone | bob@vision-media.ca |
| Joe | Whatever | joe@vision-media.ca |
+------------+-----------------------------+---------------------+

+------------+-------------+-----------+--------+
| First Name | Last Name | Phones |
+------------+-------------+-----------+--------+
| Bob | Someone | 123 | 456 |
| TJ | Holowaychuk | No phones |
| Joe | Whatever | 4324 | 343242 |
+------------+-------------+-----------+--------+

+------------+-------+
| | Lines |
+------------+-------+
| Lines | 100 |
| Comments | 20 |
| Ruby | 70 |
| JavaScript | 30 |
+------------+-------+

+------------+-----+
| Lines | 100 |
| Comments | 20 |
| Ruby | 70 |
| JavaScript | 30 |
+------------+-----+

== License:

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 specifify 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

To change the default style options:

Terminal::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>

== License

(The MIT License)

Expand Down

0 comments on commit 1b40f74

Please sign in to comment.