tabulo 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1ac51b57ff0b2dc5ce13ea28612183fe2691ed88
-  data.tar.gz: f004eedf9ec5fa112a289aba3f8411805d88a9fb
+  metadata.gz: 02a658d45fe5df2a6b02a39ff1ef8b85b9406a5d
+  data.tar.gz: 1edee8575e0098a1d5b383f596ff8ef77e3916a0
 SHA512:
-  metadata.gz: 5aa026d70495b3a06a6d364ef2f58bfdb007911f0f43f770dd7fc66bdc6b7c55321234cfe938d1869661d6f5e5526b1b0eea4bf0c31348ccab4a901151c7347a
-  data.tar.gz: e05b95a3ee28396e71b4771ddaf2f3803715935c391cfce31e1488c8dbdbb3d5c9e5fc641c7fb8a61ffb24ea241979a637f285b24cabf6c49d54fbd24842b8c1
+  metadata.gz: 2d76f4fd33ede6de1a466affd190c6377f8e0a29b2c3986c7c4c83c0ac8001b285f880589d5a74668b572e8219c570f3aaa391b0dd8839f89c478f58b9bbc5f2
+  data.tar.gz: c4766b9abff559fd30f65356731e18311984b459bd67e11b7dc308bf93c92a2fab4902c6ea0c13bab81ffe5459df134074d93b2beec3ec26af8d8b5a4f4899df

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## v0.2.0
+
+* Allow columns to be initialized with `columns` option in `Table` initializer
+* Removed redundant `truncate` option.
+* Rename `wrap_cells_to` to `wrap_body_cells_to`.
+* Improve README.
+
+## v0.1.0
+
+Initial release.

data/README.md

@@ -2,9 +2,9 @@
 
 ## Overview
 
-Tabulo generates ASCII tables for displaying in a terminal or as preformatted text.
+Tabulo generates ASCII tables.
 
-A `Tabulo::Table` can be printed:
+A `Tabulo::Table` can, of course, be printed:
 
 ```
 > puts table
@@ -16,7 +16,7 @@ A `Tabulo::Table` can be printed:
 | 50000000 | 10000000 |
 ```
 
-But it is also `Enumerable`, so you can process it one row at a time:
+But it is also `Enumerable`, so you can process one row at a time:
 
 ```ruby
 table.each do |row|
@@ -25,6 +25,17 @@ table.each do |row|
 end
 ```
 
+And rows are themselves `Enumerable`, providing access to the underlying cell values:
+
+```ruby
+table.each do |row|
+  row.each do |cell|
+    # 1, 2, 50000000...
+    puts cell.class  # Fixnum
+  end
+end
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -37,23 +48,25 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
+Or install it yourself:
 
     $ gem install tabulo
 
-## Usage
+## Detailed usage
 
-Require the gem:
+### Requiring the gem
 
 ```ruby
 require 'tabulo'
 ```
 
-Instantiate a `Tabulo::Table` by passing it an underlying `Enumerable` and then telling it
+### Configuring columns
+
+You instantiate a `Tabulo::Table` by passing it an underlying `Enumerable` and then telling it
 the columns you want to generate.
 
 A simple case involves initializing columns from symbols corresponding to methods on members of the
-`Enumerable`. In this case the symbol also provides the header for each column:
+underlying `Enumerable`. In this case the symbol also provides the header for each column:
 
 ```ruby
 table = Tabulo::Table.new([1, 2, 5]) do |t|
@@ -61,36 +74,169 @@ table = Tabulo::Table.new([1, 2, 5]) do |t|
   t.add_column(:even?)
   t.add_column(:odd?)
 end
+```
+
+Or equivalently:
+
+```ruby
+Tabulo::Table.new([1, 2, 5], columns: %i(itself even odd))
+```
+
+The resulting table looks like this:
 
-# > puts table
-# +----------+----------+----------+
-# |  itself  |   even?  |   odd?   |
-# +----------+----------+----------+
-# |        1 |   false  |   true   |
-# |        2 |   true   |   false  |
-# |        5 |   false  |   true   |
+```
+> puts table
++----------+----------+----------+
+|  itself  |   even?  |   odd?   |
++----------+----------+----------+
+|        1 |   false  |   true   |
+|        2 |   true   |   false  |
+|        5 |   false  |   true   |
 ```
 
-Columns can also be initialized using blocks or procs that are called on each object. In this case
-the first argument provides the column header:
+Columns can also be initialized using a callable to which each object will be passed to determine
+the value to be displayed in the table. In this case, the first argument to `add_column` provides
+the header text:
 
 ```ruby
 table = Tabulo::Table.new([1, 2, 5]) do |t|
   t.add_column("N", &:itself)
   t.add_column("Doubled") { |n| n * 2 }
