terminal-table 1.8.0 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8fbefc4babd3ccb3e9e7caca474bec488cf6f234
-  data.tar.gz: 1ed67b9091ccce0e7d1d4782e7d7a9d0d59359c4
+SHA256:
+  metadata.gz: 6213eea6e6bf691a9594f64660d97e3c56503c43bf2a95075f62aafca2b4d130
+  data.tar.gz: a3511ef514b25731d1753bc695e7066ac04c76d9ce5da62ac5d8d3f6208daa3a
 SHA512:
-  metadata.gz: 6b5b405dc6afba3a3388c2f4d70c61a01130946b050c94e33414822868d432809f4cde2c1c4a724995d862a763664dc2f6cfeeffa6339f468e9c1a34aa111d63
-  data.tar.gz: 9418542619af83d894a50f9a5a8e0e564f86382f378fe5ea15adc8a4331eaf3ffb7e7c11d86f945239aff2d758962f359a1acff9e60fa46a3b622ef9aaeaaceb
+  metadata.gz: bb49c90ce6d6edbfe07c2c335b2c5bf25df41f67a3d31b4d413febebc597ce47906575e738dd05be742d948bd854948c605414ad581ea033b36099c52dd1cf36
+  data.tar.gz: f49a1837097b5417887ba6eddd2deaad9e3dab933a67d22b23fd6028255dfd56d0e2d327dd80c87b6a99da94a5d00e2147feed2155b37590b72284610c3b408d

data/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+on: [push]
+
+jobs:
+  test:
+    if: "!contains(github.event.head_commit.message, 'ci skip')"
+
+    continue-on-error: ${{ endsWith(matrix.ruby, 'head') || matrix.ruby == 'debug' }}
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        os: [ubuntu]
+        ruby: [2.4, 2.5, 2.6, 2.7]
+
+    runs-on: ${{ matrix.os }}-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: ${{ matrix.ruby }}
+
+      - run: bundle install
+      - run: bundle exec rspec

data/.gitignore

@@ -3,4 +3,9 @@ pkg
 tmp
 *.cache
 doc
+vendor
+/.bundle
 Gemfile.lock
+
+# tempfiles
+*~

data/History.rdoc

