table_tennis 0.0.6 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b141b15004b90e5acaf6f4ed92d7f71a49fbb8376875fd50cf5ed1d8e555c365
-  data.tar.gz: f9dd1e36fa97767addcce2abbfca0eb721137d6c87f0556f0ed79ca8677fa15c
+  metadata.gz: 2dea31d2827226b7c2a9a92414ef69a99eddecafd6dc8bb9865c975fa48a9f2a
+  data.tar.gz: 2fe778598f290d8ede809971ab3ddf9bc12c16fa913542dac795708145230759
 SHA512:
-  metadata.gz: eba4146e9b2953bef53d958b7d3bab8d65f25be9c0011309cc511f3ecc254385dc3193f9f84c12c6d768010a9d7b4ae35d49530c6a2756906eb50aeb756d72db
-  data.tar.gz: f7d7262f3afb54a563a73d5e7279052e6dd2f4fb39a4e916994ee35f966b1f36ff7a45e22eb18619db43fe6cc516f0f34a714bb17614fcd03d1562a20fcd0ede
+  metadata.gz: 964ac069a29278563120f105ae399b42cb086aa332ba2e47e2816142b5fab6af80acd91a03e7b69b746ca59c85541d64e71c56a3409304e009b33b0ff7887820
+  data.tar.gz: 06ab17c03ed9b367b3a668275d3ac5030f3c865222d851c5545ee757dbe525a67cae60f045554775589191168016f3aa4587862b79f28fae2bda0f2f4b7959e5

data/.github/workflows/test.yml

@@ -13,10 +13,10 @@ jobs:
       max-parallel: 3
       matrix:
         os: [macos, ubuntu, windows]
-        ruby-version: [3.0, 3.4]
+        ruby-version: [3.0, 3.4, 4.0]
     runs-on: ${{ matrix.os }}-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v7
       - uses: taiki-e/install-action@just
       - uses: ruby/setup-ruby@v1
         with:

data/.justfile

@@ -0,0 +1,85 @@
+set quiet := true
+
+default: test
+
+# check repo - lint & test
+check: lint test
+
+# for ci. don't bother linting on windows
+ci:
+  if [[ "{{os()}}" != "windows" ]]; then just lint ; fi
+  just test
+
+# check test coverage
+coverage:
+  COVERAGE=1 just test
+  open /tmp/coverage/index.html
+
+# format with rubocop
+fmt: (lint "-a")
+
+gem-local:
+  just banner rake install:local...
+  bundle exec rake install: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...
+  bundle exec rake release
+
+# optimize images
+image_optim:
+  # advpng/pngout are slow. consider --verbose as well
+  bundle exec image_optim --allow-lossy --svgo-precision=1 --no-advpng --no-pngout -r .
+
+# check for outdated deps
+outdated:
+  just banner Here are the easy ones:
+  bundle outdated --filter-minor || true
+  just banner The full list:
+  bundle outdated || true
+
+# lint with rubocop
+lint *ARGS:
+  just banner lint...
+  bundle exec rubocop {{ARGS}}
+
+# start pry with the lib loaded
+pry:
+  bundle exec pry -I lib -r table_tennis.rb
+
+# run tennis repeatedly
+tennis-watch *ARGS:
+  watchexec --stop-timeout=0 --clear clear tennis {{ARGS}}
+
+# run tests
+test *ARGS:
+  just banner rake test {{ARGS}}
+  bundle exec rake test {{ARGS}}
+
+# run tests repeatedly
+test-watch *ARGS:
+  watchexec --stop-timeout=0 --clear clear just test "{{ARGS}}"
+
+# create sceenshot using vhs
+vhs:
+  just banner "running vhs..."
+  vhs demo.tape
+  magick /tmp/dark.png -crop 1448x1004+18+16 screenshots/dark.png
+
+#
+# util
+#
+
+TRUWHITE := '\e[38;5;231m'
+GREEN    := '\e[48;2;064;160;043m'
+ORANGE   := '\e[48;2;251;100;011m'
+RED      := '\e[48;2;210;015;057m'
+
+banner +ARGS: (_banner GREEN ARGS)
+warning +ARGS: (_banner ORANGE ARGS)
+fatal +ARGS: (_banner RED ARGS)
+  exit 1
+_banner BG +ARGS:
+  printf '{{BOLD+TRUWHITE+BG}}[%s] %-72s {{NORMAL}}\n' "$(date +%H:%M:%S)" "{{ARGS}}"

