natty-ui 0.34.0 → 1.0.2

data/lib/natty-ui/helper/table.rb

@@ -0,0 +1,1376 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module NattyUI
+  # Data structure for building terminal tables.
+  #
+  # A `Table` is populated through its {#rows} and {#columns} collections and
+  # then passed to {Features#table} for rendering.  Cells accept text and
+  # formatting attributes; rows and columns can carry default attributes that
+  # are merged with individual cell attributes during rendering.
+  #
+  # @example Build and render a simple table
+  #   ui.table border_frame: :double do |t|
+  #     t.add_row '[b]Name', '[b]Score', align: :center
+  #     t.add_row 'Alice', 42
+  #     t.add_row 'Bob',   17
+  #   end
+  #
+  # @example Access cells by row and column index
+  #   ui.table do |t|
+  #     t[0, 0] = 'Header'
+  #     t[1, 0] = 'Row 1'
+  #   end
+  class Table
+    # A single cell in a {Table}.
+    #
+    # Cells are created implicitly when rows are populated via {Row#add},
+    # {Row#add_text}, {Row#fill}, and similar helpers.  Each cell holds
+    # {#text} content and a set of {#attributes} that control its layout.
+    class Cell
+      # Formatting attributes for a {Cell}, {Row}, or {Column}.
+      #
+      # An `Attributes` instance is exposed on each {Cell} (via {Cell#attributes}),
+      # each {Row} (via {Row#attributes}), and each {Column} (via
+      # {Column#attributes}).  Attributes set on a row or column serve as
+      # defaults that are merged with individual cell attributes during rendering.
+      #
+      # @example Set alignment on a cell
+      #   cell.attributes.align = :center
+      #
+      # @example Set padding via the bulk helper
+      #   cell.attributes.assign(padding: [1, 2], vertical: :middle)
+      class Attributes
+        # Whether line breaks inside the text are collapsed to spaces.
+        #
+        # @return [Boolean]
+        attr_reader :eol
+
+        # @attribute [w] eol
+        # @param value [Boolean]
+        def eol=(value)
+          @eol = value ? true : false
+        end
+
+        # Whether whitespace are preserved.
+        #
+        # @return [Boolean]
+        attr_reader :spaces
+
+        # @attribute [w] spaces
+        # @param value [Boolean]
+        def spaces=(value)
+          @spaces = value ? true : false
+        end
+
+        # Horizontal text alignment within the cell.
+        #
+        # @return [:left, :center, :right, nil]
+        attr_reader :align
+
+        # @attribute [w] align
+        # @param value [:left, :center, :right, nil]
+        # @raise [ArgumentError] if value is not one of the accepted symbols
+        def align=(value)
+          return @align = value if ALIGN_VALUES.include?(value)
+          raise(ArgumentError, "value must be one of #{ALIGN_VALUES.inspect}")
+        end
+
+        # Vertical text alignment within the cell.
+        #
+        # @return [:top, :middle, :bottom, nil]
+        attr_reader :vertical
+
+        # @attribute [w] vertical
+        # @param value [:top, :middle, :bottom, nil]
+        # @raise [ArgumentError] if value is not one of the accepted symbols
+        def vertical=(value)
+          return @vertical = value if VERTICAL_VALUES.include?(value)
+          raise(
+            ArgumentError,
+            "value must be one of #{VERTICAL_VALUES.inspect}"
+          )
+        end
+
+        # Minimum column width in characters for this cell.
+        #
+        # @return [Integer, Float, nil]
+        attr_reader :min_width
+
+        # @attribute [w] min_width
+        # @param value [Integer, Float, nil]
+        # @raise [ArgumentError] if value is not `Integer`, `Float`, or `nil`
+        def min_width=(value)
+          case value
+          when nil
+            @min_width = nil
+          when Integer, Float
+            value = [0, value].max
+            @min_width = @max_width ? [value, @max_width].min : value
+          else
+            raise(ArgumentError, 'value must be an Integer, Float or nil')
+          end
+        end
+
+        # Maximum column width in characters for this cell.
+        #
+        # @return [Integer, Float, nil]
+        attr_reader :max_width
+
+        # @attribute [w] max_width
+        # @param value [Integer, Float, nil]
+        # @raise [ArgumentError] if value is not `Integer`, `Float`, or `nil`
+        def max_width=(value)
+          case value
+          when nil
+            @max_width = nil
+          when Integer, Float
+            value = [0, value].max
+            @max_width = @min_width ? [@min_width, value].max : value
+          else
+            raise(ArgumentError, 'value must be an Integer, Float or nil')
+          end
+        end
+
+        # Width constraint for this cell.
+        #
+        # Returns an exact `Integer` or `Float` when `min_width` equals
+        # `max_width`, a `Range` when they differ, or `nil` when neither is set.
+        #
+        # @example
+        #   cell.attributes.width   # => nil, Integer, Float, or Range
+        #
+        # @example Set exact width
+        #   cell.attributes.width = 20
+        #
+        # @example Set width range
+        #   cell.attributes.width = (10..30)
+        #
+        # @attribute [r] width
+        # @return [Integer, Float, Range, nil]
+        def width
+          return @min_width if @min_width == @max_width
+          (@min_width..@max_width) if @min_width || @max_width
+        end
+
+        # @attribute [w] width
+        # @param value [Integer, Float, Range, nil]
+        #   - `Integer` or `Float` — sets an exact width
+        #   - `Range` — bounds must be `Integer` or `Float`; an open end means
+        #     no constraint on that side
+        #   - `nil` — clears both constraints
+        # @raise [ArgumentError] if value is not one of the accepted types
+        def width=(value)
+          case value
+          when nil
+            @min_width = @max_width = nil
+          when Integer, Float
+            @min_width = @max_width = [0, value].max
+          when Range
+            b = value.begin
+            e = value.end
+
+            if Integer === b || Float === b
+              @min_width = [0, b].max
+              return @max_width = @min_width if b == e
+              return @max_width = e && @min_width < e ? e : nil
+            end
+
+            if Integer === e || Float === e
+              @max_width = [0, e].max
+              return @min_width = nil
+            end
+
+            raise(
+              ArgumentError,
+              'value can only be a range of Integer or Float'
+            )
+          else
+            raise(ArgumentError, 'value must be an Integer, Range or nil')
+          end
+        end
+
+        # Minimum row height in lines for this cell.
+        #
+        # @return [Integer, nil]
+        attr_reader :min_height
+
+        # @attribute [w] min_height
+        # @param value [Integer, Float, nil]
+        #   `Float` is rounded to the nearest integer
+        # @raise [ArgumentError] if value is not `Integer`, `Float`, or `nil`
+        def min_height=(value)
+          case value
+          when nil
+            @min_height = nil
+          when Integer, Float
+            value = [0, value.round].max
+            @min_height = @max_height ? [value, @max_height].min : value
+          else
+            raise(ArgumentError, 'value must be an Integer, Float or nil')
+          end
+        end
+
+        # Maximum row height in lines for this cell.
+        #
+        # @return [Integer, nil]
+        attr_reader :max_height
+
+        # @attribute [w] max_height
+        # @param value [Integer, Float, nil]
+        #   `Float` is rounded to the nearest integer
+        # @raise [ArgumentError] if value is not `Integer`, `Float`, or `nil`
+        def max_height=(value)
+          case value
+          when nil
+            @max_height = nil
+          when Integer, Float
+            value = [0, value.round].max
+            @max_height = @min_height ? [@min_height, value].max : value
+          else
+            raise(ArgumentError, 'value must be an Integer, Float or nil')
+          end
+        end
+
+        # Height constraint for this cell.
+        #
+        # Returns an exact `Integer` when both bounds are equal, a `Range` when
+        # they differ, or `nil` when neither is set.
+        #
+        # @example
+        #   cell.attributes.height   # => nil, Integer, or Range
+        #
+        # @example Set exact height
+        #   cell.attributes.height = 3
+        #
+        # @example Set height range
+        #   cell.attributes.height = (2..5)
+        #
+        # @attribute [r] height
+        # @return [Integer, Range, nil]
+        def height
+          return @min_height if @min_height == @max_height
+          (@min_height..@max_height) if @min_height || @max_height
+        end
+
+        # @attribute [w] height
+        # @param value [Integer, Range, nil]
+        #   - `Integer` — sets an exact height
+        #   - `Range` — bounds must be `Integer` or `Float` (floats are rounded)
+        #   - `nil` — clears both constraints
+        # @raise [ArgumentError] if value is not one of the accepted types
+        def height=(value)
+          case value
+          when nil
+            @min_height = @max_height = nil
+          when Integer
+            value = [0, value.round].max
+            @min_height = @max_height = value
+          when Range
+            b = value.begin
+            e = value.end
+
+            if Integer === b || Float === b
+              @min_height = [0, b.round].max
+              return @max_height = @min_height if b == e
+              return @max_height = e && @min_height < e ? e.round : nil
+            end
+
+            if Integer === e || Float === e
+              @max_height = [0, e.round].max
+              return @min_height = nil
+            end
+
+            raise(
+              ArgumentError,
+              'value can only be a range of Integer or Float'
+            )
+          else
+            raise(ArgumentError, 'value must be an Integer, Range or nil')
+          end
+        end
+
+        # Cell padding as a four-element array `[top, right, bottom, left]`.
+        #
+        # @return [Array(Integer, Integer, Integer, Integer)]
+        attr_reader :padding
+
+        # Sets cell padding.
+        #
+        # @example All sides
+        #   cell.attributes.padding = 2
+        #
+        # @example Vertical / horizontal
+        #   cell.attributes.padding = [1, 4]
+        #
+        # @attribute [w] padding
+        # @param value [Integer, #map, nil]
+        #   - `Integer` — all four sides
+        #   - `#map` (Enumerable) of 1–4 `#to_int` values:
+        #     1 element = all sides; 2 elements = [vertical, horizontal];
+        #     3 elements = [top, horizontal, bottom];
+        #     4 elements = [top, right, bottom, left]
+        #   - `nil` — resets all sides to zero
+        # @raise [ArgumentError] if value has more than 4 elements or wrong type
+        def padding=(value)
+          return @padding = Array.new(4, 0) if value.nil?
+          return @padding = Array.new(4, value) if Integer === value
+          unless value.respond_to?(:map)
+            raise(ArgumentError, 'value must be an Integer, Enumerable or nil')
+          end
+          value = value.map { [0, it.to_int].max }
+          @padding =
+            case value.size
+            when 0
+              Array.new(4, 0)
+            when 1
+              Array.new(4, value)
+            when 2
+              value * 2
+            when 3
+              value << value[1]
+            when 4
+              value
+            else
+              raise(ArgumentError, 'too many values Enumerable')
+            end
+        end
+
+        # Top padding in lines.
+        #
+        # @attribute [r] top_padding
+        # @return [Integer]
+        def top_padding = @padding[0]
+
+        # @attribute [w] top_padding
+        # @param value [#to_int]
+        def top_padding=(value)
+          @padding[0] = [0, value.to_int].max
+        end
+
+        # Right padding in characters.
+        #
+        # @attribute [r] right_padding
+        # @return [Integer]
+        def right_padding = @padding[1]
+
+        # @attribute [w] right_padding
+        # @param value [#to_int]
+        def right_padding=(value)
+          @padding[1] = [0, value.to_int].max
+        end
+
+        # Bottom padding in lines.
+        #
+        # @attribute [r] bottom_padding
+        # @return [Integer]
+        def bottom_padding = @padding[2]
+
+        # @attribute [w] bottom_padding
+        # @param value [#to_int]
+        def bottom_padding=(value)
+          @padding[2] = [0, value.to_int].max
+        end
+
+        # Left padding in characters.
+        #
+        # @attribute [r] padding_left
+        # @return [Integer]
+        def left_padding = @padding[3]
+
+        # @attribute [w] padding_left
+        # @param value [#to_int]
+        def padding_left=(value)
+          @padding[3] = [0, value.to_int].max
+        end
+
+        # Returns `true` when all attributes are at their default values.
+        #
+        # @return [Boolean]
+        def empty?
+          @align.nil? && @vertical.nil? && @min_width.nil? && @max_width.nil? &&
+            @min_height.nil? && @max_height.nil? && @padding.all?(&:zero?)
+        end
+
+        # @private
+        def to_hash
+          ret = {}
+          ret[:eol] = false unless @eol
+          ret[:spaces] = false unless @spaces
+          ret[:align] = @align if @align
+          ret[:vertical] = @vertical if @vertical
+          value = width and ret[:width] = value
+          value = height and ret[:height] = value
+          value = real_padding and ret[:padding] = value
+          ret
+        end
+
+        # Applies attribute values from a hash.
+        #
+        # @example
+        #   cell.attributes.assign(align: :center, padding: [0, 2])
+        #
+        # @param attributes [#to_hash] attribute hash, see {#initialize}
+        # @return [Cell::Attributes]
+        def assign(attributes)
+          attributes = attributes.to_hash
+          unless attributes.empty?
+            @eol = false if attributes[:eol] == false
+            @spaces = false if attributes[:spaces] == false
+            self.align = attributes[:align] if attributes.key?(:align)
+            self.vertical = attributes[:vertical] if attributes.key?(:vertical)
+            assign_padding(attributes)
+            assign_width(attributes)
+            assign_height(attributes)
+          end
+          self
+        end
+
+        # @param attributes [Hash] a customizable set of attributes
+        # @option attributes [Boolean] :eol (true)
+        #   see {#eol}
+        # @option attributes [Boolean] :spaces (true)
+        #   see {#spaces}
+        # @option attributes [:left, :center, :right, nil] :align (nil)
+        #   see {#align}
+        # @option attributes [:top, :middle, :bottom, nil] :vertical (nil)
+        #   see {#vertical}
+        # @option attributes [Integer, Float, Range, nil] :width (nil)
+        #   see {#width}
+        # @option attributes [Integer, Float, nil] :min_width (nil)
+        #   see {#min_width}
+        # @option attributes [Integer, Float, nil] :max_width (nil)
+        #   see {#max_width}
+        # @option attributes [Integer, Range, nil] :height (nil)
+        #   see {#height}
+        # @option attributes [Integer, nil] :min_height (nil)
+        #   see {#min_height}
+        # @option attributes [Integer, nil] :max_height (nil)
+        #   see {#max_height}
+        # @option attributes [Integer, #map, nil] :padding (0)
+        #   see {#padding}
+        # @option attributes [Integer, nil] :top_padding (0)
+        #   see {#top_padding}
+        # @option attributes [Integer, nil] :right_padding (0)
+        #   see {#right_padding}
+        # @option attributes [Integer, nil] :bottom_padding (0)
+        #   see {#bottom_padding}
+        # @option attributes [Integer, nil] :left_padding (0)
+        #   see {#left_padding}
+        def initialize(**attributes)
+          @eol = @spaces = true
+          @padding = [0, 0, 0, 0]
+          assign(attributes) unless attributes.empty?
+        end
+
+        # @private
+        def dup = Attributes.new(**to_hash)
+
+        private
+
+        alias _to_s to_s
+        private :_to_s, :clone
+
+        # @private
+        def inspect
+          return _to_s if (opts = to_hash).empty?
+          "#{_to_s.chop} #{opts.map { |k, v| "#{k}=#{v}" }.join(', ')}>"
+        end
+
+        def assign_padding(options)
+          self.padding = options[:padding] if options.key?(:padding)
+          self.top_padding = options[:top_padding] if options.key?(:top_padding)
+          self.right_padding = options[:right_padding] if options.key?(
+            :right_padding
+          )
+          self.bottom_padding = options[:bottom_padding] if options.key?(
+            :bottom_padding
+          )
+          self.padding_left = options[:padding_left] if options.key?(
+            :padding_left
+          )
+        end
+
+        def assign_width(options)
+          if options.key?(:min_width)
+            if options.key?(:max_width)
+              return self.width = (options[:min_width]..options[:max_width])
+            end
+            return self.min_width = options[:min_width]
+          end
+          return self.max_width = options[:max_width] if options.key?(
+            :max_width
+          )
+          self.width = options[:width] if options.key?(:width)
+        end
+
+        def assign_height(options)
+          if options.key?(:min_height)
+            if options.key?(:max_height)
+              return self.height = (options[:min_height]..options[:max_height])
+            end
+            return self.min_height = options[:min_height]
+          end
+          if options.key?(:max_height)
+            return self.max_height = options[:max_height]
+          end
+          self.height = options[:height] if options.key?(:height)
+        end
+
+        def real_padding
+          ret = @padding.dup
+          return ret if ret[-1] != ret[1]
+          ret.pop
+          return ret if ret[-1] != ret[0]
+          return (ret = ret[0]).zero? ? nil : ret if ret[0] == ret[1]
+          ret.pop
+          ret
+        end
+      end
+
+      # Returns `true` when this cell has no text and default attributes.
+      #
+      # @attribute [r] empty?
+      # @return [Boolean]
+      def empty? = @text.empty? && @attributes.empty?
+
+      # Text content of this cell.
+      #
+      # @return [Array] array of text values passed at construction
+      attr_reader :text
+
+      # Formatting attributes of this cell.
+      #
+      # @return [Cell::Attributes]
+      attr_reader :attributes
+
+      # @param text [#to_s, ...]
+      #   cell text
+      # @param attributes
+      #   cell attributes (see {Cell::Attributes#initialize})
+      def initialize(*text, **attributes)
+        @text = text
+        @attributes = Attributes.new(**attributes)
+      end
+
+      # @private
+      EMPTY = new.freeze
+
+      private
+
+      def initialize_copy(*)
+        super
+        @text.map!(&:dup)
+        @attributes = @attributes.dup
+      end
+
+      alias _to_s to_s
+      private :_to_s
+
+      def inspect
+        return _to_s if (att = @attributes.to_hash).empty?
+        "#{_to_s.chop} #{att.map { |k, v| "#{k}=#{v}" }.join(', ')}>"
+      end
+
+      ALIGN_VALUES = [:left, :center, :right, nil].freeze
+      VERTICAL_VALUES = [:top, :middle, :bottom, nil].freeze
+      private_constant :ALIGN_VALUES, :VERTICAL_VALUES
+    end
+
+    # A single row in a {Table}.
+    #
+    # Rows are accessed through {Table#rows} or created implicitly by
+    # {Table#add_row} and {Table#[]}.  A row holds an ordered list of {Cell}
+    # objects and carries default formatting {#attributes} that apply to all
+    # cells in the row during rendering.
+    class Row
+      include Enumerable
+      extend Forwardable
+
+      def_delegators :@cells,
+                     :size,
+                     :length,
+                     :empty?,
+                     :any?,
+                     :none?,
+                     :at,
+                     :clear,
+                     :pop
+
+      # @attribute [r] size
+      # Number of columns.
+      # @return [Integer]
+
+      # @attribute [r] empty?
+      # Wheter the row is empty.
+      # @return [Boolean]
+
+      # @attribute [r] any?
+      # Wheter the row contains at least one {Cell}.
+      # @return [Boolean]
+
+      # @attribute [r] none?
+      # Wheter the row contains at no {Cell}.
+      # @return [Boolean]
+
+      # Default formatting attributes for all cells in this row.
+      #
+      # @return [Cell::Attributes]
+      attr_reader :attributes
+
+      # @!method at(index)
+      # Returns the {Cell} at `index`, or `nil` if it does not exist.
+      # @param index [#to_int] zero-based column index
+      # @return [Cell, nil]
+
+      # Returns the cell at `index`, creating an empty cell if none exists.
+      #
+      # @param index (see #at)
+      # @return [Cell]
+      def [](index) = @cells[index.to_int] ||= Cell.new
+
+      # Sets or replaces the cell at `index`.
+      #
+      # Accepts the same arguments as {Cell#initialize}: optional text values
+      # followed by an optional keyword hash of {Cell::Attributes} options.
+      #
+      # @example
+      #   row[1] = 'Hello', align: :center
+      #
+      # @param index (see #fill)
+      def []=(index, *args)
+        opts = args.pop if args[-1].is_a?(Hash)
+        fill(index, *args, **opts)
+      end
+
+      # Appends a new cell to this row.
+      #
+      # @example Append and return the new cell
+      #   row.add 'Alice', align: :left
+      #
+      # @example Append and configure via block
+      #   row.add 'Alice' do |cell|
+      #     cell.attributes.align = :center
+      #   end
+      #
+      # @param (see Cell#initialize)
+      # @yield [cell] the new {Cell}
+      # @yieldparam cell [Cell]
+      # @return [Object] return value of the block
+      # @return [Cell] the new {Cell}, if no block is specified
+      def add(*text, **attributes)
+        @cells << (cell = Cell.new(*text, **attributes))
+        block_given? ? yield(cell) : cell
+      end
+
+      # Inserts a new cell at the given index.
+      #
+      # @example Insert and return the new cell
+      #   row.insert 0, 'Header', align: :center
+      #
+      # @example Insert and configure via block
+      #   row.insert(0, 'Header') { |c| c.attributes.align = :center }
+      #
+      # @param index [#to_int] position to insert at
+      # @param (see #add)
+      # @yield (see #add)
+      # @yieldparam (see #add)
+      # @return (see #add)
+      def insert(index, *texts, **attributes)
+        @cells.insert(index.to_int, cell = Cell.new(*texts, **attributes))
+        block_given? ? yield(cell) : cell
+      end
+
+      # Appends one cell per text value.
+      #
+      # @example Append cells and return them
+      #   row.add_text 'A', 'B', 'C', align: :center
+      #
+      # @example Append cells and configure via block
+      #   row.add_text 'X', 'Y' do |cells|
+      #     cells.each { it.attributes.align = :right }
+      #   end
+      #
+      # @param texts [#to_s, ...] one text value per cell
+      # @param attributes (see Cell#initialize)
+      # @yield [cells] array of the new {Cell} objects
+      # @yieldparam cells [Array<Cell>]
+      # @return [Object] return value of the block
+      # @return [Array<Cell>] array of the new {Cell} objects,
+      #   if no block is specified
+      def add_text(*texts, **attributes)
+        cells = texts.map! { Cell.new(it, **attributes) }
+        @cells.concat(cells)
+        block_given? ? yield(cells) : cells
+      end
+
+      # Sets the cell at one or more indices.
+      #
+      # @example Single index
+      #   row.fill 2, 'value'
+      #
+      # @example Multiple indices (same content)
+      #   row.fill [0, 2, 4], 'x', align: :center
+      #
+      # @example Configure via block
+      #   row.fill(1, 'val') { |cell| cell.attributes.vertical = :middle }
+      #
+      # @param index [#to_int, #each] a single index or an enumerable of indices
+      # @param (see #add)
+      # @yield (see #add_text)
+      # @yieldparam (see #add_text)
+      # @return (see #add_text)
+      def fill(index, *text, **attributes)
+        ret =
+          if index.respond_to?(:each)
+            index.each.map { @cells[it] = Cell.new(*text, **attributes) }
+          else
+            @cells[index] = Cell.new(*text, **attributes)
+          end
+        block_given? ? yield(ret) : ret
+      end
+
+      # Fills cells sequentially by calling the block for each index.
+      #
+      # The block receives the current `Integer` index and must return an
+      # `Array` whose elements are the text/attribute arguments for the new
+      # cell (an optional trailing `Hash` is treated as attribute options).
+      # Returning `nil` or `false` stops iteration.
+      #
+      # @example
+      #   row.fill_while do |i|
+      #     break if i >= 3
+      #     ["Col #{i}", { align: :center }]
+      #   end
+      #
+      # @param index [#to_int] starting index
+      # @yield [index] current column index
+      # @yieldparam index [Integer]
+      # @yieldreturn [Array, nil]
+      #   arguments for {Cell#initialize}, or `nil` to stop
+      def fill_while(index = 0)
+        index = index.to_int
+        while (args = yield(index))
+          opts = args.pop if args[-1].is_a?(Hash)
+          @cells[index] = Cell.new(*args, **opts)
+          index += 1
+        end
+      end
+
+      # Fills consecutive cells starting at `index` with one cell per text value.
+      #
+      # @example Fill and return the cells
+      #   row.fill_text 1, 'B', 'C', 'D'
+      #
+      # @example Fill and configure via block
+      #   row.fill_text(1, 'B', 'C') do |cells|
+      #     cells.each { it.attributes.align = :right }
+      #   end
+      #
+      # @param index [#to_int] starting column index
+      # @param (see #add_text)
+      # @yield (see #add_text)
+      # @yieldparam (see #add_text)
+      # @return (see #add_text)
+      def fill_text(index, *texts, **attributes)
+        index = index.to_int - 1
+        cells = texts.map! { @cells[index += 1] = Cell.new(it, **attributes) }
+        block_given? ? yield(cells) : cells
+      end
+
+      # Removes a cell from this row.
+      #
+      # @param index [#to_int, Cell] column index or the {Cell} object itself
+      # @return [Boolean] `true` if a cell was removed, `false` otherwise
+      def delete(index)
+        cell =
+          if Cell === index
+            @cells.delete(index)
+          else
+            @cells.delete_at(index.to_int)
+          end
+        !cell.freeze.nil?
+      end
+
+      # Iterates over non-nil cells in this row.
+      #
+      # @example With a block
+      #   row.each { |cell| cell.attributes.align = :center }
+      #
+      # @yield [cell] each non-nil {Cell}
+      # @yieldparam cell [Cell]
+      # @return [nil] if block is specified
+      # @return [Enumerator] if no block is specified
+      def each
+        return to_enum unless block_given?
+        @cells.each { yield(it) if it }
+        nil
+      end
+
+      private
+
+      def initialize(**)
+        @cells = []
+        @attributes = Cell::Attributes.new(**)
+      end
+
+      alias _to_s to_s
+      private :_to_s, :dup, :clone
+
+      # @private
+      def inspect = "#{_to_s.chop} index=#{@index}>"
+    end
+
+    # A vertical slice through a {Table} — all cells at a given column index.
+    #
+    # Columns are accessed through {Table#columns}.  A `Column` holds a
+    # reference to its owning {Table} and provides a view of cells at its
+    # {#index}.  The {#attributes} object carries default formatting applied to
+    # all cells in the column during rendering.
+    class Column
+      include Enumerable
+
+      # Zero-based index of this column in the table.
+      #
+      # @return [Integer]
+      attr_reader :index
+
+      # Default formatting attributes for all cells in this column.
+      #
+      # @return [Cell::Attributes]
+      attr_reader :attributes
+
+      # Number of rows in the owning table.
+      #
+      # @attribute [r] size
+      # @return [Integer]
+      def size = @table.rows.size
+
+      # Returns the cell at row `index`, or `nil` if it does not exist.
+      #
+      # @param index [#to_int] zero-based row index
+      # @return [Cell, nil]
+      def at(index) = @table.at(index, @index)
+
+      # Returns the cell at row `index`, creating an empty cell if needed.
+      #
+      # @param index [#to_int] zero-based row index
+      # @return [Cell]
+      def [](index) = @table[index, @index]
+
+      # Sets or replaces the cell at `index`.
+      #
+      # Accepts the same arguments as {Cell#initialize}: optional text values
+      # followed by an optional keyword hash of {Cell::Attributes} options.
+      #
+      # @example
+      #   col[0] = 'Header', align: :center
+      #
+      # @param index (see #fill)
+      # @param (see Cell#initialize)
+      def []=(index, *args)
+        opts = args.pop if args[-1].is_a?(Hash)
+        fill(index, *args, **opts)
+      end
+
+      # Sets the cell at one or more row indices.
+      #
+      # @example Single index
+      #   col.fill 0, 'Header', align: :center
+      #
+      # @example Multiple indices and configure via block
+      #   col.fill([0, 1], 'x') { |cells| cells.each { it.attributes.align = :right } }
+      #
+      # @param index [#to_int, #each] row index or enumerable of row indices
+      # @param (see Cell#initialize)
+      # @yield [result] cell or array of cells
+      # @return [Object] return value of the block
+      # @return [Cell, Array<Cell>] cell or array of cells,
+      #   if no block is specified
+      def fill(index, *text, **attributes)
+        ret =
+          if index.respond_to?(:each)
+            index.each.map { @table.rows[it].fill(@index, *text, **attributes) }
+          else
+            @table.rows[index].fill(@index, *text, **attributes)
+          end
+        block_given? ? yield(ret) : ret
+      end
+
+      # Fills consecutive rows starting at `index` with one cell per text value.
+      #
+      # @example Fill and return the cells
+      #   col.fill_text 0, 'A', 'B', 'C'
+      #
+      # @example Fill and configure via block
+      #   col.fill_text(0, 'A', 'B') { |cells| cells.each { it.attributes.align = :center } }
+      #
+      # @param index [#to_int] starting row index
+      # @param texts [#to_s, ...] one text value per row
+      # @param attributes (see Cell#initialize)
+      # @yield [cells] array of created cells
+      # @return [Object] return value of the block
+      # @return [Array<Cell>] array of created cells,
+      #   if no block is specified
+      def fill_text(index, *texts, **attributes)
+        index = index.to_int - 1
+        rows =
+          texts.map! { @table.rows[index += 1].fill(@index, it, **attributes) }
+        block_given? ? yield(rows) : rows
+      end
+
+      # Fills cells in this column sequentially by calling the block for each row.
+      #
+      # The block receives the current `Integer` row index and must return an
+      # `Array` of arguments for the cell (optional trailing `Hash` for
+      # attributes), or `nil` / `false` to stop.
+      #
+      # @example
+      #   col.fill_while { |i| i < 3 ? ["Row #{i}"] : nil }
+      #
+      # @param index [#to_int] starting row index
+      # @yield [index] current row index
+      # @yieldparam index [Integer]
+      # @yieldreturn [Array, nil]
+      #   arguments for {Cell#initialize}, or `nil` to stop
+      def fill_while(index = 0)
+        index = index.to_int
+        while (args = yield(index))
+          opts = args.pop if args[-1].is_a?(Hash)
+          @table.rows[index].fill(@index, *args, **opts)
+          index += 1
+        end
+      end
+
+      # Removes this column from the table (deletes all cells at this index).
+      #
+      # @return [Integer, nil] number of cells deleted, or `nil` if the column
+      #   was already empty
+      def delete!
+        @table.rows.each.find_all { it.delete(@index) }.size.nonzero?
+      end
+
+      # Iterates over non-nil cells in this column.
+      #
+      # @example
+      #   col.each { |cell| cell.attributes.align = :right }
+      #
+      # @yield [cell] each non-nil {Cell}
+      # @yieldparam cell [Cell]
+      # @return [nil] if block is specified
+      # @return [Enumerator] if no block is specified
+      def each
+        return to_enum unless block_given?
+        @table.rows.each { (cell = it.at(@index)) and yield(cell) }
+        nil
+      end
+
+      private
+
+      def initialize(table, index)
+        @table = table
+        @index = index
+        @attributes = Cell::Attributes.new
+      end
+
+      alias _to_s to_s
+      private :_to_s
+
+      # @private
+      def inspect = "#{_to_s.chop} #{@index}>"
+    end
+
+    # Ordered collection of {Row} objects belonging to a {Table}.
+    # Accessed via {Table#rows}.
+    class RowCollection
+      include Enumerable
+
+      extend Forwardable
+
+      def_delegators :@rows,
+                     :size,
+                     :length,
+                     :empty?,
+                     :any?,
+                     :none?,
+                     :clear,
+                     :pop
+
+      # @attribute [r] size
+      # Number of rows.
+      # @return [Integer]
+
+      # @attribute [r] empty?
+      # Wheter the collection is empty.
+      # @return [Boolean]
+
+      # @attribute [r] any?
+      # Wheter the collection contains at least one {Row}.
+      # @return [Boolean]
+
+      # @attribute [r] none?
+      # Wheter the collection contains at no {Row}.
+      # @return [Boolean]
+
+      # Returns the row at `index`, or `nil` if it does not exist.
+      #
+      # @example
+      #   rows.at(0)   # => first Row or nil
+      #
+      # @param index [#to_int] zero-based row index
+      # @return [Row, nil]
+      def at(index) = @rows[index]
+
+      # Returns the row at `index`, creating an empty row if none exists.
+      #
+      # @example
+      #   rows[0]   # => Row (created if missing)
+      #
+      # @param index [#to_int] zero-based row index
+      # @return [Row]
+      def [](index) = @rows[index.to_int] ||= Row.new
+
+      # Appends a new row, optionally pre-populated with text cells.
+      #
+      # @example Append and return the new row
+      #   rows.add 'Alice', 'Bob', align: :center
+      #
+      # @example Append and populate via block
+      #   rows.add do |row|
+      #     row.add 'Name', align: :right
+      #     row.add 'Score', align: :left
+      #   end
+      #
+      # @param texts [#to_s, ...] text values; each becomes a cell in the new row
+      # @param attributes [Hash] default attributes applied to the row,
+      #   see {Cell::Attributes#initialize}
+      # @yield [row] the new {Row}
+      # @yieldparam row [Row]
+      # @return [Object] return value of the block
+      # @return [Row] the new row, if no block is specified
+      def add(*texts, **attributes)
+        @rows << (row = Row.new(**attributes))
+        row.add_text(*texts) unless texts.empty?
+        block_given? ? yield(row) : row
+      end
+
+      # Inserts a new row at the given index.
+      #
+      # @example Insert and return the new row
+      #   rows.insert 0, 'Header A', 'Header B', align: :center
+      #
+      # @example Insert and populate via block
+      #   rows.insert(0) { |row| row.add 'Header' }
+      #
+      # @param index [#to_int] position to insert at
+      # @param (see #add)
+      # @yield (see #add)
+      # @yieldparam (see #add)
+      # @return (see #add)
+      def insert(index, *texts, **attributes)
+        @rows.insert(index.to_int, row = Row.new(**attributes))
+        row.add_text(*texts) unless texts.empty?
+        block_given? ? yield(row) : row
+      end
+
+      # Appends one new row per text value (each value becomes a single-cell row).
+      #
+      # @example Append and return the rows
+      #   rows.add_text 'Row A', 'Row B'
+      #
+      # @example Append and configure via block
+      #   rows.add_text('Row A', 'Row B') { |rows| rows.each { it.attributes.align = :center } }
+      #
+      # @param texts [#to_s, ...] one text value per row
+      # @param attributes [Hash] default attributes applied to each row,
+      #   see {Cell::Attributes#initialize}
+      # @yield [rows] array of the new {Row} objects
+      # @yieldparam rows [Array<Row>]
+      # @return [Object] return value of the block
+      # @return [Array<Row>] the new rows, if no block is specified
+      def add_text(*texts, **attributes)
+        @rows.concat(
+          rows =
+            texts.map! do |txt|
+              row = Row.new(**attributes)
+              row.add(*txt)
+              row
+            end
+        )
+        block_given? ? yield(rows) : rows
+      end
+
+      # Removes a row from the collection.
+      #
+      # @param index [#to_int, Row] row index or the {Row} object itself
+      # @return [Boolean] `true` if a row was removed, `false` otherwise
+      def delete(index)
+        row =
+          if Row === index
+            @rows.delete(index)
+          else
+            @rows.delete_at(index.to_int)
+          end
+        !row.freeze.nil?
+      end
+
+      # Iterates over all non-nil rows.
+      #
+      # @example
+      #   rows.each { |r| r.attributes.align = :center }
+      #
+      # @yield [row] each non-nil {Row}
+      # @yieldparam row [Row]
+      # @return [nil] if block is specified
+      # @return [Enumerator] if no block is specified
+      def each
+        return to_enum unless block_given?
+        @rows.each { yield(it) if it }
+        nil
+      end
+
+      # Iterates over non-nil rows that contain at least one cell.
+      #
+      # @yield [row] each non-empty {Row}
+      # @yieldparam (see #each)
+      # @return (see #each)
+      def each_filled
+        return to_enum(__method__) unless block_given?
+        @rows.each { yield(it) if it&.any? }
+        nil
+      end
+
+      private
+
+      def initialize
+        @rows = []
+      end
+
+      alias _to_s to_s
+
+      # @private
+      def inspect = "#{_to_s.chop} size=#{size}>"
+      private :_to_s, :dup, :clone
+    end
+
+    # Collection of {Column} objects for a {Table}.
+    #
+    # Accessed via {Table#columns}.  Columns are created on demand; accessing
+    # a column index that has no data still returns a valid {Column} object
+    # whose cells reference the underlying table rows.
+    class ColumnCollection
+      include Enumerable
+
+      # @private
+      def max = @table.rows.each.max_by(&:size)&.size || 0
+
+      # @private
+      def min = @table.rows.each.min_by(&:size)&.size || 0
+
+      alias size max
+      alias length max
+
+      # @attribute [r] size
+      # Number of columns.
+      # @return [Integer]
+
+      # Returns the column at `index`, or `nil` if no cells exist at that index.
+      #
+      # @param index [#to_int] zero-based column index
+      # @return [Column, nil]
+      def at(index)
+        @columns.key?(index = index.to_int) and @columns[index]
+      end
+
+      # Returns the column at `index`, or `nil` if the index is beyond the
+      # table width.
+      #
+      # @param (see #at)
+      # @return (see #at)
+      def [](index)
+        index = index.to_int
+        @columns[index] if index < max
+      end
+
+      # Appends a new column (adds cells to each existing row) and returns it.
+      #
+      # @example Append and return the column
+      #   columns.add 'Alice', 'Bob', 'Carol', align: :left
+      #
+      # @example Append and configure via block
+      #   columns.add('X', 'Y') { |col| col.attributes.align = :center }
+      #
+      # @param texts [#to_s, ...] one text value per row in the new column
+      # @param attributes [Hash] attribute options applied to the column,
+      #   (see Cell#initialize)
+      # @yield [column] the {Column}
+      # @yieldparam column [Column]
+      # @return [Object] return value of the block
+      # @return [Column] the {Column}, if no block is specified
+      def add(*texts, **attributes)
+        col = @columns[max]
+        col.attributes.assign(attributes) unless attributes.empty?
+        col.fill_text(0, *texts)
+        block_given? ? yield(col) : col
+      end
+
+      # Iterates over columns that contain at least one non-nil cell.
+      #
+      # @example
+      #   columns.each { |col| col.attributes.align = :center }
+      #
+      # @yield [column] each non-empty {Column}
+      # @yieldparam column [Column]
+      # @return [nil] if block is specified
+      # @return [Enumerator] if no block is specified
+      def each
+        return to_enum unless block_given?
+        max.times do |index|
+          @table.rows.any? { it.at(index) } or next
+          yield(@columns[index])
+        end
+      end
+
+      private
+
+      def initialize(table)
+        @table = table
+        @columns =
+          Hash.new { |h, k| h[k] = Column.new(table, k) }.compare_by_identity
+      end
+
+      # @private
+      alias inspect to_s
+      private :dup, :clone
+    end
+
+    # Row collection for this table.
+    #
+    # @return [RowCollection]
+    attr_reader :rows
+
+    # Column collection for this table.
+    #
+    # @return [ColumnCollection]
+    attr_reader :columns
+
+    # Returns `true` when the table has no cells.
+    #
+    # @attribute [r] empty?
+    # @return [Boolean] whether the table is empty
+    def empty? = @rows.none?
+
+    # Returns the row at `row_index`, or the cell at `[row_index, column_index]`.
+    #
+    # Returns `nil` when the row (or cell) does not exist.
+    #
+    # @example Get a row
+    #   table.at(0)
+    #
+    # @example Get a cell
+    #   table.at(0, 2)
+    #
+    # @param row_index [#to_int] zero-based row index
+    # @param column_index [#to_int, nil] zero-based column index, or `nil` for the row
+    # @return [Row, Cell, nil]
+    def at(row_index, column_index = nil)
+      row = @rows.at(row_index) or return
+      column_index ? row.at(column_index) : row
+    end
+
+    # Returns (or creates) the row at `row_index`, or the cell at
+    # `[row_index, column_index]`.
+    #
+    # @example Get or create a row
+    #   table[0]
+    #
+    # @example Get or create a cell
+    #   table[1, 2] = 'value'
+    #
+    # @param row_index [#to_int] zero-based row index
+    # @param column_index [#to_int, nil] zero-based column index, or `nil` for the row
+    # @return [Row, Cell]
+    def [](row_index, column_index = nil)
+      row = @rows[row_index]
+      column_index ? row[column_index] : row
+    end
+
+    # Appends a new row to the table.
+    #
+    # @example
+    #   table.add_row 'Alice', 42, align: :center
+    #
+    # @param (see RowCollection#add)
+    # @yield (see RowCollection#add)
+    # @yieldparam (see RowCollection#add)
+    # @return (see RowCollection#add)
+    def add_row(*texts, **attributes, &)
+      @rows.add(*texts, **attributes, &)
+    end
+
+    # Appends a new column to the table.
+    #
+    # @example
+    #   table.add_column 'Header A', 'Header B', align: :center
+    #
+    # @param (see ColumnCollection#add)
+    # @yield (see ColumnCollection#add)
+    # @yieldparam (see ColumnCollection#add)
+    # @return (see ColumnCollection#add)
+    def add_column(*texts, **attributes, &)
+      @columns.add(*texts, **attributes, &)
+    end
+
+    # Iterates over all rows in the table.
+    #
+    # @example
+    #   table.each_row { |r| r.attributes.align = :center }
+    #
+    # @yield (see RowCollection#each)
+    # @yieldparam (see RowCollection#each)
+    # @return (see RowCollection#each)
+    def each_row(&) = @rows.each(&)
+
+    # Iterates over all columns in the table.
+    #
+    # @example
+    #   table.each_column { |col| col.attributes.align = :right }
+    #
+    # @yield (see ColumnCollection#each)
+    # @yieldparam (see ColumnCollection#each)
+    # @return (see ColumnCollection#each)
+    def each_column(&) = @columns.each(&)
+
+    # @private
+    def to_ary
+      return [] if (max = @columns.max).zero?
+      @rows.each_filled.map do |row|
+        Array.new(max) { |idx| (cell = row.at(idx)) ? cell.dup : Cell::EMPTY }
+      end
+    end
+
+    # @private
+    def texts
+      return [] if (max = @columns.max).zero?
+      @rows.each_filled.map do |row|
+        Array.new(max) do |idx|
+          (cell = row.at(idx)) ? cell.text.join("\n") : ''
+        end
+      end
+    end
+
+    private
+
+    def initialize
+      @rows = RowCollection.new
+      @columns = ColumnCollection.new(self)
+    end
+
+    alias _to_s to_s
+
+    # @private
+    def inspect = "#{_to_s.chop} rows=#{@rows.size} columns=#{@columns.size}>"
+    private :_to_s, :dup, :clone
+  end
+end