table_tennis 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 03c38407a65288ded066cc1986f53453d8dafe6e51096ea597e843c8ad115afb
+  data.tar.gz: a76db1bbb2a0ef775a629f71f6f76c2ee5c67a42255ba9856c5ccb9f66bb89bf
+SHA512:
+  metadata.gz: 51d515f45a6f62d6ede57e5b8d752ccd5a637dc107d170e526693600d91e9a91988cef1ee570104c413951759cf673e80d569076544a137398ac09bf1b2735e7
+  data.tar.gz: 3e269c16f3a95e4e948d55d8713d5349d2e5b5527b97c0fd5722d8cee88e17f182078d720b9bafb6d233dc9feb76f209a8b17780549ad03468817dcaaeb2aedb

data/.github/workflows/test.yml

@@ -0,0 +1,26 @@
+name: test
+
+on:
+  push:
+    paths-ignore:
+      - README.md
+      - 'screenshots/**'
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    strategy:
+      max-parallel: 3
+      matrix:
+        os: [macos, ubuntu, windows]
+        ruby-version: [3.0, 3.4]
+    runs-on: ${{ matrix.os }}-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: taiki-e/install-action@just
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: ${{ matrix.ruby-version }}
+      - run: just ci

data/.gitignore

@@ -0,0 +1,5 @@
+.envrc
+.tool-versions
+.vscode
+*.gem
+terminals/

data/.rubocop.yml

@@ -0,0 +1,58 @@
+require:
+  - standard
+
+inherit_gem:
+  standard: config/ruby-3.3.yml
+  standard-custom: config/base.yml
+  standard-performance: config/base.yml
+
+plugins:
+  - standard-custom
+  - standard-performance
+  - rubocop-performance
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+
+#
+# fight with standardrb!
+#
+
+# we like these, don't remove
+Bundler/OrderedGems: { Enabled: true } # sort gems in gemfile
+Layout/EmptyLineBetweenDefs: { AllowAdjacentOneLineDefs: true }
+Lint/NonLocalExitFromIterator: { Enabled: false }
+Lint/RedundantDirGlobSort: { Enabled: true } # glob is already sorted
+Performance/RegexpMatch: { Enabled: false }
+Style/HashSyntax: { EnforcedShorthandSyntax: always } # use modern hash syntax
+Style/NestedTernaryOperator: { Enabled: false } # we do this sometimes
+Style/NonNilCheck: { Enabled: false } # allow x != nil for clarity
+Style/RedundantAssignment: { Enabled: false } # allows s=xxx;s=yyy;s
+Style/RedundantReturn: { Enabled: false } # sometines we do this while working on something
+Style/StringConcatenation: { Enabled: true } # prefer interpolation
+Style/TrailingCommaInArrayLiteral: { EnforcedStyleForMultiline: consistent_comma } # commas!!
+Style/TrailingCommaInHashLiteral: { EnforcedStyleForMultiline: consistent_comma } # commas!!
+
+#
+# These are rules that are not enabled by default (in standardrb) but we tend to
+# write code this way. We don't often trigger these, but it matches our style.
+#
+
+Lint/MissingSuper: { Enabled: true }
+Naming/FileName: { Enabled: true }
+Naming/MemoizedInstanceVariableName: { Enabled: true }
+Naming/MethodName: { Enabled: true }
+Performance/MapCompact: { Enabled: true }
+Performance/SelectMap: { Enabled: true }
+Style/BlockDelimiters: { Enabled: true }
+Style/CollectionCompact: { Enabled: true }
+Style/CollectionMethods: { Enabled: true }
+Style/HashEachMethods: { Enabled: true }
+Style/HashTransformKeys: { Enabled: true }
+Style/HashTransformValues: { Enabled: true }
+Style/MinMax: { Enabled: true }
+Style/PreferredHashMethods: { Enabled: true }
+Style/SelectByRegexp: { Enabled: true }
+Style/SymbolArray: { Enabled: true }
+Style/WordArray: { Enabled: true }

data/Gemfile

