table_tennis 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '009a0c9bbb140d308d55441602f96a534e51d989259c70b2e3cc2661213252cb'
-  data.tar.gz: 6422661f90e1e6e15ddb67c0fff92d6d1c1f3d3454e95a57ae79652d83b981ca
+  metadata.gz: 85ab2cbb42c928e7231529feaa15416f752b3efa3ca13d0ba54331b79cb41cc0
+  data.tar.gz: bbd1d0477437ab63c0302a8796ca058eb94a5084595a190032695188680214ef
 SHA512:
-  metadata.gz: af82ae82579222df273e5244c2dde9137547cce527b4c5e4b900feeb7129beb7d9b5d9ea80ae849f62ac79befd14c38be0f8e8c311a651f8dc63660b1953190a
-  data.tar.gz: 7eae197b20fe45f0b65f9987097e38233dac3ea113fcabbfd27011340a18910f9c8d701a3352cb482819f266391e98a0daaeec0857e966982e6d6ffcf2aa2121
+  metadata.gz: 7729436cacaa34103047f9d039e1a81626ad8b9f86b33062e3e8ab58067aa69bc56242d19e7861ec44284c6e277b3daf32966129c0d41da7b389dce591371ee0
+  data.tar.gz: 97165044e352b52af3b31870b1999624a4a3b3f6dd8624cd69a9935d594461a1842568973fb8a101438d4a26b6ddc2df754ff6b88fcc5f61a982894fb33c329c

data/.github/workflows/test.yml

@@ -2,9 +2,8 @@ name: test
 
 on:
   push:
-    paths-ignore:
-      - README.md
-      - 'screenshots/**'
+    branches: [main]
+    paths-ignore: [README.md, "screenshots/**"]
   pull_request:
   workflow_dispatch:
 
@@ -17,7 +16,7 @@ jobs:
         ruby-version: [3.0, 3.4]
     runs-on: ${{ matrix.os }}-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: taiki-e/install-action@just
       - uses: ruby/setup-ruby@v1
         with:

data/.rubocop.yml

@@ -21,6 +21,7 @@ AllCops:
 
 # we like these, don't remove
 Bundler/OrderedGems: { Enabled: true } # sort gems in gemfile
+Bundler/GemVersion: { Enabled: true } # make sure we have versions
 Layout/EmptyLineBetweenDefs: { AllowAdjacentOneLineDefs: true }
 Lint/NonLocalExitFromIterator: { Enabled: false }
 Lint/RedundantDirGlobSort: { Enabled: true } # glob is already sorted

data/Gemfile

@@ -2,15 +2,15 @@ source "https://rubygems.org"
 gemspec
 
 group :development, :test do
-  gem "amazing_print"
-  gem "image_optim"
-  gem "image_optim_pack"
-  gem "minitest"
-  gem "minitest-hooks"
-  gem "mocha"
-  gem "ostruct" # required for Ruby 3.5+
-  gem "pry"
-  gem "rake"
-  gem "simplecov", require: false
-  gem "standard", require: false, platform: :mri
+  gem "amazing_print", "~> 1.7"
+  gem "image_optim", "~> 0.31"
+  gem "image_optim_pack", "~> 0.12"
+  gem "minitest", "~> 5.25"
+  gem "minitest-hooks", "~> 1.5"
+  gem "mocha", "~> 2.7"
+  gem "ostruct", "~> 0.6" # required for Ruby 3.5+
+  gem "pry", "~> 0.15"
+  gem "rake", "~> 13.2"
+  gem "simplecov", "~> 0.22", require: false
+  gem "standard", "~> 1.49", require: false, platform: :mri
 end

data/README.md

