tabulo 2.3.3 → 2.6.1

data/lib/tabulo/row.rb

@@ -7,11 +7,12 @@ module Tabulo
     attr_reader :source
 
     # @!visibility private
-    def initialize(table, source, divider: false, header: :top)
+    def initialize(table, source, divider:, header:, index:)
       @table = table
       @source = source
       @divider = divider
       @header = header
+      @index = index
     end
 
     # Calls the given block once for each {Cell} in the {Row}, passing that {Cell} as parameter.
@@ -23,8 +24,8 @@ module Tabulo
     #     puts cell.value   # => 1,       => false
     #   end
     def each
-      @table.column_registry.each do |_, column|
-        yield column.body_cell(@source)
+      @table.column_registry.each_with_index do |(_, column), column_index|
+        yield column.body_cell(@source, row_index: @index, column_index: column_index)
       end
     end
 
@@ -34,7 +35,7 @@ module Tabulo
     #   and divider frequency).
     def to_s
       if @table.column_registry.any?
-        @table.formatted_body_row(@source, header: @header, divider: @divider)
+        @table.formatted_body_row(@source, divider: @divider, header: @header, index: @index)
       else
         ""
       end
@@ -42,7 +43,9 @@ module Tabulo
 
     # @return a Hash representation of the {Row}, with column labels acting as keys and the {Cell}s the values.
     def to_h
-      @table.column_registry.map { |label, column| [label, column.body_cell(@source)] }.to_h
+      @table.column_registry.map.with_index do |(label, column), column_index|
+        [label, column.body_cell(@source, row_index: @index, column_index: column_index)]
+      end.to_h
     end
   end
 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
@@ -64,14 +69,15 @@ module Tabulo
     #   If passed <tt>nil</tt>, then no additional styling will be applied to borders. If passed a
     #   callable, then that callable will be called for each border section, with the
     #   resulting string rendered in place of that border. The extra width of the string returned by the
-    #   {border_styler} is not taken into consideration by the internal table rendering calculations
+    #   <tt>border_styler</tt> is not taken into consideration by the internal table rendering calculations
     #   Thus it can be used to apply ANSI escape codes to border characters, to colour the borders
     #   for example, without breaking the table formatting.
     # @param [nil, Integer, Array] column_padding (1) Determines the amount of blank space with which to pad
     #   either side of each column. If passed an Integer, then the given amount of padding is
     #   applied to each side of each column. If passed a two-element Array, then the first element of the
     #   Array indicates the amount of padding to apply to the left of each column, and the second
-    #   element indicates the amount to apply to the right.
+    #   element indicates the amount to apply to the right. This setting can be overridden for
+    #   individual columns using the `padding` option of {#add_column}.
     # @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 [nil, #to_proc] formatter (:to_s.to_proc) The default formatter for columns in this
@@ -89,6 +95,31 @@ 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. Can be passed
+    #   <tt>nil</tt>, or can be passed a callable that takes either 1 or 2 parametes:
+    #   * If passed <tt>nil</tt>, then no additional styling will be applied to the title.
+    #   * If passed a callable, then that callable will be called for each line of
+    #     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 and cell width calculations involved in rendering the
+    #     table. Thus it can be used to apply ANSI escape codes to title content, to color the
+    #     content for example, without breaking the table formatting.
+    #     * If the passed callable takes 1 parameter, then the first parameter is a string
+    #       representing a single line within the title. For example, if the title
+    #       is wrapped over three lines, then the <tt>title_styler</tt> will be called
+    #       three times, once for each line of content.
+    #     * If the passed callable takes 2 parameters, then the first parameter is as above, and the
+    #       second parameter is an Integer representing the index of the line within the
+    #       title that is currently being styled. For example, if the title is wrapped over 3
+    #       lines, then the callable will be called first with a line index of 0, to style the first line,
+    #       then with a line index of 1, to style the second line, and finally with a line index of 2, for
+    #       the third and final wrapped line of the cell.
+    #
     # @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,22 +138,24 @@ 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)
       @column_padding = (column_padding || DEFAULT_COLUMN_PADDING)
 
       @left_column_padding, @right_column_padding =
-        Array === @column_padding ? @column_padding : [@column_padding, @column_padding]
+        (Array === @column_padding ? @column_padding : [@column_padding, @column_padding])
 
       @column_width = (column_width || DEFAULT_COLUMN_WIDTH)
       @formatter = formatter
