tabulo 2.7.3 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d0744fe4dfb79a4a05cf2f7c0e2222c3364dfc907897ed7f1d304f9b2702ba9
-  data.tar.gz: 9008fd0d0ce6a4df33650bfd317030d5ed36aede411cb476f0d2774352b87b8a
+  metadata.gz: d58a5b883e9c9685c3cff492c6ad49b88ce921c5947596c5fe9199a5818dbfab
+  data.tar.gz: d9e2d10ea6314b73bdc3ad5a41bf790211ad7abe1e42899c52bc8bf2b405e8e6
 SHA512:
-  metadata.gz: a076fadf6d1fcb905f52c735396bdbed69b03718ca8bac21fa25d2f6c64f16e5b20b196b9f0d16d73b34b9d25b71abac6485fe68bbc733d7474348f84f6dc768
-  data.tar.gz: 72a96aa1c8d9152d95a77a98cd0478701cfd97d56fed4da51534d199bc7165f255b0001accea4bc9602d67291cd5725d0c2db03043e1e1f742014985ea183f97
+  metadata.gz: 3fb526cb0ddc9d63033eb40aa81a0aa2f39a306e051074693fcc4d08c95a216d13ffa27c92a1eb7bed08d3daef431bff6d15faa839b87580f830b916409c46a7
+  data.tar.gz: 587ba915a07b2e6d67d58296a7147fab9017d038facf0976a628baa71f8ebdf6a08f3d25559ca372630026452d65d12f83ced616c78cd33fca9e7e31ff0ed597

data/.github/workflows/tests.yml

@@ -26,6 +26,7 @@ jobs:
           '2.6.9',
           '2.7.5',
           '3.0.3',
+          '3.1.0',
         ]
     steps:
     - uses: actions/checkout@v2

data/CHANGELOG.md

@@ -1,8 +1,26 @@
 # 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
+* Fix malformed YARD documentation for `Tabulo::Table#initialize` method
 
 ### v2.7.2
 

data/README.md

@@ -74,13 +74,13 @@ 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)
@@ -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)
 
@@ -408,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.
@@ -453,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
@@ -529,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.
@@ -792,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.3/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>
@@ -838,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.3/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
@@ -858,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.3/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>
@@ -872,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.3/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>
@@ -1073,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.3/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)
@@ -1463,6 +1478,7 @@ 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
@@ -1475,7 +1491,7 @@ License](http://opensource.org/licenses/MIT).
 [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.3-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
 [AR img]: https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg

data/VERSION

@@ -1 +1 @@
-2.7.3
+2.8.0

data/lib/tabulo/table.rb

@@ -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).
@@ -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.3"
+  VERSION = "2.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tabulo
 version: !ruby/object:Gem::Version
-  version: 2.7.3
+  version: 2.8.0
 platform: ruby
 authors:
 - Matthew Harvey
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-12-19 00:00:00.000000000 Z
+date: 2022-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-screen