@@ -67,25 +67,34 @@ options = {
 }
 ```
 
-| option | default | details |
-| ------ | ------- | ------- |
-| `color_scales` | ─ | Color code a column of floats, similar to the "conditional formatting" feature in Google Sheets. See [docs below](#color-scales). |
-| `color` | `nil` | Are ANSI colors enabled? Specify `true` or `false`, or leave it as nil to autodetect. Autodetect will turn on color unless redirecting to a file. When using autodetect, you can force it on by setting `ENV["FORCE_COLOR"]`, or off with `ENV["NO_COLOR"]`. |
-| `columns` | `nil` | Manually set which columns to include. Leave unset to show all columns.
-| `delims` | true | Format ints & floats with comma delimiter, like 123,456. |
-| `digits` | `3` | Format floats to this number of digits. TableTennis will look for either `Float` cells or string floats. |
-| `layout` | `true` | This controls column widths. Leave unset or use `true` for autolayout. Autolayout will shrink the table to fit inside the terminal. `false` turns off layout and columns will be full width. Use an int to fix all columns to a certain width, or a hash to just set a few. |
-| `mark` | ─ | `mark` is a way to highlight specific columns with a nice color. For example, use `mark: ->(row) { row[:planet] == "tatooine" }` to highlight those rows. Your lambda can also return a specific color if you want.
-| `placeholder` | `"—"` | Put this into empty cells. |
-| `row_numbers` | `false` | Show row numbers in the table. |
-| `save` | ─ | If you set this to a file path, TableTennis will save your table as a CSV file too. Useful if you want to do something else with the data. |
-| `search` | ─ | string/regex to highlight in output |
-| `separators` | `true` | Include column and header separators in output. |
-| `strftime` | see → | strftime string for formatting Date/Time objects. The default is `"%Y-%m-%d"`, which looks like `2025-04-21`  |
-| `theme` | nil | When unset, will be autodetected based on terminal background color. If autodetect fails the theme defaults to :dark. You can also manually specify `:dark`, `:light` or `:ansi`. If colors are turned off this setting has no effect.|
-| `title` | ─ | Add a title line to the table. |
-| `titleize` | ─ | Titleize column names, so `person_id` becomes `Person`. |
-| `zebra` | `false` | Turn on zebra stripes. |
+#### Popular Options
+
+| option         | default | details                                                                                                                                                                                                                         |
+| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `color_scales` | ─       | Color code a column of floats, similar to the "conditional formatting" feature in Google Sheets. See [docs below](#color-scales).                                                                                               |
+| `columns`      | ─       | Manually set which columns to include. Leave unset to show all columns.                                                                                                                                                         |
+| `headers`      | ─       | Specify some or all column headers. For example, `{user_id: "Customer"}`. When unset, headers are inferred.                                                                                                                     |
+| `mark`         | ─       | `mark` is a way to highlight specific columns with a nice color. For example, use `mark: ->(row) { row[:planet] == "tatooine" }` to highlight those rows. Your lambda can also return a specific bg color or Paint color array. |
+| `row_numbers`  | `false` | Show row numbers in the table.                                                                                                                                                                                                  |
+| `search`       | ─       | String/regex to highlight in output.                                                                                                                                                                                            |
+| `separators`   | `true`  | Include column and header separators in output.                                                                                                                                                                                 |
+| `title`        | ─       | Add a title line to the table.                                                                                                                                                                                                  |
+| `titleize`     | ─       | Titleize column headers, so `person_id` becomes `Person`.                                                                                                                                                                       |
+| `zebra`        | `false` | Turn on zebra stripes.                                                                                                                                                                                                          |
+
+#### More Advanced Options
+
+| option        | default | details                                                                                                                                                                                                                                                                     |
+| ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `coerce`      | `true`  | if true, try to coerce strings into numbers where possible so we can format with `digits`. You may want to disable this if you already have nicely formatted ints/floats and you don't want TableTennis to mess with them.                                                  |
+| `color`       | ─       | Are ANSI colors enabled? Specify `true` or `false`, or leave it as nil to autodetect. Autodetect will turn on color unless redirecting to a file. When using autodetect, you can force it on by setting `ENV["FORCE_COLOR"]`, or off with `ENV["NO_COLOR"]`.                |
+| `delims`      | `true`  | Format ints & floats with comma delimiter, like 123,456.                                                                                                                                                                                                                    |
+| `digits`      | `3`     | Format floats to this number of digits. TableTennis will look for either `Float` cells or string floats.                                                                                                                                                                    |
+| `layout`      | `true`  | This controls column widths. Leave unset or use `true` for autolayout. Autolayout will shrink the table to fit inside the terminal. `false` turns off layout and columns will be full width. Use an int to fix all columns to a certain width, or a hash to just set a few. |
+| `placeholder` | `"—"`   | Put this into empty cells.                                                                                                                                                                                                                                                  |
+| `save`        | ─       | If you set this to a file path, TableTennis will save your table as a CSV file too. Useful if you want to do something else with the data.                                                                                                                                  |
+| `strftime`    | see →   | strftime string for formatting Date/Time objects. The default is `"%Y-%m-%d"`, which looks like `2025-04-21`                                                                                                                                                                |
+| `theme`       | ─       | When unset, will be autodetected based on terminal background color. If autodetect fails the theme defaults to :dark. You can also manually specify `:dark`, `:light` or `:ansi`. If colors are turned off this setting has no effect.                                      |
 
 ### Color Scales
 
@@ -111,8 +120,8 @@ puts TableTennis.new(rows, search: /hope.*empire/i })
 puts TableTennis.new(rows, row_numbers: true, zebra: true)
 ```
 
