tabulo 2.4.1 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d49cd1a3bfb031b2ced0f4539bd8ea16b2943df0c999f7b70e8ddf83cfcd5fa1
-  data.tar.gz: 745a3834a8c62ba85a7fbd8bdd826dc0bf9e18a1cb6fd54ac81e311870c02f61
+  metadata.gz: 970ffd91a62eceded969200a310d85faaf83f8a264f12b4d7dbbbb20d913d6cf
+  data.tar.gz: 1b1d3452e33cb7a07f4940291f68370a6443beb46c013e109348c6ec81647f9c
 SHA512:
-  metadata.gz: 939d50fdbe7bdfd94740ddddc86d3774c688e505633e693e27f41806224af8c601de6a4aa124ff868aefdc151ca72d4da89dfa2c045bce2b9e45c61064a7723a
-  data.tar.gz: 6cad47f7c06a52de935ebeec3710722344ac7d28159bca3d7efb2b9b627751a1c4d879d8b0d22beb0eb4af8705f03ee310d925b96b86d175d4c39e3f7b76acbf
+  metadata.gz: 34d885006b3dbf0d8190d91126e4b9ead491b214014f172d57187708836e00ec2e3f97cbe5aa7dc2b9a44ef559bc142cd51c2f3ce255e9e0e20bcc320dd7f73b
+  data.tar.gz: 9e14cb7b9a6423bb37d863c5a1d0e1c9198804bf2018889400e51fa4c98622dc498d37914aacc9c79602b21ef493e8e0ac62274609e05993de7d78e70064871c

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+### v2.5.0
+
+* Add option of table title, together with options for styling and aligning the title
+
 ### v2.4.1
 
 * Fix warnings under Ruby 2.7

data/README.md

