tty-table 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5fd8b00601ae34976c7045b404d50fabf7729279
-  data.tar.gz: 446d1950b5192161cab664732b9caeeec25bd186
+  metadata.gz: 4c9b59ba29023d88b80d1337c882ed5a8a21994e
+  data.tar.gz: 15ead8cc776eaa5a61920719a1b2252a04505827
 SHA512:
-  metadata.gz: 821d23c84214d24ba025b652bfecc77c155ffce1af44e9a575d3f8187b3165393e1e2085740570b359a6e4d9d7c4607b784fc1a863090512fd248fa762f55e8c
-  data.tar.gz: e3a93020ff3ab85e8afbca2664c7a6034cb385a2d2fce62e37563ea14c37255e0a5a18ab6ebaad72a1c2d7fd29933614212d43843300ed866959b7a4251beecb
+  metadata.gz: 90fa0140b4962bacd8aa1fc51fdb33e4390113ad915b3b9c4789e237073507210276c0ea4f3df6ead55c2f5b820aaa737deab5ea70e88366d196f6718141f243
+  data.tar.gz: 87f0906fffa4b503fc4d02bffcb4c0eb909730b76cff707a9aeaca9374f6c1118a359c03d364dac28db6645b37ed2fcb3f9340d91f8162c0ebb67bcce1e2ac05

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+0.2.0 (Mar 30, 2015)
+
+* Add UTF-8 support for operations
+* Add AlignmentSet for alignments storage
+* Add tests for multilne column widths
+
+* Remove padding from wrapped operation to fully rely on Verse.wrap
+* Remove color renderer
+* Remove adjust_padding from Columns
+
+* Change Table each_with_index to iterate over rows
+* Change Alignment operation to use AlignmentSet
+* Change Columns to directly depend on table data
+* Change Indentation to stop relying on renderer
+* Change Border to accept padding as argument
+* Change and extract padding operation
+* Change Columns to ColumnConstraint and refactor enforce
+
+* Fix table rendering for UTF-8 content
+* Fix alignment to allow for individual field alignment
+* Fix bug with padding operation
+* Fix table border and content coloring
+* Fix bug with table rerendering to allow for multiple renders
+* Fix bug with ANSI codes in table content

data/README.md