-| `:mark` | `:search` | `:row_numbers` and `:zebra` |
-| - | - | - |
+| `:mark`                             | `:search`                       | `:row_numbers` and `:zebra`                   |
+| ----------------------------------- | ------------------------------- | --------------------------------------------- |
 | ![droids](./screenshots/droids.png) | ![hope](./screenshots/hope.png) | ![row numbers](./screenshots/row_numbers.png) |
 
 ### Links
@@ -163,6 +172,18 @@ We love CSV tools and use them all the time! Here are a few that we rely on:
 
 ### Changelog
 
+#### 0.0.7 (Aug '25)
+
+- handle data that already contains ANSI colors (thx @ronaldtse, #12)
+- don't crash if IO.console is nil (thx @ronaldtse, #14)
+
+#### 0.0.6 (May '25)
+
+- added `coerce:` option to disable string => numeric coercion
+- added `headers:` option to manually set column headers
+- fixed some issues related to links, including `save:`
+- added MagicOptions
+
 #### 0.0.5 (April '25)
 
 - Support for markdown style links in the cells

data/justfile

@@ -22,8 +22,9 @@ gem-local:
 
 # this will tag, build and push to rubygems
 gem-push: check
+  @if rg -g '!justfile' "\bREMIND\b" ; then just _fatal "REMIND found, bailing" ; fi
   @just _banner rake release...
-  rake release
+  bundle exec rake release
 
 # optimize images
 image_optim:

data/lib/table_tennis/column.rb

@@ -10,12 +10,12 @@ module TableTennis
     # c is the column index
     attr_reader :name, :data, :c
     attr_accessor :header, :width
-    def_delegators :data, *%i[rows]
+    def_delegators :data, *%i[config rows]
 
     def initialize(data, name, c)
       @name, @data, @c = name, data, c
-      @header = name.to_s
-      if data&.config&.titleize?
+      @header = config&.headers&.dig(name) || name.to_s
+      if config&.titleize?
         @header = Util::Strings.titleize(@header)
       end
     end

data/lib/table_tennis/config.rb

@@ -3,15 +3,17 @@ module TableTennis
     attr_accessor :defaults
   end
 
-  # Store the table configuration options, with lots of validation.
-  class Config
+  # Table configuration options, with schema validation courtesy of MagicOptions.
+  class Config < Util::MagicOptions
     OPTIONS = {
+      coerce: true, # if true, we try to coerce strings into numbers
       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
       delims: true, # true for numeric delimeters
       digits: 3, # format floats
+      headers: nil, # columns => header strings, or inferred from columns
       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
@@ -26,206 +28,94 @@ module TableTennis
       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["TT_DEBUG"]
-      options.each { self[_1] = _2 }
-
-      yield self if block_given?
-    end
-
-    # readers
-    attr_reader(*OPTIONS.keys)
-
-    #
-    # simple writers
-    #
-
-    {
+    SCHEMA = {
+      coerce: :bool,
+      color_scales: -> do
+        Config.magic_validate!(:color_scales, _1, {Symbol => Symbol})
+        if !(invalid = _1.values - Util::Scale::SCALES.keys).empty?
+          raise ArgumentError, "invalid color scale(s): #{invalid.inspect}"
+        end
+      end,
       color: :bool,
+      columns: :symbols,
       debug: :bool,
       delims: :bool,
-      digits: :int,
+      digits: (0..10),
+      headers: {sym: :str},
+      layout: -> do
+        return if _1 == true || _1 == false || _1.is_a?(Integer)
+        Config.magic_validate!(:layout, _1, {Symbol => Integer})
+      end,
       mark: :proc,
       placeholder: :str,
       row_numbers: :bool,
       save: :str,
+      search: -> do
+        if !(_1.is_a?(String) || _1.is_a?(Regexp))
+          raise ArgumentError, "expected string/regex"
+        end
+      end,
       separators: :bool,
       strftime: :str,
+      theme: %i[dark light ansi],
       title: :str,
       titleize: :bool,
       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
+    def initialize(options = {}, &block)
+      # assemble from OPTIONS, defaults and options
+      options = [OPTIONS, TableTennis.defaults, options].reduce { _1.merge(_2 || {}) }
+      options[:color] = Config.detect_color? if options[:color].nil?
+      options[:debug] = true if ENV["TT_DEBUG"]
+      options[:theme] = Config.detect_theme if options[:theme].nil?
+      super(SCHEMA, options, &block)
     end
 
     #
-    # complex writers
+    # override a few setters to coerce values
     #
 
     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
+      if value.is_a?(Array) || value.is_a?(Symbol)
+        value = Array(value).to_h { [_1, :g] }
       end
+      self[:color_scales] = value
     end
+    alias_method :color_scale=, :color_scales=
 
-    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}>"
+    def placeholder=(value)
+      value = "" if value.nil?
+      self[:placeholder] = value
     end
 
-    def to_h
-      OPTIONS.keys.to_h { [_1, self[_1]] }.compact
+    def title=(value)
+      value = value.to_s if value.is_a?(Symbol)
+      self[:title] = value
     end
 
-    protected
-
     #
-    # validations
+    # helpers
     #
 
-    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
+    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 _str(option, value)
-      case option
-      when :placeholder
-        value = "" if value.nil?
-      when :title
-        value = value.to_s if value.is_a?(Symbol)
-      end
-      validate(option, value) do
-        "expected string" if !value.is_a?(String)
+    def self.detect_theme
+      case terminal_dark?
+      when true, nil then :dark
+      when false then :light
       end
     end
 
-    def _sym(option, value)
-      validate(option, value) do
-        "expected symbol" if !value.is_a?(Symbol)
+    # is this a dark terminal?
+    def self.terminal_dark?
+      if (bg = Util::Termbg.bg)
+        Util::Colors.dark?(bg)
       end
     end
   end

data/lib/table_tennis/stage/format.rb

@@ -27,7 +27,7 @@ module TableTennis
             str ||= fn_default(value) || config.placeholder
 
             # look for markdown-style links
-            if (link = detect_link(str))
+            if (link = Util::Strings.hyperlink(str))
               str, data.links[[r, c]] = link
             end
 
@@ -46,16 +46,24 @@ module TableTennis
         @_memo_wise[__method__].tap { _1.clear if _1.length > 5000 }
 
         case value
-        when String then fmt_number(to_f(value), digits: config.digits) if Util::Identify.number?(value)
-        when Numeric then fmt_number(value, digits: config.digits)
+        when String
+          if config.coerce && Util::Identify.number?(value)
+            fmt_number(to_f(value), digits: config.digits)
+          end
+        when Numeric
+          fmt_number(value, digits: config.digits)
         end
       end
       memo_wise :fn_float
 
       def fn_int(value)
         case value
-        when String then fmt_number(to_i(value)) if Util::Identify.int?(value)
-        when Integer then fmt_number(value)
+        when String
+          if config.coerce && Util::Identify.int?(value)
+            fmt_number(to_i(value))
+          end
+        when Integer
+          fmt_number(value)
         end
       end
 
@@ -100,14 +108,6 @@ module TableTennis
         x
       end
 
-      def detect_link(str)
-        # fail fast, for speed
-        return unless str.length >= 6 && str[0] == "["
-        if str =~ /^\[([^\]]+)\]\(([^\)]+)\)$/
-          [$1, $2]
-        end
-      end
-
       # str to_xxx that are resistant to commas
       def to_f(str) = str.delete(",").to_f
       def to_i(str) = str.delete(",").to_i

data/lib/table_tennis/stage/layout.rb

@@ -37,7 +37,7 @@ module TableTennis
         columns.each { _1.width = _1.measure }
 
         # How much space is available, and do we already fit?
-        screen_width = IO.console.winsize[1]
+        screen_width = Util::Console.winsize[1]
         available = screen_width - chrome_width - FUDGE
         return if available >= data_width
 

data/lib/table_tennis/stage/render.rb

@@ -50,7 +50,7 @@ module TableTennis
         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)
