tabulo 2.4.1 → 2.6.3

data/VERSION

@@ -1 +1 @@
-2.4.1
+2.6.3

data/lib/tabulo/border.rb

@@ -3,107 +3,62 @@ module Tabulo
   # @!visibility private
   class Border
 
+    Style = Struct.new(
+        :corner_top_left, :corner_top_right, :corner_bottom_right, :corner_bottom_left,
+        :edge_top, :edge_right, :edge_bottom, :edge_left,
+        :tee_top, :tee_right, :tee_bottom, :tee_left,
+        :divider_vertical, :divider_horizontal, :intersection)
+
     STYLES = {
-      ascii: {
-        corner_top_left: "+",
-        corner_top_right: "+",
-        corner_bottom_right: "+",
-        corner_bottom_left: "+",
-        edge_top: "-",
-        edge_right: "|",
-        edge_bottom: "-",
-        edge_left: "|",
-        tee_top: "+",
-        tee_right: "+",
-        tee_bottom: "+",
-        tee_left: "+",
-        divider_vertical: "|",
-        divider_horizontal: "-",
-        intersection: "+",
-      },
-      classic: {
-        corner_top_left: "+",
-        corner_top_right: "+",
-        edge_top: "-",
-        edge_right: "|",
-        edge_left: "|",
-        tee_top: "+",
-        tee_right: "+",
-        tee_left: "+",
-        divider_vertical: "|",
-        divider_horizontal: "-",
-        intersection: "+",
-      },
-      reduced_ascii: {
-        corner_top_left: "",
-        corner_top_right: "",
-        corner_bottom_right: "",
-        corner_bottom_left: "",
-        edge_top: "-",
-        edge_right: "",
-        edge_bottom: "-",
-        edge_left: "",
-        tee_top: " ",
-        tee_right: "",
-        tee_bottom: " ",
-        tee_left: "",
-        divider_vertical: " ",
-        divider_horizontal: "-",
-        intersection: " ",
-      },
-      reduced_modern: {
-        corner_top_left: "",
-        corner_top_right: "",
-        corner_bottom_right: "",
-        corner_bottom_left: "",
-        edge_top: "─",
-        edge_right: "",
-        edge_bottom: "─",
-        edge_left: "",
-        tee_top: " ",
-        tee_right: "",
-        tee_bottom: " ",
-        tee_left: "",
-        divider_vertical: " ",
-        divider_horizontal: "─",
-        intersection: " ",
-      },
-      markdown: {
-        corner_top_left: "",
-        corner_top_right: "",
-        corner_bottom_right: "",
-        corner_bottom_left: "",
-        edge_top: "",
-        edge_right: "|",
-        edge_bottom: "",
-        edge_left: "|",
-        tee_top: "",
-        tee_right: "|",
-        tee_bottom: "",
-        tee_left: "|",
-        divider_vertical: "|",
-        divider_horizontal: "-",
-        intersection: "|",
-      },
-      modern: {
-        corner_top_left: "┌",
-        corner_top_right: "┐",
-        corner_bottom_right: "┘",
-        corner_bottom_left: "└",
-        edge_top: "─",
-        edge_right: "│",
-        edge_bottom: "─",
-        edge_left: "│",
-        tee_top: "┬",
-        tee_right: "┤",
-        tee_bottom: "┴",
-        tee_left: "├",
-        divider_vertical: "│",
-        divider_horizontal: "─",
-        intersection: "┼",
-      },
-      blank: {
-      },
+      ascii:
+        Style.new(
+          "+", "+", "+", "+",
+          "-", "|", "-", "|",
+          "+", "+", "+", "+",
+          "|", "-", "+",
+        ),
+      classic:
+        Style.new(
+          "+", "+", "", "",
+          "-", "|", "", "|",
+          "+", "+", "", "+",
+          "|", "-", "+",
+        ),
+      reduced_ascii:
+        Style.new(
+          "", "", "", "",
+          "-", "", "-", "",
+          " ", "", " ", "",
+          " ", "-", " ",
+        ),
+      reduced_modern:
+        Style.new(
+          "", "", "", "",
+          "─", "", "─", "",
+          " ", "", " ", "",
+          " ", "─", " ",
+        ),
+      markdown:
+        Style.new(
+          "", "", "", "",
+          "", "|", "", "|",
+          "", "|", "", "|",
+          "|", "-", "|",
+        ),
+      modern:
+        Style.new(
+          "┌", "┐", "┘", "└",
+          "─", "│", "─", "│",
+          "┬", "┤", "┴", "├",
+          "│", "─", "┼",
+        ),
+      blank:
+        Style.new(
+          "", "", "", "",
+          "", "", "", "",
+          "", "", "", "",
+          "", "", "",
+        ),
     }
 
     # @!visibility private
@@ -115,6 +70,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 +82,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
 