@@ -14,6 +14,14 @@
 
 **TTY::Table** provides independent table formatting component for [TTY](https://github.com/peter-murach/tty) toolkit.
 
+## Features
+
+* Table behaves like an array with familiar API [see](#2-interface)
+* Create table once and render using custom view renderers [see](#3-rendering)
+* Rendering provides many display options [see](#33-options)
+* Easy custom border creation [see](#352-custom)
+* Supports multibyte character encodings
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -34,14 +42,28 @@ Or install it yourself as:
 
 * [1. Usage](#1-usage)
 * [2. Interface](#2-interface)
-  * [2.1 Initializaation](#21-initialization)
-  * [2.2 Rendering](#22-rendering)
-  * [2.3 Multiline](#23-multiline)
-  * [2.4 Border](#24-border)
-  * [2.5 Alignment](#25-alignment)
-  * [2.6 Padding](#26-padding)
-  * [2.7 Filter](#27-filter)
-  * [2.8 Width](#28-width)
+  * [2.1 Initialization](#21-initialization)
+  * [2.2 Iteration](#22-iteration)
+  * [2.3 Access](#23-access)
+  * [2.4 Size](#24-size)
+* [3. Rendering](#3-rendering)
+  * [3.1 Render](#31-render)
+  * [3.2 Renderer](#32-renderer)
+    * [3.1.1 Basic renderer](#311-basic)
+    * [3.1.2 ASCII renderer](#312-ascii-renderer)
+    * [3.1.3 Unicode renderer](#313-unicode-renderer)
+  * [3.3 Options](#33-options)
+  * [3.4 Alignment](#34-alignment)
+  * [3.5 Border](#35-border)
+    * [3.5.1 Parts](#351-parts)
+    * [3.5.2 Custom](#352-custom)
+    * [3.5.3 Separator](#353-separator)
+    * [3.5.4 Style](#354-style)
+  * [3.6 Filter](#36-filter)
+  * [3.7 Multiline](#37-multiline)
+  * [3.8 Padding](#38-padding)
+  * [3.9 Resize](#39-resize)
+  * [3.10 Width](#310-width)
 
 ## 1. Usage
 
@@ -51,10 +73,10 @@ First, provide **TTY::Table** with headers and data:
 table = TTY::Table.new ['header1','header2'], [['a1', 'a2'], ['b1', 'b2']]
 ```
 
-Then simply call `render` or `to_s` on the instance:
+Then simply call `render` on the instance with with border type as first argument:
 
 ```ruby
-table.render
+table.render(:ascii)
 # =>
   +-------+-------+
   |header1|header2|
@@ -69,12 +91,34 @@ table.render
 
 ### 2.1 Initialization
 
-To instantiate **TTY::Table** pass 2-dimensional array:
+**TTY::Table** can be created in variety of ways. The easiest way is to pass 2-dimensional array:
 
 ```ruby
 table = TTY::Table[['a1', 'a2'], ['b1', 'b2']]
 table = TTY::Table.new [['a1', 'a2'], ['b1', 'b2']]
 table = TTY::Table.new rows: [['a1', 'a2'], ['b1', 'b2']]
+```
+
+Alternatively you can specify rows one by one inside block:
+
+```ruby
+table = TTY::Table.new do |t|
+  t << ['a1', 'a2']
+  t << ['b1', 'b2']
+end
+```
+
+You can add rows of data after initialization:
+
+```ruby
+table = TTY::Table.new
+table << ['a1','a2']
+table << ['b1','b2']
+```
+
+In addition to rows you can specify table header:
+
+```ruby
 table = TTY::Table.new ['h1', 'h2'], [['a1', 'a2'], ['b1', 'b2']]
 table = TTY::Table.new header: ['h1', 'h2'], rows: [['a1', 'a2'], ['b1', 'b2']]
 ```
@@ -85,98 +129,301 @@ or cross header with rows inside a hash like so
 table = TTY::Table.new [{'h1' => ['a1', 'a2'], 'h2' => ['b1', 'b2']}]
 ```
 
-Table behaves like an Array so `<<`, `each` and familiar methods can be used
+### 2.2 Iteration
+
+Table behaves like an Array so `<<`, `each` and familiar methods can be used:
 
 ```ruby
 table << ['a1', 'a2', 'a3']
 table << ['b1', 'b2', 'b3']
 table << ['a1', 'a2'] << ['b1', 'b2']  # chain rows assignment
+```
+
+In order to iterate over table rows including headers do:
+
+```ruby
+table.each { |row| ... }                       # iterate over rows
+table.each_with_index  { |row, index| ... }    # iterate over rows with an index
+```
+
+### 2.3 Access
+
+In order to referene the row at `index` do:
+
+```ruby
+table = TTY::Table.new [['a1','a2'], ['b1','b2']]
+table[0]                    # => ['a1','a2']
+table.row(0)                # => ['a1','a2']
+table.row(i) { |row| ... }  # return array for row(i)
+```
+
+Negative indices count backwards from the end of table data (`-1` is the last element):
+
+```ruby
+table[-1]   # => ['b1','b2']
+```
+
+To reference element at given row(i) and column(j) do:
+
+```ruby
+table[i, j]   # return element at row(i) and column(j)
+table[0,0]    # => 'a1'
+```
+
+To specifically reference column(j) do:
 
-table.each { |row| ... }  # iterate over rows
-table.each_with_index     # iterate over each element with row and column index
-table[i, j]               # return element at row(i) and column(j)
-table.row(i) { ... }      # return array for row(i)
+```ruby
 table.column(j) { ... }   # return array for column(j)
+table.column(0)           # => ['a1','b1']
 table.column(name)        # return array for column(name), name of header
-table.row_size            # return row size
-table.column_size         # return column size
-table.size                # return an array of [row_size, column_size]
-table.border              # specify border properties
 ```
 
-or pass your rows in a block
+An `IndexError` is raised for indexes outside of data range.
+
+### 2.4 Size
+
+In order to query the number of rows, columns or size do:
+
+```ruby
+table.rows_size        # return row size
+table.columns_size     # return column size
+table.size             # return an array of [row_size, column_size]
+```
+
+### 2.5 Orientation
+
+## 3 Rendering
+
+**TTY-Table** rendering process means you can create tabular data once and then create different renderers to match your needs for formatting the data.
+
+### 3.1 Render
+
+Given a table:
+
+```ruby
+table = TTY::Table.new ['header1','header2'], [['a1', 'a2'], ['b1', 'b2']]
+```
+
+Once you have an instance of `TTY::Table` you can decorate the content using the `render` method. In order to display a basic whitespace delimited view do:
+
+```ruby
+table.render(:basic)
+# =>
+  header1 header2
+  a1      a2
+  b1      b2
+```
+
+This will use so called `:basic` renderer with default options. The other renderers are `:ascii` and `:unicode`.
+
+The `render` method can accept as a second argument the [rendering options](#33-options) either as hash value:
+
+```ruby
+table.render(:basic, alignments: [:left, :center])
+```
+
+or inside a block:
 
 ```ruby
-table = TTY::Table.new  do |t|
-  t << ['a1', 'a2', 'a3']
-  t << ['b1', 'b2', 'b3']
+table.render(:basic) do |renderer|
+  renderer.alignments= [:left, :center]
 end
 ```
 
-### 2.2 Rendering
+### 3.2 Renderer
+
+**TTY::Table** has a definition of `TTY::Table::Renderer` which allows you to provide different view for your tabular data. It comes with few initial renderers built in such as `TTY::Table::Renderer::Basic`, `TTY::Table::Renderer::ASCII` and `TTY::Table::Renderer:Unicode`.
 
-Once you have an instance of `TTY::Table` you can print it out to the stdout like so:
+Given a table of data:
 
 ```ruby
-table.to_s
+table = TTY::Table.new ['header1','header2'], [['a1', 'a2'], ['b1', 'b2']]
+```
 
-a1  a2  a3
-b1  b2  b3
+You can create a special renderer for it:
+
+```ruby
+multi_renderer = TTY::Table::Renderer::Basic.new(table, multiline: true)
 ```
 
-This will use so called `basic` renderer with default options.
+and then call `render`
 
-However, you can include other customization options such as
+```ruby
+multi_renderer.render
+```
+
+This way, you create tabular data once and then create different renderers to match your needs for formatting the data.
+
+#### 3.2.1 Basic Renderer
+
+The basic render allows for formatting table with whitespace without any border:
+
+```ruby
+renderer = TTY::Table::Renderer::Basic.new(table)
+```
+
+```ruby
+renderer.render
+# =>
+  header1 header2
+  a1      a2
+  b1      b2
+```
+
+This is the same as calling `render` directly on table:
+
+```ruby
+table.render
+```
+
+#### 3.2.2 ASCII Renderer
+
+The ascii renderer allows for formatting table with ASCII type border.
+
+Create an instance of ASCII renderer:
+
+```ruby
+renderer = TTY::Table::Renderer::ASCII.new(table)
+```
+
+and then call `render` to get the formatted data:
+
+```ruby
+renderer.render
+# =>
+  +-------+-------+
+  |header1|header2|
+  +-------+-------+
+  |a1     |a2     |
+  |b1     |b2     |
+  +-------+-------+
+```
+
+This is the same as calling `render` directly on table instance with `:ascii` as the first argument:
 
 ```ruby
-border         # hash of border properties out of :characters, :style, :separator keys
-border_class   # a type of border to use
-column_widths  # array of maximum columns widths
-column_aligns  # array of cell alignments out of :left, :center and :right, default :left
+table.render(:ascii)
+```
+
+#### 3.2.3 Unicode Renderer
+
+The uniocde renderer allows for formatting table with Unicode type border.
+
+Create an instance of Unicode renderer:
+
+```ruby
+renderer = TTY::Table::Renderer::Unicode.new(table)
+```
+
+and then call `render` to get the formatted data:
+
+```ruby
+renderer.render
+# =>
+  ┌───────┬───────┐
+  │header1│header2│
+  ├───────┼───────┤
+  │a1     │a2     │
+  │b1     │b2     │
+  └───────┴───────┘
+```
+
+This is the same as calling `render` directly on table instance with `:unicode` as the first argument:
+
+```ruby
+table.render(:unicode)
+```
+
+### 3.3 Options
+
+Rendering of **TTY-Table** includes numerous customization options:
+
+```ruby
+alignments     # array of cell alignments out of :left, :center and :right,
+               # default :left
+border         # hash of border options - :characters, :style and :separator
+border_class   # a type of border to use such as TTY::Table::Border::Null,
+               # TTY::Table::Border::ASCII, TTY::Table::Border::Unicode
+column_widths  # array of maximum column widths
 filter         # a proc object that is applied to every field in a row
-indent         # indentation applied to rendered table
+indent         # indentation applied to rendered table, by default 0
 multiline      # if true will wrap text at new line or column width,
                # when false will escape special characters
-orientation    # either :horizontal or :vertical
-padding        # array of integers to set table fields padding
-renderer       # enforce display type out of :basic, :color, :unicode, :ascii
-resize         # if true will expand/shrink table column sizes to match the width,
-               # otherwise if false rotate table vertically
-width          # constrain the table total width, otherwise dynamically
-               # calculated from content and terminal size
+padding        # array of integers to set table fields padding,
+               # by default [0,0,0,0]
+resize         # if true will expand/shrink table column sizes to match
+               # the terminal width, otherwise if false will rotate
+               # table vertically. By default set to false
+width          # constrain the table total width, by default dynamically
+               # calculated based on content and terminal size
 ```
 
-### 2.3 Multiline
+The `render` method can accept as a second argument the above options either as hash value:
+
+```ruby
+table.render(:basic, alignments: [:left, :center])
+```
 
-Renderer options may include `multiline` parameter. The `true` value will cause the table fields wrap at their natural line breaks or in case when the column widths are set the content will wrap.
+or inside a block:
 
 ```ruby
-table = TTY::Table.new [ ["First", '1'], ["Multi\nLine\nContent", '2'], ["Third", '3']]
-table.render :ascii, multiline: true
+table.render(:basic) do |renderer|
+  renderer.alignments= [:left, :center]
+end
+```
+
+### 3.4 Alignment
+
+By default all columns are `:left` aligned.
+
+You can align each column individuall by passing `alignments` option to table renderer:
+
+```ruby
+table.render :ascii, alignments: [:center, :right]
 # =>
-  +-------+-+
-  |First  |1|
-  |Multi  |2|
-  |Line   | |
-  |Content| |
-  |Third  |3|
-  +-------+-+
+  +-------+-------+
+  |header1|header2|
+  +-------+-------+
+  |  a1   |     a2|
+  |  b1   |     b2|
+  +-------+-------+
 ```
 
-When the `false` option is specified all the special characters will be escaped and if the column widths are set the content will be truncated like so
+Alternatively you can align all columns with `alignment` option:
 
 ```ruby
-table = TTY::Table.new [ ["First", '1'], ["Multiline\nContent", '2'], ["Third", '3']]
-table.render :ascii, multiline: false
+table.render :ascii, alignment: [:center]
 # =>
-  +------------------+-+
-  |First             |1|
-  |Multiline\nContent|2|
-  |Third             |3|
-  +------------------+-+
+  +-------+-------+
+  |header1|header2|
+  +-------+-------+
+  |  a1   |  a2   |
+  |  b1   |  b2   |
+  +-------+-------+
+```
+
+If you require a more granular alignment you can align individual fields in a row by passing `:alignment` option like so:
+
+```ruby
+table = TTY::Table.new header: ['header1', 'header2']
+table << [{value: 'a1', alignment: :right}, 'a2']
+table << ['b1', {value: 'b2', alignment: :center}]
+```
+
+and then simply render:
+
+```ruby
+table.render(:ascii)
+# =>
+  +-------+-------+
+  |header1|header2|
+  +-------+-------+
+  |     a1|a2     |
+  |b1     |  b2   |
+  +-------+-------+
 ```
 
-### 2.4 Border
+### 3.5 Border
 
 To print border around data table you need to specify `renderer` type out of `basic`, `ascii`, `unicode`. By default `basic` is used. For instance, to output unicode border:
 
@@ -192,6 +439,54 @@ table.render :unicode
   └───────┴───────┘
 ```
 
+or by creating unicode renderer:
+
+```ruby
+renderer = TTY::Table::Renderer::Unicode.new(table)
+renderer.render
+```
+
+#### 3.5.1 Parts
+
+The following are available border parts:
+
+| Part          | ASCII | Unicode |
+| ------------- |:-----:|:-------:|
+|  top          | `-`   | `─`     |
+|  top_mid      | `+`   | `┬`     |
+|  top_left     | `+`   | `┌`     |
+|  top_right    | `+`   | `┐`     |
+|  bottom       | `-`   | `─`     |
+|  bottom_mid   | `+`   | `┴`     |
+|  bottom_left  | `+`   | `└`     |
+|  bottom_right | `+`   | `┘`     |
+|  mid          | `-`   | `─`     |
+|  mid_mid      | `+`   | `┼`     |
+|  mid_left     | `+`   | `├`     |
+|  mid_right    | `+`   | `┤`     |
+|  left         | `|`   | `│`     |
+|  center       | `|`   | `│`     |
+|  right        | `|`   | `│`     |
+
+Using the above border parts you can create your own border with the `border` helper:
+
+```ruby
+table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
+table.render do |renderer|
+  renderer.border do
+    mid          '='
+    mid_mid      ' '
+  end
+end
+# =>
+  header1 header2
+  ======= =======
+  a1      a2
+  b1      b2
+```
+
+#### 3.5.2 Custom
+
 You can also create your own custom border by subclassing `TTY::Table::Border` and implementing the `def_border` method using internal DSL methods like so:
 
 ```ruby
@@ -219,22 +514,7 @@ table.render_with MyBorder
   *       *       *
 ```
 
-Finally, if you want to introduce slight modifications to the predefined border types, you can use table `border` helper like so
-
-```ruby
-table = TTY::Table.new ['header1', 'header2'], [['a1', 'a2'], ['b1', 'b2']
-table.render do |renderer|
-  renderer.border do
-    mid          '='
-    mid_mid      ' '
-  end
-end
-# =>
-  header1 header2
-  ======= =======
-  a1      a2
-  b1      b2
-```
+#### 3.5.3 Separator
 
 In addition to specifying border characters you can force table to render separator line on each row like:
 
@@ -253,75 +533,19 @@ end
   +-------+-------+
 ```
 
-Also to change the display color of your border do:
+#### 3.5.4 Style
 
-```ruby
-table.render do |renderer|
-  renderer.border.style = :red
-end
-```
-
-### 2.5 Alignment
-
-All columns are left aligned by default. You can enforce per column alignment by passing `column_aligns` option like so
-
-```ruby
-rows = [['a1', 'a2'], ['b1', 'b2']
-table = TTY::Table.new rows: rows
-table.render column_aligns: [:center, :right]
-```
-
-To align a single column do
-
-```ruby
-table.align_column(1, :right)
-```
-
-If you require a more granular alignment you can align individual fields in a row by passing `align` option
+If you want to change the display color of your border do:
 
 ```ruby
-table = TTY::Table.new do |t|
-  t << ['a1', 'a2', 'a3']
-  t << ['b1', {:value => 'b2', :align => :right}, 'b3']
-  t << ['c1', 'c2', {:value => 'c3', :align => :center}]
+table.render do |renderer|
+  renderer.border.style = :green
 end
 ```
 
-#### 2.6 Padding
-
-By default padding is not applied. You can add `padding` to table fields like so
-
-```ruby
-header = ['Field', 'Type', 'Null', 'Key', 'Default', 'Extra']
-rows  = [['id', 'int(11)', 'YES', 'nil', 'NULL', '']]
-table = TTY::Table.new(header, rows)
-table.render { |renderer| renderer.padding= [0,1,0,1] }
-# =>
-  +-------+---------+------+-----+---------+-------+
-  | Field | Type    | Null | Key | Default | Extra |
-  +-------+---------+------+-----+---------+-------+
-  | id    | int(11) | YES  | nil | NULL    |       |
-  +-------+---------+------+-----+---------+-------+
-```
-
-or you can set specific padding using `right`, `left`, `top`, `bottom` helpers. However, when adding top or bottom padding a `multiline` option needs to be set to `true` to allow for rows to span multiple lines. For example
+All [supported colors](https://github.com/peter-murach/pastel#3-supported-colors) are provided by the **Pastel** dependency.
 
-```ruby
-table.render { |renderer|
-  renderer.multiline = true
-  renderer.padding.top = 1
-}
-# =>
-  +-----+-------+----+---+-------+-----+
-  |     |       |    |   |       |     |
-  |Field|Type   |Null|Key|Default|Extra|
-  +-----+-------+----+---+-------+-----+
-  |     |       |    |   |       |     |
-  |id   |int(11)|YES |nil|NULL   |     |
-  +-----+-------+----+---+-------+-----+
-```
-
-### 2.7 Filter
+### 3.6 Filter
 
 You can define filters that will modify individual table fields value before they are rendered. A filter can be a callable such as proc. Here's an example that formats
 
@@ -356,7 +580,99 @@ table.render do |renderer|
 end
 ```
 
-### 2.8 Width
+### 3.7 Multiline
+
+Renderer options may include `multiline` parameter. When set to `true`, table fields will wrap at their natural line breaks or the column widths(if provided).
+
+```ruby
+table = TTY::Table.new [ ["First", '1'], ["Multi\nLine\nContent", '2'], ["Third", '3']]
+table.render :ascii, multiline: true
+# =>
+  +-------+-+
+  |First  |1|
+  |Multi  |2|
+  |Line   | |
+  |Content| |
+  |Third  |3|
+  +-------+-+
+```
+
+When `multiline` is set to `false`, all line break characters will be escaped. In cases when the column widths are set, the content will be truncated.
+
+```ruby
+table = TTY::Table.new [["First", '1'], ["Multiline\nContent", '2'], ["Third", '3']]
+table.render :ascii, multiline: false
+# =>
+  +------------------+-+
+  |First             |1|
+  |Multiline\nContent|2|
+  |Third             |3|
+  +------------------+-+
+```
+
+### 3.8 Padding
+
+Renderer also accepts `padding` option which accepts array with arguments similar to CSS padding.
+
+```ruby
+[2,2,2,2]  # => pad left and right with 2 characters, add 2 lines above and below
+[1,2]      # => pad left and right with 2 characters, add 1 line above and below
+1          # => pad left and right with 1 character, and 1 lines above and below
+```
+
+Therefore, to apply padding to the example table do:
+
+```ruby
+table.render(:ascii, padding: [1,2,1,2])
+# =>
+  +---------+---------+
+  |         |         |
+  | header1 | header2 |
+  |         |         |
+  +---------+---------+
+  |         |         |
+  | a1      | a2      |
+  |         |         |
+  |         |         |
+  | b1      | b2      |
+  |         |         |
+  +---------+---------+
+```
+
+However, when adding top or bottom padding to content with line breaks, the `multiline` option needs to be set to `true` to allow for rows to span multiple lines. For example:
+
+```ruby
+table = TTY::Table.new header: ['head1', 'head2']
+table << ["Multi\nLine", "Text\nthat\nwraps"]
+table << ["Some\nother\ntext", 'Simple']
+```
+
+would render as:
+
+```ruby
+table.render :ascii, multiline: true, padding: [1,2,1,2]
+# =>
+  +---------+----------+
+  |         |          |
+  |  h1     |  head2   |
+  |         |          |
+  +---------+----------+
+  |         |          |
+  |  Multi  |  Text    |
+  |  Line   |  that    |
+  |         |  wraps   |
+  |         |          |
+  |         |          |
+  |  Some   |  Simple  |
+  |  other  |          |
+  |  text   |          |
+  |         |          |
+  +---------+----------+
+```
+
+### 3.9 Resize
+
+### 3.10 Width
 
 To control table's column sizes pass `width`, `resize` options. By default table's natural column widths are calculated from the content. If the total table width does not fit in terminal window then the table is rotated vertically to preserve content.