+        line = paint(Util::Strings.center(title, title_width), title_style || :cell)
         paint("#{pipe} #{line} #{pipe}", Theme::BG)
       end
 
@@ -81,7 +81,7 @@ module TableTennis
         style ||= :cell
 
         # add ansi codes for search
-        value = value.gsub(search) { paint(_1, :search) } if search
+        value = search_cell(value) if search
 
         # add ansi codes for links
         if config.color && (link = data.links[[r, c]])
@@ -155,6 +155,14 @@ module TableTennis
         end
       end
       memo_wise :search
+
+      # add ansi codes for search
+      def search_cell(value)
+        return value if !value.match?(search)
+        # edge case - we can't gsub a painted cell, it can mess up the escaping
+        value = Util::Strings.unpaint(value)
+        value.gsub(search) { paint(_1, :search) }
+      end
     end
   end
 end

data/lib/table_tennis/table.rb

@@ -3,10 +3,6 @@
 #
 # 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.
@@ -41,7 +37,16 @@ module TableTennis
     def save(path)
       headers = column_names
       CSV.open(path, "wb", headers:, write_headers: true) do |csv|
-        rows.each { csv << _1 }
+        rows.each do |row|
+          # strip hyperlinks
+          row = row.map do |value|
+            if value.is_a?(String) && (h = Util::Strings.hyperlink(value))
+              value = h[1]
+            end
+            value
+          end
+          csv << row
+        end
       end
     end
 
