table_tennis 0.0.1

data/lib/table_tennis/config.rb

@@ -0,0 +1,221 @@
+module TableTennis
+  class << self
+    attr_accessor :defaults
+  end
+
+  # Store the table configuration options, with lots of validation.
+  class Config
+    OPTIONS = {
+      color_scales: nil, # columns => color scale
+      color: nil, # true/false/nil (detect)
+      columns: nil, # array of symbols, or inferred from rows
+      debug: false, # true for debug output
+      digits: 3, # format floats
+      layout: true, # true/false/int or hash of columns -> width. true to infer
+      mark: nil, # lambda returning boolean or symbol to mark rows in output
+      placeholder: "—", # placeholder for empty cells. default is emdash
+      row_numbers: false, # show line numbers?
+      save: nil, # csv file path to save the table when created
+      search: nil, # string/regex to highlight in output
+      strftime: nil, # string for formatting dates
+      theme: nil,  # :dark, :light or :ansi. :dark is the default
+      title: nil, # string for table title, if any
+      zebra: false, # turn on zebra stripes
+    }.freeze
+
+    def initialize(options = {}, &block)
+      options = [OPTIONS, TableTennis.defaults, options].reduce { _1.merge(_2 || {}) }
+      options[:color] = Config.detect_color? if options[:color].nil?
+      options[:theme] = Config.detect_theme if options[:theme].nil?
+      options[:debug] = true if ENV["TM_DEBUG"]
+      options.each { self[_1] = _2 }
+
+      yield self if block_given?
+    end
+
+    # readers
+    attr_reader(*OPTIONS.keys)
+
+    #
+    # simple writers
+    #
+
+    {
+      color: :bool,
+      debug: :bool,
+      digits: :int,
+      mark: :proc,
+      placeholder: :str,
+      row_numbers: :bool,
+      save: :str,
+      strftime: :str,
+      title: :str,
+      zebra: :bool,
+    }.each do |option, type|
+      define_method(:"#{option}=") do |value|
+        instance_variable_set(:"@#{option}", send(:"_#{type}", option, value))
+      end
+      alias_method(:"#{option}?", option) if type == :bool
+    end
+
+    #
+    # helpers
+    #
+
+    # is this a dark terminal?
+    def self.terminal_dark?
+      if (bg = Util::Termbg.bg)
+        Util::Colors.dark?(bg)
+      end
+    end
+
+    def self.detect_color?
+      return false if ENV["NO_COLOR"] || ENV["CI"]
+      return true if ENV["FORCE_COLOR"] == "1"
+      return false if !($stdout.tty? && $stderr.tty?)
+      Paint.detect_mode > 0
+    end
+
+    def self.detect_theme
+      case terminal_dark?
+      when true, nil then :dark
+      when false then :light
+      end
+    end
+
+    #
+    # complex writers
+    #
+
+    def color_scales=(value)
+      case value
+      when Array then value = value.to_h { [_1, :g] }
+      when Symbol then value = {value => :g}
+      end
+      value.to_h { [_1, :g] } if value.is_a?(Array)
+      @color_scales = validate(:color_scales, value) do
+        if !value.is_a?(Hash)
+          "expected hash"
+        elsif value.keys.any? { !_1.is_a?(Symbol) }
+          "keys must be symbols"
+        elsif value.values.any? { !_1.is_a?(Symbol) }
+          "values must be symbols"
+        elsif value.values.any? { !Util::Scale::SCALES.include?(_1) }
+          "values must be the name of a color scale"
+        end
+      end
+    end
+    alias_method(:"color_scale=", :"color_scales=")
+
+    def columns=(value)
+      @columns = validate(:columns, value) do
+        if !(value.is_a?(Array) && !value.empty? && value.all? { _1.is_a?(Symbol) })
+          "expected array of symbols"
+        end
+      end
+    end
+
+    def theme=(value)
+      @theme = validate(:theme, value) do
+        if !value.is_a?(Symbol)
+          "expected symbol"
+        elsif !Theme::THEMES.key?(value)
+          "expected one of #{Theme::THEMES.keys.inspect}"
+        end
+      end
+    end
+
+    def search=(value)
+      @search = validate(:search, value) do
+        if !(value.is_a?(String) || value.is_a?(Regexp))
+          "expected string/regex"
+        end
+      end
+    end
+
+    def layout=(value)
+      @layout = validate(:layout, value) do
+        next if [true, false].include?(value) || value.is_a?(Integer)
+        if !value.is_a?(Hash)
+          "expected boolean, int or hash"
+        elsif value.keys.any? { !_1.is_a?(Symbol) }
+          "keys must be symbols"
+        elsif value.values.any? { !_1.is_a?(Integer) }
+          "values must be ints"
+        end
+      end
+    end
+
+    def [](key)
+      raise ArgumentError, "unknown TableTennis.#{key}" if !respond_to?(key)
+      send(key)
+    end
+
+    def []=(key, value)
+      raise ArgumentError, "unknown TableTennis.#{key}=" if !respond_to?(:"#{key}=")
+      send(:"#{key}=", value)
+    end
+
+    def inspect
+      options = to_h.map { "@#{_1}=#{_2.inspect}" }.join(", ")
+      "#<Config #{options}>"
+    end
+
+    def to_h
+      OPTIONS.keys.to_h { [_1, self[_1]] }.compact
+    end
+
+    protected
+
+    #
+    # validations
+    #
+
+    def validate(option, value, &block)
+      if value != nil && (error = yield)
+        raise ArgumentError, "TableTennis.#{option} #{error}, got #{value.inspect}"
+      end
+      value
+    end
+
+    def _bool(option, value)
+      value = case value
+      when true, 1, "1", "true" then true
+      when false, 0, "", "0", "false" then false
+      else; value # this will turn into an error down below
+      end
+      validate(option, value) do
+        "expected boolean" if ![true, false].include?(value)
+      end
+    end
+
+    def _int(option, value)
+      validate(option, value) do
+        if !value.is_a?(Integer)
+          "expected int"
+        elsif value < 0
+          "expected positive int"
+        end
+      end
+    end
+
+    def _proc(option, value)
+      validate(option, value) do
+        "expected proc" if !value.is_a?(Proc)
+      end
+    end
+
+    def _str(option, value)
+      value = value.to_s if option == :title && value.is_a?(Symbol)
+      validate(option, value) do
+        "expected string" if !value.is_a?(String)
+      end
+    end
+
+    def _sym(option, value)
+      validate(option, value) do
+        "expected symbol" if !value.is_a?(Symbol)
+      end
+    end
+  end
+end

