table_tennis 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '009a0c9bbb140d308d55441602f96a534e51d989259c70b2e3cc2661213252cb'
-  data.tar.gz: 6422661f90e1e6e15ddb67c0fff92d6d1c1f3d3454e95a57ae79652d83b981ca
+  metadata.gz: b141b15004b90e5acaf6f4ed92d7f71a49fbb8376875fd50cf5ed1d8e555c365
+  data.tar.gz: f9dd1e36fa97767addcce2abbfca0eb721137d6c87f0556f0ed79ca8677fa15c
 SHA512:
-  metadata.gz: af82ae82579222df273e5244c2dde9137547cce527b4c5e4b900feeb7129beb7d9b5d9ea80ae849f62ac79befd14c38be0f8e8c311a651f8dc63660b1953190a
-  data.tar.gz: 7eae197b20fe45f0b65f9987097e38233dac3ea113fcabbfd27011340a18910f9c8d701a3352cb482819f266391e98a0daaeec0857e966982e6d6ffcf2aa2121
+  metadata.gz: eba4146e9b2953bef53d958b7d3bab8d65f25be9c0011309cc511f3ecc254385dc3193f9f84c12c6d768010a9d7b4ae35d49530c6a2756906eb50aeb756d72db
+  data.tar.gz: f7d7262f3afb54a563a73d5e7279052e6dd2f4fb39a4e916994ee35f966b1f36ff7a45e22eb18619db43fe6cc516f0f34a714bb17614fcd03d1562a20fcd0ede

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:
 

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 = {
 }
 ```
 
+#### 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). |
-| `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. |
+| `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. |
-| `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. |
+| `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
 
@@ -163,6 +172,13 @@ We love CSV tools and use them all the time! Here are a few that we rely on:
 
 ### Changelog
 
+#### 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,6 +22,7 @@ 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
 

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: ->(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"
+        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(_1, {Symbol => Integer})
+      end,
       mark: :proc,
       placeholder: :str,
       row_numbers: :bool,
       save: :str,
+      search: -> do
+        if !(_1.is_a?(String) || _1.is_a?(Regexp))
+          "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
+      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 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
+    def placeholder=(value)
+      value = "" if value.nil?
+      self[:placeholder] = value
     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
+    def title=(value)
+      value = value.to_s if value.is_a?(Symbol)
+      self[:title] = value
     end
 
-    def search=(value)
-      @search = validate(:search, value) do
-        if !(value.is_a?(String) || value.is_a?(Regexp))
-          "expected string/regex"
-        end
-      end
-    end
-
-    def layout=(value)
-      @layout = validate(:layout, value) do
-        next if [true, false].include?(value) || value.is_a?(Integer)
-        if !value.is_a?(Hash)
-          "expected boolean, int or hash"
-        elsif value.keys.any? { !_1.is_a?(Symbol) }
-          "keys must be symbols"
-        elsif value.values.any? { !_1.is_a?(Integer) }
-          "values must be ints"
-        end
-      end
-    end
-
-    def [](key)
-      raise ArgumentError, "unknown TableTennis.#{key}" if !respond_to?(key)
-      send(key)
-    end
-
-    def []=(key, value)
-      raise ArgumentError, "unknown TableTennis.#{key}=" if !respond_to?(:"#{key}=")
-      send(:"#{key}=", value)
-    end
-
-    def inspect
-      options = to_h.map { "@#{_1}=#{_2.inspect}" }.join(", ")
-      "#<Config #{options}>"
-    end
-
-    def to_h
-      OPTIONS.keys.to_h { [_1, self[_1]] }.compact
-    end
-
-    protected
-
     #
-    # validations
+    # 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/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/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/magic_options.rb

@@ -0,0 +1,255 @@
+#
+# 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 lambda which should return an error string or nil.
+# (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)
+        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
+      end
+
+      # these are part of the public api
+      alias_method :[], :magic_get
+      alias_method :[]=, :magic_set
+
+      #
+      # magic_validate and static helpers
+      #
+
+      def self.magic_validate(value, type)
+        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
+        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

@@ -22,8 +22,10 @@ module TableTennis
         simple?(text) ? text.length : Unicode::DisplayWidth.of(text)
       end
 
-      def hyperlink(value)
-        if value =~ /^\[([^\]]*)\]\(([^\)]*)\)$/
+      def hyperlink(str)
+        # fail fast, for speed
+        return unless str.length >= 6 && str[0] == "["
+        if str =~ /^\[(.*)\]\((.*)\)$/
           [$1, $2]
         end
       end

data/lib/table_tennis/version.rb

@@ -1,3 +1,3 @@
 module TableTennis
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 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"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: table_tennis
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Adam Doppelt
 bindir: bin
 cert_chain: []
-date: 2025-04-28 00:00:00.000000000 Z
+date: 2025-05-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: csv
@@ -108,6 +108,7 @@ files:
 - lib/table_tennis/util/colors.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