@@ -1,3 +1,60 @@
+3.0.2 / 2021-09-19
+==================
+
+- fix align_column for nil values and colspan
+
+3.0.1 / 2021-05-10
+==================
+
+- Support for unicode-display_width 2.0
+- Fix issue where last row of an empty table changed format
+
+3.0.0 / 2020-01-27
+==================
+
+- Support for (optional) Unicode border styles on tables.  In order to support decent looking Unicode borders, different types of intersections get different types of intersection characters.  This has the side effect of subtle formatting differences even for the ASCII table border case due to removal of certain intersections near colspans.
+
+For example, previously the output of a table may be:
+        +------+-----+
+        |   Title    |
+        +------+-----+
+        | Char | Num |
+        +------+-----+
+        | a    | 1   |
+        | b    | 2   |
+        | c    | 3   |
+        +------+-----+
+
+And now the `+` character above the word Title is removed, as it is no longer considered an intersection:
+
+        +------------+
+        |   Title    |
+        +------+-----+
+        | Char | Num |
+        +------+-----+
+        | a    | 1   |
+        | b    | 2   |
+        +------+-----+
+
+- The default border remains an ASCII border for backwards compatibility, however multiple border classes are included / documented, and user defined border types can be applied as needed.
+
+In support of this update, the following issues were addressed:
+- colspan creates conflict with colorize (#95)
+- Use nice UTF box-drawing characters by default (#99)
+    - Note that `AsciiBorder` is stll the default
+- Border-left and border-right style (#100)
+- Helper function to style as Markdown (#111)
+    - Achieved using `MarkdownBorder`
+
+2.0.0 / 2020-10-28
+==================
+
+- Drops official support for Ruby 1.9.x with and of life on 2015-02-23
+- Drops official support for Ruby 2.0.x with and of life on 2016-02-24
+- Drops official support for Ruby 2.1.x with and of life on 2017-03-31
+- Drops official support for Ruby 2.2.x with and of life on 2018-03-31
+- Drops official support for Ruby 2.3.x with and of life on 2019-03-31
+
 1.8.0 / 2017-05-16
 ==================
 

data/README.md

@@ -0,0 +1,417 @@
+[![CI status](https://github.com/tj/terminal-table/workflows/CI/badge.svg)](https://github.com/tj/terminal-table/actions)
+[![Gem Version](https://badge.fury.io/rb/terminal-table.svg)](https://badge.fury.io/rb/terminal-table)
+
+# Terminal Table
+
+## Description
+
+Terminal Table is a fast and simple, yet feature rich table generator
+written in Ruby.  It supports ASCII and Unicode formatted tables.
+
+## Installation
+
+```
+$ gem install terminal-table
+```
+## Usage
+
+### Basics
+
+To use Terminal Table:
+
+```ruby
+require 'terminal-table'
+```
+To generate a table, provide an array of arrays (which are interpreted as
+rows):
+
+```ruby
+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:
+
+```ruby
+table = Terminal::Table.new do |t|
+  t.rows = rows
+end
+
+table = Terminal::Table.new do
+  self.rows = rows
+end
+```
+Adding rows one by one:
+
+```ruby
+table = Terminal::Table.new do |t|
+  t << ['One', 1]
+  t.add_row ['Two', 2]
+end
+```
+To add separators between rows:
+
+```ruby
+table = Terminal::Table.new do |t|
+  t << ['One', 1]          # Using << (push) as an alias for add_row
+  t << :separator          # Using << with :separator as an alias for add_separator
+  t.add_row ['Two', 2]
+  t.add_separator          # Note - this version allows setting the separator's border_type
+  t.add_row ['Three', 3]
+end
+
+# > puts table
+#
+# +-------+---+
+# | One   | 1 |
+# +-------+---+
+# | Two   | 2 |
+# +-------+---+
+# | Three | 3 |
+# +-------+---+
+```
+Cells can handle multiline content:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+table.style = {:width => 40, :padding_left => 3, :border_x => "=", :border_i => "x"}
+
+# > puts table
+#
+# 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:
+
+```ruby
+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.
+
+```ruby
+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 |
+```
+
+And also to disable left and right borders of the table.
+
+```ruby
+table = Terminal::Table.new do |t|
+  t.headings = ['id', 'name']
+  t.rows = [[1, 'One'], [2, 'Two'], [3, 'Three']]
+  t.style = { :border_left => false, :border_right => false }
+end
+
+# > puts table
+# ----+-------
+#  id | name
+# ----+-------
+#  1  | One
+#  2  | Two
+#  3  | Three
+# ----+-------
+```
+
+To change the default style options:
+
+```ruby
+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:
+
+```ruby
+table = Terminal::Table.new
+table.title = "Cheatsheet"
+table.headings = ['Word', 'Number']
+table.rows = rows
+table.style = {:width => 40}
+```
+
+## New Formatting
+
+### Unicode Table Borders
+Support for Unicode 'box art' borders presented a challenge, as the original terminal-table only handled three border types:  horizontal (x), vertical (y), and intersection (i).  For proper box-art, it became necessary to enable different types of corners/edges for multiple intersection types.
+
+For the sake of backward compatiblity, the previous interface is still supported, as this gem has been around a long time and making breaking changes would have been inconvenient.  The new interface is required for any complex and/or Unicode style bordering. A few variations on border style are supported via some new classes and creation of additional classes (or modification of characters used in existing ones) will allow for customized border types.
+
+The simplest way to use an alternate border is one of the following:
+```
+table.style = { :border => :unicode }
+table.style = { :border => :unicode_round }
+table.style = { :border => :unicode_thick_edge }
+```
+
+These are a convenience wrapper around setting border using an instance of a class that inherits from Table::Terminal::Border
+```
+table.style = { :border => Terminal::Table::UnicodeBorder.new() }
+table.style = { :border => Terminal::Table::UnicodeRoundBorder.new() }
+table.style = { :border => Terminal::Table::UnicodeThickEdgeBorder.new() }
+```
+
+If you define a custom class and wish to use the symbol shortcut, you must namespace within `Terminal::Table` and end your class name with `Border`.
+
+### Markdown Compatiblity
+Per popular request, Markdown formatted tables can be generated by using the following border style:
+
+```
+table.style = { :border => :markdown }
+```
+
+### Ascii Borders
+Ascii borders are default, but can be explicitly set with:
+```
+table.style = { :border => :ascii }
+```
+
+### Customizing Borders
+Inside the `UnicodeBorder` class, there are definitions for a variety of corner/intersection and divider types.
+
+```ruby
+@data = {
+  nil => nil,
+  nw: "┌", nx: "─", n:  "┬", ne: "┐",
+  yw: "│",          y:  "│", ye: "│", 
+  aw: "╞", ax: "═", ai: "╪", ae: "╡", ad: '╤', au: "╧", # double
+  bw: "┝", bx: "━", bi: "┿", be: "┥", bd: '┯', bu: "┷", # heavy/bold/thick
+  w:  "├", x:  "─", i:  "┼", e:  "┤", dn: "┬", up: "┴", # normal div
+  sw: "└", sx: "─", s:  "┴", se: "┘",
+  # alternative dots/dashes
+  x_dot4:  '┈', x_dot3:  '┄', x_dash:  '╌',
+  bx_dot4: '┉', bx_dot3: '┅', bx_dash: '╍',
+}
+```
+
+Note that many are defined as directional (:nw == north-west), others defined in terms of 'x' or 'y'.
+The border that separates headings (below each heading) is of type `:double` and is defined with `a*` entries.
+Alternate `:heavy` types that can be applied to separators can be defined with `b*` entries.
+
+When defining a new set of borders, it's probably easiest to define a new class that inherits from UnicodeBorder and replaces the `@data` Hash.
+However, these elements can be these can be overridden by poking setting the Hash, should the need arise:
+
+```
+table.style = {border: :unicode}
+table.style.border[:nw] = '*'  # Override the north-west corner of the table
+```
+
+### Customizing row separators
+
+Row-separators can now be customized in a variety of ways.  The default separator's border_type is referred to as `:div`.  Additional separator border types (e.g. `:double`, `:heavy`, `:dash` - see full list below) can be applied to separate the sections (e.g. header/footer/title).
+
+The separator's `border_type`  may be specified when a user-defined separator is added.  Alternatively, borders may be adjusted after the table's rows are elaborated, but before the table is rendered.
+
+Separator `border_type`s can be adjusted to be heavy, use double-lines, and different dash/dot styles.  The border type should be one of:
+
+    div dash dot3 dot4 
+    thick thick_dash thick_dot3 thick_dot4
+    heavy heavy_dash heavy_dot3 heavy_dot4
+    bold bold_dash bold_dot3 bold_dot4
+    double
+
+To manually set the separator border_type, the `add_separator` method may be called.
+```ruby
+add_separator(border_type: :heavy_dash)
+```
+
+Alternatively, if `style: :all_separators` is used at the table level, it may be necessary to elaborate the implicit Separator rows prior to rendering.
+```ruby
+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
+rows = table.elaborate_rows
+rows[2].border_type = :heavy # modify separator row: emphasize below title
+puts table.render
+```
+
+## Example: Displaying a small CSV spreadsheet
+
+This example code demonstrates using Terminal-table and CSV to display a small spreadsheet.
+
+```ruby
+#!/usr/bin/env ruby
+require "csv"
+require "terminal-table"
+use_stdin = ARGV[0].nil? || (ARGV[0] == '-')
+io_object = use_stdin ? $stdin : File.open(ARGV[0], 'r')
+csv = CSV.new(io_object)
+csv_array = csv.to_a
+user_table = Terminal::Table.new do |v|
+  v.style = { :border => :unicode_round } # >= v3.0.0
+  v.title = "Some Title"
+  v.headings = csv_array[0]
+  v.rows = csv_array[1..-1]
+end
+puts user_table
+```
+
+See also `examples/show_csv_table.rb` in the source distribution.
+
+## More examples
+
+For more examples, please see the `examples` directory included in the
+source distribution.
+
+## Author
+
+TJ Holowaychuk <tj@vision-media.ca>
+
+Unicode table support by Ben Bowers https://github.com/nanobowers

data/examples/data.csv

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

data/examples/examples_unicode.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.dirname(__FILE__) + '/../lib'
+require 'terminal-table/import'
+
+Terminal::Table::Style.defaults = { :border => :unicode_round }
+# Terminal::Table::UnicodeThickEdgeBorder.new()
+
+puts
+puts table(['a', 'b'], [1, 2], [3, 4])
+
+puts
+puts table(['name', 'content'], ['ftp.example.com', '1.1.1.1'], ['www.example.com', '|lalalala|lalala|'])
+
+puts
+t = table ['a', 'b']
+t.style = {:padding_left => 2, :width => 80}
+t << [1, 2]
+t << [3, 4]
+t << :separator
+t << [4, 6]
+puts t
+
+puts
+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
+
+puts
+user_table = table do
+  self.headings = 'First Name', 'Last Name', 'Email'
+  add_row ['TJ',  'Holowaychuk', 'tj@vision-media.ca']
+  add_row ['Bob', 'Someone',     'bob@vision-media.ca']
+  add_row ['Joe', 'Whatever',    'joe@vision-media.ca']
+  add_separator
+  add_row ['Total', { :value => '3', :colspan => 2, :alignment => :right }]
+  align_column 1, :center
+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 [{:value => "Bob Someone", :colspan => 3, :alignment => :center}, '123456']
+  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
+
+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)
+
+rows = []
+rows << ['Lines',      100]
+rows << ['Comments',   20]
+rows << ['Ruby',       70]
+rows << ['JavaScript', 30]
+table = table([{ :value => 'Stats', :colspan => 2, :alignment => :center }], *rows)
+table.align_column 1, :right
+puts table

data/examples/issue100.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+
+# Methods to suppress left/right borders using border_left & border_right
+
+require_relative "../lib/terminal-table"
+table = Terminal::Table.new do |t|
+  t.headings = ['id', 'name']
+  t.rows = [[1, 'One'], [2, 'Two'], [3, 'Three']]
+  t.style = { :border_left => false, :border_top => false, :border_bottom => false }
+end
+
+puts table
+puts
+
+# no right
+table.style = {:border_right => false }
+puts table
+puts
+
+# no right
+table.style = {:border_left => true }
+puts table
+puts
+
+table.style.border = Terminal::Table::UnicodeBorder.new
+puts table
+
+
+table.style = {:border_right => false, :border_left => true }
+puts table
+
+table.style = {:border_right => true, :border_left => false }
+puts table
+

data/examples/issue111.rb

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative "../lib/terminal-table"
+puts Terminal::Table.new(headings: ['heading A', 'heading B'], rows: [['a', 'b'], ['a', 'b']], style: {border: Terminal::Table::MarkdownBorder.new})
+

data/examples/issue118.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/terminal-table'
+
+puts Terminal::Table.new(headings: ['a', 'b', 'c', 'd'], style: { border: :unicode })
+
+puts
+
+tbl = Terminal::Table.new do |t|
+  t.style = { border: :unicode }
+  t.add_separator
+  t.add_separator
+  t.add_row ['x','y','z']
+  t.add_separator
+  t.add_separator
+end
+puts tbl
+
+puts
+
+puts Terminal::Table.new(headings: [['a', 'b', 'c', 'd'], ['cat','dog','frog','mouse']], style: { border: :unicode })
+
+puts
+
+puts Terminal::Table.new(headings: ['a', 'b', 'c', 'd'])
+
+puts
+
+tbl = Terminal::Table.new do |t|
+  t.add_separator
+  t.add_separator
+  t.add_row ['x','y','z']
+  t.add_separator
+  t.add_separator
+end
+puts tbl