tabulo 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8e5af752ebead6db9dfc76f720fe93390e1476d8
-  data.tar.gz: 3aaeac2dcb657193be54534bac8babbad1cb56d7
+  metadata.gz: 452523797b11a532c291705852d73cc00c7aa93b
+  data.tar.gz: 889621678407822d354bbc5aab7a086aaefdf1b4
 SHA512:
-  metadata.gz: 1227ced88276ad18ac557b66c2bf9db675dba4b9061797c7ddf9432b14c7882eb025b6b126bfa833dd15f92bd6421e42481bed5b858f369ac8c48e811a2da544
-  data.tar.gz: 9f68e39a20c006414d65d0239188df0ae66eb912e9e99de51ea310636d15cf2a9b0038819bbcae39f9b26982ae5f69ddcf1e410efc13cdd2c1d91cb487fbd858
+  metadata.gz: b5311c3013bdba6ff2e7c6a8f0a31d0373d5167c9f34aa45caf2ca1cc5d49c8fbb5c058f166daa6b0d5da41d9d516ee87fd256893d7ce6496277bac9746f0e71
+  data.tar.gz: 8b515f7eca75f4ba532b482d81699b711387e822668f71b9dce86a52f7e71ff27dcdc7bda955525e4d1974346272c49d28422b5c5eb85f4a981962feaedd1961

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v0.5.0
+
+* Add Table#shrinkwrap! method to automate column widths so they "just fit".
+* Improve documentation.
+* Minor tidy-ups.
+
 ## v0.4.2
 
 * Improve README.

data/README.md

@@ -26,21 +26,25 @@ end
 |      5000000 |     10000000 |
 ```
 
-A `Tabulo::Table` is an `Enumerable`, so you can process one row at a time:
-
-```ruby
-table.each do |row|
-  puts row
-  # do some other thing that you want to do for each row
-end
-```
-
-Each `Tabulo::Row` is also an `Enumerable`, which provides access to the underlying cell values:
+Tabulo is flexible:
+
+* Fix individual column widths, then either [wrap](#width-wrapping-truncation) or
+  [truncate](#width-wrapping-truncation) the overflow as you prefer.
+* Alternatively, [shrinkwrap](#shrinkwrap) the table so that each column is just wide enough for
+  its contents.
+* You can cap total table width when shrinkwrapping, to [stop it overflowing your terminal](#max-table-width)
+  horizontally and becoming an unreadable mess.
+* Cell content [alignment](#cell-alignment) is configurable, but with useful defaults, with numbers
+  aligned right and strings left.
+* Headers can be [repeated](#repeating-headers) as desired.
+* A `Tabulo::Table` is an `Enumerable`, so you can [step through it](#enumerator) one row at a time,
+  without having to wait for the entire underlying collection to load.
+* Each `Tabulo::Row` is also an `Enumerable`.
 
 ```ruby
 table.each do |row|
   row.each do |cell|
-    # cell => 1, 2... 2, 4... etc.
+    # cell => 1, 2 ... 2, 4 ... etc.
   end
 end
 ```
@@ -123,6 +127,7 @@ end
 |            5 |           10 |     true     |
 ```
 
+<a name="cell-alignment"></a>
 ### Cell alignment
 
 By default, column header text is center-aligned, while the content of each body cell is aligned
@@ -131,19 +136,20 @@ and `true`) are center-aligned. This can be customized by passing `:center`, `:l
 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 }
+table.add_column("Doubled", align_header: :left, align_body: :left) { |n| n * 2 }
 ```
 
+<a name="width-wrapping-truncation"></a>
 ### Column width, wrapping and truncation
 
 By default, column width is fixed at 12 characters, plus 1 character of padding on either side.
 This can be adjusted on a column-by-column basis using the `width` option of `add_column`:
 
 ```ruby
-  table = Tabulo::Table.new([1, 2]) do |t|
-    t.add_column(:itself, width: 6)
-    t.add_column(:even?, width: 9)
-  end
+table = Tabulo::Table.new([1, 2]) do |t|
+  t.add_column(:itself, width: 6)
+  t.add_column(:even?, width: 9)
+end
 ```
 
 ```
@@ -159,7 +165,7 @@ If you want to set the default column width for all columns of the table to some
 than 12, use the `column_width` option when initializing the table:
 
 ```ruby
-  table = Tabulo::Table.new([1, 2], columns: %i(itself even?), column_width: 6)
+table = Tabulo::Table.new([1, 2], columns: %i(itself even?), column_width: 6)
 ```
 
 ```
@@ -173,6 +179,60 @@ than 12, use the `column_width` option when initializing the table:
 
 Widths set for individual columns always override the default column width for the table.
 