@@ -54,7 +59,7 @@ module TableTennis
 
     # we cnan do a bit more config checking now
     def sanity!
-      %i[color_scales layout].each do |key|
+      %i[color_scales headers 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
@@ -71,9 +76,6 @@ module TableTennis
     #
     # 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

data/lib/table_tennis/table_data.rb

@@ -114,7 +114,7 @@ module TableTennis
     def debug(str)
       return if !config&.debug
       str = "[#{Time.now.strftime("%H:%M:%S")}] #{str}"
-      str = str.ljust(@debug_width ||= IO.console.winsize[1])
+      str = str.ljust(@debug_width ||= Util::Console.winsize[1])
       puts Paint[str, :white, :green]
     end
 

data/lib/table_tennis/theme.rb

@@ -101,9 +101,18 @@ module TableTennis
     # use osc 8 to create a terminal hyperlink. underline too
     def link(str, link)
       linked = "#{OSC_8}#{link}#{ST}#{str}#{OSC_8}#{ST}"
-      Paint[linked, :underline]
+      # underline if aren't on iterm
+      linked = Paint[linked, :underline] if term_program != :iterm
+      linked
     end
 
+    def term_program
+      if ENV["TERM_PROGRAM"] == "iTerm.app"
+        :iterm
+      end
+    end
+    memo_wise :term_program
+
     # for debugging, mostly
     def self.info
       sample = if !Config.detect_color?

data/lib/table_tennis/util/console.rb

@@ -0,0 +1,23 @@
+module TableTennis
+  module Util
+    # static wrapper around IO.console to handle the case where IO.console is nil
+    module Console
+      module_function
+
+      # supported when IO.console is nil
+      def winsize(...)
+        IO.console&.winsize(...) || [48, 80]
+      end
+
+      # not supported, don't call these
+      %i[fileno getbyte raw syswrite].each do |name|
+        define_method(name) do |*args, **kwargs, &block|
+          if !IO.console
+            raise "IO.console.#{name} not supported when IO.console is nil"
+          end
+          IO.console.send(name, *args, **kwargs, &block)
+        end
+      end
+    end
+  end
+end

data/lib/table_tennis/util/magic_options.rb

@@ -0,0 +1,285 @@
+#
+# Helper class for validated option processing. This is used by Config but could probably be a
+# custom gem at some point...
+#
+# MagicOptions is created with a `schema` defining a list of `attributes`. Each attribute has a
+# `name` and a `type`. `options` is a hash of values that will be validated against the schema.
+# MagicOptions adds getters and setters for each attribute, and also supports [] and []=. The
+# setters perform validation and raise ArgumentError if something is awry. Because setters always
+# validate, it is not possible to populate MagicOptions with invalid values.
+#
+# To use, subclass MagicOptions and construct with a schema:
+#
+#   class Config < MagicOptions
+#     def initialize
+#       super(
+#         first_name: :str,
+#         colors: :strings,
+#         customer: :bool,
+#         age: (20..90)
+#       )
+#     end
+#   end
+#
+# Then assign values:
+#
+#   config = Config.new
+#   config.colors = %w[red white blue]
+#   config.update!(first_name: "john", customer: false)
+#
+# Here are the supported attribute types:
+#
+# (1) A simple type like :bool, :int, :num, :float, :str or :sym.
+# (2) An array type like :bools, :ints, :nums, :floats, :strs, or :syms.
+# (3) A range, regexp or Class.
+# (4) A custom validation lambda. The lambda should raise an ArgumentError if
+#     the value is invalid.
+# (5) An array of possible values (typically numbers, strings, or symbols). The
+#     value must be one of those possibilities.
+# (6) A hash with one element { class => class }. This specifies the hash
+#     signature, and the value must be a hash where the keys and values are
+#     those classes.
+#
+# There is a bit of type coercion, but not much. For example, the string "true" or "1" will be
+# coerced to true for boolean options. Integers can be used when the schema calls for floats.
+#
+
+module TableTennis
+  module Util
+    class MagicOptions
+      #
+      # public api (also see [] and []=)
+      #
+
+      attr_accessor :magic_attributes, :magic_values
+
+      def initialize(schema, options = {}, &block)
+        @magic_attributes, @magic_values = {}, {}
+
+        if self.class == MagicOptions # rubocop:disable Style/ClassEqualityComparison
+          raise ArgumentError, "MagicOptions is an abstract class"
+        end
+
+        schema.each { magic_add_attribute(_1, _2) }
+        update!(options) if options
+        yield self if block_given?
+      end
+
+      def update!(hash) = hash.each { send("#{_1}=", _2) }
+      def to_h = magic_values.dup
+
+      def inspect
+        values = magic_values.compact.map { "#{_1}=#{_2.inspect}" }.join(", ")
+        "#<#{self.class} #{values}>"
+      end
+
+      #
+      # magic_add_attribute
+      #
+
+      def magic_add_attribute(name, type)
+        # resolve :boolean to :bool, :int => Integer class, etc.
+        type = if type.is_a?(Hash)
+          type.to_h { [self.class.magic_resolve(_1), self.class.magic_resolve(_2)] }
+        else
+          self.class.magic_resolve(type)
+        end
+
+        # sanity check for schema errors
+        if (error = magic_sanity(name, type))
+          raise ArgumentError, "MagicOptions schema #{name.inspect} #{error}"
+        end
+
+        # all is well
+        magic_attributes[name] = type
+        if !respond_to?(name)
+          define_singleton_method(name) { self[name] }
+        end
+        if type == :bool && !respond_to?("#{name}?")
+          define_singleton_method("#{name}?") { !!self[name] }
+        end
+        if !respond_to?("#{name}=")
+          define_singleton_method("#{name}=") { |value| self[name] = value }
+        end
+      end
+
+      # sanity check a name/type from the schema
+      def magic_sanity(name, type)
+        if !name.is_a?(Symbol)
+          return "attribute names must be symbols"
+        end
+        if !name.to_s.match?(/\A[a-z_][0-9a-z_]*\z/i)
+          return "attribute names must be valid method names"
+        end
+
+        case type
+        when :bool, :bools, :floats, :ints, :nums, :strs, :syms, Class, Proc, Range, Regexp
+          return
+        when Array
+          "must be an array of possible values" if type.empty?
+        when Hash
+          valid = type.length == 1 && type.first.all? { _1 == :bool || _1.is_a?(Class) }
+          "must be { class => class }" if !valid
+        else
+          "unknown schema type #{type.inspect}"
+        end
+      end
+
+      #
+      # magic_get/set
+      #
+
+      def magic_get(name)
+        raise ArgumentError, "unknown #{self.class}.#{name}" if !magic_attributes.key?(name)
+        magic_values[name]
+      end
+
+      def magic_set(name, value)
+        raise ArgumentError, "unknown #{self.class}.#{name}=" if !magic_attributes.key?(name)
+        magic_values[name] = self.class.magic_validate!(name, value, magic_attributes[name])
+      end
+
+      # these are part of the public api
+      alias_method :[], :magic_get
+      alias_method :[]=, :magic_set
+
+      #
+      # magic_validate! and static helpers
+      #
+
+      # validate name=value against type, raise on failure
+      def self.magic_validate!(name, value, type)
+        # we validate against coerced values, but squirrel away the original
+        # uncoerced in case we need to use it inside an error message
+        original, value = value, magic_coerce(value, type)
+        return if value.nil?
+
+        case type
+        when Array then validate_any_of(value, type)
+        when Class, :bool then validate_class(value, type)
+        when Hash then validate_hash(value, type)
+        when Proc then type.call(value)
+        when Range then validate_range(value, type)
+        when Regexp then validate_regexp(value, type)
+        when :bools, :floats, :ints, :nums, :strs, :syms then validate_array(value, type)
+        else
+          raise "impossible"
+        end
+        value
+      rescue ArgumentError => ex
+        # add context to msg if necessary
+        msg = ex.message
+        if !msg.include?("#{name} = #{original.inspect}")
+          msg = "#{self}.#{name} = #{original.inspect} failed, #{msg}"
+        end
+        raise ArgumentError, msg
+      end
+
+      #
+      # validators
+      #
+
+      def self.validate_any_of(value, possibilities)
+        if !possibilities.include?(value)
+          raise ArgumentError, "expected one of #{possibilities.inspect}"
+        end
+      end
+
+      def self.validate_class(value, klass)
+        if !magic_is_a?(value, klass)
+          raise ArgumentError, "expected #{magic_pretty(klass)}"
+        end
+      end
+
+      def self.validate_hash(value, hash_type)
+        kk, vk = hash_type.first
+        if !(value.is_a?(Hash) && value.all? { magic_is_a?(_1, kk) && magic_is_a?(_2, vk) })
+          raise ArgumentError, "expected hash of #{magic_pretty(kk)} => #{magic_pretty(vk)}"
+        end
+      end
+
+      def self.validate_range(value, range)
+        if !value.is_a?(Numeric) || !range.include?(value)
+          raise ArgumentError, "expected to be in range #{range.inspect}"
+        end
+      end
+
+      def self.validate_regexp(value, regexp)
+        if !value.is_a?(String) || !value.match?(regexp)
+          raise ArgumentError, "expected to be a string matching #{regexp}"
+        end
+      end
+
+      def self.validate_array(value, array_type)
+        klass = magic_resolve(array_type.to_s[..-2].to_sym)
+        if !(value.is_a?(Array) && value.all? { magic_is_a?(_1, klass) })
+          raise ArgumentError, "expected array of #{array_type}"
+        end
+      end
+
+      # coerce value into type. pretty conservative at the moment
+      def self.magic_coerce(value, type)
+        if type == :bool
+          case value
+          when true, 1, "1", "true" then value = true
+          when false, 0, "", "0", "false" then value = false
+          end
+        end
+        value
+      end
+
+      # like is_a?, but supports :bool and allows ints to be floats
+      def self.magic_is_a?(value, klass)
+        if klass == :bool
+          value == true || value == false
+        elsif klass == Float
+          value.is_a?(klass) || value.is_a?(Integer)
+        else
+          value.is_a?(klass)
+        end
+      end
+
+      MAGIC_ALIASES = {
+        boolean: :bool,
+        booleans: :bools,
+        bool: :bool,
+        bools: :bools,
+        float: Float,
+        floats: :floats,
+        int: Integer,
+        integer: Integer,
+        integers: :ints,
+        ints: :ints,
+        lambda: Proc,
+        num: Numeric,
+        number: Numeric,
+        numbers: :nums,
+        nums: :nums,
+        proc: Proc,
+        str: String,
+        string: String,
+        strings: :strs,
+        strs: :strs,
+        sym: Symbol,
+        symbol: Symbol,
+        symbols: :syms,
+        syms: :syms,
+      }
+
+      MAGIC_PRETTY = {
+        :bool => "boolean",
+        Float => "float",
+        Integer => "integer",
+        Numeric => "number",
+        String => "string",
+        Symbol => "symbol",
+      }
+
+      # pretty print a class (or :bool)
+      def self.magic_pretty(klass) = MAGIC_PRETTY[klass] || klass.to_s
+
+      # resolve :boolean to :bool, :int => Integer class, etc.
+      def self.magic_resolve(type) = MAGIC_ALIASES[type] || type
+    end
+  end
+end

data/lib/table_tennis/util/strings.rb

@@ -6,6 +6,9 @@ module TableTennis
 
       module_function
 
+      # does this string contain ansi codes?
+      def painted?(str) = str.match?(/\e/)
+
       # strip ansi codes
       def unpaint(str) = str.gsub(/\e\[[0-9;]*m/, "")
 
@@ -18,23 +21,55 @@ module TableTennis
         str
       end
 
-      def width(text)
-        simple?(text) ? text.length : Unicode::DisplayWidth.of(text)
+      # measure width of text, with support for emojis, painted/ansi strings, etc
+      def width(str)
+        if simple?(str)
+          str.length
+        elsif painted?(str)
+          unpaint(str).length
+        else
+          Unicode::DisplayWidth.of(str)
+        end
       end
 
-      def hyperlink(value)
-        if value =~ /^\[([^\]]*)\]\(([^\)]*)\)$/
+      # center text, like String#center but works with painted strings
+      def center(str, width)
+        # artificially inflate width to include escape codes
+        if painted?(str)
+          width += str.length - unpaint(str).length
+        end
+        str.center(width)
+      end
+
+      def hyperlink(str)
+        # fail fast, for speed
+        return unless str.length >= 6 && str[0] == "["
+        if str =~ /^\[(.*)\]\((.*)\)$/
           [$1, $2]
         end
       end
 
       # truncate a string based on the display width of the grapheme clusters.