data/lib/table_tennis/row.rb

@@ -0,0 +1,9 @@
+module TableTennis
+  # A single table row (a hash). Doesn't have much behavior.
+  class Row < Hash
+    def initialize(column_names, fat_row)
+      super()
+      column_names.each { self[_1] = fat_row[_1] }
+    end
+  end
+end

data/lib/table_tennis/stage/base.rb

@@ -0,0 +1,19 @@
+module TableTennis
+  module Stage
+    # Base class for each stage of the rendering pipeline, mostly here just to
+    # delegate to TableData.
+    class Base
+      prepend MemoWise
+      extend Forwardable
+      include Util::Inspectable
+
+      attr_reader :data
+      def_delegators :data, *%i[column_names columns config input_rows rows theme]
+      def_delegators :data, *%i[debug debug_if_slow]
+
+      def initialize(data)
+        @data = data
+      end
+    end
+  end
+end

data/lib/table_tennis/stage/format.rb

@@ -0,0 +1,68 @@
+module TableTennis
+  module Stage
+    # This stage "formats" the table by injesting cells that contain various
+    # ruby objects and formatting each one as a string. `rows` are formatted in
+    # place.
+    #
+    # For performance reasons, formatting is implemented as a series of lambdas.
+    # Each fn must return a string. Minimize the number of times we examine each
+    # cell. Float detection/printing can be slow. Favor .match? over =~.
+    class Format < Base
+      attr_reader :fns
+
+      def run
+        setup_fns
+        rows.each do |row|
+          row.transform_values! do
+            fn = fns[fn_for(_1)] || fns[:other]
+            fn.call(_1)
+          end
+        end
+      end
+
+      def fn_for(value)
+        case value
+        when String then float?(value) ? :floatstr : :str
+        when Float then :float
+        when Date, Time, DateTime then :time
+        else
+          if value.respond_to?(:acts_like_time)
+            # Rails TimeWithZone
+            return :time
+          end
+          :other
+        end
+      end
+
+      def float?(str) = str.match?(/^-?\d+[.]\d+$/)
+
+      def setup_fns
+        placeholder = config.placeholder || ""
+        str = ->(s) do
+          # normalize whitespace
+          if s.match?(/\s/)
+            s = s.strip.gsub("\n", "\\n").gsub("\r", "\\r")
+          end
+          # replace empty values with placeholder
+          s = placeholder if s.empty?
+          s
+        end
+        other = ->(x) { str.call(x.to_s) }
+
+        # default behavior
+        @fns = {other:, str:}
+
+        # now mix in optional float/time formatters
+        if config.digits
+          fmt = "%.#{config.digits}f"
+          @to_f_cache = Hash.new { _1[_2] = fmt % _2.to_f }
+          fns[:float] = -> { fmt % _1 }
+          fns[:floatstr] = -> { @to_f_cache[_1] }
+        end
+        if config.strftime
+          fns[:time] = -> { _1.strftime(config.strftime) }
+        end
+      end
+    end
+  end
+end

