table_tennis 0.0.7 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85ab2cbb42c928e7231529feaa15416f752b3efa3ca13d0ba54331b79cb41cc0
-  data.tar.gz: bbd1d0477437ab63c0302a8796ca058eb94a5084595a190032695188680214ef
+  metadata.gz: 2dea31d2827226b7c2a9a92414ef69a99eddecafd6dc8bb9865c975fa48a9f2a
+  data.tar.gz: 2fe778598f290d8ede809971ab3ddf9bc12c16fa913542dac795708145230759
 SHA512:
-  metadata.gz: 7729436cacaa34103047f9d039e1a81626ad8b9f86b33062e3e8ab58067aa69bc56242d19e7861ec44284c6e277b3daf32966129c0d41da7b389dce591371ee0
-  data.tar.gz: 97165044e352b52af3b31870b1999624a4a3b3f6dd8624cd69a9935d594461a1842568973fb8a101438d4a26b6ddc2df754ff6b88fcc5f61a982894fb33c329c
+  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@v4
+      - 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

@@ -172,6 +172,13 @@ 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)

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

@@ -10,7 +10,7 @@ module TableTennis
       end
 
       # not supported, don't call these
-      %i[fileno getbyte raw syswrite].each do |name|
+      %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"

data/lib/table_tennis/util/strings.rb

@@ -6,11 +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)
@@ -49,50 +51,50 @@ module TableTennis
         end
       end
 
-      # truncate a string based on the display width of the grapheme clusters.
-      # Should handle emojis and international characters. Painted strings too.
+      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 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
+        if str.bytesize <= stop
+          str
+        elsif simple?(str)
+          (str.length <= stop) ? str : "#{str[0, stop - 1]}#{ELLIPSIS}"
         else
           truncate0(str, stop)
         end
       end
 
-      # slow, but handles graphemes
+      # This is a slower truncate to handle ansi colors and wide characters like
+      # emojis. Inspired by piotrmurach/strings-truncation
       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
-            if width(_1) == 0 && !accum.empty?
-              accum[-1] = "#{accum[-1]}#{_1}"
-            else
-              accum << _1
+        [].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
 

data/lib/table_tennis/util/termbg.rb

@@ -118,18 +118,18 @@ module TableTennis
       def read_term_response
         # fast forward to ESC
         loop do
-          return if !(ch = Util::Console.getbyte&.chr)
+          return if !(ch = getch)
           break ch if ch == ESC
         end
         # next char should be either [ or ]
-        return if !(type = Util::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 = Util::Console.getbyte&.chr)
+          return if !(ch = getch)
           buf << ch
           break if type == "[" && buf.end_with?("R")
           break if type == "]" && buf.end_with?(BEL, ST)
@@ -138,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
       #
@@ -182,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")
@@ -204,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.7"
+  VERSION = "1.0.0"
 end

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.7
+  version: 1.0.0
 platform: ruby
 authors:
 - Adam Doppelt
 bindir: bin
 cert_chain: []
-date: 2025-08-06 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
@@ -144,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...
-  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 .
-
-# 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"