@@ -130,6 +163,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
@@ -168,56 +203,119 @@ module Tabulo
     #   in either String or Symbol form for this purpose.
     # @param [#to_proc] formatter (nil) 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 (see below). For example, if the extractor for this column
-    #   generates a Date, then the formatter might format that Date in a particular way.
-    #   If no formatter is provided, then the callable that was passed to the `formatter` option
-    #   of the table itself on its creation (see {#initialize}) (which itself defaults to
-    #   `:to_s.to_proc`), will be used as the formatter for the column.
+    #   is distinct from the extractor and the styler (see below).
+    #   For example, if the extractor for this column generates a Date, then the formatter might format
+    #   that Date in a particular way.
+    #   * If <tt>nil</tt> is provided, then the callable that was passed to the `formatter` option
+    #    of the table itself on its creation (see {#initialize}) (which itself defaults to
+    #    `:to_s.to_proc`), will be used as the formatter for the column.
+    #   * If a 1-parameter callable is passed, then this callable will be called with the calculated
+    #     value of the cell; it should then return a String, and this String will be displayed as
+    #     the formatted value of the cell.
+    #   * If a 2-parameter callable is passed, then the first parameter represents the calculated
+    #     value of the cell, and the second parameter is a {CellData} instance, containing
+    #     additional information about the cell that may be relevant to what formatting should
+    #     be applied. For example, the {CellData#row_index} attribute can be inspected to determine
+    #     whether the {Cell} is an odd- or even-numbered {Row}, to arrange for different formatting
+    #     to be applied to alternating rows.
+    #     See the documentation for {CellData} for more.
     # @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 [nil, #to_proc] header_styler (nil) A lambda or other callable object taking
-    #   a single parameter, representing a single line of within the header content for
-    #   this column. For example, if the header cell content is wrapped over three lines, then
-    #   the {header_styler} will be called once for each line. If passed <tt>nil</tt>, then
-    #   no additional styling will be applied to the header cell content. If passed a callable,
-    #   then that callable will be called for each line of content within the header cell, and the
-    #   resulting string rendered in place of that line. The extra width of the string returned by the
-    #   {header_styler} is not taken into consideration by the internal table and
-    #   cell width calculations involved in rendering the table. Thus it can be used to apply
-    #   ANSI escape codes to header cell content, to colour the cell content for example, without
-    #   breaking the table formatting.
-    #   Note that if the header content is truncated, then any {header_styler} will be applied to the
+    # @param [nil, #to_proc] header_styler (nil) A lambda or other callable object that will
+    #   determine the colors or other styling applied to the header content. Can be passed
+    #   <tt>nil</tt>, or can be passed a callable that takes 1, 2 or 3 parameters:
+    #   * If passed <tt>nil</tt>, then no additional styling will be applied to the cell content
+    #     (other than what was already applied by the <tt>formatter</tt>).
+    #   * If passed a callable, then that callable will be called for each line of content within
+    #     the header cell, and the resulting string rendered in place of that line.
+    #     The extra width of the string returned by the <tt>header_styler</tt> is not taken into
+    #     consideration by the internal table and cell width calculations involved in rendering the
+    #     table. Thus it can be used to apply ANSI escape codes to header cell content, to color the
+    #     cell content for example, without breaking the table formatting.
+    #     * If the passed callable takes 1 parameter, then the first parameter is a string
+    #       representing a single formatted line within the header cell. For example, if the header
+    #       cell content is wrapped over three lines, then the <tt>header_styler</tt> will be called
+    #       three times for that header cell, once for each line of content.
+    #     * If the passed callable takes 2 parameters, then the first parameter is as above, and the
+    #       second parameter is an Integer representing the positional index of this header's {Column},
+    #       with the leftmost column having index 0, the next having index 1 etc.. This can be
+    #       used, for example, to apply different styles to alternating {Column}s.
+    #     * If the passed callable takes 3 parameters, then the first and second parameters are as above,
+    #       and the third parameter is an Integer representing the index of the line within the
+    #       header cell that is currently being styled. For example, if the cell content is wrapped over 3
+    #       lines, then the callable will be called first with a line index of 0, to style the first line,
+    #       then with a line index of 1, to style the second line, and finally with a line index of 2, for
+    #       the third and final wrapped line of the cell.
+    #
+    #   Note that if the header content is truncated, then any <tt>header_styler</tt> will be applied to the
     #   truncation indicator character as well as to the truncated content.