data/lib/table_tennis/stage/layout.rb

@@ -0,0 +1,76 @@
+module TableTennis
+  module Stage
+    # This stage figures out how wide each column should be. Most of the fun is
+    # in the autolayout behavior, which tries to fill the terminal without
+    # overflowing. Once we know the column sizes, it will go ahead and truncate
+    # the cells if necessary.
+    class Layout < Base
+      def_delegators :data, :chrome_width, :data_width
+
+      def run
+        # did the user specify a layout strategy?
+        if config.layout
+          case config.layout
+          when true then autolayout
+          when Hash then columns.each { _1.width = config.layout[_1.name] }
+          when Integer then columns.each { _1.width = config.layout }
+          end
+        end
+
+        # fill in missing widths, and truncate if necessary
+        columns.each do
+          _1.width ||= _1.measure
+          _1.truncate(_1.width) if config.layout
+        end
+      end
+
+      #
+      # some math
+      #
+
+      AUTOLAYOUT_MIN_COLUMN_WIDTH = 2
+      AUTOLAYOUT_FUDGE = 2
+
+      # Fit columns into terminal width. This is copied from the very simple HTML
+      # table column algorithm. Returns a hash of column name to width.
+      def autolayout
+        # set provisional widths
+        columns.each { _1.width = _1.measure }
+
+        # how much space is available, and do we already fit?
+        screen_width = IO.console.winsize[1]
+        available = screen_width - chrome_width - AUTOLAYOUT_FUDGE
+        return if available >= data_width
+
+        # min/max column widths, which we use below
+        min = columns.map { [_1.width, AUTOLAYOUT_MIN_COLUMN_WIDTH].min }
+        max = columns.map(&:width)
+
+        # W = difference between the available space and the minimum table width
+        # D = difference between maximum and minimum width of the table
+        w = available - min.sum
+        d = max.sum - min.sum
+
+        # edge case if we don't even have enough room for min
+        if w <= 0
+          columns.each.with_index { _1.width = min[_2] }
+          return
+        end
+
+        # expand min to fit available space
+        columns.each.with_index do
+          # width = min + (delta * W / D)
+          _1.width = min[_2] + ((max[_2] - min[_2]) * w / d.to_f).to_i
+        end
+
+        # because we always round down, there might be some extra space to distribute
+        if (extra_space = available - data_width) > 0
+          distribute = columns.sort_by.with_index do |_, c|
+            [-(max[c] - min[c]), c]
+          end
+          distribute[0, extra_space].each { _1.width += 1 }
+        end
+      end
+    end
+  end
+end

data/lib/table_tennis/stage/painter.rb

