tabulo 2.7.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 632d2d2d3b7d0120410d0afd2b8f1d1b341fd1b6daa7802b15b6f791640d409e
-  data.tar.gz: f5720b528f1c4384118196619ea923b317ec3ff7d374fa87d79808361031e7cc
+  metadata.gz: d58a5b883e9c9685c3cff492c6ad49b88ce921c5947596c5fe9199a5818dbfab
+  data.tar.gz: d9e2d10ea6314b73bdc3ad5a41bf790211ad7abe1e42899c52bc8bf2b405e8e6
 SHA512:
-  metadata.gz: 283e3ac39971cfdf9df9968fe0e40b00d049865fe7f49ef0403d71e35ea8f49a43d85579cb9f12d080e0bacafa48c943d2e57176309be99809272983cd9db2d7
-  data.tar.gz: 32256e95de32d81a65d64e49a6f1eb42c33d7ccca2c76a5d6ce5cb6d0beee8c9d5588aa6d5df2c68a59ac8805e5b5048851a0959ddf281eaf891771ee162158c
+  metadata.gz: 3fb526cb0ddc9d63033eb40aa81a0aa2f39a306e051074693fcc4d08c95a216d13ffa27c92a1eb7bed08d3daef431bff6d15faa839b87580f830b916409c46a7
+  data.tar.gz: 587ba915a07b2e6d67d58296a7147fab9017d038facf0976a628baa71f8ebdf6a08f3d25559ca372630026452d65d12f83ced616c78cd33fca9e7e31ff0ed597

data/.github/workflows/tests.yml

@@ -23,9 +23,10 @@ jobs:
           '2.3.8',
           '2.4.10',
           '2.5.9',
-          '2.6.7',
-          '2.7.3',
-          '3.0.1',
+          '2.6.9',
+          '2.7.5',
+          '3.0.3',
+          '3.1.0',
         ]
     steps:
     - uses: actions/checkout@v2

data/.gitignore

@@ -10,3 +10,4 @@
 **/.*.swp
 coverage
 gh-md-toc
+.ruby-version

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+### v2.8.0
+
+* Add `except:` param to `Tabulo::Table#pack` method, allowing specific
+  columns to be excluded from the action of `.pack`
+* Provide method `Tabulo::Table#autosize_columns`, allowing columns to be auto-sized
+  to fit their contents' widths, without having to call `.pack` (which also has
+  other effects on the table). This method also has an `except:` param allowing columns
+  to be excluded from its action.
+* Provide method `Tabulo::Table#shrink_to`, allowing the table's width to be reduced
+  so as not to exceed a given target number of characters (or the argument `:screen`
+  meaning "width of terminal"), independently of the `.pack` method.
+  This method also has an `except:` param allowing columns to be excluded from its action.
+* Fix `max_table_width:` param to `.pack` not being respected if table title was
+  wider than terminal.
+* Documentation improvements
+* Fix broken documentation links
+* Add Ruby 3.1 to CI config
+
+### v2.7.3
+
+* Fix malformed YARD documentation for `Tabulo::Table#initialize` method
+
+### v2.7.2
+
+* Minor documentation improvements and tweaks
+* Upgrade Ruby patch versions in CI config
+
+### v2.7.1
+
+* Dependency version upgrades
+* Minor documentation improvements and tweaks
+
 ### v2.7.0
 
 * Add `wrap_preserve` option, allowing whole words to be preserved when wrapping.

data/README.md

@@ -4,11 +4,9 @@
 [![Documentation][DC img]][Documentation]
 [![Build Status][BS img]][Build Status]
 [![Coverage Status][CS img]][Coverage Status]
-[![Code Climate][CC img]][Code Climate]
 [![Awesome][AR img]][Awesome Ruby]
 
-Tabulo is a Ruby library for generating plain text tables (also known as “terminal tables”
-or “ASCII tables”). It is both highly configurable and very easy to use.
+Tabulo is a Ruby library for generating plain text tables. It is both highly configurable and very easy to use.
 
 <a name="overview"></a>
 ## Overview
