tabulo 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2db6b288685b76e7cab29fc52f1f0d265cb77310392449681bd15950231fb3d7
-  data.tar.gz: 8a9477cc4c7f04a0219bac645c774bd5569f1cd2baff5bfb17ffba57e22b497b
+  metadata.gz: 6ca950eccef1e0d5bcd333ce42584fd4a95020316e80d2f684b721f0cb6ec00a
+  data.tar.gz: ea4c7f96ebce149b131db590fdeb75a54152576717007024556047a36004469f
 SHA512:
-  metadata.gz: 292313dfb4ec2e67e0f0f879c61f9b3797b407d9c8bf1a1e049126b509cedeca557b4cb0d0e4498658438ced29a0faf0aab868ee821cda92a9cea6959a81e75c
-  data.tar.gz: 8714b8dae9a6373d0953a496816e14264af2c78e680b8854866e513776f6aa81827d9beb4c29c190455b3911326495a4cfbe5b712175c54b5087e7927531737b
+  metadata.gz: 2f83f8889ad5f72954bc0a16a743c6ecdb00b732fdac29d179a43874eba68b021f180be981bbce82773bf4f8f0e968a92c03400cf9af74cf8a6bb23ed585cf77
+  data.tar.gz: f9a47229fe11cfc79ea265f4280ca84666e7e09c7d325db4e4b4feb9c2a854f76a9c1647fdcbd2eff3a5073fd327044be75758af839f227750ab1fd24aa2eccc

data/.travis.yml

@@ -4,6 +4,6 @@ rvm:
   - 2.1.10
   - 2.2.10
   - 2.3.8
-  - 2.4.5
+  - 2.4.6
   - 2.5.5
   - 2.6.2

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+### v1.3.0
+
+* More ergonomic Table initializer, allowing you to specify columns directly as varargs rather
+  than as an array passed to `columns:` option (the latter is now deprecated)
+* New `#pack` method to autosize table, capping total table width at width of terminal
+  by default (replaces `#shrinkwrap!` method, now deprecated)
+* Ability to set table-level defaults for column header and body cell alignments
+* Accessor methods for `source` attribute, representing the underlying collection
+  being tabulated, facilitating reuse of the same table to tabulate different collections
+* Documentation improvements
+
 ### v1.2.2
 
 * Improve documentation.

data/README.md

@@ -10,8 +10,21 @@
 
 Tabulo is a Ruby library for generating ASCII tables.
 
+*Quick API:*
+
+```
+> puts Tabulo::Table.new(User.all, :id, :first_name, :last_name)
++--------------+--------------+--------------+
+|      id      |  first_name  |   last_name  |
++--------------+--------------+--------------+
+|            1 | John         | Citizen      |
+|            2 | Jane         | Doe          |
+```
+
+*Full API:*
+
 ```ruby
-underyling_enumerable = [1, 2, 50000000] # need not be an array
+underyling_enumerable = [1, 2, 50000000]
 
 table = Tabulo::Table.new(underlying_enumerable) do |t|
   t.add_column("N") { |n| n }
@@ -31,13 +44,10 @@ end
 
 ## Features
 
-* A [DRY interface](#configuring-columns): by being "column based", it is designed to spare the
-  developer the burden of syncing the ordering within the header row with that of the body rows.
 * Lets you set [fixed column widths](#fixed-column-widths), then either [wrap](#overflow-handling) or
   [truncate](#overflow-handling) the overflow.
-* Alternatively, [shrinkwrap](#shrinkwrap) the table so that each column is just wide enough for its contents.
-* Put an upper limit on total table width when shrinkwrapping, to
-  [stop it overflowing your terminal horizontally](#max-table-width).
+* Alternatively, ["pack"](#pack) the table so that each column is automatically just wide enough for its
+  contents, but [without overflowing the terminal horizontally](#max-table-width).
 * Alignment of cell content is [configurable](#cell-alignment), but has helpful content-based defaults
   (numbers right, strings left).
 * Headers are [repeatable](#repeating-headers).
@@ -47,6 +57,8 @@ end
 * Each `Tabulo::Row` is also an `Enumerable`, [providing access](#accessing-cell-values) to the underlying cell values.
 * Tabulate any `Enumerable`: the underlying collection need not be an array.
 * [Customize](#additional-configuration-options) border and divider characters.
+* Use a [DRY interface](#configuring-columns): by being "column based", it is designed to spare the
+  developer the burden of syncing the ordering within the header row with that of the body rows.
 
 Tabulo has also been ported to Crystal (with some modifications): see [Tablo](https://github.com/hutou/tablo).
 
@@ -54,7 +66,7 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
 
   * [Overview](#overview)
   * [Features](#features)
-  * [Table of Contents](#table-of-contents)
+  * [Table of contents](#table-of-contents)
   * [Installation](#installation)
   * [Detailed usage](#detailed-usage)
      * [Requiring the gem](#requiring-the-gem)
@@ -69,8 +81,9 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
      * [Repeating headers](#repeating-headers)
      * [Using a Table Enumerator](#using-a-table-enumerator)
      * [Accessing cell values](#accessing-cell-values)
+     * [Accessing the underlying enumerable](#accessing-sources)
      * [Additional configuration options](#additional-configuration-options)
-  * [Development](#development)
+  * [Motivation](#motivation)
   * [Contributing](#contributing)
   * [License](#license)
 
@@ -114,10 +127,10 @@ table = Tabulo::Table.new([1, 2, 5]) do |t|
 end
 ```
 
