terminal-table 1.4.3 → 1.4.4

data/History.rdoc

@@ -1,3 +1,8 @@
+1.4.4 / 2011-11-07
+==================
+
+  * Add support for multi-line rows, table titles, and colors
+
 1.4.3 / 2011-10-13
 ==================
 

data/README.rdoc

@@ -1,138 +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 column span
-* Easy modification of table strings (+, -, |)
-
-== Examples:
-
-  require 'rubygems'
-  require 'terminal-table/import'
-   
-  puts table(['a', 'b'], [1, 2], [3, 4], :separator, [4, 6])
-   
-  t = table ['a', 'b']
-  t << [1, 2]
-  t << [3, 4]
-  t.add_separator
-  t << [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']
+== Description
+
+Terminal Table is a fast and simple, yet feature rich ASCII table generator written in Ruby.
+
+== Installation
+
+Install http://gemcutter.org and 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)
 

data/Todo.rdoc

@@ -6,7 +6,6 @@
 == Minor:
 
 * Programmatically add separator rows
-* Arbitrary dimensions
 * Add multi-column sorting
 * Change; pre-create Cell and Heading objects to clean up Table a bit
 

data/examples/examples.rb

@@ -1,4 +1,3 @@
-
 $:.unshift File.dirname(__FILE__) + '/../lib'
 require 'terminal-table/import'
 
@@ -7,6 +6,7 @@ puts table(['a', 'b'], [1, 2], [3, 4])
 
 puts
 t = table ['a', 'b']
+t.style = {:padding_left => 2, :width => 80}
 t << [1, 2]
 t << [3, 4]
 t << :separator
@@ -14,11 +14,22 @@ t << [4, 6]
 puts t
 
 puts
-user_table = table do |t|
-  t.headings = 'First Name', 'Last Name', 'Email'
-  t << %w( TJ Holowaychuk tj@vision-media.ca )
-  t << %w( Bob Someone bob@vision-media.ca )
-  t << %w( Joe Whatever bob@vision-media.ca )
+user_table = table do |v|
+  v.title = "Contact Information"
+  v.headings = 'First Name', 'Last Name', 'Email'
+  v << %w( TJ Holowaychuk tj@vision-media.ca )
+  v << %w( Bob Someone bob@vision-media.ca )
+  v << %w( Joe Whatever bob@vision-media.ca )
+end
+puts user_table
+
+puts
+user_table = table do |v|
+  v.style.width = 80
+  v.headings = 'First Name', 'Last Name', 'Email'
+  v << %w( TJ Holowaychuk tj@vision-media.ca )
+  v << %w( Bob Someone bob@vision-media.ca )
+  v << %w( Joe Whatever bob@vision-media.ca )
 end
 puts user_table
 
@@ -38,7 +49,9 @@ 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 :separator
+  add_row ['TJ',  'Holowaychuk', {:value => "No phones\navaiable", :colspan => 2, :alignment => :center}]
+  add_row :separator
   add_row ['Joe', 'Whatever',    '4324', '343242']
 end
 puts user_table

data/lib/terminal-table.rb

@@ -22,10 +22,6 @@
 #++
 
 $:.unshift File.dirname(__FILE__)
-
-require 'terminal-table/version'
-require 'terminal-table/core_ext'
-require 'terminal-table/table'
-require 'terminal-table/cell'
-require 'terminal-table/heading'
-require 'terminal-table/table_helper'
+%w(version core_ext table cell row separator style table_helper).each do |file|
+  require "terminal-table/#{file}"
+end

data/lib/terminal-table/cell.rb

@@ -13,40 +13,75 @@ module Terminal
       
       attr_reader :value
       
-      ##
-      # Cell alignment.
-      
-      attr_reader :alignment
-      
       ##
       # Column span.
       
       attr_reader :colspan
       
       ##
-      # Initialize with _width_ and _options_.
+      # Initialize with _options_.
       
-      def initialize width, options = nil
-        @width = width
+      def initialize options = nil
         @value, options = options, {} unless Hash === options
         @value = options.fetch :value, value
-        @alignment = options.fetch :alignment, :left
+        @alignment = options.fetch :alignment, nil
         @colspan = options.fetch :colspan, 1
+        @width = options.fetch :width, @value.to_s.size
+        @index = options.fetch :index
+        @table = options.fetch :table
+      end
+      
+      def alignment?
+        !@alignment.nil?
+      end
+      
+      def alignment
+        @alignment || :left
+      end
+      
+      def alignment=(val)
+        supported = %w(left center right)
+        if supported.include?(val.to_s)
+          @alignment = val
+        else
+          raise "Aligment must be one of: #{supported.join(' ')}"
+        end
+      end
+      
+      def lines
+        @value.to_s.split(/\n/)
       end
       
       ##
       # Render the cell.
       
-      def render
-        " #{value} ".align alignment, width + 2
+      def render(line = 0)
+        left = " " * @table.style.padding_left
+        right = " " * @table.style.padding_right
+        "#{left}#{lines[line]}#{right}".align(alignment, width + @table.cell_padding)
       end
       alias :to_s :render
       
       ##
-      # Cell length.
+      # Returns the longest line in the cell and
+      # removes all ANSI escape sequences (e.g. color)
+      
+      def value_for_column_width_recalc
+        str = lines.sort_by { |s| s.size }.last.to_s
+        str = str.gsub(/\x1b(\[|\(|\))[;?0-9]*[0-9A-Za-z]/, '')
+        str = str.gsub(/\x1b(\[|\(|\))[;?0-9]*[0-9A-Za-z]/, '')
+        str.gsub(/[\x03|\x1a]/, '')
+      end
+      
+      ##
+      # Returns the width of this cell
       
-      def length
-        value.to_s.length + 2
+      def width
+        padding = (colspan - 1) * @table.cell_spacing
+        inner_width = (1..@colspan).to_a.inject(0) do |w, counter|
+          w + @table.column_width(@index + counter - 1)
+        end
+        inner_width + padding
       end
     end
   end