-    # @param [nil, #to_proc] styler (nil) A lambda or other callable object that will be passed
-    #   two arguments: the calculated value of the cell (prior to the {formatter} being applied);
-    #   and a string representing a single formatted line within the cell. For example, if the
-    #   cell content is wrapped over three lines, then for that cell, the {styler} will be called
-    #   three times, once for each line of content within the cell. If passed <tt>nil</tt>, then
-    #   no additional styling will be applied to the cell content (other than what was already
-    #   applied by the {formatter}). If passed a callable, then that callable will be called for
-    #   each line of content within the cell, and the resulting string rendered in place of that
-    #   line. The {styler} option differs from the {formatter} option in that the extra width of the
-    #   string returned by {styler} is not taken into consideration by the internal table and
-    #   cell width calculations involved in rendering the table. Thus it can be used to apply
-    #   ANSI escape codes to cell content, to colour the cell content for example, without
-    #   breaking the table formatting.
+    # @param [nil, Integer, Array] padding (nil) Determines the amount of blank space with which to
+    #   pad either side of the column. If passed nil, then the `column_padding` setting of the
+    #   {Table} will determine the column's padding. (See {#initialize}.) Otherwise, this option
+    #   overrides, for this column, the `column_padding` that was set at the table level: if passed an Integer,
+    #   then the given amount of padding is applied to either side of the column; or if passed a two-element Array,
+    #   then the first element of the Array indicates the amount of padding to apply to the left of the column,
+    #   and the second element indicates the amount to apply to the right.
+    # @param [nil, #to_proc] styler (nil) A lambda or other callable object that will determine
+    #   the colors or other styling applied to the formatted value of the cell. Can be passed
+    #   <tt>nil</tt>, or can be passed a callable that takes either 2 or 3 parameters:
+    #   * If passed <tt>nil</tt>, then no additional styling will be applied to the cell content
+    #     (other than what was already applied by the <tt>formatter</tt>).
+    #   * If passed a callable, then that callable will be called for each line of content within
+    #     the cell, and the resulting string rendered in place of that line.
+    #     The <tt>styler</tt> option differs from the <tt>formatter</tt> option in that the extra width of the
+    #     string returned by <tt>styler</tt> is not taken into consideration by the internal table and
+    #     cell width calculations involved in rendering the table. Thus it can be used to apply
+    #     ANSI escape codes to cell content, to color the cell content for example, without
+    #     breaking the table formatting.
+    #     * If the passed callable takes 2 parameters, then the first parameter is the calculated
+    #       value of the cell (prior to the <tt>formatter</tt> being applied); and the second parameter is
+    #       a string representing a single formatted line within the cell. For example, if the cell
+    #       content is wrapped over three lines, then for that cell, the <tt>styler</tt> will be called
+    #       three times, once for each line of content within the cell.
+    #     * If the passed callable takes 3 parameters, then the first two parameters are as above,
+    #       and the third parameter is a {CellData} instance, containing additional information
+    #       about the cell that may be relevant to what styles should be applied. For example, the
+    #       {CellData#row_index} attribute can be inspected to determine whether the {Cell} is an
+    #       odd- or even-numbered {Row}, to arrange for different styling to be applied to
+    #       alternating rows. See the documentation for {CellData} for more.
+    #     * If the passed callable takes 4 parameters, then the first three parameters are as above,
+    #       and the fourth parameter is an Integer representing the index of the line within the
+    #       cell that is currently being styled. For example, if the cell content is wrapped over 3
+    #       lines, then the callable will be called first with a line index of 0, to style the first
+    #       line, then with a line index of 1, to style the second line, and finally with a line
+    #       index of 2, to style the third and final wrapped line of the cell.
+    #
     #   Note that if the content of a cell is truncated, then the whatever styling is applied by the
-    #   {styler} to the cell content will also be applied to the truncation indicator character.
+    #   <tt>styler</tt> to the cell content will also be applied to the truncation indicator character.
     # @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.