-Or equivalently:
+Or equivalently, using the "quick API":
 
 ```ruby
-table = Tabulo::Table.new([1, 2, 5], columns: %i[itself even? odd?])
+table = Tabulo::Table.new([1, 2, 5], :itself, :even?, :odd?)
 ```
 
 ```
@@ -157,11 +170,20 @@ end
 
 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.:
+and `true`) are center-aligned.
+
+This default behaviour can be set at the table level, by passing `:center`, `:left` or `:right`
+to the `align_header` or `align_body` options when initializing the table:
+
+```ruby
+table = Tabulo::Table.new([1, 2], :itself, :even?, align_header: :left, align_body: :right)
+```
+
+The table-level alignment settings can be overridden for individual columns by
+passing using similarly-named options passed to `add_column`, e.g.:
 
 ```ruby
-table.add_column("Doubled", align_header: :left, align_body: :left) { |n| n * 2 }
+table.add_column("Doubled", align_header: :right, align_body: :left) { |n| n * 2 }
 ```
 
 ### Column width, wrapping and truncation
@@ -192,7 +214,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], :itself, :even?, column_width: 6)
 ```
 
 ```
@@ -213,7 +235,7 @@ The single character of padding either side of each column is not counted in the
 The amount of this padding can be configured for the table as a whole, using the `column_padding`
 option passed to `Table.new`.
 
-<a name="shrinkwrap"></a>
+<a name="pack"></a>
 #### Automating column widths
 
 Instead of setting column widths "manually", you can tell the table to sort out the widths
@@ -221,8 +243,8 @@ itself, so that each column is just wide enough for its header and contents (plu
 of padding):
 
 ```ruby
-table = Tabulo::Table.new([1, 2], columns: %i[itself even?])
-table.shrinkwrap!
+table = Tabulo::Table.new([1, 2], :itself, :even?)
+table.pack
 ```
 
 ```
@@ -234,17 +256,17 @@ table.shrinkwrap!
 |      2 |  true |
 ```
 
-The `shrinkwrap!` method returns the table itself, so you can "wrap-and-print" in one go:
+The `pack` method returns the table itself, so you can "pack-and-print" in one go:
 
 ```ruby
-puts Tabulo::Table.new([1, 2], columns: %i[itself even?]).shrinkwrap!
+puts Tabulo::Table.new([1, 2], :itself, :even?).pack
 ```
 
 <a name="max-table-width"></a>
-You can place an upper limit on the total width of the table when shrinkwrapping:
+You can manually place an upper limit on the total width of the table when packing:
 
 ```ruby