+  t.add_column(:odd?)  # we can mix and match
 end
+```
+
+```
+> puts table
++----------+----------+----------+
+|     N    |  Doubled |   odd?   |
++----------+----------+----------+
+|        1 |        2 |   true   |
+|        2 |        4 |   false  |
+|        5 |       10 |   true   |
+```
+
+### Cell alignment
+
+By default, column header text is center-aligned, while the content of each body cell is aligned
+according to its data type. Numbers are right-aligned, text is left-aligned, and booleans (`false`
+and `true`) are center-aligned. This can be customized by passing `:center`, `:left` or `:right` to
+the `align_header` or `align_body` options of `add_column`, e.g.:
+
+```ruby
+  table.add_column("Doubled", align_header: :left, align_body: :left) { |n| n * 2 }
+```
+
+### Column width, wrapping and truncation
+
+By default, column width is fixed at 8 characters, plus 1 character of padding on either side.
+This can be customized using the `width` option of `add_column`:
+
+```ruby
+  table.add_column(:even?, width: 5)
+```
+
+### Overflow handling
+
+By default, if cell contents exceed their column width, they are wrapped for as many rows as
+required:
+
+```ruby
+table = Tabulo::Table.new(["hello", "abcdefghijklmnopqrstuvwxyz"], columns: %i(itself length))
+```
+
+```
+> puts table
++----------+----------+
+|  itself  |  length  |
++----------+----------+
+| hello    |        5 |
+| abcdefgh |       26 |
+| ijklmnop |          |
+| qrstuvwx |          |
+| yz       |          |
+```
+
+Wrapping behaviour is configured for the table as a whole using the `wrap_header_cells_to` option
+for header cells and `wrap_body_cells_to` for body cells, both of which default to `nil`, meaning
+that cells are wrapped to as many rows as required. Passing a `Fixnum` limits wrapping to the given
+number of rows, with content truncated from that point on. The `~` character is appended to the
+outputted cell content to show that truncation has occurred:
+
+```ruby
+table = Tabulo::Table.new(["hello", "abcdefghijklmnopqrstuvwxyz"], wrap_body_cells_to: 1, columns: %i(itself length))
+```
+
+```
+> puts table
++----------+----------+
+|  itself  |  length  |
++----------+----------+
+| hello    |        5 |
+| abcdefgh~|       26 |
+```
 
-# > puts table
-# +----------+----------+
-# |     N    |  Doubled |
-# +----------+----------+
-# |        1 |        2 |
-# |        2 |        4 |
-# |        5 |       10 |
+### Repeating headers
+
+By default, headers are only shown once, at the top of the table (`header_frequency: :start`). If
+`header_frequency` is passed `nil`, headers are not shown at all; or, if passed a `Fixnum` N,
+headers are shown at the top and then repeated every N rows. This can be handy when you're looking
+at table that's taller than your terminal.
+
+E.g.:
+
+```ruby
+table = Tabulo::Table.new(1..10, columns: %i(itself even?), header_frequency: 5)
 ```
 
-TODO: Finish this...
+```
+> puts table
++----------+----------+
+|  itself  |   even?  |
++----------+----------+
+|        1 |   false  |
+|        2 |   true   |
+|        3 |   false  |
+|        4 |   true   |
+|        5 |   false  |
++----------+----------+
+|  itself  |   even?  |
++----------+----------+
+|        6 |   true   |
+|        7 |   false  |
+|        8 |   true   |
+|        9 |   false  |
+|       10 |   true   |
+```
+
+TODO: Write rdocs, and link to them here "for more".
+
+### Using a Table Enumerator
+
+Because it's an `Enumerable`, a `Tabulo::Table` can also give you an `Enumerator`,
+which is useful when you want to step through rows one at a time. In a Rails console,
+for example, you might do this:
+
+```
+> e = Tabulo::Table.new(User.find_each) do |t|
+  t.add_column(:id)
+  t.add_column(:email, width: 25)
+end.to_enum  # <-- make an Enumerator
+...
+> puts e.next
++----------+--------------------------+
+|    id    |          email           |
++----------+--------------------------+
+|        1 | jane@example.com         |
+=> nil
+> puts e.next
+|        2 | betty@example.net        |
+=> nil
+```
 
+Note the used of `.find_each`: we can start printing the table without having to load the entire
+underlying collection. (The cost of supporting this behaviour is that Tabulo requires us to set
+column widths up front, rather than adapting to the width of the widest value.)
 
 ## Development
 

data/lib/tabulo.rb

@@ -3,6 +3,7 @@ require "tabulo/table"
 require "tabulo/row"
 require "tabulo/column"
 
+# TODO Document the methods.
 # TODO Tidy the code.
 # TODO Handle newline in output.
 # TODO Allow the option of a horizontal rule between rows.

data/lib/tabulo/column.rb

@@ -2,15 +2,20 @@ module Tabulo
 
   class Column
 
-    attr_reader :label, :truncate, :width
+    attr_reader :label, :width
 
     def initialize(options)
       @label, @header = options[:label], options[:header]
-      @truncate = options[:truncate]
-      @align_header, @align_body = options[:align_header], options[:align_body]
-      @extractor, @formatter = options[:extractor], options[:formatter]
-      @width = options[:width]
-      @horizontal_rule_character = options[:horizontal_rule_character]
+      @align_header = options[:align_header] || :center
+      @align_body = options[:align_body]  || nil
+      @extractor = options[:extractor] || @label.to_proc
+      @formatter = options[:formatter] || :to_s.to_proc
+
+      # TODO Should be able to set these default on a Table-by-Table basis.
+      @width = options[:width] || Table::DEFAULT_COLUMN_WIDTH
+
+      @horizontal_rule_character =
+        options[:horizontal_rule_character] || Table::DEFAULT_HORIZONTAL_RULE_CHARACTER
     end
 
     def header_cell

data/lib/tabulo/table.rb

@@ -3,29 +3,47 @@ module Tabulo
   class Table
     include Enumerable
 
+    DEFAULT_COLUMN_WIDTH = 8
+    DEFAULT_HORIZONTAL_RULE_CHARACTER = "-"
+
     attr_reader :columns
 
     def initialize(sources, options = { })
       opts = {
+        columns: [],
         header_frequency: :start,
 
         # nil to wrap to no max, 1 to wrap to 1 row then truncate, etc..
         wrap_header_cells_to: nil,
-        wrap_cells_to: nil
+        wrap_body_cells_to: nil
 
       }.merge(options)
 
       @header_frequency = opts[:header_frequency]
       @wrap_header_cells_to = opts[:wrap_header_cells_to]
-      @wrap_cells_to = opts[:wrap_cells_to]
+      @wrap_body_cells_to = opts[:wrap_body_cells_to]
       @sources = sources
       @joiner = "|"
       @corner_character = "+"
       @horizontal_rule_character = "-"
       @truncation_indicator = "~"
       @padding_character = " "
-      @columns = []
-      @default_column_width = 8
+      @default_column_width = DEFAULT_COLUMN_WIDTH
+      @columns = opts[:columns].map do |item|
+        case item
+        when Column
+          item
+        else
+          Column.new({
+            label: item.to_sym,
+            header: item.to_s,
+            align_header: :center,
+            horizontal_rule_character: @horizontal_rule_character,
+            width: @default_column_width,
+            formatter: :to_s.to_proc
+          })
+        end
+      end
       yield self if block_given?
     end
 
@@ -35,7 +53,6 @@ module Tabulo
         header: label.to_s,
         truncate: true,
         align_header: :center,
-        align_body: nil,
         horizontal_rule_character: @horizontal_rule_character,
         width: @default_column_width,
         extractor: extractor || (label.respond_to?(:to_proc) ? label.to_proc : proc { nil }),
@@ -89,10 +106,9 @@ module Tabulo
     def format_row(header = false, padder = @padding_character, joiner = @joiner)
       cell_stacks = @columns.map do |column|
         raw = yield column
-        wrap = (header ? @wrap_header_cells_to : @wrap_cells_to)
-        truncate = (column.truncate && wrap)
+        wrap = (header ? @wrap_header_cells_to : @wrap_body_cells_to)
         column_width = column.width
-        cell_body_length = (truncate ? column_width * wrap : raw.length)
+        cell_body_length = (wrap ? column_width * wrap : raw.length)
         truncated = (cell_body_length < raw.length)
         cell_body = raw[0...cell_body_length]
         num_subcells = (cell_body_length.to_f / column_width).ceil

data/lib/tabulo/version.rb

@@ -1,3 +1,3 @@
 module Tabulo
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tabulo
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Matthew Harvey
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-04-21 00:00:00.000000000 Z
+date: 2017-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -62,6 +62,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md