fatty 0.99.0

data/lib/fatty/ansi.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+require_relative "ansi/renderer"
+
+module Fatty
+  module Ansi
+  end
+end
+
+module Fatty
+  # Parse ANSI escape sequences (primarily SGR, i.e. "\e[...m") into styled text
+  # segments. This is intentionally curses-agnostic: the renderer/context decides
+  # how to map Style -> terminal attributes / color pairs.
+  #
+  # Supported SGR:
+  # - 0 reset
+  # - 1 bold
+  # - 22 normal intensity (clears bold)
+  # - 7 reverse
+  # - 27 reverse off
+  # - 30-37 / 90-97 foreground (16-color)
+  # - 40-47 / 100-107 background (16-color)
+  # - 38;5;n foreground (256-color index)
+  # - 48;5;n background (256-color index)
+  #
+  # Everything else is ignored (but does not break parsing).
+  module Ansi
+    ESC = "\e"
+    CSI = "#{ESC}["
+    COMBINING_MARK_RE = /\p{M}/
+
+    ANSI_ESCAPE = %r{
+      \e\[ [0-9;?]* [A-Za-z]   | # CSI sequences
+      \e\] .*? (?:\a|\e\\)     | # OSC sequences
+      \e[@-Z\\-_]                # single-char escapes
+    }x
+
+    Style = Struct.new(
+      :fg,
+      :bg,
+      :bold,
+      :italic,
+      :underline,
+      :strike,
+      :reverse,
+      keyword_init: true,
+    ) do
+      def dup
+        self.class.new(
+          fg: fg,
+          bg: bg,
+          bold: bold,
+          italic: italic,
+          underline: underline,
+          strike: strike,
+          reverse: reverse,
+        )
+      end
+
+      def normalize!
+        self.bold = !!bold
+        self.italic = !!italic
+        self.underline = !!underline
+        self.strike = !!strike
+        self.reverse = !!reverse
+        self
+      end
+
+      def self.default
+        new(
+          fg: nil,
+          bg: nil,
+          bold: false,
+          italic: false,
+          underline: false,
+          strike: false,
+          reverse: false,
+        )
+      end
+    end
+
+    # Remove any ANSI escape sequences from text.
+    def self.strip(text)
+      text.to_s.gsub(ANSI_ESCAPE, "")
+    end
+
+    # Public: segment a string into [[text, Style], ...]
+    #
+    # The returned Style objects are independent copies; you can safely mutate
+    # them downstream if you want.
+    def self.segment(str, base: nil)
+      s = str.to_s
+      style = (base ? base.dup : Style.default).normalize!
+
+      out = []
+      buf = +""
+
+      i = 0
+      n = s.bytesize
+      while i < n
+        if s.getbyte(i) == 27 # ESC
+          # Flush buffered text before processing escape
+          unless buf.empty?
+            out << [buf, style.dup]
+            buf = +""
+          end
+
+          consumed = consume_escape!(s, i, style)
+          if consumed > 0
+            i += consumed
+          else
+            # Not a recognized/complete escape; treat ESC as literal.
+            buf << ESC
+            i += 1
+          end
+        else
+          buf << s.byteslice(i, 1)
+          i += 1
+        end
+      end
+
+      out << [buf, style.dup] unless buf.empty?
+      merge_adjacent_segments(out)
+    end
+
+    def self.merge_adjacent_segments(segments)
+      return segments if segments.length <= 1
+
+      merged = []
+      segments.each do |text, st|
+        if merged.empty?
+          merged << [text.dup, st]
+        else
+          prev_text, prev_st = merged[-1]
+          if same_style?(prev_st, st)
+            prev_text << text
+          else
+            merged << [text.dup, st]
+          end
+        end
+      end
+
+      merged
+    end
+
+    def self.same_style?(a, b)
+      a.fg == b.fg &&
+        a.bg == b.bg &&
+        a.bold == b.bold &&
+        a.italic == b.italic &&
+        a.underline == b.underline &&
+        a.strike == b.strike &&
+        a.reverse == b.reverse
+    end
+
+    # Internal: attempts to consume an ANSI escape starting at position i.
+    # Returns number of bytes consumed, or 0 if not recognized.
+    def self.consume_escape!(s, i, style)
+      consumed = 0
+
+      # Only support CSI sequences for now: ESC '[' ... final
+      if s.bytesize >= i + 2 && s.getbyte(i + 1) == 91 # '['
+        # We only actively handle SGR: ... 'm'
+        j = i + 2
+        params = +""
+
+        while j < s.bytesize
+          b = s.getbyte(j)
+          if b.between?(48, 57) || b == 59 # 0-9 or ';'
+            params << b
+            j += 1
+          else
+            final = b
+            consumed = (j - i) + 1
+            if final == 109 # 'm'
+              apply_sgr!(style, parse_params(params))
+            end
+            break
+          end
+        end
+      end
+      consumed
+    end
+
+    def self.parse_params(param_str)
+      # SGR with empty params means reset
+      parts =
+        if param_str.empty?
+          ["0"]
+        else
+          param_str.split(";")
+        end
+
+      parts.map do |p|
+        p = "0" if p.nil? || p.empty?
+        begin
+          Integer(p, 10)
+        rescue
+          0
+        end
+      end
+    end
+
+    def self.apply_sgr!(style, params)
+      params = [0] if params.empty?
+      i = 0
+      while i < params.length
+        code = params[i].to_i
+        case code
+        when 0
+          style.fg = nil
+          style.bg = nil
+          style.bold = false
+          style.italic = false
+          style.underline = false
+          style.strike = false
+          style.reverse = false
+        when 1
+          style.bold = true
+        when 3
+          style.italic = true
+        when 4
+          style.underline = true
+        when 7
+          style.reverse = true
+        when 9
+          style.strike = true
+        when 22
+          style.bold = false
+        when 23
+          style.italic = false
+        when 24
+          style.underline = false
+        when 27
+          style.reverse = false
+        when 29
+          style.strike = false
+        when 30..37
+          style.fg = code - 30
+        when 39
+          style.fg = nil
+        when 40..47
+          style.bg = code - 40
+        when 49
+          style.bg = nil
+        when 90..97
+          style.fg = code - 90 + 8
+        when 100..107
+          style.bg = code - 100 + 8
+        when 38
+          if params[i + 1].to_i == 5 && params[i + 2]
+            style.fg = params[i + 2].to_i
+            i += 2
+          elsif params[i + 1].to_i == 2 && params[i + 2] && params[i + 3] && params[i + 4]
+            style.fg = [params[i + 2].to_i, params[i + 3].to_i, params[i + 4].to_i]
+            i += 4
+          end
+        when 48
+          if params[i + 1].to_i == 5 && params[i + 2]
+            style.bg = params[i + 2].to_i
+            i += 2
+          elsif params[i + 1].to_i == 2 && params[i + 2] && params[i + 3] && params[i + 4]
+            style.bg = [params[i + 2].to_i, params[i + 3].to_i, params[i + 4].to_i]
+            i += 4
+          end
+        end
+        i += 1
+      end
+      style.normalize!
+    end
+
+    def self.sgr_for(style)
+      codes = []
+      codes << 1 if style.bold
+      codes << 3 if style.italic
+      codes << 4 if style.underline
+      codes << 9 if style.strike
+      codes << 7 if style.reverse
+
+      if style.fg
+        if style.fg.between?(0, 7)
+          codes << 30 + style.fg
+        elsif style.fg.between?(8, 15)
+          codes << 90 + (style.fg - 8)
+        else
+          codes.push(38, 5, style.fg)
+        end
+      end
+
+      if style.bg
+        if style.bg.between?(0, 7)
+          codes << 40 + style.bg
+        elsif style.bg.between?(8, 15)
+          codes << 100 + (style.bg - 8)
+        else
+          codes.push(48, 5, style.bg)
+        end
+      end
+
+      if codes.empty?
+        ""
+      else
+        "\e[#{codes.join(';')}m"
+      end
+    end
+
+    def self.plain_text(str)
+      segment(str).map { |text, _style| text }.join
+    end
+
+    # Return the screen width taken up by an ANSI-encoded sequence, taking
+    # into account Unicode combining characters.
+    def self.visible_length(str)
+      segment(str.to_s).sum do |segment_text, _style|
+        segment_text.each_char.count { |ch| visible_char?(ch) }
+      end
+    end
+
+    # Don't count a "combining character" as visible in the sense that it
+    # contributes to width.  It overlays the prior character so it does not
+    # add to the visible width.
+    def self.visible_char?(ch)
+      !ch.match?(COMBINING_MARK_RE)
+    end
+
+    def self.truncate_visible(text, max_width)
+      max_width = max_width.to_i
+      return "" if max_width <= 0
+
+      out = +""
+      visible = 0
+      scanner = StringScanner.new(text.to_s)
+
+      until scanner.eos? || visible >= max_width
+        if (esc = scanner.scan(ANSI_ESCAPE))
+          out << esc
+        else
+          ch = scanner.getch
+          width = visible_length(ch)
+          break if visible + width > max_width
+
+          out << ch
+          visible += width
+        end
+      end
+      out
+    end
+
+    private_class_method :consume_escape!, :parse_params, :apply_sgr!
+    private_class_method :merge_adjacent_segments, :same_style?, :sgr_for
+  end
+end