@@ -0,0 +1,84 @@
+module TableTennis
+  module Stage
+    # This stage "paints" the table by calculating the style for cells, rows and
+    # columns. The styles are stuffed into `data.set_style`. Later, the
+    # rendering stage can apply them if color is enabled.
+    #
+    # A "style" is either:
+    #
+    # - a theme symbol (like :title or :chrome)
+    # - hex colors, for color scaling
+    #
+    # Other kinds of styles are theoretically possible but not tested.
+    class Painter < Base
+      def_delegators :data, :set_style
+
+      def run
+        return if !config.color
+        paint_title if config.title
+        paint_row_numbers if config.row_numbers
+        paint_rows if config.mark || config.zebra
+        paint_columns if config.color_scales
+        paint_placeholders if config.placeholder
+      end
+
+      protected
+
+      #
+      # helpers
+      #
+
+      def paint_title
+        set_style(r: :title, style: :title)
+      end
+
+      def paint_row_numbers
+        set_style(c: 0, style: :chrome)
+      end
+
+      def paint_rows
+        rows.each_index do |r|
+          style = nil
+          if config.zebra? && r.even?
+            style = :zebra
+          end
+          if (mark_style = config.mark&.call(input_rows[r]))
+            style = mark_style.is_a?(Symbol) ? mark_style : :mark
+          end
+          set_style(r:, style:) if style
+        end
+      end
+
+      def paint_columns
+        columns.each.with_index do |column, c|
+          scale = config.color_scales[column.name]
+          next if !scale
+
+          floats = column.map { _1.to_f if _1 =~ /^-?\d+(\.\d+)?$/ }
+          min, max = floats.compact.minmax
+          next if min == max # edge case
+
+          # color
+          column.each_index.zip(floats).each do |r, f|
+            next if !f
+            t = (f - min) / (max - min)
+            bg = Util::Scale.interpolate(scale, t)
+            fg = Util::Colors.contrast(bg)
+            set_style(r:, c:, style: [fg, bg])
+          end
+        end
+      end
+
+      def paint_placeholders
+        placeholder = config.placeholder
+        rows.each.with_index do |row, r|
+          row.each_value.with_index do |value, c|
+            if value == placeholder
+              set_style(r:, c:, style: :chrome)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/table_tennis/stage/render.rb

@@ -0,0 +1,146 @@
+module TableTennis
+  module Stage
+    # This is the final stage of the rending pipeline - take our layout
+    # information, the table cells, and the painted styles to render the table
+    # as a string. This is the slowest part of rendering since there is a lot of
+    # ansi/string manipulation.
+    #
+    # This is also where config.search is applied.
+    class Render < Base
+      BOX = [
+        "╭─┬─╮", # 0
+        "│ │ │", # 1
+        "├─┼─┤", # 2
+        "╰─┴─╯", # 3
+      ]
+
+      # take these from BOX
+      NW, N, NE = BOX[0].chars.values_at(0, 2, 4)
+      W, C, E = BOX[2].chars.values_at(0, 2, 4)
+      SW, S, SE = BOX[3].chars.values_at(0, 2, 4)
+
+      # horizontal and vertical lines
+      BAR, PIPE = BOX[0][1], BOX[1][0]
+
+      def run(io)
+        # edge case - empty
+        if rows.empty? || columns.empty?
+          io.puts render_empty
+          return
+        end
+
+        if config.title
+          io.puts render_separator(NW, BAR, NE)
+          io.puts render_title
+          io.puts render_separator(W, N, E)
+        else
+          io.puts render_separator(NW, N, NE)
+        end
+        io.puts render_row(:header)
+        io.puts render_separator(W, C, E)
+        rows.each_index { io.puts render_row(_1) }
+        io.puts render_separator(SW, S, SE)
+      end
+
+      #
+      # render different parts of the table
+      #
+
+      def render_title
+        title_width = data.table_width - 4
+        title = Util::Strings.truncate(config.title, title_width)
+        title_style = data.get_style(r: :title) || :cell
+        line = paint(title.center(title_width), title_style || :cell)
+        paint("#{pipe} #{line} #{pipe}", Theme::BG)
+      end
+
+      def render_row(r)
+        row_style = data.get_style(r:)
+
+        # assemble line by rendering cells
+        enum = (r != :header) ? rows[r].each_value : columns.map(&:header)
+        line = enum.map.with_index do |value, c|
+          render_cell(value, r, c, row_style)
+        end.join(" #{pipe} ")
+        line = "#{pipe} #{line} #{pipe}"
+
+        # afterward, apply row color
+        paint(line, row_style || Theme::BG)
+      end
+
+      def render_cell(value, r, c, default_cell_style)
+        # calculate whitespace based on plaintext
+        whitespace = columns[c].width - Util::Strings.width(value)
+
+        # cell > column > default > cell (row styles are applied elsewhere)
+        style = nil
+        style ||= data.get_style(r:, c:)
+        style ||= data.get_style(c:)
+        style ||= default_cell_style
+        style ||= :cell
+
+        # add ansi codes for search
+        value = value.gsub(search) { paint(_1, :search) } if search
+
+        # pad and paint
+        value = "#{value}#{" " * whitespace}" if whitespace > 0
+        paint(value, style)
+      end
+
+      def render_separator(l, m, r)
+        line = [].tap do |buf|
+          columns.each.with_index do |column, c|
+            buf << ((c == 0) ? l : m)
+            buf << (BAR * (column.width + 2))
+          end
+          buf << r
+        end.join
+        paint(paint(line, :chrome), Theme::BG)
+      end
+
+      def render_empty
+        title, body = config.title || "empty table", "no data"
+        width = [title, body].map(&:length).max
+
+        # helpers
+        sep_row = ->(l, c, r) do
+          paint("#{l}#{c * (width + 2)}#{r}", :chrome)
+        end
+        text_row = ->(str, style) do
+          inner = paint(str.center(width), style)
+          paint("#{pipe} #{inner} #{pipe}", Theme::BG)
+        end
+
+        # go
+        [].tap do
+          _1 << sep_row.call(NW, BAR, NE)
+          _1 << text_row.call(title, data.get_style(r: :title) || :cell)
+          _1 << sep_row.call(W, BAR, E)
+          _1 << text_row.call(body, :chrome)
+          _1 << sep_row.call(SW, BAR, SE)
+        end.join("\n")
+      end
+
+      #
+      # helpers
+      #
+
+      def paint(str, style)
+        # delegate painting to the theme, if color is enabled
+        str = theme.paint(str, style) if config.color
+        str
+      end
+
+      def pipe = paint(PIPE, :chrome)
+      memo_wise :pipe
+
+      def search
+        case config.search
+        when String then /#{Regexp.escape(config.search)}/i
+        when Regexp then config.search
+        end
+      end
+      memo_wise :search
+    end
+  end
+end