@@ -76,15 +74,16 @@ 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](#contents)
   * [Installation](#installation)
   * [Detailed usage](#detailed-usage)
      * [Creating a table](#table-initialization)
      * [Adding columns](#adding-columns)
         * [Quick API](#quick-api)
-        * [Full API](#quick-api)
+        * [Full API](#full-api)
         * [Column labels _vs_ headers](#labels-headers)
         * [Positioning columns](#column-positioning)
+        * [Extracting column content from a hash or array](#from-arrays-hashes)
      * [Removing columns](#removing-columns)
      * [Adding a title](#title)
      * [Cell alignment](#cell-alignment)
@@ -93,6 +92,7 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
         * [Automating column widths](#automating-column-widths)
         * [Configuring padding](#configuring-padding)
         * [Overflow handling](#overflow-handling)
+        * [Wrapping at word boundaries](#preserve-words)
         * [Manual cell wrapping](#manual-wrapping)
      * [Formatting cell values](#formatting-cell-values)
      * [Colours and other styling](#colours-and-styling)
@@ -102,7 +102,7 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
         * [Setting default styles](#default-styles)
         * [Styling borders](#styling-borders)
      * [Repeating headers](#repeating-headers)
-     * [Using a Table Enumerator](#using-a-table-enumerator)
+     * [Using a Table Enumerator](#enumerator)
      * [Accessing cell values](#accessing-cell-values)
      * [Accessing the underlying enumerable](#accessing-sources)
      * [Transposing rows and columns](#transposition)
@@ -113,6 +113,7 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
   * [Contributing](#contributing)
   * [License](#license)
 
+<a name="installation"></a>
 ## Installation [&#x2191;](#contents)
 
 Add this line to your application&#8217;s Gemfile:
@@ -135,6 +136,7 @@ To use the gem, you need to require it in your source code as follows:
 require 'tabulo'
 ```
 
+<a name="detailed-usage"></a>
 <a name="table-initialization"></a>
 ### Creating a table [&#x2191;](#contents)
 
@@ -281,6 +283,69 @@ table.add_column(:even?, before: :odd?)
 +--------------+--------------+--------------+
 ```
 
+<a name="from-arrays-hashes"></a>
+#### Extracting column content from a hash or array [&#x2191;](#contents)
+
+Sometimes the data source for the table may be a collection of hashes or arrays. For example:
+
+```ruby
+data = [
+  { english: "hello", portuguese: "bom dia" },
+  { english: "goodbye", portuguese: "adeus" },
+]
+```
+
+or
+
+```ruby
+data = [
+  ["hello", "bom dia"],
+  ["goodbye", "adeus"],
+]
+```
+
+To tabulate such a collection, simply use the same mechanism as described above, passing a block to
+the `add_column` method to tell Tabulo how to extract the data for each column from a row. For
+example, to tabulate the first example above, you could do something like this:
+
+```ruby
+table = Tabulo::Table.new(data) do |t|
+  t.add_column("English") { |h| h[:english] }
+  t.add_column("Portuguese") { |h| h[:portuguese] }
+end
+
+puts table
+```
+
+For the second example, you could do the following:
+
+```ruby
+table = Tabulo::Table.new(data) do |t|
+  t.add_column("English") { |a| a[0] }
+  t.add_column("Portuguese") { |a| a[1] }
+end
+
+puts table
+```
+
+In both cases, the output will be as follows:
+
+```
++--------------+--------------+
+|    English   |  Portuguese  |
++--------------+--------------+
+| hello        | bom dia      |
+| goodbye      | adeus        |
++--------------+--------------+
+```
+
+If you have previously used other terminal tabulation libraries, you may be accustomed to being _required_
+to place your data into an array of hashes or arrays before you can tabulate them. Tabulo, however,
+offers an API that is more general and flexible than this; your data source can be _any_
+enumerable collection (not just an array), and each item in that collection can be _any_ object (not
+necessarily an array or a hash). However, as shown above, it is still straightforward to tabulate an
+array of hashes or arrays, if your data source happens to take that form.
+
 <a name="removing-columns"></a>
 ### Removing columns [&#x2191;](#contents)
 
@@ -345,9 +410,11 @@ If a table title is present, it is center-aligned by default. This can be change
 table = Tabulo::Table.new([1, 2], :itself, :even?, title: "Numbers", align_title: :left)
 ```
 
+<a name="column-width-wrapping-and-truncation"></a>
 ### Column width, wrapping and truncation [&#x2191;](#contents)
 
 <a name="fixed-column-widths"></a>
+<a name="configuring-fixed-widths"></a>
 #### Configuring fixed widths [&#x2191;](#contents)
 
 By default, column width is fixed at 12 characters, plus 1 character of padding on either side.
@@ -390,6 +457,7 @@ table = Tabulo::Table.new([1, 2], :itself, :even?, column_width: 6)
 Widths set for individual columns always override the default column width for the table.
 
 <a name="pack"></a>
+<a name="automating-column-widths"></a>
 #### Automating column widths [&#x2191;](#contents)
 
 Instead of setting column widths &ldquo;manually&rdquo;, you can tell the table to sort out the widths
@@ -466,6 +534,16 @@ necessary (see [Overflow handling](#overflow-handling)). Under the hood, a chara
 is deducted column by column&mdash;the widest column being targetted each time&mdash;until
 the table will fit.
 
+To resize only specific columns, `pack` takes an `except:` argument, which can be a single column
+label or an Array of column labels. E.g. `pack(except: :id)` will exclude the `id` column from
+resizing and let it keep its current width. This is useful if you want to prevent the addition of
+linebreaks in your data. When using this option, other columns might be shrunk more to still make
+the table fit within the `max_table_width`.
+
+For even finer-grained control over column and table resizing, see the
+for the [`#autosize_columns`](https://www.rubydoc.info/gems/tabulo/2.8.0/Tabulo/Table#autosize_columns-instance_method)
+and [`#shrink_to`](https://www.rubydoc.info/gems/tabulo/2.8.0/Tabulo/Table#autosize_columns-instance_method) methods.
+
 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.
@@ -729,7 +807,7 @@ the table.
 The `formatter` callback also has an alternative, 2-parameter version. If `formatter` is passed
 a 2-parameter callable, the second parameter will be given a `CellData` instance,
 containing additional information about the cell that may be useful in determining how to format
-it&mdash;see the [documentation](https://www.rubydoc.info/gems/tabulo/2.7.0/Tabulo/CellData.html)
+it&mdash;see the [documentation](https://www.rubydoc.info/gems/tabulo/2.8.0/Tabulo/CellData.html)
 for details.
 
 <a name="colours-and-styling"></a>
@@ -775,7 +853,7 @@ number is even). The second parameter represents the formatted string value of t
 content after any processing by the [formatter](#formatting-cell-values). The third and fourth
 parameters are optional, and contain further information about the cell and its contents that may be useful in
 determining how to style it. See the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.7.0/Tabulo/Table#add_column-instance_method) for details.
+[documentation](https://www.rubydoc.info/gems/tabulo/2.8.0/Tabulo/Table#add_column-instance_method) for details.
 
 If the content of a cell is wrapped over multiple lines, then the `styler` will be called once
 per line, so that each line of the cell will have the escape sequence applied to it separately
@@ -795,7 +873,7 @@ table.add_column(:even?, header_styler: -> (s) { "\033[32m#{s}\033[0m" })
 ```
 
 The `header_styler` option accepts a 1-, 2- or 3-parameter callable. See the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.7.0/Tabulo/Table#add_column-instance_method)
+[documentation](https://www.rubydoc.info/gems/tabulo/2.8.0/Tabulo/Table#add_column-instance_method)
 for details.
 
 <a name="styling-title"></a>
@@ -809,7 +887,7 @@ table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, title: "Numbers", title_
 ```
 
 The `title_styler` option accepts a 1- or 2-parameter callable. See the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.7.0/Tabulo/Table#initialize-instance_method)
+[documentation](https://www.rubydoc.info/gems/tabulo/2.8.0/Tabulo/Table#initialize-instance_method)
 for details.
 
 <a name="styling-borders"></a>
@@ -875,6 +953,12 @@ table = Tabulo::Table.new(1..10, :itself, :even?, header_frequency: 5)
 
 Note that if the table has a [title](#title), it will not be repeated; only column headers are repeated.
 
+One can achieve even finer-grained control over printing of headers within the table body by stepping
+through the table a row at a time (using `.each` or other methods of `Enumerable`) and calling the
+the [`formatted_header`](https://www.rubydoc.info/gems/tabulo/Tabulo/Table#formatted_header-instance_method)
+method in combination with [`horizontal_rule`](https://www.rubydoc.info/gems/tabulo/Tabulo%2FTable:horizontal_rule)
+to produce headers at arbitrary points in the output.
+
 <a name="enumerator"></a>
 ### Using a Table Enumerator [&#x2191;](#contents)
 
@@ -1004,7 +1088,7 @@ a new table in which the rows and columns are swapped:
 By default, a header row is added to the new table, showing the string value of the element
 represented in that column. This can be configured, however, along with other aspects of
 `transpose`&#8217;s behaviour. For details, see the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.7.0/Tabulo/Table#transpose-instance_method).
+[documentation](https://www.rubydoc.info/gems/tabulo/2.8.0/Tabulo/Table#transpose-instance_method).
 
 <a name="borders"></a>
 ### Configuring borders [&#x2191;](#contents)
@@ -1222,6 +1306,11 @@ If you want a line before every row, pass `1` to `row_divider_frequency`. For ex
 +--------------+--------------+--------------+
 ```
 
+In addition to these options, it is also possible to print horizontal dividers at any chosen
+point in the table output, by stepping through the table one row at a time
+and calling the [`horizontal_rule`](https://www.rubydoc.info/gems/tabulo/Tabulo%2FTable:horizontal_rule)
+method as required.
+
 <a name="freezing-a-table"></a>
 ### Using a table as a snapshot rather than as a dynamic view [&#x2191;](#contents)
 
@@ -1389,21 +1478,20 @@ install dependencies.
 `bundle exec rake spec` will run the test suite. For a list of other Rake tasks that are available in
 the development environment, run `bundle exec rake -T`.
 
+<a name="license"></a>
 ## License [&#x2191;](#contents)
 
 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/2.7.0
+[Documentation]: http://www.rubydoc.info/gems/tabulo
 [Build Status]: https://github.com/matt-harvey/tabulo/actions/workflows/tests.yml
 [Coverage Status]: https://coveralls.io/github/matt-harvey/tabulo
-[Code Climate]: https://codeclimate.com/github/matt-harvey/tabulo
 [Awesome Ruby]: https://github.com/markets/awesome-ruby#cli-utilities
 
 [GV img]: https://img.shields.io/gem/v/tabulo.svg
-[DC img]: https://img.shields.io/badge/documentation-v2.7.0-blue.svg
+[DC img]: https://img.shields.io/badge/documentation-v2.8.0-blue.svg
 [BS img]: https://github.com/matt-harvey/tabulo/actions/workflows/tests.yml/badge.svg
 [CS img]: https://img.shields.io/coveralls/matt-harvey/tabulo.svg
-[CC img]: https://codeclimate.com/github/matt-harvey/tabulo/badges/gpa.svg
 [AR img]: https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg

data/VERSION

@@ -1 +1 @@
-2.7.0
+2.8.0

data/lib/tabulo/table.rb

@@ -125,7 +125,7 @@ module Tabulo
     #   defaults to {DEFAULT_TRUNCATION_INDICATOR}. If passed something other than <tt>nil</tt> or
     #   a single-character String, raises {InvalidTruncationIndicatorError}.
     # @param [Symbol] wrap_preserve Specifies what unit of text the wrapping mechanism will try to
-    #     preserve intact when wrapping column content when the column width is reached.
+    #   preserve intact when wrapping column content when the column width is reached:
     #   * If passed `:rune` (the default), then it will wrap at the "character" level (approximately
     #     speaking, the Unicode grapheme cluster level). This means the maximum number of what
     #     readers usually think of as "characters" will be fit on each line, within the column's allocated
@@ -207,11 +207,10 @@ module Tabulo
     #   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 [Symbol, String, Integer, nil] before The label of the column before (i.e. to
-    #   the left of) which the new column should inserted. If <tt>nil</tt> is passed, it will be
-    #   inserted after all other columns. If there is no column with the given label, then an
-    #   {InvalidColumnLabelError} will be raised. A non-Integer labelled column can be identified
-    #   in either String or Symbol form for this purpose.
+    # @param [Symbol, Integer, nil] before The label of the column before (i.e. to the left of) which the
+    #   new column should inserted. If <tt>nil</tt> is passed, it will be inserted after all other columns.
+    #   If there is no column with the given label, then an {InvalidColumnLabelError} will be raised.
+    #   A non-Integer labelled column can be identified in Symbol form for this purpose.
     # @param [#to_proc] formatter A lambda or other callable object that
     #   will be passed the calculated value of each cell to determine how it should be displayed. This
     #   is distinct from the extractor and the styler (see below).
@@ -420,7 +419,7 @@ module Tabulo
     end
 
     # @return [String] a graphical representation of the Table column headers formatted with fixed
-    #   width plain text.
+    #   width plain text, excluding any horizontal borders above or below.
     def formatted_header
       cells = get_columns.map(&:header_cell)
       format_row(cells, @wrap_header_cells_to)
@@ -453,8 +452,10 @@ module Tabulo
 
     # Resets 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. In addition, if the table has a title but is not wide enough to
+    # collection, together with padding (by default 1 character on either side of the column),
+    # without wrapping. Other adjustments may also be performed (see below).
+    #
+    # In addition, if the table has a title but is not wide enough to
     # accommodate (without wrapping) the title text (with a character of padding either side),
     # widens the columns roughly evenly until the table as a whole is just wide enough to
     # accommodate the title text.
@@ -468,7 +469,7 @@ 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 With no args, or if passed <tt>:auto</tt>,
+    # @param [nil, :auto, Numeric] max_table_width 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.
@@ -476,34 +477,104 @@ module Tabulo
     #   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
+    #   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 for each column, and the padding
+    #   configured for each column (by default 1 character either side), 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.
+    # @param [nil, Symbol, Integer, Array[Symbol|Integer]] except If passed one or multiple column labels,
+    #   these columns will be excluded from resizing and will keep their current width.
+    #   (Note if passing integers, these are not necessarily positional: only columns _explicitly_
+    #   given an integer label will have these as labels.)
     # @return [Table] the Table itself
-    def pack(max_table_width: :auto)
-      get_columns.each { |column| column.width = Util.wrapped_width(column.header) }
+    def pack(max_table_width: :auto, except: nil)
+      autosize_columns(except: except)
+
+      max_width = nil
+      if max_table_width
+        max_width = (max_table_width == :auto ? TTY::Screen.width : max_table_width)
+        shrink_to(max_width, except: except)
+      end
+
+      if @title
+        border_edge_width = (@border == :blank ? 0 : 2)
+        all_columns = get_columns
+        min_width =
+          Unicode::DisplayWidth.of(@title) +
+          all_columns.first.left_padding +
+          all_columns.last.right_padding +
+          border_edge_width
 
+        min_width = max_width if max_width && max_width < min_width
+        expand_to(min_width, except: except)
+      end
+
+      self
+    end
+
+    # Resets 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 padding (by default 1 character either side), without wrapping.
+    #
+    # @param [nil, Symbol, Integer, Array[Symbol|Integer]] except If passed one or multiple column labels,
+    #   these columns will be excluded from resizing and will keep their current width.
+    #   (Note if using integers, these are not necessarily positional: only columns _explicitly_
+    #   given an integer label will have these as labels.)
+    # @return [Table] the Table itself
+    def autosize_columns(except: nil)
+      columns = get_columns(except: except)
+      columns.each { |column| column.width = Util.wrapped_width(column.header) }
       @sources.each_with_index do |source, row_index|
-        get_columns.each_with_index do |column, column_index|
+        columns.each_with_index do |column, column_index|
           cell = column.body_cell(source, row_index: row_index, column_index: column_index)
           cell_width = Util.wrapped_width(cell.formatted_content)
           column.width = Util.max(column.width, cell_width)
         end
       end
+      self
+    end
 
-      shrink_to(max_table_width == :auto ? TTY::Screen.width : max_table_width) if max_table_width
+    # If `max_table_width` is passed an integer, then column widths will be adjusted downward so
+    # that the total table width is reduced to the passed target width. (If the total width of the
+    # table exceeds the passed `max_table_width`, then this method is a no-op.)
+    #
+    # 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 for each column, and the padding
+    # configured for each column (by default 1 character either side), 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.
+    #
+    # If `max_table_width` is passed the symbol `:screen`, then this method will behave as if it
+    # were passed an integer, with that integer being the width of the terminal.
+    #
+    # @param [Integer, :screen] the desired maximum table width
+    # @param [nil, Symbol, Integer, Array[Symbol|Integer]] except If passed one or multiple column labels,
+    #   these columns will be excluded from resizing and will keep their current width.
+    #   (Note if passing integers, these are not necessarily positional: only columns _explicitly_
+    #   given an integer label will have these as labels.)
+    # @return [Table] the Table itself
+    def shrink_to(max_table_width, except: nil)
+      min_content_width_per_column = 1
+      min_total_column_content_width = num_columns * min_content_width_per_column
+      min_table_width = total_padding_width + total_borders_width + min_total_column_content_width
 
-      if @title
-        border_edge_width = (@border == :blank ? 0 : 2)
-        columns = get_columns
-        expand_to(
-          Unicode::DisplayWidth.of(@title) +
-          columns.first.left_padding +
-          columns.last.right_padding +
-          border_edge_width
-        )
+      max_table_width = (max_table_width == :screen ? TTY::Screen.width : max_table_width)
+      max_table_width = Util.max(min_table_width, max_table_width)
+
+      required_reduction = Util.max(total_table_width - max_table_width, 0)
+
+      shrinkable_columns = get_columns(except: except)
+      required_reduction.times do
+        widest_column = shrinkable_columns.inject(shrinkable_columns.first) do |widest, column|
+          column.width >= widest.width ? column : widest
+        end
+
+        widest_column.width -= 1
       end
 
       self
@@ -609,8 +680,13 @@ module Tabulo
     private
 
     # @!visibility private
-    def get_columns
-      column_registry.values
+    def get_columns(except: nil)
+      if except
+        column_labels = except ? column_registry.keys - Array(except) : column_registry.keys
+        column_labels.map { |label| column_registry[label] }
+      else
+        column_registry.values
+      end
     end
 
     # @!visibility private
@@ -695,16 +771,35 @@ module Tabulo
     end
 
     # @!visibility private
-    def expand_to(min_table_width)
-      columns = get_columns
-      num_columns = columns.count
-      total_columns_padded_width = columns.inject(0) { |sum, column| sum + column.padded_width }
-      total_borders = num_columns + 1
-      unadjusted_table_width = total_columns_padded_width + total_borders
-      required_increase = Util.max(min_table_width - unadjusted_table_width, 0)
+    # @return [Integer] the total combined width of padding characters
+    def total_padding_width
+      get_columns.inject(0) { |sum, column| sum + column.total_padding }
+    end
 
+    # @!visibility private
+    # @return [Integer] the total combined width of vertical border characters
+    def total_borders_width
+      num_columns + 1
+    end
+
+    # @!visibility private
+    # @return [Integer] the total combined width of column contents (excludes borders and padding)
+    def total_column_content_width
+      get_columns.inject(0) { |sum, column| sum + column.width }
+    end
+
+    # @!visibility private
+    # @return [Integer] the total actual width of the table as a whole
+    def total_table_width
+      total_column_content_width + total_padding_width + total_borders_width
+    end
+
+    # @!visibility private
+    def expand_to(min_table_width, except: nil)
+      required_increase = Util.max(min_table_width - total_table_width, 0)
+      expandable_columns = get_columns(except: except)
       required_increase.times do
-        narrowest_column = columns.inject(columns.first) do |narrowest, column|
+        narrowest_column = expandable_columns.inject(expandable_columns.first) do |narrowest, column|
           column.width <= narrowest.width ? column : narrowest
         end
 
@@ -713,27 +808,8 @@ module Tabulo
     end
 
     # @!visibility private
-    def shrink_to(max_table_width)
-      columns = get_columns
-      num_columns = columns.count
-      total_columns_padded_width = columns.inject(0) { |sum, column| sum + column.padded_width }
-      total_padding = columns.inject(0) { |sum, column| sum + column.total_padding }
-      total_borders = num_columns + 1
-      unadjusted_table_width = total_columns_padded_width + 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 = Util.max(min_table_width, max_table_width)
-      required_reduction = Util.max(unadjusted_table_width - max_table_width, 0)
-
-      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
+    def num_columns
+      column_registry.count
     end
 
     # @!visibility private

data/lib/tabulo/version.rb

@@ -1,3 +1,3 @@
 module Tabulo
-  VERSION = "2.7.0"
+  VERSION = "2.8.0"
 end

data/tabulo.gemspec

@@ -29,7 +29,7 @@ Gem::Specification.new do |spec|
   }
 
   spec.add_runtime_dependency "tty-screen", "0.8.1"
-  spec.add_runtime_dependency "unicode-display_width", "2.0.0"
+  spec.add_runtime_dependency "unicode-display_width", "2.1.0"
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake", "~> 12.3.3"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tabulo
 version: !ruby/object:Gem::Version
-  version: 2.7.0
+  version: 2.8.0
 platform: ruby
 authors:
 - Matthew Harvey
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-07-18 00:00:00.000000000 Z
+date: 2022-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-screen
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 2.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 2.1.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -206,7 +206,7 @@ licenses:
 metadata:
   source_code_uri: https://github.com/matt-harvey/tabulo
   changelog_uri: https://raw.githubusercontent.com/matt-harvey/tabulo/master/CHANGELOG.md
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -221,8 +221,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key:
+rubygems_version: 3.2.3
+signing_key: 
 specification_version: 4
 summary: Terminal table generator
 test_files: []