@@ -0,0 +1,14 @@
+source "https://rubygems.org"
+gemspec
+
+group :development, :test do
+  gem "amazing_print"
+  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
+end

data/Gemfile.lock

@@ -0,0 +1,122 @@
+PATH
+  remote: .
+  specs:
+    table_tennis (0.0.1)
+      csv (~> 3.3)
+      ffi (~> 1.17)
+      memo_wise (~> 1.11)
+      paint (~> 2.3)
+      unicode-display_width (~> 3.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    amazing_print (1.7.2)
+    ast (2.4.3)
+    coderay (1.1.3)
+    csv (3.3.2)
+    docile (1.4.1)
+    ffi (1.17.1)
+    ffi (1.17.1-aarch64-linux-gnu)
+    ffi (1.17.1-aarch64-linux-musl)
+    ffi (1.17.1-arm-linux-gnu)
+    ffi (1.17.1-arm-linux-musl)
+    ffi (1.17.1-arm64-darwin)
+    ffi (1.17.1-x86-linux-gnu)
+    ffi (1.17.1-x86-linux-musl)
+    ffi (1.17.1-x86_64-darwin)
+    ffi (1.17.1-x86_64-linux-gnu)
+    ffi (1.17.1-x86_64-linux-musl)
+    json (2.10.2)
+    language_server-protocol (3.17.0.4)
+    lint_roller (1.1.0)
+    memo_wise (1.11.0)
+    method_source (1.1.0)
+    minitest (5.25.5)
+    minitest-hooks (1.5.2)
+      minitest (> 5.3)
+    mocha (2.7.1)
+      ruby2_keywords (>= 0.0.5)
+    ostruct (0.6.1)
+    paint (2.3.0)
+    parallel (1.26.3)
+    parser (3.3.7.4)
+      ast (~> 2.4.1)
+      racc
+    prism (1.4.0)
+    pry (0.15.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    regexp_parser (2.10.0)
+    rubocop (1.73.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.43.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.24.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    standard (1.47.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.73.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.7)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.7.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.24.0)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  ruby
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  amazing_print
+  minitest
+  minitest-hooks
+  mocha
+  ostruct
+  pry
+  rake
+  simplecov
+  standard
+  table_tennis!
+
+BUNDLED WITH
+   2.6.5

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 gurgeous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,154 @@
+# TableTennis [![test](https://github.com/gurgeous/table_tennis/actions/workflows/test.yml/badge.svg)](https://github.com/gurgeous/table_tennis/actions/workflows/test.yml)
+
+TableTennis is a Ruby library for printing stylish tables in your terminal.
+
+```rb
+require "table_tennis"
+
+options = { title: "Star Wars People", zebra: true, color_scale: :height }
+puts TableTennis.new(Starwars.all, options)
+```
+
+Prints this lovely table in your terminal:
+
+![starwars](./screenshots/dark.png)
+
+### Installation
+
+```ruby
+# install gem
+$ gem install table_tennis
+
+# or add to your Gemfile
+gem "table_tennis"
+```
+
+### Important Features
+
+- auto-themes to pick light or dark based on your terminal background
+- auto-layout to fit your terminal window
+- auto-format floats and dates
+- auto-color numeric columns
+- titles, row numbers, zebra stripes...
+
+### Themes
+
+TableTennis examines the background color of your terminal to pick either the dark or light theme. You can also specify `:dark` or `:light` manually, or even an `:ansi` theme to use your terminal's default colors. This feature is [surprisingly complicated](https://github.com/gurgeous/table_tennis/blob/main/lib/table_tennis/util/termbg.rb).
+
+![themes](./screenshots/themes.png)
+
+### Rows (Your Data)
+
+Construct your table with an array of rows. Rows are hashes, ActiveRecord objects, structs, Data records, or anything that responds to `to_h`. It also supports oddballs like arrays (as rows) or even a single hash.
+
+```ruby
+puts TableTennis.new([{a: "hello", b: "world"}, {a: "foo", b: "bar"})
+puts TableTennis.new(Recipe.all.to_a)  # activerecord
+puts TableTennis.new(array_of_structs) # these use to_h
+puts TableTennis.new([[1,2],[3,4]]])   # array of arrays
+puts TableTennis.new(authors[0])       # single hash
+```
+
+### Big List of Options
+
+Here is a more complex example to get you started:
+
+```ruby
+options = {
+  color_scales: :commission,
+  columns: %i[ name commission bday phone ],
+  mark: -> { _1[:name] =~ /jane|john/i },
+  row_numbers: true,
+  save: "/tmp/people.csv",
+  search: "february",
+  title: "Employees",
+  zebra: true,
+}
+```
+
+| 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.
+| `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 |
+| `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. |
+| `zebra` | `false` | Turn on zebra stripes. |
+
+### Color Scales
+
+Color scales are useful for visualizing numeric columns. The `:color_scales` option can be a single column, an array of column names, or a hash from column names to colors. The scale defaults to `:b` (blue) if you don't use a hash.
+
+```ruby
+puts TableTennis.new(rows, color_scales: :price)
+puts TableTennis.new(rows, color_scales: [ :price, :quantity ])
+puts TableTennis.new(rows, color_scales: { price: :b, quantity: :r })
+```
+
+The color names are abbreviations, so `:gyr` goes from green to yellow to red. Here is the full list of supported color scales - `%i[g y r b gw yw rw bw rg gr gyr]`. For clarity this screenshot uses sorted columns, but note that TableTennis never does any sorting:
+
+![scales](./screenshots/scales.png)
+
+### Tips
+
+Use **mark** to highlight certain rows. Maybe you need to find the droids? Or **search** to highlight text. I almost always use **row numbers** and **zebra stripes** too.
+
+```ruby
+puts TableTennis.new(rows, mark: ->(row) { row[:homeworld] =~ /droids/i })
+puts TableTennis.new(rows, search: /hope.*empire/i })
+puts TableTennis.new(rows, row_numbers: true, zebra: true)
+```
+
+| `:mark` | `:search` | `:row_numbers` and `:zebra` |
+| - | - | - |
+| ![droids](./screenshots/droids.png) | ![hope](./screenshots/hope.png) | ![row numbers](./screenshots/row_numbers.png) |
+
+### Advanced Usage
+
+TableTennis can be configured a few different ways:
+
+```ruby
+
+TableTennis.defaults = { title: "All Tables Have This Name" }
+TableTennis.new(rows, title: "An Amazing Title")
+TableTennis.new do |t|
+  t.title = "Yet Another Way To Set Things Up"
+end
+```
+
+Tables usually get `puts` to $stdout, but there are other ways to do it:
+
+```ruby
+# Uses `to_s`, so there can be a pause before output shows up. Best for small tables.
+puts TableTennis.new(rows)
+
+# Write to `$stdout` one row at a time. Prefer this for tables over 10,000 rows.
+TableTennis.new(rows).render
+
+# Render to any I/O stream ($stdout/$stderr, an open file, StringIO...)
+TableTennis.new(rows).render(io)
+```
+
+### Similar Tools
+
+We love CSV tools and use them all the time! Here are a few that we rely on:
+
+- [bat](https://github.com/sharkdp/bat) - syntax highlights csv files, and many others
+- [csvlens](https://github.com/YS-L/csvlens) & [tidy viewer](https://github.com/alexhallam/tv) - great viewers for CSV files, beautiful and fun
+- [qsv](https://github.com/dathere/qsv) - filter, sort, combine, join... (a fork of [xsv](https://github.com/BurntSushi/xsv))
+- [Terminal::Table](https://github.com/tj/terminal-table) - wonderful rubygem for pretty printing tables, great for non-hash data like confusion matrices
+- [visidata](https://www.visidata.org) - the best for poking around large files, it does everything
+
+### Special Thanks
+
+- [termbg](https://github.com/dalance/termbg) and [termenv](https://github.com/muesli/termenv) for showing how to safely detect the terminal background color. These libraries are widely used for Rust/Go, but as far as I know nothing similar exists for Ruby.
+- The [Paint gem](https://github.com/janlelis/paint) for help with ansi colors.
+- Google Sheets for providing nice color scales

data/Rakefile

@@ -0,0 +1,12 @@
+require "bundler/setup"
+require "rake/testtask"
+
+Rake::TestTask.new do
+  # let the user pass *.rb on the command line
+  files = ARGV.grep(%r{^test/.*\.rb$}).sort
+  _1.test_files = files.empty? ? FileList["test/**/test_*.rb"] : files
+  # autoload test_helper
+  _1.ruby_opts = ["-w", "-r#{File.realpath("test/test_helper.rb")}"]
+end
+
+task default: :test

data/justfile

@@ -0,0 +1,75 @@
+
+# read gem version
+gemver := `grep -Eo "[0-9]+\.[0-9]+\.[0-9]+" lib/table_tennis/version.rb`
+
+#
+# dev
+#
+
+default:
+  @just --list
+
+check: lint test
+
+ci: check
+
+demo-watch *ARGS:
+  @watchexec --stop-timeout=0 --clear clear table-tennis-demo {{ARGS}}
+
+format:
+  @just banner format...
+  bundle exec rubocop -a
+
+image_optim:
+  @bundle exec image_optim --allow-lossy --svgo-precision=1 -r .
+
+lint:
+  @just banner lint...
+  bundle exec rubocop
+
+pry:
+  bundle exec pry -I lib -r table_tennis.rb
+
+test *ARGS:
+  @just banner rake test {{ARGS}}
+  @bundle exec rake test {{ARGS}}
+
+test-watch *ARGS:
+  @watchexec --stop-timeout=0 --clear clear just test "{{ARGS}}"
+
+#
+# coverage/profiling
+#
+
+coverage:
+  COVERAGE=1 just test
+  open /tmp/coverage/index.html
+
+#
+# gem tasks
+#
+
+# you can test locally from another project by dropping gem file into vendor/cache
+gem-push: check-git-status
+  @just banner gem build...
+  gem build table_tennis.gemspec
+  @just banner tag...
+  git tag -a "v{{gemver}}" -m "Tagging {{gemver}}"
+  git push --tags
+  @just banner gem push...
+  gem push "table_tennis-{{gemver}}.gem"
+
+#
+# util
+#
+
+banner *ARGS: (_banner BG_GREEN ARGS)
+warning *ARGS: (_banner BG_YELLOW ARGS)
+fatal *ARGS: (_banner BG_RED ARGS)
+  @exit 1
+_banner color *ARGS:
+  @msg=$(printf "[%s] %s" $(date +%H:%M:%S) "{{ARGS}}") ; \
+  printf "{{color+BOLD+WHITE}}%-72s{{ NORMAL }}\n" "$msg"
+
+check-git-status:
+  @if [ ! -z "$(git status --porcelain)" ]; then just fatal "git status is dirty, bailing."; fi

data/lib/table_tennis/column.rb

@@ -0,0 +1,41 @@
+module TableTennis
+  #
+  # A single column in a table. The data is actually stored in the rows, but it
+  # can be enumerated from here. Mostly used for layout calculations.
+  #
+
+  class Column
+    include Enumerable
+    prepend MemoWise
+
+    attr_reader :name
+    attr_accessor :header, :width
+
+    def initialize(name, data)
+      @name, @data = name, data
+      @header = name.to_s
+    end
+
+    def each(&block)
+      return to_enum(__method__) unless block_given?
+      @data.rows.each { yield(_1[name]) }
+      self
+    end
+
+    def each_index(&block)
+      return to_enum(__method__) unless block_given?
+      @data.rows.each_index { yield(_1) }
+    end
+
+    def map!(&block) = @data.rows.each { _1[name] = yield(_1[name]) }
+
+    def truncate(stop)
+      @header = Util::Strings.truncate(header, stop)
+      map! { Util::Strings.truncate(_1, stop) }
+    end
+
+    def measure
+      [2, max_by(&:length)&.length, header.length].max
+    end
+  end
+end