@@ -65,6 +65,7 @@ end
 * Easily [transpose](#transposition) the table, so that rows are swapped with columns.
 * Choose from multiple [border configurations](#borders), including Markdown, “ASCII”, and smoothly
   joined Unicode border characters.
+* Optionally add a [title](#title) to your table.
 
 Tabulo has also been ported to Crystal (with some modifications): see [Tablo](https://github.com/hutou/tablo).
 
@@ -82,6 +83,7 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
         * [Column labels _vs_ headers](#labels-headers)
         * [Positioning columns](#column-positioning)
      * [Removing columns](#removing-columns)
+     * [Adding a title](#title)
      * [Cell alignment](#cell-alignment)
      * [Column width, wrapping and truncation](#column-width-wrapping-and-truncation)
         * [Configuring fixed widths](#configuring-fixed-widths)
@@ -92,6 +94,7 @@ Tabulo has also been ported to Crystal (with some modifications): see [Tablo](ht
      * [Colours and other styling](#colours-and-styling)
         * [Styling cell content](#styling-cell-content)
         * [Styling column headers](#styling-column-headers)
+        * [Styling the table title](#styling-title)
         * [Setting default styles](#default-styles)
         * [Styling borders](#border-styling)
      * [Repeating headers](#repeating-headers)
@@ -286,6 +289,33 @@ the label of the column you want to remove:
 table.remove_column(:even?)
 ```
 
+<a name="title"></a>
+### Adding a title
+
+You can optionally give your table a title, using the `title` option when initializing the table:
+
+```ruby
+table = Tabulo::Table.new([1, 2, 3], :itself, :odd?, title: "Numbers")
+table.add_column(:even?, before: :odd?)
+```
+
+```
+> puts table
++--------------------------------------------+
+|                   Numbers                  |
++--------------+--------------+--------------+
+|    itself    |     even?    |     odd?     |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
+|            3 |     false    |     true     |
++--------------+--------------+--------------+
+```
+
+There is a caveat: Using the `title` option with the `:markdown` [border type](#borders) will cause
+the rendered table to cease being valid Markdown, as unfortunately almost no markdown engines support
+adding a captions (i.e. titles) to tables.
+
 <a name="cell-alignment"></a>
 ### Cell alignment
 
@@ -307,6 +337,13 @@ passing similarly-named options to `add_column`, e.g.:
 table.add_column("Doubled", align_header: :right, align_body: :left) { |n| n * 2 }
 ```
 
+If a table title is present, it is center-aligned by default. This can be changed using the
+`align_title` option when initializing the table:
+
+```ruby
+table = Tabulo::Table.new([1, 2], :itself, :even?, title: "Numbers", align_title: :left)
+```
+
 ### Column width, wrapping and truncation
 
 <a name="fixed-column-widths"></a>
@@ -373,6 +410,26 @@ table.pack
 +-------------------------+------+
 ```
 
+If the table [title](#title) happens to be too long to for the existing width of the table, `pack`
+will also arrange for the table to be widened sufficiently to accommodate it without wrapping:
+
+```ruby
+table = Tabulo::Table.new(["a", "b"], :itself, :size, title: "Here are some letters of the alphabet")
+table.pack
+```
+
+```
+> puts table
++---------------------------------------+
+| Here are some letters of the alphabet |
++-------------------+-------------------+
+|       itself      |        size       |
++-------------------+-------------------+
+| a                 |                 1 |
+| b                 |                 1 |
++-------------------+-------------------+
+```
+
 The `pack` method returns the table itself, so you can &ldquo;pack-and-print&rdquo; in one go:
 
 ```ruby
@@ -576,7 +633,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.4.1/Tabulo/CellData.html)
+it&mdash;see the [documentation](https://www.rubydoc.info/gems/tabulo/2.5.0/Tabulo/CellData.html)
 for details.
 
 <a name="colours-and-styling"></a>
@@ -622,7 +679,7 @@ the number is even); the second represents the formatted string value of that ce
 content after any processing by the [formatter](#formatting-cell-values); and the third parameter,
 if present, will be passed a `CellData` object, containing other information about the cell
 that may be useful in determining how to style it&mdash;see the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.4.1/Tabulo/CellData.html) for details.
+[documentation](https://www.rubydoc.info/gems/tabulo/2.5.0/Tabulo/CellData.html) 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
@@ -642,8 +699,18 @@ table.add_column(:even?, header_styler: -> (s) { "\033[32m#{s}\033[0m" })
 ```
 
 The `header_styler` option accepts either a 1- or 2-parameter callable. See the
-[documentation](https://www.rubydoc.info/gems/tabulo/2.4.1/Tabulo/Table#add_column-instance_method)
+[documentation](https://www.rubydoc.info/gems/tabulo/2.5.0/Tabulo/Table#add_column-instance_method)
 for details.
+```
+
+<a name="styling-title"></a>
+#### Styling the table title
+
+To apply colours or other styling to the table title, if present, use the `title_styler` option
+when initializing the table. This accepts a single-parameter callable:
+
+```ruby
+table = Tabulo::Table.new(1..5, :itself, :even?, :odd?, title: "Numbers", title_styler: -> (s) { "\033[32m#{s}\033[0m" })
 
 <a name="default-styles"></a>
 #### Setting default styles
@@ -706,6 +773,8 @@ 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.
+
 <a name="enumerator"></a>
 ### Using a Table Enumerator
 
@@ -835,7 +904,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.4.1/Tabulo/Table#transpose-instance_method).
+[documentation](https://www.rubydoc.info/gems/tabulo/2.5.0/Tabulo/Table#transpose-instance_method).
 
 <a name="borders"></a>
 ### Configuring borders
@@ -854,6 +923,17 @@ This is done using the `border` option passed to `Table.new`. The options are as
 |            2 |     true     |     false    |
 |            3 |     false    |     true     |
 +--------------+--------------+--------------+
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :ascii, title: "Numbers")
++--------------------------------------------+
+|                   Numbers                  |
++--------------+--------------+--------------+
+|    itself    |     even?    |     odd?     |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
+|            3 |     false    |     true     |
++--------------+--------------+--------------+
 ```
 
 `:modern`&mdash;uses smoothly joined Unicode characters:
@@ -867,6 +947,17 @@ This is done using the `border` option passed to `Table.new`. The options are as
 │            2 │     true     │     false    │
 │            3 │     false    │     true     │
 └──────────────┴──────────────┴──────────────┘
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :modern, title: "Numbers")
+┌────────────────────────────────────────────┐
+│                   Numbers                  │
+├──────────────┬──────────────┬──────────────┤
+│    itself    │     even?    │     odd?     │
+├──────────────┼──────────────┼──────────────┤
+│            1 │     false    │     true     │
+│            2 │     true     │     false    │
+│            3 │     false    │     true     │
+└──────────────┴──────────────┴──────────────┘
 ```
 
 `:markdown`&mdash;renders a GitHub flavoured Markdown table:
@@ -878,8 +969,20 @@ This is done using the `border` option passed to `Table.new`. The options are as
 |            1 |     false    |     true     |
 |            2 |     true     |     false    |
 |            3 |     false    |     true     |
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :markdown, title: "Numbers")
+|                   Numbers                  |
+|    itself    |     even?    |     odd?     |
+|--------------|--------------|--------------|
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
+|            3 |     false    |     true     |
 ```
 
+_However_, note that when a table is rendered using the `:markdown` border type in combination with a
+(non-`nil`) `title`, the result will be _invalid Markdown_. This is because Markdown engines do not
+generally support adding a caption (i.e. title) element to tables.
+
 `:blank`&mdash;no border or divider characters are printed:
 
 ```
@@ -888,6 +991,14 @@ This is done using the `border` option passed to `Table.new`. The options are as
             1      false         true     
             2      true          false    
             3      false         true     
+
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :blank, title: "Numbers")
+                  Numbers                 
+    itself         even?         odd?     
+            1      false         true     
+            2      true          false    
+            3      false         true     
 ```
 
 `:reduced_ascii`&mdash;similar to `:ascii`, but without vertical lines:
@@ -901,6 +1012,17 @@ This is done using the `border` option passed to `Table.new`. The options are as
             2       true           false    
             3       false          true     
 -------------- -------------- --------------
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :reduced_modern, title: "Numbers")
+--------------------------------------------
+                   Numbers                  
+-------------- -------------- --------------
+    itself          even?          odd?     
+-------------- -------------- --------------
+            1       false          true     
+            2       true           false    
+            3       false          true     
+-------------- -------------- --------------
 ```
 
 `:reduced_modern`&mdash;similar to `:modern`, but without vertical lines:
@@ -914,6 +1036,17 @@ This is done using the `border` option passed to `Table.new`. The options are as
             2       true           false    
             3       false          true     
 ────────────── ────────────── ──────────────
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :reduced_ascii, title: "Numbers")
+────────────────────────────────────────────
+                   Numbers                  
+────────────── ────────────── ──────────────
+    itself          even?          odd?     
+────────────── ────────────── ──────────────
+            1       false          true     
+            2       true           false    
+            3       false          true     
+────────────── ────────────── ──────────────
 ```
 
 `:classic`&mdash;reproduces the default behaviour in Tabulo v1; this is like the `:ascii` option,
@@ -927,6 +1060,16 @@ but without a bottom border:
 |            1 |     false    |     true     |
 |            2 |     true     |     false    |
 |            3 |     false    |     true     |
+
+> puts Tabulo::Table.new(1..3, :itself, :even?, :odd?, border: :classic, title: "Numbers")
++--------------------------------------------+
+|                   Numbers                  |
++--------------+--------------+--------------+
+|    itself    |     even?    |     odd?     |
++--------------+--------------+--------------+
+|            1 |     false    |     true     |
+|            2 |     true     |     false    |
+|            3 |     false    |     true     |
 ```
 
 Note that, by default, none of the border options includes lines drawn _between_ rows in the body of the table.
@@ -1144,14 +1287,14 @@ 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.4.1
+[Documentation]: http://www.rubydoc.info/gems/tabulo/2.5.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
 [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.4.1-blue.svg
+[DC img]: https://img.shields.io/badge/documentation-v2.5.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 @@
-2.4.1
+2.5.0

data/lib/tabulo/border.rb

@@ -115,6 +115,10 @@ module Tabulo
     def horizontal_rule(column_widths, position = :bottom)
       left, center, right, segment =
         case position
+        when :title_top
+          [@corner_top_left, @edge_top, @corner_top_right, @edge_top]
+        when :title_bottom
+          [@tee_left, @tee_top, @tee_right, @edge_top]
         when :top
           [@corner_top_left, @tee_top, @corner_top_right, @edge_top]
         when :middle
@@ -123,6 +127,11 @@ module Tabulo
           [@corner_bottom_left, @tee_bottom, @corner_bottom_right, @edge_bottom]
         end
       segments = column_widths.map { |width| segment * width }
+
+      # Prevent weird bottom edge of title if segments empty but right/left not empty, as in
+      # Markdown border.
+      left = right = "" if segments.all?(&:empty?)
+
       style("#{left}#{segments.join(center)}#{right}")
     end
 

data/lib/tabulo/table.rb

@@ -43,13 +43,18 @@ module Tabulo
     # @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] align_header (:center) Determines the alignment of the table
+    #   title, if present.
     # @param [:ascii, :markdown, :modern, :blank, nil] border (nil) Determines the characters used
     #   for the Table border, including both the characters around the outside of table, and the lines drawn
     #   within the table to separate columns from each other and the header row from the Table body.
     #   If <tt>nil</tt>, then the value of {DEFAULT_BORDER} will be used.
     #   Possible values are:
     #   - `:ascii`          Uses ASCII characters only
-    #   - `:markdown`       Produces a GitHub-flavoured Markdown table
+    #   - `:markdown`       Produces a GitHub-flavoured Markdown table. Note: Using the `title`
+    #                       option in combination with this border type will cause the rendered
+    #                       table not to be valid Markdown, since Markdown engines do not generally
+    #                       support adding a caption element (i.e. title) to tables.
     #   - `:modern`         Uses non-ASCII Unicode characters to render a border with smooth continuous lines
     #   - `:blank`          No border characters are rendered
     #   - `:reduced_ascii`  Like `:ascii`, but without left or right borders, and with internal vertical
@@ -89,6 +94,19 @@ module Tabulo
     #   header row.
     # @param [nil, #to_proc] styler (nil) The default styler for columns in this table. See `styler`
     #   option of {#add_column} for details.
+    # @param [nil, String] title (nil) If passed a String, will arrange for a title to be shown at the top
+    #   of the table. Note: If the `border` option is set to `:markdown`, adding a title to the table
+    #   will cause it to cease being valid Markdown when rendered, since Markdown engines do not generally
+    #   support adding a caption element (i.e. title) to tables.
+    # @param [nil, #to_proc] title_styler (nil) A lambda or other callable object that will
+    #   determine the colors or other styling applied to the table title. If the table doesn't have
+    #   a title, this parameter has no effect. If passed a single-parameter callable, then that
+    #   callable will be called for each line of content within the title, and the resulting string
+    #   rendered in place of that line.
+    #   The extra width of the string returned by the <tt>title_styler</tt> is not taken into
+    #   consideration by the internal table width calculations involved in rendering the
+    #   table. Thus it can be used to apply ANSI escape codes to title content, to color the
+    #   title for example, without breaking the table formatting.
     # @param [nil, String] truncation_indicator Determines the character used to indicate that a
     #   cell's content has been truncated. If omitted or passed <tt>nil</tt>,
     #   defaults to {DEFAULT_TRUNCATION_INDICATOR}. If passed something other than <tt>nil</tt> or
@@ -107,15 +125,17 @@ module Tabulo
     # @return [Table] a new {Table}
     # @raise [InvalidColumnLabelError] if non-unique Symbols are provided to columns.
     # @raise [InvalidBorderError] if invalid option passed to `border` parameter.
-    def initialize(sources, *columns, align_body: :auto, align_header: :center, border: nil,
-      border_styler: nil, column_padding: nil, column_width: nil, formatter: :to_s.to_proc,
+    def initialize(sources, *columns, align_body: :auto, align_header: :center, align_title: :center,
+      border: nil, border_styler: nil, column_padding: nil, column_width: nil, formatter: :to_s.to_proc,
       header_frequency: :start, header_styler: nil, row_divider_frequency: nil, styler: nil,
-      truncation_indicator: nil, wrap_body_cells_to: nil, wrap_header_cells_to: nil)
+      title: nil, title_styler: nil, truncation_indicator: nil, wrap_body_cells_to: nil,
+      wrap_header_cells_to: nil)
 
       @sources = sources
 
       @align_body = align_body
       @align_header = align_header
+      @align_title = align_title
       @border = (border || DEFAULT_BORDER)
       @border_styler = border_styler
       @border_instance = Border.from(@border, @border_styler)
@@ -130,6 +150,8 @@ module Tabulo
       @header_styler = header_styler
       @row_divider_frequency = row_divider_frequency
       @styler = styler
+      @title = title
+      @title_styler = title_styler
       @truncation_indicator = validate_character(truncation_indicator,
         DEFAULT_TRUNCATION_INDICATOR, InvalidTruncationIndicatorError, "truncation indicator")
       @wrap_body_cells_to = wrap_body_cells_to
@@ -339,7 +361,8 @@ module Tabulo
       end
     end
 
-    # @return [String] an "ASCII" graphical representation of the Table column headers.
+    # @return [String] a graphical representation of the Table column headers formatted with fixed
+    #   width plain text.
     def formatted_header
       cells = get_columns.map(&:header_cell)
       format_row(cells, @wrap_header_cells_to)
@@ -348,9 +371,11 @@ module Tabulo
     # Produce a horizontal dividing line suitable for printing at the top, bottom or middle
     # of the table.
     #
-    # @param [:top, :middle, :bottom] position (:bottom) Specifies the position
-    #   for which the resulting horizontal dividing line is intended to be printed.
-    #   This determines the border characters that are used to construct the line.
+    # @param [:top, :middle, :bottom, :title_top, :title_bottom] position (:bottom)
+    #   Specifies the position for which the resulting horizontal dividing line is intended to
+    #   be printed. This determines the border characters that are used to construct the line.
+    #   The `:title_top` and `:title_bottom` options are used internally for adding borders
+    #   above and below the table title text.
     # @return [String] an "ASCII" graphical representation of a horizontal
     #   dividing line.
     # @example Print a horizontal divider between each pair of rows, and again at the bottom:
@@ -368,10 +393,13 @@ module Tabulo
       @border_instance.horizontal_rule(column_widths, position)
     end
 
-    # Reset all the column widths so that each column is *just* wide enough to accommodate
+    # 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.
+    # without any wrapping. 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.
     #
     # 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
@@ -411,6 +439,10 @@ module Tabulo
         shrink_to(max_table_width == :auto ? TTY::Screen.width : max_table_width)
       end
 
+      if @title
+        expand_to(Unicode::DisplayWidth.of(@title) + total_column_padding + (@border == :blank ? 0 : 2))
+      end
+
       self
     end
 
@@ -433,8 +465,9 @@ module Tabulo
     #   The following options are the same as the keyword params for the {#initialize} method for
     #   {Table}: <tt>column_width</tt>, <tt>column_padding</tt>, <tt>formatter</tt>,
     #   <tt>header_frequency</tt>, <tt>row_divider_frequency</tt>, <tt>wrap_header_cells_to</tt>,
-    #   <tt>wrap_body_cells_to</tt>, <tt>border</tt>, <tt>border_styler</tt>, <tt>truncation_indicator</tt>,
-    #   <tt>align_header</tt>, <tt>align_body</tt>.
+    #   <tt>wrap_body_cells_to</tt>, <tt>border</tt>, <tt>border_styler</tt>, <tt>title</tt>,
+    #   <tt>title_styler</tt>, <tt>truncation_indicator</tt>, <tt>align_header</tt>, <tt>align_body</tt>,
+    #   <tt>align_title</tt>.
     #   These are applied in the same way as documented for {#initialize}, when
     #   creating the new, transposed Table. Any options not specified explicitly in the call to {#transpose}
     #   will inherit their values from the original {Table} (with the exception of settings
@@ -458,9 +491,9 @@ module Tabulo
     # @return [Table] a new {Table}
     # @raise [InvalidBorderError] if invalid argument passed to `border` parameter.
     def transpose(opts = {})
-      default_opts = [:align_body, :align_header, :border, :border_styler, :column_padding, :column_width,
-        :formatter, :header_frequency, :row_divider_frequency, :truncation_indicator, :wrap_body_cells_to,
-        :wrap_header_cells_to].map do |sym|
+      default_opts = [:align_body, :align_header, :align_title, :border, :border_styler, :column_padding,
+        :column_width, :formatter, :header_frequency, :row_divider_frequency, :title, :title_styler,
+        :truncation_indicator, :wrap_body_cells_to, :wrap_header_cells_to].map do |sym|
         [sym, instance_variable_get("@#{sym}")]
       end.to_h
 
@@ -496,7 +529,16 @@ module Tabulo
       cells = get_columns.map.with_index { |c, i| c.body_cell(source, row_index: index, column_index: i) }
       inner = format_row(cells, @wrap_body_cells_to)
 
-      if header == :top
+      if @title && header == :top
+        join_lines([
+          horizontal_rule(:title_top),
+          formatted_title,
+          horizontal_rule(:title_bottom),
+          formatted_header,
+          horizontal_rule(:middle),
+          inner
+        ].reject(&:empty?))
+      elsif header == :top
         join_lines([
           horizontal_rule(:top),
           formatted_header,
@@ -548,6 +590,44 @@ module Tabulo
       @column_registry[label] = column
     end
 
+    # @visibility private
+    def formatted_title
+      columns = get_columns
+      num_fudged_columns = columns.count - 1
+      basic_width = columns.inject(0) { |total_width, column| total_width + column.width }
+      extra_for_internal_dividers = (@border == :blank ? 0 : 1)
+      extra_for_internal_padding = @left_column_padding + @right_column_padding
+      extra_total = num_fudged_columns * (extra_for_internal_dividers + extra_for_internal_padding)
+      title_cell_width = basic_width + extra_total
+      styler =
+        if @title_styler
+          -> (v, s) { @title_styler.call(s) }
+        else
+          -> (v, s) { s }
+        end
+      title_cell = Cell.new(
+        alignment: @align_title,
+        cell_data: nil,
+        formatter: -> (s) { s },
+        padding_character: PADDING_CHARACTER,
+        styler: styler,
+        truncation_indicator: @truncation_indicator,
+        value: @title,
+        width: title_cell_width
+      )
+      cells = [title_cell]
+      max_cell_height = cells.map(&:height).max
+      row_height = ([nil, max_cell_height].compact.min || 1)
+      subcell_stacks = cells.map do |cell|
+        cell.padded_truncated_subcells(row_height, @left_column_padding, @right_column_padding)
+      end
+      subrows = subcell_stacks.transpose.map do |subrow_components|
+        @border_instance.join_cell_contents(subrow_components)
+      end
+
+      join_lines(subrows)
+    end
+
     # @!visibility private
     def normalize_column_label(label)
       case label
@@ -558,6 +638,25 @@ module Tabulo
       end
     end
 
+    # @!visibility private
+    def expand_to(min_table_width)
+      columns = get_columns
+      num_columns = columns.count
+      total_columns_width = columns.inject(0) { |sum, column| sum + column.width }
+      total_padding = num_columns * total_column_padding
+      total_borders = num_columns + 1
+      unadjusted_table_width = total_columns_width + total_padding + total_borders
+      required_increase = Util.max(min_table_width - unadjusted_table_width, 0)
+
+      required_increase.times do
+        narrowest_column = columns.inject(columns.first) do |narrowest, column|
+          column.width <= narrowest.width ? column : narrowest
+        end
+
+        narrowest_column.width += 1
+      end
+    end
+
     # @!visibility private
     def shrink_to(max_table_width)
       columns = get_columns

data/lib/tabulo/version.rb

@@ -1,3 +1,3 @@
 module Tabulo
-  VERSION = "2.4.1"
+  VERSION = "2.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tabulo
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.5.0
 platform: ruby
 authors:
 - Matthew Harvey
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-04-16 00:00:00.000000000 Z
+date: 2020-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-screen