-puts Tabulo::Table.new([1, 2], columns: %i[itself even?]).shrinkwrap!(max_table_width: 17)
+puts Tabulo::Table.new([1, 2], :itself, :even?).pack(max_table_width: 17)
 ```
 
 ```
@@ -256,17 +278,23 @@ puts Tabulo::Table.new([1, 2], columns: %i[itself even?]).shrinkwrap!(max_table_
 |     2 |  true |
 ```
 
-If the table cannot be fit within `max_table_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.
+Or if you simply call `pack` with no parameters (or if you explicitly call
+`pack(max_table_width: :auto)`), the table width will automatically be capped at the
+width of your terminal.
 
-Note that shrinkwrapping necessarily involves traversing the entire collection up front as
+If you want the table width not to be capped at all, call `pack(max_table_width: nil)`.
+
+If the table cannot be fit within the width of the terminal, or the specified maximum width,
+then 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.
+
+Note that `pack`ing the table 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. Note also the effect of `shrinkwrap!` is to fix the column widths
+if the collection is very large. Note also the effect of `pack` is to fix the column widths
 as appropriate to the formatted cell contents given the state of the underlying collection
-_at the point of shrinkwrapping_. If the underlying collection changes between that point, and when
+_at the point of packing_. If the underlying collection changes between that point, and when
 the table is printed, then the columns will _not_ be resized yet again on printing. This is a
 consequence of the table always being essentially a "live view" on the underlying collection:
 formatted contents are never cached within the table itself.
@@ -280,7 +308,7 @@ required:
 ```ruby
 table = Tabulo::Table.new(
   ["hello", "abcdefghijklmnopqrstuvwxyz"],
-  columns: %i[itself length]
+  :itself, :length
 )
 ```
 
@@ -304,8 +332,8 @@ 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]
+  :itself, :length,
+  wrap_body_cells_to: 1
 )
 ```
 
@@ -363,7 +391,7 @@ at table that's taller than your terminal.
 E.g.:
 
 ```ruby
-table = Tabulo::Table.new(1..10, columns: %i[itself even?], header_frequency: 5)
+table = Tabulo::Table.new(1..10, :itself, :even?, header_frequency: 5)
 ```
 
 ```
@@ -411,7 +439,7 @@ end.to_enum  # <-- make an Enumerator
 ```
 
 Note the use of `.find_each`: we can start printing the table without having to load the entire
-underlying collection. (This is negated if we [shrinkwrap](#shrinkwrap) the table, however, since
+underlying collection. (This is negated if we [pack](#pack) the table, however, since
 in that case the entire collection must be traversed up front in order for column widths to be
 calculated.)
 
@@ -422,7 +450,7 @@ is itself an `Enumerable` comprising the underlying the values of each cell. A `
 also be converted to a `Hash` for keyed access. For example:
 
 ```ruby
-table = Tabulo::Table.new(1..5, columns: %i[itself even? odd?])
+table = Tabulo::Table.new(1..5, :itself, :even?, :odd?)
 
 table.each do |row|
   row.each { |cell| puts cell } # 1...2...3...4...5
@@ -449,6 +477,43 @@ table.each do |row|
 end
 ```
 
+<a name="accessing-sources"></a>
+### Accessing the underlying enumerable
+
+The underlying enumerable for a table can be retrieved by calling the `sources` getter:
+
+```ruby
+table = Tabulo::Table.new([1, 2, 5], :itself, :even?, :odd?)
+```
+
+```
+> table.sources
+=> [1, 2, 5]
+```
+
+There is also a corresponding setter, meaning you can reuse the same table to tabulate
+a different data set, without having to reconfigure the columns and other options from scratch:
+
+```ruby
+table.sources = [50, 60]
+```
+
+```
+> table.sources
+=> [50, 60]
+```
+
+In addition, the element of the underlying enumerable corresponding to a particular
+row can be accessed by calling the `source` method on that row:
+
+```ruby
+table.each do |row|
+  puts row.source # 50...60...
+end
+
+```
+
+<a name="additional-configuration-options"></a>
 ### Additional configuration options
 
 The characters used for horizontal dividers, vertical dividers and corners, which default to `-`,