@@ -138,7 +102,7 @@ module Tabulo
 
     def self.options(kind)
       opts = STYLES[kind]
-      return opts if opts
+      return opts.to_h if opts
       raise InvalidBorderError
     end
 

data/lib/tabulo/cell.rb

@@ -13,7 +13,9 @@ module Tabulo
       alignment:,
       cell_data:,
       formatter:,
+      left_padding:,
       padding_character:,
+      right_padding:,
       styler:,
       truncation_indicator:,
       value:,
@@ -21,8 +23,10 @@ module Tabulo
 
       @alignment = alignment
       @cell_data = cell_data
-      @padding_character = padding_character
       @formatter = formatter
+      @left_padding = left_padding
+      @padding_character = padding_character
+      @right_padding = right_padding
       @styler = styler
       @truncation_indicator = truncation_indicator
       @value = value
@@ -35,12 +39,12 @@ module Tabulo
     end
 
     # @!visibility private
-    def padded_truncated_subcells(target_height, padding_amount_left, padding_amount_right)
-      total_padding_amount = padding_amount_left + padding_amount_right
+    def padded_truncated_subcells(target_height)
+      total_padding_amount = @left_padding + @right_padding
       truncated = (height > target_height)
       (0...target_height).map do |subcell_index|
         append_truncator = (truncated && (total_padding_amount != 0) && (subcell_index + 1 == target_height))
-        padded_subcell(subcell_index, padding_amount_left, padding_amount_right, append_truncator)
+        padded_subcell(subcell_index, append_truncator)
       end
     end
 
@@ -60,8 +64,11 @@ module Tabulo
       end
     end
 
-    def apply_styler(content)
-      if @styler.arity == 3
+    def apply_styler(content, line_index)
+      case @styler.arity
+      when 4
+        @styler.call(@value, content, @cell_data, line_index)
+      when 3
         @styler.call(@value, content, @cell_data)
       else
         @styler.call(@value, content)
@@ -72,13 +79,13 @@ module Tabulo
       @subcells ||= calculate_subcells
     end
 
-    def padded_subcell(subcell_index, padding_amount_left, padding_amount_right, append_truncator)
-      lpad = @padding_character * padding_amount_left
+    def padded_subcell(subcell_index, append_truncator)
+      lpad = @padding_character * @left_padding
       rpad =
         if append_truncator
-          styled_truncation_indicator + padding(padding_amount_right - 1)
+          styled_truncation_indicator(subcell_index) + padding(@right_padding - 1)
         else
-          padding(padding_amount_right)
+          padding(@right_padding)
         end
       inner = subcell_index < height ? subcells[subcell_index] : padding(@width)
       "#{lpad}#{inner}#{rpad}"
@@ -88,31 +95,35 @@ module Tabulo
       @padding_character * amount
     end
 
-    def styled_truncation_indicator
-      apply_styler(@truncation_indicator)
+    def styled_truncation_indicator(line_index)
+      apply_styler(@truncation_indicator, line_index)
     end
 
     def calculate_subcells
-      formatted_content.split($/, -1).flat_map do |substr|
+      line_index = 0
+      formatted_content.split(Util::NEWLINE, -1).flat_map do |substr|
         subsubcells, subsubcell, subsubcell_width = [], String.new(""), 0
 
         substr.scan(/\X/).each do |grapheme_cluster|
           grapheme_cluster_width = Unicode::DisplayWidth.of(grapheme_cluster)
           if subsubcell_width + grapheme_cluster_width > @width
-            subsubcells << style_and_align_cell_content(subsubcell)
+            subsubcells << style_and_align_cell_content(subsubcell, line_index)
             subsubcell_width = 0
             subsubcell.clear
+            line_index += 1
           end
 
           subsubcell << grapheme_cluster
           subsubcell_width += grapheme_cluster_width
         end
 
-        subsubcells << style_and_align_cell_content(subsubcell)
+        subsubcells << style_and_align_cell_content(subsubcell, line_index)
+        line_index += 1
+        subsubcells
       end
     end
 
-    def style_and_align_cell_content(content)
+    def style_and_align_cell_content(content, line_index)
       padding = Util.max(@width - Unicode::DisplayWidth.of(content), 0)
       left_padding, right_padding =
         case real_alignment
@@ -125,7 +136,7 @@ module Tabulo
           [padding, 0]
         end
 
-      "#{' ' * left_padding}#{apply_styler(content)}#{' ' * right_padding}"
+      "#{' ' * left_padding}#{apply_styler(content, line_index)}#{' ' * right_padding}"
     end
 
     def real_alignment

data/lib/tabulo/column.rb

@@ -6,6 +6,8 @@ module Tabulo
     attr_accessor :width
     attr_reader :header
     attr_reader :index