-    # @param [#to_proc] extractor A block or other callable
-    #   that will be passed each of the Table sources to determine the value in each cell of this
-    #   column. If this is not provided, then the column label will be treated as a method to be
-    #   called on each source item to determine each cell's value.
+    # @param [#to_proc] extractor A block or other callable that will be passed each of the {Table}
+    #   sources to determine the value in each cell of this column.
+    #   * If this is not provided, then the column label will be treated as a method to be called on
+    #     each source item to determine each cell's value.
+    #   * If provided a single-parameter callable, then this callable will be passed each of the
+    #     {Table} sources to determine the cell value for each row in this column.
+    #   * If provided a 2-parameter callable, then for each of the {Table} sources, this callable
+    #     will be passed the source, and the row index, to determine the cell value for that row.
+    #     For this purpose, the first body row (not counting the header row) has an index of 0,
+    #     the next an index of 1, etc..
     # @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, align_body: nil, align_header: nil, before: nil, formatter: nil,
-      header: nil, header_styler: nil, styler: nil, width: nil, &extractor)
+      header: nil, header_styler: nil, padding: nil, styler: nil, width: nil, &extractor)
 
       column_label = normalize_column_label(label)
 
+      left_padding, right_padding =
+        if padding
+          Array === padding ? padding : [padding, padding]
+        else
+          [@left_column_padding, @right_column_padding]
+        end
+
       if column_registry.include?(column_label)
         raise InvalidColumnLabelError, "Column label already used in this table."
       end
@@ -229,7 +327,10 @@ module Tabulo
         formatter: formatter || @formatter,
         header: (header || label).to_s,
         header_styler: header_styler || @header_styler,
+        index: column_registry.count,
+        left_padding: left_padding,
         padding_character: PADDING_CHARACTER,
+        right_padding: right_padding,
         styler: styler || @styler,
         truncation_indicator: @truncation_indicator,
         width: width || @column_width,
@@ -271,7 +372,7 @@ module Tabulo
       if column_registry.any?
         bottom_edge = horizontal_rule(:bottom)
         rows = map(&:to_s)
-        bottom_edge.empty? ? join_lines(rows) : join_lines(rows + [bottom_edge])
+        bottom_edge.empty? ? Util.join_lines(rows) : Util.join_lines(rows + [bottom_edge])
       else
         ""
       end
@@ -297,24 +398,28 @@ module Tabulo
 
         show_divider = @row_divider_frequency && (index != 0) && Util.divides?(@row_divider_frequency, index)
 
-        yield Row.new(self, source, header: header, divider: show_divider)
+        yield Row.new(self, source, header: header, divider: show_divider, index: index)
       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)
     end
 
-    # @param [:top, :middle, :bottom] align_body (: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.
+    # Produce a horizontal dividing line suitable for printing at the top, bottom or middle
+    # of the table.
+    #
+    # @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 suitable for printing at the top, bottom or middle of the
-    #   table.
-    # @example Print a horizontal divider between each pair of rows, and again
-    #   at the bottom:
+    #   dividing line.
+    # @example Print a horizontal divider between each pair of rows, and again at the bottom:
     #
     #   table.each_with_index do |row, i|
     #     puts table.horizontal_rule(:middle) unless i == 0
@@ -325,14 +430,17 @@ module Tabulo
     # It may be that `:top`, `:middle` and `:bottom` all look the same. Whether
     # this is the case depends on the characters used for the table border.
     def horizontal_rule(position = :bottom)
-      column_widths = get_columns.map { |column| column.width + total_column_padding }
+      column_widths = get_columns.map { |column| column.width + column.total_padding }
       @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
@@ -358,17 +466,27 @@ module Tabulo
     #   Table will refuse to shrink itself.
     # @return [Table] the Table itself
     def pack(max_table_width: :auto)
-      get_columns.each { |column| column.width = wrapped_width(column.header) }
+      get_columns.each { |column| column.width = Util.wrapped_width(column.header) }
 
-      @sources.each do |source|
-        get_columns.each do |column|
-          cell_width = wrapped_width(column.body_cell(source).formatted_content)
+      @sources.each_with_index do |source, row_index|
+        get_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
 
-      if max_table_width
-        shrink_to(max_table_width == :auto ? TTY::Screen.width : max_table_width)
+      shrink_to(max_table_width == :auto ? TTY::Screen.width : max_table_width) if max_table_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
+        )
       end
 
       self
@@ -393,8 +511,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
@@ -418,9 +537,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
 
@@ -445,36 +564,26 @@ module Tabulo
         # Add a column to the new table for each of the original table's sources
         sources.each_with_index do |source, i|
           t.add_column(i, header: extra_opts[:headers].call(source)) do |original_column|
-            original_column.body_cell_value(source)
+            original_column.body_cell_value(source, row_index: i, column_index: original_column.index)
           end
         end
       end
     end
 
     # @!visibility private