-      # Should handle emojis and international characters
-      def truncate(text, stop)
-        if simple?(text)
-          return (text.length > stop) ? "#{text[0, stop - 1]}…" : text
+      # Should handle emojis and international characters. Painted strings too.
+      def truncate(str, stop)
+        if simple?(str)
+          (str.length > stop) ? "#{str[0, stop - 1]}…" : str
+        elsif painted?(str)
+          # generate truncated plain version
+          plain = truncate0(unpaint(str), stop)
+          # make a best effort to apply the colors
+          if (opening_codes = str[/\e\[(?:[0-9];?)+m/])
+            "#{opening_codes}#{plain}#{Paint::NOTHING}"
+          else
+            plain
+          end
+        else
+          truncate0(str, stop)
         end
+      end
 
+      # slow, but handles graphemes
+      def truncate0(text, stop)
         # get grapheme clusters, and attach zero width graphemes to the previous grapheme
         list = [].tap do |accum|
           text.grapheme_clusters.each do
@@ -59,8 +94,10 @@ module TableTennis
 
         text
       end
+      private_class_method :truncate0
 
-      SIMPLE = /\A[\x00-\x7F–—…·‘’“”•áéíñóúÓ]*\Z/
+      # note that escape \e (0x1b) is excluded
+      SIMPLE = /\A[\x00-\x1a\x1c-\x7F–—…·‘’“”•áéíñóúÓ]*\Z/
 
       # Is this a "simple" string? (no emojis, etc). Caches results for small
       # strings for performance reasons.

data/lib/table_tennis/util/termbg.rb

@@ -54,6 +54,8 @@ module TableTennis
           "bad TERM"
         elsif ENV["ZELLIJ"]
           "zellij"
+        elsif !IO.console
+          "no console"
         end
         if error
           debug("osc_supported? #{{host:, platform:, term:}} => #{error}")
@@ -75,7 +77,7 @@ module TableTennis
 
         debug("osc_query(#{attr})")
         begin
-          IO.console.raw do
+          Util::Console.raw do
             logs << "  IO.console.raw"
 
             # we send two messages - the cursor query is widely supported, so we
@@ -89,7 +91,7 @@ module TableTennis
             end.join
 
             logs << "  syswrite #{msg.inspect}"
-            IO.console.syswrite(msg)
+            Util::Console.syswrite(msg)
 
             # there should always be at least one response. If this is a response to
             # the cursor message, the first message didn't work
@@ -116,18 +118,18 @@ module TableTennis
       def read_term_response
         # fast forward to ESC
         loop do
-          return if !(ch = IO.console.getbyte&.chr)
+          return if !(ch = Util::Console.getbyte&.chr)
           break ch if ch == ESC
         end
         # next char should be either [ or ]
-        return if !(type = IO.console.getbyte&.chr)
+        return if !(type = Util::Console.getbyte&.chr)
         return if !(type == "[" || type == "]")
 
         # now read the response. note that the response can end in different ways
         # and we have to check for all of them
         buf = "#{ESC}#{type}"
         loop do
-          return if !(ch = IO.console.getbyte&.chr)
+          return if !(ch = Util::Console.getbyte&.chr)
           buf << ch
           break if type == "[" && buf.end_with?("R")
           break if type == "]" && buf.end_with?(BEL, ST)
@@ -162,7 +164,7 @@ module TableTennis
           return if !respond_to?(:tcgetpgrp)
         end
 
-        io = IO.console
+        io = Util::Console
         if (ttypgrp = tcgetpgrp(io.fileno)) <= 0
           debug("tcpgrp(#{io.fileno}) => #{ttypgrp}, errno=#{FFI.errno}")
           return

data/lib/table_tennis/version.rb

@@ -1,3 +1,3 @@
 module TableTennis
-  VERSION = "0.0.5"
+  VERSION = "0.0.7"
 end

data/lib/table_tennis.rb

@@ -9,6 +9,7 @@ require "unicode/display_width"
 
 # mixins must be at top
 require "table_tennis/util/inspectable"
+require "table_tennis/util/magic_options"
 
 require "table_tennis/column"
 require "table_tennis/config"
@@ -24,6 +25,7 @@ require "table_tennis/stage/painter"
 require "table_tennis/stage/render"
 
 require "table_tennis/util/colors"
+require "table_tennis/util/console"
 require "table_tennis/util/identify"
 require "table_tennis/util/scale"
 require "table_tennis/util/strings"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: table_tennis
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: ruby
 authors:
 - Adam Doppelt
 bindir: bin
 cert_chain: []
-date: 2025-04-28 00:00:00.000000000 Z
+date: 2025-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -106,8 +106,10 @@ files:
 - lib/table_tennis/table_data.rb
 - lib/table_tennis/theme.rb
 - lib/table_tennis/util/colors.rb
+- lib/table_tennis/util/console.rb
 - lib/table_tennis/util/identify.rb
 - lib/table_tennis/util/inspectable.rb
+- lib/table_tennis/util/magic_options.rb
 - lib/table_tennis/util/scale.rb
 - lib/table_tennis/util/strings.rb
 - lib/table_tennis/util/termbg.rb