data/lib/table_tennis/table.rb

@@ -0,0 +1,79 @@
+#
+# Welcome to TableTennis! Use as follows:
+#
+# puts TableTennis.new(array_of_hashes, options = {})
+#
+# See the README for details on options - _color_scales_, _color_, _columns_,
+# _debug_, _digits_, _layout_, _mark_, _placeholder_, _row_numbers_, _save_,
+# _search_, _strftime_, _theme_, _title_, _zebra_
+#
+
+module TableTennis
+  # Public API for TableTennis.
+  class Table
+    extend Forwardable
+    include Util::Inspectable
+
+    attr_reader :data
+    def_delegators :data, *%i[column_names columns config input_rows rows]
+    def_delegators :data, *%i[debug debug_if_slow]
+
+    # Create a new table with options (see Config or README). This is typically
+    # called using TableTennis.new.
+    def initialize(input_rows, options = {}, &block)
+      config = Config.new(options, &block)
+      @data = TableData.new(config:, input_rows:)
+      sanity!
+      save(config.save) if config.save
+    end
+
+    # Render the table to $stdout or another IO object.
+    def render(io = $stdout)
+      %w[format layout painter render].each do |stage|
+        args = [].tap do
+          _1 << io if stage == "render"
+        end
+        Stage.const_get(stage.capitalize).new(data).run(*args)
+      end
+    end
+
+    # Save the table as a CSV file. Users can also do this manually.
+    def save(path)
+      headers = column_names
+      CSV.open(path, "wb", headers:, write_headers: true) do |csv|
+        rows.each { csv << _1.values }
+      end
+    end
+
+    # Calls render to convert the table to a string.
+    def to_s
+      StringIO.new.tap { render(_1) }.string
+    end
+
+    protected
+
+    # we cnan do a bit more config checking now
+    def sanity!
+      %i[color_scales layout].each do |key|
+        next if !config[key].is_a?(Hash)
+        next if rows.empty? # ignore on empty data
+        invalid = config[key].keys - data.column_names
+        if !invalid.empty?
+          raise ArgumentError, "#{key} columns `#{invalid.join(", ")}` not found in input data"
+        end
+      end
+    end
+  end
+
+  class << self
+    #
+    # Welcome to TableTennis! Use as follows:
+    #
+    # puts TableTennis.new(array_of_hashes_or_records, options = {})
+    #
+    # See the README for details on options - _color_scales_, _color_,
+    # _columns_, _debug_, _digits_, _layout_, _mark_, _placeholder_,
+    # _row_numbers_, _save_, _search_, _strftime_, _theme_, _title_, _zebra_
+    def new(*args, &block) = Table.new(*args, &block)
+  end
+end