+    attr_reader :left_padding
+    attr_reader :right_padding
 
     def initialize(
       align_body:,
@@ -15,7 +17,9 @@ module Tabulo
       header:,
       header_styler:,
       index:,
+      left_padding:,
       padding_character:,
+      right_padding:,
       styler:,
       truncation_indicator:,
       width:)
@@ -26,12 +30,19 @@ module Tabulo
       @formatter = formatter
       @header = header
       @index = index
+      @left_padding = left_padding
+      @right_padding = right_padding
 
       @header_styler =
-        if header_styler && (header_styler.arity == 2)
-          -> (_, str, cell_data) { header_styler.call(str, cell_data.column_index) }
-        elsif header_styler
-          -> (_, str) { header_styler.call(str) }
+        if header_styler
+          case header_styler.arity
+          when 3
+            -> (_, str, cell_data, line_index) { header_styler.call(str, cell_data.column_index, line_index) }
+          when 2
+            -> (_, str, cell_data) { header_styler.call(str, cell_data.column_index) }
+          else
+            -> (_, str) { header_styler.call(str) }
+          end
         else
           -> (_, str) { str }
         end
@@ -43,14 +54,16 @@ module Tabulo
     end
 
     def header_cell
-      if @header_styler.arity == 3
+      if @header_styler.arity >= 3
         cell_data = CellData.new(nil, nil, @index)
       end
       Cell.new(
         alignment: @align_header,
         cell_data: cell_data,
         formatter: -> (s) { s },
+        left_padding: @left_padding,
         padding_character: @padding_character,
+        right_padding: @right_padding,
         styler: @header_styler,
         truncation_indicator: @truncation_indicator,
         value: @header,
@@ -66,7 +79,9 @@ module Tabulo
         alignment: @align_body,
         cell_data: cell_data,
         formatter: @formatter,
+        left_padding: @left_padding,
         padding_character: @padding_character,
+        right_padding: @right_padding,
         styler: @styler,
         truncation_indicator: @truncation_indicator,
         value: body_cell_value(source, row_index: row_index, column_index: column_index),
@@ -82,6 +97,14 @@ module Tabulo
       end
     end
 
+    def padded_width
+      width + total_padding
+    end
+
+    def total_padding
+      @left_padding + @right_padding
+    end
+
     private
 
     def body_cell_data_required?

data/lib/tabulo/table.rb

@@ -35,21 +35,26 @@ module Tabulo
     #   be unique. Each element of the Array  will be used to create a column whose content is
     #   created by calling the corresponding method on each element of sources. Note
     #   the {#add_column} method is a much more flexible way to set up columns on the table.
-    # @param [:left, :right, :center, :auto] align_body (:auto) Determines the alignment of body cell
+    # @param [:left, :right, :center, :auto] align_body Determines the alignment of body cell
     #   (i.e. non-header) content within columns in this Table. Can be overridden for individual columns
     #   using the <tt>align_body</tt> option passed to {#add_column}. If passed <tt>:auto</tt>,
     #   alignment is determined by cell content, with numbers aligned right, booleans
     #   center-aligned, and other values left-aligned.
-    # @param [:left, :right, :center] align_header (:center) Determines the alignment of header text
+    # @param [:left, :right, :center] align_header 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 [:ascii, :markdown, :modern, :blank, nil] border (nil) Determines the characters used
+    # @param [:left, :right, :center] align_header Determines the alignment of the table
+    #   title, if present.
+    # @param [:ascii, :markdown, :modern, :blank, nil] border 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
@@ -58,7 +63,7 @@ module Tabulo
     #                       borders and intersection characters consisting of whitespace only
     #   - `:classic`        Like `:ascii`, but does not have a horizontal line at the bottom of the
     #                       table. This reproduces the default behaviour in `tabulo` v1.
-    # @param [nil, #to_proc] border_styler (nil) A lambda or other callable object taking
+    # @param [nil, #to_proc] border_styler A lambda or other callable object taking
     #   a single parameter, representing a section of the table's borders (which for this purpose
     #   include any horizontal and vertical lines inside the table), and returning a string.
     #   If passed <tt>nil</tt>, then no additional styling will be applied to borders. If passed a
@@ -67,28 +72,54 @@ module Tabulo
     #   <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
+    # @param [nil, Integer, Array] column_padding 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
+    # @param [nil, #to_proc] formatter The default formatter for columns in this
     #   table. See `formatter` option of {#add_column} for details.
     # @param [:start, nil, Integer] header_frequency (:start) Controls the display of column headers.
     #   If passed <tt>:start</tt>, headers will be shown at the top of the table only. If passed <tt>nil</tt>,
     #   headers will not be shown. If passed an Integer N (> 0), headers will be shown at the top of the table,
     #   then repeated every N rows.
-    # @param [nil, #to_proc] header_styler (nil) The default header styler for columns in this
+    # @param [nil, #to_proc] header_styler The default header styler for columns in this
     #   table. See `header_styler` option of {#add_column} for details.
-    # @param [nil, Integer] row_divider_frequency (nil) Controls the display of horizontal row dividers within
+    # @param [nil, Integer] row_divider_frequency Controls the display of horizontal row dividers within
     #   the table body. If passed <tt>nil</tt>, dividers will not be shown. If passed an Integer N (> 0),
     #   dividers will be shown after every N rows. The characters used to form the dividers are
     #   determined by the `border` option, and are the same as those used to form the bottom edge of the
     #   header row.
-    # @param [nil, #to_proc] styler (nil) The default styler for columns in this table. See `styler`
+    # @param [nil, #to_proc] styler The default styler for columns in this table. See `styler`
     #   option of {#add_column} for details.
+    # @param [nil, String] title 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 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
@@ -149,24 +184,24 @@ module Tabulo
     #   a method to be called on each item in the table sources to provide the content
     #   for this column. If a String is passed as the label, then it will be converted to
     #   a Symbol for the purpose of serving as this label.
-    # @param [:left, :center, :right, :auto, nil] align_body (nil) Specifies how the cell body contents
+    # @param [:left, :center, :right, :auto, nil] align_body Specifies how the cell body contents
     #   should be aligned. If <tt>nil</tt> is passed, then the alignment is determined
     #   by the Table-level setting passed to the <tt>align_body</tt> option on Table initialization
     #   (which itself defaults to <tt>:auto</tt>). Otherwise this option determines the alignment of
     #   this column. If <tt>:auto</tt> is passed, the alignment is determined by the type of the cell
     #   value, with numbers aligned right, booleans center-aligned, and other values left-aligned.
     #   Note header text alignment is configured separately using the :align_header param.
-    # @param [:left, :center, :right, nil] align_header (nil) Specifies how the header text
+    # @param [:left, :center, :right, nil] align_header Specifies how the header text
     #   should be aligned. If <tt>nil</tt> is passed, then the alignment is determined
     #   by the Table-level setting passed to the <tt>align_header</tt> (which itself defaults
     #   to <tt>:center</tt>). Otherwise, this option determines the alignment of the header
     #   content for this column.
-    # @param [Symbol, String, Integer, nil] before (nil) The label of the column before (i.e. to
+    # @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 [#to_proc] formatter (nil) A lambda or other callable object that
+    # @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).
     #   For example, if the extractor for this column generates a Date, then the formatter might format
@@ -184,11 +219,11 @@ module Tabulo
     #     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,
+    # @param [nil, #to_s] header 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 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 either 1 or 2 parameters:
+    #   <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
@@ -205,10 +240,23 @@ module Tabulo
     #       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 determine
+    # @param [nil, Integer, Array] padding 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 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
@@ -231,10 +279,16 @@ module Tabulo
     #       {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
     #   <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
+    # @param [Integer] width 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}
@@ -251,10 +305,17 @@ module Tabulo
     #   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
@@ -267,7 +328,9 @@ module Tabulo
         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,
@@ -309,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
@@ -339,7 +402,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 +412,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
+    #   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:
@@ -364,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
@@ -382,7 +451,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 (:auto) With no args, or if passed <tt>:auto</tt>,
+    # @param [nil, 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.
@@ -397,18 +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_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 = wrapped_width(cell.formatted_content)
+          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
@@ -433,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
@@ -444,13 +523,13 @@ module Tabulo
     #   new Table, which contains the names of "fields" (corresponding to the original Table's
     #   column headings). If this is not provided, then by default this column will be made just
     #   wide enough to accommodate its contents.
-    # @option opts [String] :field_names_header ("") By default the left-most column will have a
+    # @option opts [String] :field_names_header By default the left-most column will have a
     #   blank header; but this can be overridden by passing a String to this option.
-    # @option opts [:left, :center, :right] :field_names_header_alignment (:right) Specifies how the
+    # @option opts [:left, :center, :right] :field_names_header_alignment Specifies how the
     #   header text of the left-most column (if it has header text) should be aligned.
-    # @option opts [:left, :center, :right] :field_names_body_alignment (:right) Specifies how the
+    # @option opts [:left, :center, :right] :field_names_body_alignment Specifies how the
     #   body text of the left-most column should be aligned.
-    # @option opts [#to_proc] :headers (:to_s.to_proc) A lambda or other callable object that
+    # @option opts [#to_proc] :headers A lambda or other callable object that
     #   will be passed in turn each of the elements of the current Table's <tt>sources</tt>
     #   Enumerable, to determine the text to be displayed in the header of each column of the
     #   new Table (other than the left-most column's header, which is determined as described
@@ -458,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
 
@@ -496,25 +575,15 @@ 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
-        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
@@ -548,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
@@ -558,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.
@@ -582,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.
@@ -604,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
@@ -633,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