data/.mise.toml

@@ -0,0 +1,9 @@
+[env]
+_.path = ['{{config_root}}/bin']
+
+[hooks]
+postinstall = ['bundle']
+
+[tools]
+just = "latest"
+ruby = "3.4"

data/AGENTS.md

@@ -0,0 +1,23 @@
+# Purpose
+
+TableTennis is a popular ruby gem for rendering ANSI-colored tables from csv-like rows (hash-ish objects). Beauty > performance, but keep small-table latency snappy.
+
+# Key flow
+
+- Public API: `TableTennis.new` -> `TableTennis::Table` (`lib/table_tennis/table.rb`).
+- Pipeline: `Format` -> `Layout` -> `Painter` -> `Render` (`lib/table_tennis/stage/*.rb`).
+- Data model: `TableData`, `Column`, `Row` (`lib/table_tennis/table_data.rb`, `lib/table_tennis/column.rb`, `lib/table_tennis/row.rb`).
+- Config/theming: `Config`, `Theme`, `Util::Colors/Console/Strings/Termbg` (`lib/table_tennis/config.rb`, `lib/table_tennis/theme.rb`, `lib/table_tennis/util/*`).
+
+# dev (prefer `just`)
+
+- `just test`
+- `just lint` / `just format`
+- `just check`
+
+# Style/conventions
+
+- Defaults and validation live in `Config` (`MagicOptions`).
+- Rendering cost is mostly in `Stage::Render` (ANSI/string work); memoization via `MemoWise` is used in hot paths.
+- Prefer short methods, short variable names, and comment lightly when code is complex
+- Ruby one-liners are find and even preferred for trivial methods

data/Gemfile

@@ -2,15 +2,15 @@ source "https://rubygems.org"
 gemspec
 
 group :development, :test do
-  gem "amazing_print", "~> 1.7"
-  gem "image_optim", "~> 0.31"
-  gem "image_optim_pack", "~> 0.12"
-  gem "minitest", "~> 5.25"
+  gem "amazing_print", "~> 2.0"
+  gem "image_optim", "~> 0.32"
+  gem "image_optim_pack", "~> 0.13"
+  gem "minitest", "~> 5.27"
   gem "minitest-hooks", "~> 1.5"
-  gem "mocha", "~> 2.7"
+  gem "mocha", "~> 3.1"
   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
+  gem "rake", "~> 13.4"
+  gem "simplecov", "~> 1.0", require: false
+  gem "standard", "~> 1.56", require: false, platform: :mri
 end

data/README.md