-    def formatted_body_row(source, header:, divider:)
-      cells = get_columns.map { |column| column.body_cell(source) }
+    def formatted_body_row(source, header:, divider:, index:)
+      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
-        join_lines([
-          horizontal_rule(:top),
-          formatted_header,
-          horizontal_rule(:middle),
-          inner
-        ].reject(&:empty?))
+      if @title && header == :top
+        Util.condense_lines([horizontal_rule(:title_top), formatted_title, horizontal_rule(:title_bottom),
+          formatted_header, horizontal_rule(:middle), inner])
+      elsif header == :top
+        Util.condense_lines([horizontal_rule(:top), formatted_header, horizontal_rule(:middle), inner])
       elsif header
-        join_lines([
-          horizontal_rule(:middle),
-          formatted_header,
-          horizontal_rule(:middle),
-          inner
-        ].reject(&:empty?))
+        Util.condense_lines([horizontal_rule(:middle), formatted_header, horizontal_rule(:middle), inner])
       elsif divider
-        join_lines([
-          horizontal_rule(:middle),
-          inner
-        ].reject(&:empty?))
+        Util.condense_lines([horizontal_rule(:middle), inner])
       else
         inner
       end
@@ -508,6 +617,55 @@ module Tabulo
       @column_registry[label] = column
     end
 
+    # @visibility private
+    def formatted_title
+      columns = get_columns
+
+      extra_for_internal_dividers = (@border == :blank ? 0 : 1)
+
+      title_cell_width = columns.inject(0) do |total_width, column|
+        total_width + column.padded_width + extra_for_internal_dividers
+      end
+
+      title_cell_width -= (columns.first.left_padding + columns.last.right_padding + extra_for_internal_dividers)
+
+      styler =
+        if @title_styler
+          case @title_styler.arity
+          when 1
+            -> (_val, str) { @title_styler.call(str) }
+          when 2
+            -> (_val, str, _cell_data, line_index) { @title_styler.call(str, line_index) }
+          end
+        else
+          -> (_val, str) { str }
+        end
+
+      title_cell = Cell.new(
+        alignment: @align_title,
+        cell_data: nil,
+        formatter: -> (s) { s },
+        left_padding: columns.first.left_padding,
+        padding_character: PADDING_CHARACTER,
+        right_padding: columns.last.right_padding,
+        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)
+      end
+      subrows = subcell_stacks.transpose.map do |subrow_components|
+        @border_instance.join_cell_contents(subrow_components)
+      end
+
+      Util.join_lines(subrows)
+    end
+
     # @!visibility private
     def normalize_column_label(label)
       case label
@@ -518,14 +676,32 @@ module Tabulo
       end
     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)
+
+      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
       num_columns = columns.count
-      total_columns_width = columns.inject(0) { |sum, column| sum + column.width }
-      total_padding = num_columns * total_column_padding
+      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_width + total_padding + total_borders
+      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.
@@ -542,11 +718,6 @@ module Tabulo
       end
     end
 
-    # @!visibility private
-    def total_column_padding
-      @left_column_padding + @right_column_padding
-    end
-
     # @!visibility private
     #
     # Formats a single header row or body row as a String.
@@ -564,18 +735,13 @@ module Tabulo
       max_cell_height = cells.map(&:height).max
       row_height = ([wrap_cells_to, max_cell_height].compact.min || 1)
       subcell_stacks = cells.map do |cell|
-        cell.padded_truncated_subcells(row_height, @left_column_padding, @right_column_padding)
+        cell.padded_truncated_subcells(row_height)
       end
       subrows = subcell_stacks.transpose.map do |subrow_components|
         @border_instance.join_cell_contents(subrow_components)
       end
 
-      join_lines(subrows)
-    end
-
-    # @!visibility private
-    def join_lines(lines)
-      lines.join($/)  # join strings with cross-platform newline
+      Util.join_lines(subrows)
     end
 
     # @!visibility private
@@ -593,13 +759,5 @@ module Tabulo
       c
     end
 
-    # @!visibility private
-    # @return [Integer] the length of the longest segment of str when split by newlines
-    def wrapped_width(str)
-      segments = str.split($/)
-      segments.inject(1) do |longest_length_so_far, segment|
-        Util.max(longest_length_so_far, Unicode::DisplayWidth.of(segment))
-      end
-    end
   end
 end