@@ -470,7 +535,7 @@ This will output a bottom border that's appropriately sized for the table.
 This mechanism can also be used to output a horizontal divider after each row:
 
 ```ruby
-table = Tabulo::Table.new(1..3, columns: %i[itself even?])
+table = Tabulo::Table.new(1..3, :itself, :even?)
 ```
 
 ```
@@ -486,6 +551,90 @@ table = Tabulo::Table.new(1..3, columns: %i[itself even?])
 +--------------+--------------+
 ```
 
+<a name="motivation"></a>
+## Motivation
+
+There are other terminal table generators for Ruby. Popular among these are:
+
+* [tty-table](https://github.com/piotrmurach/tty-table)
+* [terminal-table](https://github.com/tj/terminal-table)
+* [table\_print](https://github.com/arches/table_print)
+
+*DISCLAIMER: My comments regarding these other libraries are based only on my own,
+possibly-flawed, reading of the documentation for, and experimentation with, these libraries at the
+time of my writing this. Their APIs, features or documentation may well change between when I write this, and
+when you read it&mdash;possibly in ways that address the issues I describe here!*
+
+These are excellent libraries, and each has its strengths. However, I personally found that for the
+common use case of printing a table on the basis of some underlying collection (such as an
+ActiveRecord query result), using these libraries in practice was more cumbersome than it needed to
+be.
+
+For example, suppose we have called `User.all` from the Rails console, and want to print
+a table showing the email, first name, last name and ID of each user,
+with column headings. Also, we want the ID column to be right-aligned, because it's a number.
+
+In `terminal-table`, we could achieve this as follows:
+
+```ruby
+rows = User.all.map { |u| [u.email, u.first_name, u.last_name, u.id] }
+headings = ["email", "first name", "last name", "id"]
+table = Terminal::Table.new(headings: headings, rows: rows)
+table.align_column(3, :right)
+puts table
+```
+
+The problem here is that there is no single source of knowledge about which columns
+appear, and in which order. If we want to add another column to the left of "email",
+we need to amend the rows map, and the headings map, and the index passed to `align_column`.
+We bear the burden of keeping these three in sync. This is not be a big deal for small one-off
+tables, but for tables that have many columns, or that are constructed
+dynamically based on user input or other runtime factors determining the columns
+to be included, this can be a hassle and a source of brittleness.
+
+`tty-table` has a somewhat different API to `terminal-table`. It offers both a
+"row-based" and a "column-based" method of initializing a table. We won't cover
+the row-based method here, but it is similar to `terminal-table`'s in that it
+burdens the developer with syncing the column ordering across multiple code
+locations. The "column-based" API for `tty-table`, on the other hand, looks like this:
+
+```ruby
+users = User.all
+table = TTY::Table.new [
+  {
+    "email" => users.map(&:email),
+    "first name" => users.map(&:first_name),
+    "last name" => users.map(&:last_name),
+    "id" => users.map(&:id),
+  }
+]
+puts table
+```
+
+While this doesn't seem too bad, it does mean that the underlying collection (`users`) has to
+be traversed multiple times, once for each column, which is inefficient, particularly
+if the underlying collection is large. In addition, it's not clear how to pass separate
+formatting information for each column when initializing in this way. (Perhaps there is a way to do
+this, but if there is, it doesn't seem to be documented.) So it seems we still have to use
+`table.align_column(3, :right)`, which again burdens us with keeping the column index
+passed to `align_column` in sync.
+
+Finally, there is [table\_print](https://github.com/arches/table_print). This is a
+handy gem for quickly tabulating ActiveRecord collections from the Rails
+console. `table_print` is similar to `tabulo` in that it has a column-based API, so it doesn't
+suffer from the multiple-source-of-knowledge issue in regards to column orderings. However, as far
+as I can tell, it lacks certain other useful features, such as the ability to repeat headers every N
+rows, the automatic alignment of columns based on cell content (numbers right, strings left), and a
+quick and easy way to automatically resize columns to accommodate cell content without overflowing
+the terminal. Also, as of the time of writing, `table_print`'s last significant commit (ignoring a
+deprecation warning fix in April 2018) was in March 2016.
+
+I don't mean to disparage any of these other projects&mdash;they each have their strengths&mdash;but
+rather to explain my motivation for developing and maintaining Tabulo despite their existence, and
+to provide reasons one might consider for using `tabulo` rather than another terminal table
+gem.
+
+<a name="contributing"></a>
 ## Contributing
 
 Issues and pull requests are welcome on GitHub at https://github.com/matt-harvey/tabulo.
@@ -503,13 +652,13 @@ The gem is available as open source under the terms of the [MIT
 License](http://opensource.org/licenses/MIT).
 
 [Gem Version]: https://rubygems.org/gems/tabulo
-[Documentation]: http://www.rubydoc.info/gems/tabulo/1.2.2
+[Documentation]: http://www.rubydoc.info/gems/tabulo/1.3.0
 [Build Status]: https://travis-ci.org/matt-harvey/tabulo
 [Coverage Status]: https://coveralls.io/r/matt-harvey/tabulo
 [Code Climate]: https://codeclimate.com/github/matt-harvey/tabulo
 
 [GV img]: https://img.shields.io/gem/v/tabulo.svg
-[DC img]: https://img.shields.io/badge/documentation-v1.2.2-blue.svg
+[DC img]: https://img.shields.io/badge/documentation-v1.3.0-blue.svg
 [BS img]: https://img.shields.io/travis/matt-harvey/tabulo.svg
 [CS img]: https://img.shields.io/coveralls/matt-harvey/tabulo.svg
 [CC img]: https://codeclimate.com/github/matt-harvey/tabulo/badges/gpa.svg

data/VERSION

@@ -1 +1 @@
-1.2.2
+1.3.0

data/lib/tabulo.rb

@@ -1,5 +1,6 @@
-require "tabulo/version"
+require "tabulo/deprecation"
 require "tabulo/exceptions"
 require "tabulo/table"
+require "tabulo/version"
 require "tabulo/row"
 require "tabulo/column"

data/lib/tabulo/column.rb

@@ -22,7 +22,7 @@ module Tabulo
     def body_subcells(source)
       cell_datum = body_cell_value(source)
       formatted_content = @formatter.call(cell_datum)
-      real_alignment = (@align_body || infer_alignment(cell_datum))
+      real_alignment = (@align_body == :auto ? infer_alignment(cell_datum) : @align_body)
       infilled_subcells(formatted_content, real_alignment)
     end
 

data/lib/tabulo/deprecation.rb

@@ -0,0 +1,32 @@
+module Tabulo
+
+  module Deprecation
+
+    # @!visibility private
+    def self.skipping_warnings
+      @skipping_warnings ||= false
+    end
+
+    # @!visibility private
+    def self.skipping_warnings=(v)
+      @skipping_warnings = v
+    end
+
+    # @!visibility private
+    def self.without_warnings
+      original = skipping_warnings
+      self.skipping_warnings = true
+      yield
+    ensure
+      self.skipping_warnings = original
+    end
+
+    # @!visibility private
+    def self.warn(deprecated, replacement, stack_level = 1)
+      return if skipping_warnings
+
+      kaller = Kernel.caller[stack_level]
+      Kernel.warn "#{kaller}: [DEPRECATION] #{deprecated} is deprecated. Please use #{replacement} instead."
+    end
+  end
+end

data/lib/tabulo/row.rb

@@ -3,6 +3,9 @@ module Tabulo
   class Row
     include Enumerable
 
+    # @return the element of the {Table}'s underlying enumerable to which this {Row} corresponds
+    attr_reader :source
+
     # @!visibility private
     def initialize(table, source, with_header: true)
       @table = table

data/lib/tabulo/table.rb

@@ -1,3 +1,5 @@
+require "tty-screen"
+
 module Tabulo
 
   # Represents a table primarily intended for "pretty-printing" in a fixed-width font.
@@ -30,11 +32,15 @@ module Tabulo
     # @!visibility private
     attr_reader :column_registry
 
+    # @return [Enumerable] the underlying enumerable from which the table derives its data
+    attr_accessor :sources
+
     # @param [Enumerable] sources the underlying Enumerable from which the table will derive its data
-    # @param [Array[Symbol]] columns Specifies the initial columns. The Symbols provided must
+    # @param [Array[Symbol]] cols Specifies the initial columns. The Symbols provided must
     #   be unique. Each element of the Array  will be used to create a column whose content is
     #   created by calling the corresponding method on each element of sources. Note
     #   the {#add_column} method is a much more flexible way to set up columns on the table.
+    # @param [Array[Symbol]] columns <b>DEPRECATED</b> Use {cols} instead.
     # @param [Integer, nil] column_width The default column width for columns in this
     #   table, not excluding padding. If <tt>nil</tt>, then {DEFAULT_COLUMN_WIDTH} will be used.
     # @param [:start, nil, Integer] header_frequency Controls the display of column headers.
@@ -70,13 +76,27 @@ module Tabulo
     #   a single-character String, raises {InvalidTruncationIndicatorError}.
     # @param [nil, Integer] column_padding Determines the amount of blank space with which to pad either
     #   of each column. Defaults to 1.
-    # @return [Table] a new Table
+    # @param [:left, :right, :center] align_header (:center) Determines the alignment of header text
+    #   for columns in this Table. Can be overridden for individual columns using the
+    #   <tt>align_header</tt> option passed to {#add_column}
+    # @param [:left, :right, :center, :auto] align_body (:auto) Determines the alignment of body cell
+    #   (i.e. non-header) content within columns in this Table. Can be overridden for individual columns
+    #   using the <tt>align_body</tt> option passed to {#add_column}. If passed <tt>:auto</tt>,
+    #   alignment is determined by cell content, with numbers aligned right, booleans
+    #   center-aligned, and other values left-aligned.
+    # @return [Table] a new {Table}
     # @raise [InvalidColumnLabelError] if non-unique Symbols are provided to columns.
     # @raise [InvalidHorizontalRuleCharacterError] if invalid argument passed to horizontal_rule_character.
     # @raise [InvalidVerticalRuleCharacterError] if invalid argument passed to vertical_rule_character.
-    def initialize(sources, columns: [], column_width: nil, column_padding: nil, header_frequency: :start,
+    def initialize(sources, *cols, columns: [], column_width: nil, column_padding: nil, header_frequency: :start,
       wrap_header_cells_to: nil, wrap_body_cells_to: nil, horizontal_rule_character: nil,
-      vertical_rule_character: nil, intersection_character: nil, truncation_indicator: nil)
+      vertical_rule_character: nil, intersection_character: nil, truncation_indicator: nil,
+      align_header: :center, align_body: :auto)
+
+      if columns.any?
+        Deprecation.warn("`columns' option to Tabulo::Table#initialize",
+                               "the variable length parameter `cols'", 2)
+      end
 
       @sources = sources
       @header_frequency = header_frequency
@@ -84,6 +104,8 @@ module Tabulo
       @wrap_body_cells_to = wrap_body_cells_to
       @default_column_width = (column_width || DEFAULT_COLUMN_WIDTH)
       @column_padding = (column_padding || DEFAULT_COLUMN_PADDING)
+      @align_header = align_header
+      @align_body = align_body
 
       @horizontal_rule_character = validate_character(horizontal_rule_character,
         DEFAULT_HORIZONTAL_RULE_CHARACTER, InvalidHorizontalRuleCharacterError, "horizontal rule character")
@@ -95,6 +117,7 @@ module Tabulo
         DEFAULT_TRUNCATION_INDICATOR, InvalidTruncationIndicatorError, "truncation indicator")
 
       @column_registry = { }
+      cols.each { |item| add_column(item) }
       columns.each { |item| add_column(item) }
 
       yield self if block_given?
@@ -109,13 +132,18 @@ module Tabulo
     #   for this column.
     # @param [nil, #to_s] header (nil) Text to be displayed in the column header. If passed nil,
     #   the column's label will also be used as its header text.
-    # @param [:left, :center, :right] align_header (:center) Specifies how the header text
-    #   should be aligned.
-    # @param [:left, :center, :right, nil] align_body (nil) Specifies how the cell body contents
-    #   should be aligned. Possible If <tt>nil</tt> is passed, then the alignment is determined
-    #   by the type of the cell value, with numbers aligned right, booleans center-aligned, and
-    #   other values left-aligned. Note header text alignment is configured separately using the
-    #   :align_header param.
+    # @param [:left, :center, :right, nil] align_header (nil) Specifies how the header text
+    #   should be aligned. If <tt>nil</tt> is passed, then the alignment is determined
+    #   by the Table-level setting passed to the <tt>align_header</tt> (which itself defaults
+    #   to <tt>:center</tt>). Otherwise, this option determines the alignment of the header
+    #   content for this column.
+    # @param [:left, :center, :right, :auto, nil] align_body (nil) Specifies how the cell body contents
+    #   should be aligned. If <tt>nil</tt> is passed, then the alignment is determined
+    #   by the Table-level setting passed to the <tt>align_body</tt> option on Table initialization
+    #   (which itself defaults to <tt>:auto</tt>). Otherwise this option determines the alignment of
+    #   this column. If <tt>:auto</tt> is passed, the alignment is determined by the type of the cell
+    #   value, with numbers aligned right, booleans center-aligned, and other values left-aligned.
+    #   Note header text alignment is configured separately using the :align_header param.
     # @param [Integer] width (nil) Specifies the width of the column, excluding padding. If
     #   nil, then the column will take the width provided by the `column_width` param
     #   with which the Table was initialized.
@@ -132,7 +160,7 @@ module Tabulo
     # @raise [InvalidColumnLabelError] if label has already been used for another column in this
     #   Table. (This is case-sensitive, but is insensitive to whether a String or Symbol is passed
     #   to the label parameter.)
-    def add_column(label, header: nil, align_header: :center, align_body: nil,
+    def add_column(label, header: nil, align_header: nil, align_body: nil,
       width: nil, formatter: :to_s.to_proc, &extractor)
 
       column_label = label.to_sym
@@ -144,8 +172,8 @@ module Tabulo
       @column_registry[column_label] =
         Column.new(
           header: (header || label).to_s,
-          align_header: align_header,
-          align_body: align_body,
+          align_header: align_header || @align_header,
+          align_body: align_body || @align_body,
           width: (width || @default_column_width),
           formatter: formatter,
           extractor: (extractor || label.to_proc)
@@ -221,19 +249,21 @@ module Tabulo
     # is called. If the source Enumerable changes between that point, and the point when
     # the Table is printed, then columns will *not* be resized yet again on printing.
     #
-    # @param [nil, Numeric] max_table_width (nil) If provided, stops the total table
-    #   width (including padding and borders) from expanding beyond this number of characters.
+    # @param [nil, Numeric] max_table_width (:auto) With no args, or if passed <tt>:auto</tt>,
+    #   stops the total table width (including padding and borders) from expanding beyond the
+    #   bounds of the terminal screen.
+    #   If passed <tt>nil</tt>, the table width will not be capped.
     #   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). Note that regardless of the value passed to
-    #   max_table_width, the table will always be left wide enough to accommodate at least
-    #   1 character's width of content, 1 character of left padding and 1 character of right padding
-    #   in each column, together with border characters (1 on each side of the table and 1 between
-    #   adjacent columns). I.e. there is a certain width below width the Table will refuse to
-    #   shrink itself.
+    #   (depending on how they were configured).
+    #   Note that regardless of the value passed to max_table_width, the table will always be left wide
+    #   enough to accommodate at least 1 character's width of content, 1 character of left padding and
+    #   1 character of right padding in each column, together with border characters (1 on each side
+    #   of the table and 1 between adjacent columns). I.e. there is a certain width below width the
+    #   Table will refuse to shrink itself.
     # @return [Table] the Table itself
-    def shrinkwrap!(max_table_width: nil)
+    def pack(max_table_width: :auto)
       return self if column_registry.none?
       columns = column_registry.values
 
@@ -247,30 +277,48 @@ module Tabulo
       end
 
       if max_table_width
-        total_columns_width = columns.inject(0) { |sum, column| sum + column.width }
-        total_padding = column_registry.count * @column_padding * 2
-        total_borders = column_registry.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.
-        min_table_width = total_padding + total_borders + column_registry.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
+        max_table_width = TTY::Screen.width if max_table_width == :auto
+        shrink_to(max_table_width)
       end
 
       self
     end
 
+    # @deprecated Use {#pack} instead.
+    #
+    # 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.
+    #
+    # Note also that this method causes column widths to be fixed as appropriate to the
+    # formatted cell contents given the state of the source Enumerable at the point it
+    # is called. If the source Enumerable changes between that point, and the point when
+    # the Table is printed, then columns will *not* be resized yet again on printing.
+    #
+    # @param [nil, Numeric] max_table_width (nil) If provided, stops the total table
+    #   width (including padding and borders) from expanding beyond this number of characters.
+    #   If passed <tt>:auto</tt>, the table width will automatically be capped at the current
+    #   terminal width.
+    #   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).
+    #   Note that regardless of the value passed to max_table_width, the table will always be left wide
+    #   enough to accommodate at least 1 character's width of content, 1 character of left padding and
+    #   1 character of right padding in each column, together with border characters (1 on each side
+    #   of the table and 1 between adjacent columns). I.e. there is a certain width below width the
+    #   Table will refuse to shrink itself.
+    # @return [Table] the Table itself
+    def shrinkwrap!(max_table_width: nil)
+      Deprecation.warn("`Tabulo::Table#shrinkwrap!'", "`#pack'")
+      pack(max_table_width: max_table_width)
+    end
+
     # @!visibility private
     def formatted_body_row(source, with_header: false)
       cells = column_registry.map { |_, column| column.body_subcells(source) }
@@ -284,6 +332,29 @@ module Tabulo
 
     private
 
+    # @!visibility private
+    def shrink_to(max_table_width)
+      columns = column_registry.values
+      total_columns_width = columns.inject(0) { |sum, column| sum + column.width }
+      total_padding = column_registry.count * @column_padding * 2
+      total_borders = column_registry.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.
+      min_table_width = total_padding + total_borders + column_registry.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
+
     # @!visibility private
     def body_row(source, with_header: false)
       Row.new(self, source, with_header: with_header)

data/lib/tabulo/version.rb

@@ -1,3 +1,3 @@
 module Tabulo
-  VERSION = "1.2.2"
+  VERSION = "1.3.0"
 end

data/tabulo.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Matthew Harvey"]
   spec.email         = ["software@matthewharvey.net"]
 
-  spec.summary       = "Enumerable ASCII table"
-  spec.description   = "Enumerable ASCII table"
+  spec.summary       = "Enumerable ASCII terminal table"
+  spec.description   = "Enumerable ASCII terminal table"
   spec.homepage      = "https://github.com/matt-harvey/tabulo"
   spec.license       = "MIT"
 
@@ -28,6 +28,8 @@ Gem::Specification.new do |spec|
     "changelog_uri"   => "https://raw.githubusercontent.com/matt-harvey/tabulo/master/CHANGELOG.md"
   }
 
+  spec.add_runtime_dependency "tty-screen", "0.6.5"
+
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake", "~> 11.0"
   spec.add_development_dependency "rspec", "~> 3.0"

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: tabulo
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Matthew Harvey
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-03-26 00:00:00.000000000 Z
+date: 2019-04-22 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: tty-screen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.6.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.6.5
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -136,7 +150,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
-description: Enumerable ASCII table
+description: Enumerable ASCII terminal table
 email:
 - software@matthewharvey.net
 executables: []
@@ -160,6 +174,7 @@ files:
 - bin/setup
 - lib/tabulo.rb
 - lib/tabulo/column.rb
+- lib/tabulo/deprecation.rb
 - lib/tabulo/exceptions.rb
 - lib/tabulo/row.rb
 - lib/tabulo/table.rb
@@ -190,5 +205,5 @@ rubyforge_project:
 rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: Enumerable ASCII table
+summary: Enumerable ASCII terminal table
 test_files: []