@@ -69,32 +69,32 @@ options = {
 
 #### 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. |
+| 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.|
+| 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
 
@@ -120,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
@@ -172,6 +172,18 @@ We love CSV tools and use them all the time! Here are a few that we rely on:
 
 ### Changelog
 
+#### 1.0.0 (Jul '26)
+
+- better truncation with ansi colors, inspired by strings-truncation gem
+- set timeout in io/console getch to make OSC query more resilient
+- truncation no longer supports graphemes (breaking)
+- added AGENTS.md and mise.toml
+
+#### 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

data/lib/table_tennis/config.rb

@@ -30,11 +30,10 @@ module TableTennis
 
     SCHEMA = {
       coerce: :bool,
-      color_scales: ->(value) do
-        if (error = Config.magic_validate(value, {Symbol => Symbol}))
-          error
-        elsif value.values.any? { !Util::Scale::SCALES.include?(_1) }
-          "values must be the name of a color scale"
+      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,
@@ -45,7 +44,7 @@ module TableTennis
       headers: {sym: :str},
       layout: -> do
         return if _1 == true || _1 == false || _1.is_a?(Integer)
-        Config.magic_validate(_1, {Symbol => Integer})
+        Config.magic_validate!(:layout, _1, {Symbol => Integer})
       end,
       mark: :proc,
       placeholder: :str,
@@ -53,7 +52,7 @@ module TableTennis
       save: :str,
       search: -> do
         if !(_1.is_a?(String) || _1.is_a?(Regexp))
-          "expected string/regex"
+          raise ArgumentError, "expected string/regex"
         end
       end,
       separators: :bool,
@@ -83,6 +82,7 @@ module TableTennis
       end
       self[:color_scales] = value
     end
+    alias_method :color_scale=, :color_scales=
 
     def placeholder=(value)
       value = "" if value.nil?

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_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/util/colors.rb

@@ -489,6 +489,7 @@ module TableTennis
 
       # print all colors to $stdout, helps with creating themes
       def spectrum
+        # paint goes bg, fg
         max = NAMED.keys.map(&:length).max
         fmt = " %-#{max}s %s  %0.3f "
         NAMED.each do |name, color|
@@ -500,6 +501,17 @@ module TableTennis
           puts "#{str1}#{str2}#{str3}#{str4}"
         end
 
+        # with 256 - 38/5/fg or 38/5/bg
+        fmt = " ansi256 %d"
+        (1..256).each do |color|
+          str = sprintf(" ansi256 %3d ", color)
+          str1 = Paint[str, 38, 5, color, "white"]
+          str2 = Paint[str, 38, 5, color, "black"]
+          str3 = Paint["  white   ", "white", 48, 5, color]
+          str4 = Paint[" black  ", "black", 48, 5, color]
+          puts "#{str1}#{str2}#{str3}#{str4}"
+        end
+
         fmt = " ansi %-6s %-8s "
         colors = Paint::ANSI_COLORS_FOREGROUND.keys
         puts

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 getch 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

@@ -32,7 +32,8 @@
 # (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 lambda which should return an error string or nil.
+# (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
@@ -135,15 +136,7 @@ module TableTennis
 
       def magic_set(name, value)
         raise ArgumentError, "unknown #{self.class}.#{name}=" if !magic_attributes.key?(name)
-        type = magic_attributes[name]
-        value = self.class.magic_coerce(value, type)
-        if !value.nil? && (error = MagicOptions.magic_validate(value, type))
-          if !type.is_a?(Proc)
-            error = "#{error}, got #{value.inspect}"
-          end
-          raise ArgumentError, "#{self.class}.#{name}= #{error}"
-        end
-        magic_values[name] = value
+        magic_values[name] = self.class.magic_validate!(name, value, magic_attributes[name])
       end
 
       # these are part of the public api
@@ -151,39 +144,76 @@ module TableTennis
       alias_method :[]=, :magic_set
 
       #
-      # magic_validate and static helpers
+      # magic_validate! and static helpers
       #
 
-      def self.magic_validate(value, type)
+      # 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
-          "expected one of #{type.inspect}" if !type.include?(value)
-        when Class, :bool
-          "expected #{magic_pretty(type)}" if !magic_is_a?(value, type)
-        when Hash
-          name_klass, value_klass = type.first
-          valid = value.is_a?(Hash) && value.all? { magic_is_a?(_1, name_klass) && magic_is_a?(_2, value_klass) }
-          "expected hash of #{magic_pretty(name_klass)} => #{magic_pretty(value_klass)}" if !valid
-        when Proc
-          ret = type.call(value)
-          case ret
-          when String, false, nil then ret
-          else
-            puts "warning: MagicOptions.proc should ONLY return error string or nil/false, not #{ret.inspect}"
-            ret.to_s
-          end
-        when Range
-          if !value.is_a?(Numeric) || !type.include?(value)
-            "expected to be in range #{type.inspect}"
-          end
-        when Regexp
-          if !value.is_a?(String) || !value.match?(type)
-            "expected to be a string matching #{type.inspect}"
-          end
-        when :bools, :floats, :ints, :nums, :strs, :syms
-          klass = magic_resolve(type.to_s[..-2].to_sym)
-          valid = value.is_a?(Array) && value.all? { magic_is_a?(_1, klass) }
-          "expected array of #{type}" if !valid
+        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
 

data/lib/table_tennis/util/strings.rb

@@ -6,8 +6,13 @@ module TableTennis
 
       module_function
 
+      ANSI_CODE = /\e\[[0-9;]*m/
+
+      # does this string contain ansi codes?
+      def painted?(str) = str.match?(/\e/)
+
       # strip ansi codes
-      def unpaint(str) = str.gsub(/\e\[[0-9;]*m/, "")
+      def unpaint(str) = str.gsub(ANSI_CODE, "")
 
       # similar to rails titleize
       def titleize(str)
@@ -18,8 +23,24 @@ 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
+
+      # 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)
@@ -30,39 +51,55 @@ module TableTennis
         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
+      ELLIPSIS = "…"
+      INVISIBLE = /\A(\e\[[0-9;]*m|\u200B)*\z/
+
+      # Truncate a string based on the display width of characters. Does not
+      # attempt to handle graphemes. Should handle emojis and international
+      # characters. Painted strings too.
+      def truncate(str, stop)
+        if str.bytesize <= stop
+          str
+        elsif simple?(str)
+          (str.length <= stop) ? str : "#{str[0, stop - 1]}#{ELLIPSIS}"
+        else
+          truncate0(str, stop)
         end
+      end
 
-        # get grapheme clusters, and attach zero width graphemes to the previous grapheme
-        list = [].tap do |accum|
-          text.grapheme_clusters.each do
-            if width(_1) == 0 && !accum.empty?
-              accum[-1] = "#{accum[-1]}#{_1}"
-            else
-              accum << _1
+      # This is a slower truncate to handle ansi colors and wide characters like
+      # emojis. Inspired by piotrmurach/strings-truncation
+      def truncate0(text, stop)
+        [].tap do |buf|
+          scan, len, painting = StringScanner.new(text), 0, false
+          until scan.eos?
+            # are we looking at an ansi code?
+            if scan.scan(ANSI_CODE)
+              buf << scan.matched
+              painting = scan.matched != Paint::NOTHING
+              next
             end
-          end
-        end
 
-        width = 0
-        list.each_index do
-          w = Unicode::DisplayWidth.of(list[_1])
-          next if (width += w) <= stop
+            # what's next?
+            ch = scan.getch
 
-          # we've gone too far. do we need to pop for the ellipsis?
-          text = list[0, _1]
-          text.pop if width - w == stop
-          return "#{text.join}…"
-        end
+            # done? append one final char, possible an ELLIPSIS
+            len += Unicode::DisplayWidth.of(ch)
+            if len >= stop
+              buf << (scan.check(INVISIBLE) ? ch : ELLIPSIS)
+              break
+            end
 
-        text
+            # keep going
+            buf << ch
+          end
+          buf << Paint::NOTHING if painting
+        end.join
       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 = getch)
           break ch if ch == ESC
         end
         # next char should be either [ or ]
-        return if !(type = IO.console.getbyte&.chr)
+        return if !(type = getch)
         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 = getch)
           buf << ch
           break if type == "[" && buf.end_with?("R")
           break if type == "]" && buf.end_with?(BEL, ST)
@@ -136,6 +138,10 @@ module TableTennis
       end
       private_class_method :read_term_response
 
+      # get the next character, with a 100ms timeout
+      def getch = Util::Console.getch(min: 0, time: 0.1)
+      private_class_method :read_term_response
+
       #
       # color math
       #
@@ -162,7 +168,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
@@ -180,6 +186,7 @@ module TableTennis
       def load_ffi!
         module_eval do
           extend FFI::Library
+
           ffi_lib "c"
           attach_function :tcgetpgrp, %i[int], :int32
           debug("ffi attach libc.tcgetpgrp => success")
@@ -202,7 +209,9 @@ module TableTennis
       private_class_method :env_colorfgbg
 
       def debug(s)
-        puts "termbg: #{s}" if ENV["TT_DEBUG"]
+        return if !ENV["TT_DEBUG"]
+        $stderr.write "termbg: #{s}\r\n"
+        $stderr.flush
       end
       private_class_method :debug
     end

data/lib/table_tennis/version.rb

@@ -1,3 +1,3 @@
 module TableTennis
-  VERSION = "0.0.6"
+  VERSION = "1.0.0"
 end

data/lib/table_tennis.rb

@@ -25,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"

data/table_tennis.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |s|
   # gem dependencies
   s.add_dependency "csv", "~> 3.3" # required for Ruby 3.4+
   s.add_dependency "ffi", "~> 1.17" # required for Ruby 3.2+
-  s.add_dependency "memo_wise", "~> 1.11"
+  s.add_dependency "memo_wise", "~> 1.13"
   s.add_dependency "paint", "~> 2.3"
-  s.add_dependency "unicode-display_width", "~> 3.1"
+  s.add_dependency "unicode-display_width", "~> 3.2"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: table_tennis
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 1.0.0
 platform: ruby
 authors:
 - Adam Doppelt
 bindir: bin
 cert_chain: []
-date: 2025-05-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '1.13'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '1.13'
 - !ruby/object:Gem::Dependency
   name: paint
   requirement: !ruby/object:Gem::Requirement
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '3.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: '3.2'
 email: amd@gurge.com
 executables: []
 extensions: []
@@ -86,13 +86,15 @@ extra_rdoc_files: []
 files:
 - ".github/workflows/test.yml"
 - ".gitignore"
+- ".justfile"
+- ".mise.toml"
 - ".rubocop.yml"
+- AGENTS.md
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
 - demo.tape
-- justfile
 - lib/table_tennis.rb
 - lib/table_tennis/column.rb
 - lib/table_tennis/config.rb
@@ -106,6 +108,7 @@ 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
@@ -143,7 +146,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Stylish tables in your terminal.
 test_files: []

data/justfile

@@ -1,72 +0,0 @@
-default: test
-
-# check repo - lint & test
-check: lint test
-
-# for ci. don't bother linting on windows
-ci:
-  @if [[ "{{os()}}" != "windows" ]]; then just lint ; fi
-  @just test
-
-# check test coverage
-coverage:
-  COVERAGE=1 just test
-  open /tmp/coverage/index.html
-
-# format with rubocop
-format: (lint "-a")
-
-gem-local:
-  @just _banner rake install:local...
-  bundle exec rake install: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
-
-# optimize images
-image_optim:
-  @# advpng/pngout are slow. consider --verbose as well
-  @bundle exec image_optim --allow-lossy --svgo-precision=1 --no-advpng --no-pngout -r .
-
-# lint with rubocop
-lint *ARGS:
-  @just _banner lint...
-  bundle exec rubocop {{ARGS}}
-
-# start pry with the lib loaded
-pry:
-  bundle exec pry -I lib -r table_tennis.rb
-
-# run tennis repeatedly
-tennis-watch *ARGS:
-  @watchexec --stop-timeout=0 --clear clear tennis {{ARGS}}
-
-# run tests
-test *ARGS:
-  @just _banner rake test {{ARGS}}
-  @bundle exec rake test {{ARGS}}
-
-# run tests repeatedly
-test-watch *ARGS:
-  watchexec --stop-timeout=0 --clear clear just test "{{ARGS}}"
-
-# create sceenshot using vhs
-vhs:
-  @just _banner "running vhs..."
-  vhs demo.tape
-  magick /tmp/dark.png -crop 1448x1004+18+16 screenshots/dark.png
-
-#
-# util
-#
-
-_banner *ARGS: (_message BG_GREEN ARGS)
-_warning *ARGS: (_message BG_YELLOW ARGS)
-_fatal *ARGS: (_message BG_RED ARGS)
-  @exit 1
-_message color *ARGS:
-  @msg=$(printf "[%s] %s" $(date +%H:%M:%S) "{{ARGS}}") ; \
-  printf "{{color+BOLD+WHITE}}%-72s{{ NORMAL }}\n" "$msg"