+<a name="shrinkwrap"></a>
+### Automating column widths
+
+Instead of setting column widths "manually", you can tell the table to sort out the widths
+itself, so that each column is just wide enough for its header and contents (plus a character
+of padding):
+
+```ruby
+table = Tabulo::Table.new([1, 2], columns: %i(itself even?))
+table.shrinkwrap!
+```
+
+```
+> puts table
++--------+-------+
+| itself | even? |
++--------+-------+
+|      1 | false |
+|      2 |  true |
+```
+
+The `shrinkwrap!` method returns the table itself, so you can "wrap-and-print" in one go:
+
+```ruby
+puts Tabulo::Table.new([1, 2], columns: %i(itself even?)).shrinkwrap!
+```
+
+<a name="max-table-width"></a>
+You can place an upper limit on the total width of the table when shrinkwrapping:
+
+```ruby
+puts Tabulo::Table.new([1, 2], columns: %i(itself even?)).shrinkwrap!(max_table_width: 17)
+```
+
+```
++-------+-------+
+| itsel | even? |
+| f     |       |
++-------+-------+
+|     1 | false |
+|     2 |  true |
+```
+
+If the table cannot be fit within `max_column_width`, column widths are reduced as required, with
+wrapping or truncation then occuring as necessary (see [Overflow handling](#overflow-handling)).
+Under the hood, a character of width is deducted column by column&mdash;the widest column being
+targetted each time&mdash;until the table will fit. This is very useful when you want to ensure the
+table will not overflow your terminal horizontally.
+
+Note that shrinkwrapping necessarily involves traversing the entire collection up front as
+the maximum cell width needs to be calculated for each column. You may not want to do this
+if the collection is very large.
+
+<a name="overflow-handling"></a>
 ### Overflow handling
 
 By default, if cell contents exceed their column width, they are wrapped for as many rows as
@@ -253,6 +313,7 @@ of the underlying cell value, not the way it is formatted. This is usually the d
 Note also that the item yielded to `.each` for each cell when enumerating over a `Tabulo::Row` is
 the underlying value of that cell, not its formatted value.
 
+<a name="repeating-headers"></a>
 ### Repeating headers
 
 By default, headers are only shown once, at the top of the table (`header_frequency: :start`). If
@@ -286,6 +347,7 @@ table = Tabulo::Table.new(1..10, columns: %i(itself even?), header_frequency: 5)
 |           10 |     true     |
 ```
 
+<a name="enumerator"></a>
 ### Using a Table Enumerator
 
 Because it's an `Enumerable`, a `Tabulo::Table` can also give you an `Enumerator`,

data/lib/tabulo/column.rb

@@ -3,7 +3,8 @@ module Tabulo
   # @!visibility private
   class Column
 
-    attr_reader :label, :width
+    attr_accessor :width
+    attr_reader :header, :label
 
     # @!visibility private
     def initialize(options)
@@ -28,9 +29,14 @@ module Tabulo
     # @!visibility private
     def body_cell(source)
       cell_datum = body_cell_value(source)
-      formatted_cell_content = @formatter.call(cell_datum)
-      real_alignment = @align_body || infer_alignment(cell_datum)
-      align_cell_content(formatted_cell_content, real_alignment)
+      formatted_content = @formatter.call(cell_datum)
+      real_alignment = (@align_body || infer_alignment(cell_datum))
+      align_cell_content(formatted_content, real_alignment)
+    end
+
+    # @!visibility private
+    def formatted_cell_content(source)
+      @formatter.call(body_cell_value(source))
     end
 
     # @!visibility private

data/lib/tabulo/table.rb

@@ -148,6 +148,64 @@ module Tabulo
       format_row(false, HORIZONTAL_RULE_CHARACTER, CORNER_CHARACTER, &:horizontal_rule)
     end
 
+    # Reset all the column widths so that each column is *just* wide enough to accommodate
+    # its header text as well as the formatted content of each its cells for the entire
+    # collection, together with a single character of padding on either side of the column,
+    # without any wrapping.
+    #
+    # Note that calling this method will cause the entire source Enumerable to
+    # be traversed and all the column extractors and formatters to be applied in order
+    # to calculate the required widths.
+    #
+    # @param [Hash] options
+    # @option options [String] :max_table_width (nil) If provided, stops the total table
+    #   width (including padding and borders) from expanding beyond this number of characters.
+    #   Width is deducted from columns if required to achieve this, with one character progressively
+    #   deducted from the width of the widest column until the target is reached. When the
+    #   table is printed, wrapping or truncation will then occur in these columns as required
+    #   (depending on how they were configured).
+    #
+    # @return [Table] the Table itself
+    def shrinkwrap!(options = { })
+      return self if columns.none?
+      max_table_width = options[:max_table_width]
+
+      header_widths = columns.map { |c| c.header.length }
+
+      column_widths = @sources.inject(header_widths) do |widths, source|
+        columns.map { |c| c.formatted_cell_content(source).length }.zip(widths).map(&:max)
+      end
+
+      columns.zip(column_widths).each do |column, width|
+        column.width = width
+      end
+
+      if max_table_width
+        total_columns_width = columns.inject(0) { |sum, column| sum + column.width }
+        total_padding = columns.count * 2
+        total_borders = columns.count + 1
+        unadjusted_table_width = total_columns_width + total_padding + total_borders
+
+        # Ensure max table width is at least wide enough to accommodate table borders and padding
+        # and one character of content.
+        # TODO Document this behaviour.
+        min_table_width = total_padding + total_borders + columns.count
+        max_table_width = min_table_width if min_table_width > max_table_width
+
+        required_reduction = [unadjusted_table_width - max_table_width, 0].max
+
+        required_reduction.times do
+          widest_column = columns.inject(columns.first) do |widest, column|
+            column.width >= widest.width ? column : widest
+          end
+
+          widest_column.width -= 1
+        end
+      end
+
+      self
+    end
+
     # @!visibility private
     def formatted_body_row(source, options = { with_header: false })
       inner = format_row { |column| column.body_cell(source) }

data/lib/tabulo/version.rb

@@ -1,3 +1,3 @@
 module Tabulo
-  VERSION = "0.4.2"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tabulo
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Matthew Harvey