data/lib/fatty/colors/color.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+module Fatty
+  module Color
+    DEFAULT_INDEX = -1
+
+    # Expected location for a bundled X11 rgb.txt (you provide it in the repo).
+    # Recommended path:
+    #   lib/fatty/color/rgb.txt
+    RGB_TXT_PATH = File.expand_path("rgb.txt", __dir__)
+
+    # ANSI 0..15 names (de-facto standard names)
+    ANSI_NAMES = {
+      "black" => 0,
+      "red" => 1,
+      "green" => 2,
+      "yellow" => 3,
+      "blue" => 4,
+      "magenta" => 5,
+      "cyan" => 6,
+      "white" => 7,
+      "bright_black" => 8,
+      "bright_red" => 9,
+      "bright_green" => 10,
+      "bright_yellow" => 11,
+      "bright_blue" => 12,
+      "bright_magenta" => 13,
+      "bright_cyan" => 14,
+      "bright_white" => 15,
+      "gray" => 8,
+      "grey" => 8,
+      "bright_gray" => 15,
+      "bright_grey" => 15,
+      "default" => DEFAULT_INDEX,
+    }.freeze
+
+    # Small alias set (xterm-256 indices). Keep this small + opinionated.
+    # Users can always use integers/hex/X11 names.
+    ALIASES_256 = {
+      "navy" => 17,
+      "dark_blue" => 18,
+      "orange" => 208,
+      "pink" => 205,
+      "violet" => 141,
+      "sky" => 117,
+      "teal" => 37,
+      "lime" => 118,
+      "dark_grey" => 238,
+      "dark_gray" => 238,
+      "grey" => 244,
+      "gray" => 244,
+      "light_grey" => 250,
+      "light_gray" => 250,
+    }.freeze
+
+    # Approximate RGB for xterm-style ANSI 0..15.
+    # Used only when down-mapping to <=16 colors.
+    ANSI_RGB = {
+      0 => [0, 0, 0],
+      1 => [205, 0, 0],
+      2 => [0, 205, 0],
+      3 => [205, 205, 0],
+      4 => [0, 0, 238],
+      5 => [205, 0, 205],
+      6 => [0, 205, 205],
+      7 => [229, 229, 229],
+      8 => [127, 127, 127],
+      9 => [255, 0, 0],
+      10 => [0, 255, 0],
+      11 => [255, 255, 0],
+      12 => [92, 92, 255],
+      13 => [255, 0, 255],
+      14 => [0, 255, 255],
+      15 => [255, 255, 255],
+    }.freeze
+
+    # Resolve a color specification to an integer color index suitable for curses init_pair.
+    #
+    # Accepts:
+    # - Integer (e.g. 17, 226, -1)
+    # - ANSI name (e.g. "yellow", "bright_blue", "default")
+    # - Alias (e.g. "navy")
+    # - Hex string (#RRGGBB or #RGB)
+    # - X11 name (e.g. "MidnightBlue") resolved via bundled rgb.txt
+    #
+    # available_colors:
+    # - If <= 16, any resolved 256-color index is down-mapped to nearest ANSI 0..15.
+    # - If > 16, returns xterm-256 indices 0..255 (or -1 for default).
+    def self.resolve(spec, available_colors: 256)
+      spec_norm = spec
+
+      idx =
+        if spec_norm.is_a?(Integer)
+          spec_norm
+        elsif spec_norm.nil?
+          DEFAULT_INDEX
+        else
+          resolve_stringish(spec_norm.to_s, available_colors: available_colors)
+        end
+
+      if idx == DEFAULT_INDEX
+        idx
+      else
+        clamp_index(idx, available_colors: available_colors)
+      end
+    end
+
+    def self.resolve_stringish(str, available_colors: 256)
+      s = normalize_name(str)
+      # Disambiguation prefixes:
+      # - "ansi:yellow" forces ANSI 0..15 names
+      # - "x11:yellow" forces X11 rgb.txt lookup
+      #
+      # Without a prefix, prefer X11 names when 256 colors are available so
+      # common names like "yellow" match X11 "#FFFF00" rather than ANSI 3.
+      mode = nil
+      if s.start_with?("ansi:")
+        mode = :ansi
+        s = s.delete_prefix("ansi:")
+      elsif s.start_with?("x11:")
+        mode = :x11
+        s = s.delete_prefix("x11:")
+      end
+
+      idx = ALIASES_256[s]
+      return idx unless idx.nil?
+
+      rgb = parse_hex(s)
+      return xterm_index_for_rgb(rgb[0], rgb[1], rgb[2]) if rgb
+
+      prefer_x11 = (mode == :x11) || (mode.nil? && available_colors.to_i >= 256)
+
+      if prefer_x11
+        rgb2 = x11_rgb_for_name(s)
+        return xterm_index_for_rgb(rgb2[0], rgb2[1], rgb2[2]) if rgb2
+      end
+
+      idx = ANSI_NAMES[s]
+      return idx unless idx.nil?
+
+      unless prefer_x11
+        rgb2 = x11_rgb_for_name(s)
+        return xterm_index_for_rgb(rgb2[0], rgb2[1], rgb2[2]) if rgb2
+      end
+
+      # Unknown name: treat as default.
+      DEFAULT_INDEX
+    end
+
+    def self.normalize_name(str)
+      # normalize spaces/underscores/hyphens and case, so:
+      # "Light Sky Blue" == "light_sky_blue" == "lightskyblue"
+      s = str.to_s.strip.downcase
+      s = s.tr("-", "_")
+      s = s.gsub(/\s+/, "")
+      s
+    end
+
+    def self.parse_hex(s)
+      # Accept "#rgb" or "#rrggbb"
+      hex = s
+      if hex.start_with?("#")
+        hex = hex[1..]
+      end
+
+      if hex.match?(/\A[0-9a-f]{3}\z/i)
+        r = (hex[0] * 2).to_i(16)
+        g = (hex[1] * 2).to_i(16)
+        b = (hex[2] * 2).to_i(16)
+        [r, g, b]
+      elsif hex.match?(/\A[0-9a-f]{6}\z/i)
+        r = hex[0, 2].to_i(16)
+        g = hex[2, 2].to_i(16)
+        b = hex[4, 2].to_i(16)
+        [r, g, b]
+      end
+    end
+
+    def self.clamp_index(idx, available_colors:)
+      max = available_colors.to_i - 1
+      0 if max < 0
+
+      i = idx.to_i
+
+      if available_colors.to_i <= 16
+        downmap_to_ansi16(i)
+      else
+        i.clamp(0, 255)
+      end
+    end
+
+    def self.rgb(spec)
+      if spec.is_a?(Integer)
+        xterm_rgb_for_index(spec)
+      elsif spec.nil?
+        nil
+      else
+        s = normalize_name(spec.to_s)
+
+        if s.start_with?("ansi:")
+          s = s.delete_prefix("ansi:")
+        elsif s.start_with?("x11:")
+          s = s.delete_prefix("x11:")
+        end
+
+        idx = ALIASES_256[s]
+        if idx
+          xterm_rgb_for_index(idx)
+        else
+          parsed = parse_hex(s)
+          parsed ||= x11_rgb_for_name(s)
+          parsed ||= begin
+            ansi = ANSI_NAMES[s]
+            xterm_rgb_for_index(ansi) unless ansi == DEFAULT_INDEX || ansi.nil?
+          end
+          parsed
+        end
+      end
+    end
+
+    # Convert any RGB to an xterm-256 index (16..255).
+    # We consider both the 6x6x6 cube and the grayscale ramp and pick the closer.
+    def self.xterm_index_for_rgb(r, g, b)
+      rr = clamp_byte(r)
+      gg = clamp_byte(g)
+      bb = clamp_byte(b)
+
+      cube = xterm_cube_index(rr, gg, bb)
+      gray = xterm_gray_index(rr, gg, bb)
+
+      cube_rgb = xterm_rgb_for_index(cube)
+      gray_rgb = xterm_rgb_for_index(gray)
+
+      if dist2(rr, gg, bb, gray_rgb[0], gray_rgb[1], gray_rgb[2]) <
+         dist2(rr, gg, bb, cube_rgb[0], cube_rgb[1], cube_rgb[2])
+        gray
+      else
+        cube
+      end
+    end
+
+    def self.xterm_cube_index(r, g, b)
+      levels = [0, 95, 135, 175, 215, 255]
+      ri = nearest_index(levels, r)
+      gi = nearest_index(levels, g)
+      bi = nearest_index(levels, b)
+      16 + (36 * ri) + (6 * gi) + bi
+    end
+
+    def self.xterm_gray_index(r, g, b)
+      # grayscale ramp 232..255 maps to levels 8 + 10*n
+      avg = (r + g + b) / 3
+      if avg < 8
+        16 # near black; keep in extended palette, not ANSI black
+      elsif avg > 238
+        231 # near white; a cube white
+      else
+        n = ((avg - 8) / 10.0).round
+        n = 0 if n < 0
+        n = 23 if n > 23
+        232 + n
+      end
+    end
+
+    def self.xterm_rgb_for_index(idx)
+      i = idx.to_i
+
+      if i.between?(232, 255)
+        v = 8 + (i - 232) * 10
+        [v, v, v]
+      elsif i.between?(16, 231)
+        j = i - 16
+        r = j / 36
+        g = (j % 36) / 6
+        b = j % 6
+        levels = [0, 95, 135, 175, 215, 255]
+        [levels[r], levels[g], levels[b]]
+      else
+        # for 0..15 we use ANSI_RGB as an approximation
+        ANSI_RGB[i] || [0, 0, 0]
+      end
+    end
+
+    def self.downmap_to_ansi16(idx)
+      if idx == DEFAULT_INDEX
+        DEFAULT_INDEX
+      elsif idx.between?(0, 15)
+        idx
+      else
+        rgb = xterm_rgb_for_index(idx)
+        nearest_ansi_index(rgb[0], rgb[1], rgb[2])
+      end
+    end
+
+    def self.nearest_ansi_index(r, g, b)
+      best = 0
+      best_d = nil
+
+      ANSI_RGB.each do |i, rgb|
+        d = dist2(r, g, b, rgb[0], rgb[1], rgb[2])
+        if best_d.nil? || d < best_d
+          best_d = d
+          best = i
+        end
+      end
+
+      best
+    end
+
+    def self.nearest_index(levels, value)
+      v = value.to_i
+      best_i = 0
+      best_d = nil
+
+      levels.each_with_index do |lvl, i|
+        d = (lvl - v).abs
+        if best_d.nil? || d < best_d
+          best_d = d
+          best_i = i
+        end
+      end
+
+      best_i
+    end
+
+    def self.clamp_byte(v)
+      x = v.to_i
+      x = 0 if x < 0
+      x = 255 if x > 255
+      x
+    end
+
+    def self.dist2(r1, g1, b1, r2, g2, b2)
+      dr = r1 - r2
+      dg = g1 - g2
+      db = b1 - b2
+      (dr * dr) + (dg * dg) + (db * db)
+    end
+
+    def self.x11_rgb_for_name(name_norm)
+      table = x11_table
+      table[name_norm]
+    end
+
+    def self.x11_table
+      path = RGB_TXT_PATH
+
+      if @x11_table_path != path
+        @x11_table = load_x11_rgb_txt(path)
+        @x11_table_path = path
+      end
+      @x11_table
+    end
+
+    def self.load_x11_rgb_txt(path)
+      table = {}
+
+      if File.file?(path)
+        File.foreach(path) do |line|
+          next if line.strip.empty?
+          next if line.lstrip.start_with?("!")
+
+          # Format: R G B <name...>
+          parts = line.strip.split(/\s+/)
+          next if parts.length < 4
+
+          r = parts[0].to_i
+          g = parts[1].to_i
+          b = parts[2].to_i
+          name = parts[3..].join(" ")
+          key = normalize_name(name)
+          table[key] = [r, g, b]
+        end
+      end
+
+      table
+    end
+  end
+end