fatty 0.99.0

data/lib/fatty/curses/event_source.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Fatty
+  module Curses
+    class EventSource
+      MOUSE_BSTATE_BUTTON_MAP = {
+        ::Curses::BUTTON1_PRESSED => :left_pressed,
+        ::Curses::BUTTON1_RELEASED => :left_released,
+        ::Curses::BUTTON1_CLICKED => :left_clicked,
+        ::Curses::BUTTON1_DOUBLE_CLICKED => :left_double_clicked,
+        ::Curses::BUTTON1_TRIPLE_CLICKED => :left_triple_clicked,
+
+        ::Curses::BUTTON2_PRESSED => :middle_pressed,
+        ::Curses::BUTTON2_RELEASED => :middle_released,
+        ::Curses::BUTTON2_CLICKED => :middle_clicked,
+        ::Curses::BUTTON2_DOUBLE_CLICKED => :middle_double_clicked,
+        ::Curses::BUTTON2_TRIPLE_CLICKED => :middle_triple_clicked,
+
+        ::Curses::BUTTON3_PRESSED => :right_pressed,
+        ::Curses::BUTTON3_RELEASED => :right_released,
+        ::Curses::BUTTON3_CLICKED => :right_clicked,
+        ::Curses::BUTTON3_DOUBLE_CLICKED => :right_double_clicked,
+        ::Curses::BUTTON3_TRIPLE_CLICKED => :right_triple_clicked
+      }.freeze
+
+      ESCAPE_LOOKAHEAD_MS = 0
+
+      BRACKETED_PASTE_START = "[200~"
+      BRACKETED_PASTE_END   = "\e[201~"
+
+      attr_reader :context, :key_decoder
+
+      def initialize(context:, key_decoder:, poll_ms: 200)
+        @context = context
+        @key_decoder = key_decoder
+        @poll_ms = poll_ms.to_i
+        configure_input_polling!
+      end
+
+      def next_event
+        raw = read_raw
+        return unless raw
+
+        if raw.is_a?(Fatty::MouseEvent)
+          return [:key, raw]
+        end
+
+        if raw.is_a?(Array) && raw.first == :paste
+          return [:cmd, :paste, { text: raw.last }]
+        end
+
+        ev = @key_decoder.decode(raw)
+        return unless ev
+
+        [:key, ev]
+      end
+
+      private
+
+      def window
+        context.input_win
+      end
+
+      def configure_input_polling!
+        win = window
+        return unless win
+
+        # Make getch return nil periodically so Terminal can keep rendering,
+        # which allows output to animate smoothly.
+        win.timeout = @poll_ms if win.respond_to?(:timeout=)
+      end
+
+      def read_raw
+        return unless window
+
+        window.timeout = @poll_ms if window.respond_to?(:timeout=)
+
+        ch = window.getch
+        return if ch == -1
+        return unless ch
+
+        if ch.is_a?(Integer) && ch == ::Curses::KEY_MOUSE
+          mouse = ::Curses.getmouse
+          Fatty.debug("EventSource#read_raw: bstate=#{mouse&.bstate}", tag: :mouse)
+          return decode_mouse(mouse)
+        end
+
+        if Fatty::Config.config.dig(:log, :tags)&.include?(:keycode)
+          Fatty.debug(
+            :curses_getch,
+            tag: :keycode,
+            ch_class: ch.class.name,
+            ch_inspect: ch.inspect,
+            ch_int: (ch.is_a?(Integer) ? ch : nil),
+            ch_chr: (ch.is_a?(Integer) && ch.between?(0, 255) ? ch.chr : nil),
+          )
+        end
+
+        if ch.is_a?(Integer) && ch == 27
+          nxt = with_window_timeout(ESCAPE_LOOKAHEAD_MS) { window.getch }
+
+          if nxt == -1 || !nxt
+            ch
+          elsif nxt == "[".ord || nxt == "["
+            suffix = read_escape_suffix
+            seq = "[" + suffix
+
+            if seq == BRACKETED_PASTE_START
+              [:paste, read_bracketed_paste]
+            else
+              [ch, nxt]
+            end
+          else
+            [ch, nxt]
+          end
+        else
+          ch
+        end
+      end
+
+      def with_window_timeout(ms)
+        result = nil
+        win = window
+        if win&.respond_to?(:timeout=)
+          begin
+            win.timeout = ms
+            result = yield
+          ensure
+            win.timeout = @poll_ms
+          end
+        else
+          result = yield
+        end
+        result
+      end
+
+      def decode_mouse(mouse)
+        return unless mouse&.respond_to?(:bstate)
+
+        bstate = mouse.bstate
+
+        ctrl  = (bstate & ::Curses::BUTTON_CTRL).positive?
+        meta  = (bstate & ::Curses::BUTTON_ALT).positive?
+        shift = (bstate & ::Curses::BUTTON_SHIFT).positive?
+
+        button = mouse_button_from_bstate(bstate)
+        return unless button
+
+        Fatty::MouseEvent.new(
+          button: button,
+          x: mouse.x,
+          y: mouse.y,
+          ctrl: ctrl,
+          meta: meta,
+          shift: shift,
+          raw: mouse,
+        )
+      end
+
+      def mouse_button_from_bstate(bstate)
+        return :scroll_up   if (bstate & ::Curses::BUTTON4_PRESSED).positive?
+        return :scroll_down if (bstate & ::Curses::BUTTON5_PRESSED).positive?
+
+        MOUSE_BSTATE_BUTTON_MAP.each do |mask, button|
+          return button if (bstate & mask).positive?
+        end
+
+        nil
+      end
+
+      def read_escape_suffix
+        suffix = +""
+        done = false
+
+        until done
+          ch = with_window_timeout(0) { window.getch }
+
+          if ch == -1 || !ch
+            done = true
+          else
+            suffix << raw_char_to_s(ch)
+            done = true if suffix.end_with?("~")
+          end
+        end
+
+        suffix
+      end
+
+      def read_bracketed_paste
+        text = +""
+        done = false
+        limit = 1_000_000
+        hit_limit = false
+
+        until done
+          ch = window.getch
+
+          if ch == -1 || !ch
+            done = true
+          else
+            text << raw_char_to_s(ch)
+            if text.end_with?(BRACKETED_PASTE_END)
+              text = text.delete_suffix(BRACKETED_PASTE_END)
+              done = true
+            end
+          end
+
+          if text.length >= limit
+            hit_limit = true
+            done = true
+          end
+        end
+
+        Fatty.debug("EventSource#read_bracketed_paste: hit limit #{limit}", tag: :keycode) if hit_limit
+        text
+      end
+
+      def raw_char_to_s(ch)
+        case ch
+        when String
+          ch
+        when Integer
+          ch.between?(0, 255) ? ch.chr : ""
+        else
+          ""
+        end
+      end
+    end
+  end
+end

data/lib/fatty/curses/key_decoder.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Fatty
+  module Curses
+    # The KeyDecoder class is responsible for converting raw key events returned
+    # by the curses library into KeyEvent's to be used by Fatty. This allows
+    # Fatty to deal with keyboard actions using friendly names, like
+    # :home. :page_down, :f5, and so forth.  It also sets the modifiers, :shift,
+    # :ctrl, and :meta, in the KeyEvent so that the KeyMap can assign different
+    # actions to the modified keys.
+    class KeyDecoder
+      attr_reader :map, :env
+
+      def initialize(env:)
+        @env = env
+        @map = {}
+        load_builtin_map
+        load_user_config
+      end
+
+      # Return a KeyEvent object based on the raw keyboard input as returned by
+      # Screen#read_raw.
+      def decode(raw)
+        return unless raw
+
+        result =
+          case raw
+          when Array
+            decode_meta(raw)
+          else
+            decode_single(raw)
+          end
+        Fatty.debug("#{self.class}#decode(raw: #{raw}) -> #{result}", tag: :keycode)
+        result
+      end
+
+      private
+
+      # Handle the decoding of meta keys which are returned as an Array of the
+      # escape code followed by another key, nxt, which can be either a String
+      # or an Integer.
+      def decode_meta((esc, nxt))
+        case nxt
+        when String
+          # Meta + printable => action key, not self-insert
+          KeyEvent.new(
+            key:  nxt.to_sym,
+            meta: true,
+            raw:  [esc, nxt],
+          )
+        when Integer
+          # Meta + NUL => Meta-Ctrl-@
+          if nxt == 0
+            return KeyEvent.new(
+              key:  :'@',
+              ctrl: true,
+              meta: true,
+              raw:  [esc, nxt],
+            )
+          end
+
+          if (base = @map[nxt])
+            KeyEvent.new(
+              key:   base.key,
+              ctrl:  base.ctrl?,
+              shift: base.shift?,
+              meta:  true,
+              raw:   [esc, nxt],
+            )
+          else
+            KeyEvent.new(key: nxt, meta: true, raw: [esc, nxt])
+          end
+        end
+      end
+
+      # Decode a raw input returned as a single character rather than an Array.
+      def decode_single(ch)
+        if ch.is_a?(Integer) && @map.key?(ch)
+          Fatty.debug("#{self.class}#decode_single: #{ch} found in @map -> #{@map[ch]}", tag: :keycode)
+          ev = @map[ch]
+
+          # Some terminals/configs map printable ASCII keycodes (like 97 for "a")
+          # through keydefs. Those KeyEvents often have nil text, which breaks
+          # self-insert in sessions that fall back on ev.text.
+          if ev.respond_to?(:text) && ev.text.nil? &&
+             ev.respond_to?(:ctrl?) && ev.respond_to?(:meta?) &&
+             !ev.ctrl? && !ev.meta? &&
+             ch.between?(32, 126)
+
+            KeyEvent.new(
+              key:   ev.key,
+              text:  ch.chr,
+              ctrl:  ev.ctrl?,
+              meta:  ev.meta?,
+              shift: ev.shift?,
+              raw:   ch,
+            )
+          else
+            ev
+          end
+        else
+          fallback_decode(ch)
+        end
+      end
+
+      def fallback_decode(ch, raw: nil)
+        case ch
+        when Integer
+          # Many Ruby curses builds return Integers for printable characters
+          # (e.g. 97 for "a"). Treat printable ASCII as self-inserting text.
+          if (32..126).cover?(ch)
+            fallback_decode(ch.chr, raw: ch)
+          elsif ch == 10 || ch == 13
+            # Enter can arrive as LF (10) or CR (13). Do this BEFORE ctrl-letter mapping.
+            KeyEvent.new(key: :enter, text: "\n", raw: ch)
+          elsif ch == 0
+            # Ctrl-@ => NUL
+            KeyEvent.new(key: :'@', ctrl: true, raw: ch)
+          elsif (1..26).cover?(ch)
+            KeyEvent.new(key: (ch + 96).chr.to_sym, ctrl: true, raw: ch)
+          elsif ch == 27
+            KeyEvent.new(key: :escape, raw: ch)
+          else
+            KeyEvent.new(key: ch, raw: ch)
+          end
+        when String
+          key =
+            case ch
+            when " "  then :space
+            when "\t" then :tab
+            when "\n", "\r" then :enter
+            else
+              # bindable “literal” key, e.g. "h" => :h, "x" => :x, "." => :"."
+              ch.to_sym
+            end
+          KeyEvent.new(key: key, text: ch, raw: ch)
+        end
+      end
+
+      # Add to the @map any keydefs defined by the user for the terminal
+      # detected in the environment.  The user config, usually in
+      # ~/.config/fatty/keydefs.yml, takes into account the vagaries of how
+      # different terminal programs process keys.
+      def load_user_config
+        config = Fatty::Config.keydefs
+        Fatty.info("KeyDecode#load_user_config", config: config, tag: :keycode)
+        return unless config
+
+        terminal = @env[:terminal]
+        Fatty.info("KeyDecoder#load_user_config: detected terminal `#{terminal}`")
+        Fatty.info("KeyDecoder#load_user_config: only keydefs for `#{terminal}` will be loaded")
+        section = config.dig(:terminal, terminal.to_sym, :map)
+        return unless section
+
+        section.each do |code, spec|
+          @map[Integer(code.to_s)] = KeyEvent.new(**normalize_spec(spec))
+          Fatty.debug("KeyDecoder#load_user_config: user keydef: code: #{code} -> #{spec}")
+        end
+      end
+
+      # Add to the @map keydefs as assumed by the curses library, defined in the
+      # constant Fatty::CUSRSES_TO_EVENT.  These can be overridden by the the
+      # user config in #load_user_config.
+      def load_builtin_map
+        Fatty.info("#{self.class}#load_builtin_map from CURSES_TO_EVENT", tag: :keycode)
+        CURSES_TO_EVENT.each do |code, event|
+          @map[code] = event
+          Fatty.debug("KeyDecoder#load_builtin_map: system keydef: code: #{code} -> event: #{event}", tag: :keycode)
+        end
+      end
+
+      # Make sure the user config Hash uses symbols for its keys.  Return the
+      # Hash as so corrected.
+      def normalize_spec(hash)
+        spec = hash.transform_keys(&:to_sym)
+        if spec[:key].is_a?(String)
+          spec[:key] = spec[:key].to_sym
+        end
+        spec
+      end
+    end
+  end
+end

data/lib/fatty/curses/patch.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# This is here to supress a particular warning that is emitted by Curses mouse
+# code.
+module Warning
+  class << self
+    alias_method :fatty_orig_warn, :warn unless method_defined?(:fatty_orig_warn)
+  end
+
+  def self.warn(msg, category: nil, **kwargs)
+    return if msg.include?("undefining the allocator of T_DATA class Curses::MouseEvent")
+
+    fatty_orig_warn(msg, category: category, **kwargs)
+  end
+end
+
+# Curses button-related constants:
+#
+# * Button1 (Left button)
+# BUTTON1_PRESSED         0x00000002
+# BUTTON1_RELEASED        0x00000001
+# BUTTON1_CLICKED         0x00000004
+# BUTTON1_DOUBLE_CLICKED  0x00000008
+# BUTTON1_TRIPLE_CLICKED  0x00000010
+#
+# * Button2 (Middle button)
+# BUTTON2_PRESSED         0x00000080
+# BUTTON2_RELEASED        0x00000040
+# BUTTON2_CLICKED         0x00000100
+# BUTTON2_DOUBLE_CLICKED  0x00000200
+# BUTTON2_TRIPLE_CLICKED  0x00000400
+#
+# * Button3 (Right button)
+# BUTTON3_PRESSED         0x00002000
+# BUTTON3_RELEASED        0x00001000
+# BUTTON3_CLICKED         0x00004000
+# BUTTON3_DOUBLE_CLICKED  0x00008000
+# BUTTON3_TRIPLE_CLICKED  0x00010000
+#
+# * Button4 (wheel up)
+# BUTTON4_PRESSED         0x00020000
+# BUTTON4_RELEASED        0x00040000
+# BUTTON4_CLICKED         0x00080000
+# BUTTON4_DOUBLE_CLICKED  0x00100000
+# BUTTON4_TRIPLE_CLICKED  0x00200000
+#
+# * Button5 (wheel down)
+# BUTTON5_PRESSED         0x00200000
+# BUTTON5_RELEASED        0x00400000
+# BUTTON5_CLICKED         0x00800000
+# BUTTON5_DOUBLE_CLICKED  0x01000000
+# BUTTON5_TRIPLE_CLICKED  0x02000000
+#
+# * Modifier Flags
+# BUTTON_SHIFT  0x04000000
+# BUTTON_CTRL   0x08000000
+# BUTTON_ALT    0x10000000
+#
+# The ruby implementation of curses apparently does not expose some
+# mouse-related constants.  Here we provide a method to ensure that they are
+# defined.
+module Fatty
+  module Curses
+    module MouseConstants
+      CONSTANTS = {
+        # Button 1 (left)
+        BUTTON1_RELEASED: 0x00000001,
+        BUTTON1_PRESSED: 0x00000002,
+        BUTTON1_CLICKED: 0x00000004,
+        BUTTON1_DOUBLE_CLICKED: 0x00000008,
+        BUTTON1_TRIPLE_CLICKED: 0x00000010,
+
+        # Button 2 (middle)
+        BUTTON2_RELEASED: 0x00000040,
+        BUTTON2_PRESSED: 0x00000080,
+        BUTTON2_CLICKED: 0x00000100,
+        BUTTON2_DOUBLE_CLICKED: 0x00000200,
+        BUTTON2_TRIPLE_CLICKED: 0x00000400,
+
+        # Button 3 (right)
+        BUTTON3_RELEASED: 0x00001000,
+        BUTTON3_PRESSED: 0x00002000,
+        BUTTON3_CLICKED: 0x00004000,
+        BUTTON3_DOUBLE_CLICKED: 0x00008000,
+        BUTTON3_TRIPLE_CLICKED: 0x00010000,
+
+        # Wheel up
+        BUTTON4_PRESSED: 0x00020000,
+        BUTTON4_RELEASED: 0x00040000,
+        BUTTON4_CLICKED: 0x00080000,
+        BUTTON4_DOUBLE_CLICKED: 0x00100000,
+        BUTTON4_TRIPLE_CLICKED: 0x00200000,
+
+        # Wheel down
+        BUTTON5_PRESSED: 0x00200000,
+        BUTTON5_RELEASED: 0x00400000,
+        BUTTON5_CLICKED: 0x00800000,
+        BUTTON5_DOUBLE_CLICKED: 0x01000000,
+        BUTTON5_TRIPLE_CLICKED: 0x02000000,
+
+        # Modifier masks
+        BUTTON_SHIFT: 0x04000000,
+        BUTTON_CTRL: 0x08000000,
+        BUTTON_ALT: 0x10000000,
+      }.freeze
+
+      def self.ensure!
+        CONSTANTS.each do |name, value|
+          next if ::Curses.const_defined?(name)
+
+          ::Curses.const_set(name, value)
+        end
+      end
+    end
+  end
+end

data/lib/fatty/curses/window_styling.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Fatty
+  module Curses
+    module WindowStyling
+      ATTR_FLAGS = {
+        bold: ::Curses::A_BOLD,
+        dim: ::Curses::A_DIM,
+        reverse: ::Curses::A_REVERSE,
+        underline: ::Curses::A_UNDERLINE,
+      }.freeze
+
+      def pair_attr(role, fallback:)
+        palette = context.palette
+        spec = palette&.[](role)
+        return fallback unless spec && spec[:pair]
+
+        attr = ::Curses.color_pair(spec[:pair])
+
+        Array(spec[:attrs]).each do |a|
+          attr |= attr_flag(a)
+        end
+
+        attr
+      end
+
+      def attr_flag(name)
+        ATTR_FLAGS.fetch(name.to_sym, 0)
+      end
+    end
+  end
+end

data/lib/fatty/curses.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Curses
+  class Window
+    def origin
+      [begy, begx]
+    end
+  end
+end
+
+require_relative "curses/patch"
+require_relative "curses/curses_coder"
+require_relative "curses/key_decoder"
+require_relative "curses/event_source"
+require_relative "curses/context"
+require_relative "curses/window_styling"

data/lib/fatty/env.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Fatty
+  module Env
+    extend self
+
+    def detect
+      {
+        os: os,
+        arch: arch,
+        ruby_platform: RUBY_PLATFORM,
+        term: ENV["TERM"],
+        terminal: detect_terminal_program,
+        terminal_version: ENV["KONSOLE_VERSION"] || ENV["TERM_PROGRAM_VERSION"],
+        tmux: tmux?,
+        screen: screen?,
+        ssh: ssh?,
+        curses: curses_info,
+      }
+    end
+
+    # -----------------------
+    # OS / platform
+    # -----------------------
+
+    def os
+      case RUBY_PLATFORM
+      when /linux/  then :linux
+      when /darwin/ then :darwin
+      when /bsd/    then :bsd
+      when /mswin|mingw|cygwin/ then :windows
+      else :unknown
+      end
+    end
+
+    def arch
+      case RUBY_PLATFORM
+      when /x86_64/ then :x86_64
+      when /arm64|aarch64/ then :arm64
+      else :unknown
+      end
+    end
+
+    # -----------------------
+    # Terminal identity
+    # -----------------------
+
+    def term_program
+      ENV["TERM_PROGRAM"]&.downcase ||
+        ENV["COLORTERM"]&.downcase
+    end
+
+    def detect_terminal_program
+      return "tmux"     if ENV.key?("TMUX")
+      return "screen"   if ENV.key?("STY")
+      return "konsole"  if ENV.key?("KONSOLE_VERSION")
+      return "kitty"    if ENV.key?("KITTY_WINDOW_ID")
+      return "wezterm"  if ENV["TERM_PROGRAM"]&.downcase == "wezterm"
+      return "iterm"    if ENV["TERM_PROGRAM"] == "iTerm.app"
+      return "ghostty"  if ENV["TERM_PROGRAM"]&.downcase == "ghostty"
+      return "alacritty" if ENV.key?("ALACRITTY_LOG")
+      return "terminator" if ENV.key?("TERMINATOR_UUID")
+
+      if ENV.key?("TERM_PROGRAM")
+        ENV["TERM_PROGRAM"]&.downcase
+      elsif ENV.key?("TERM")
+        ENV["TERM"]&.downcase
+      else
+        'unknown'
+      end
+    end
+
+    def tmux?
+      ENV.key?("TMUX")
+    end
+
+    def screen?
+      ENV.key?("STY")
+    end
+
+    def ssh?
+      ENV.key?("SSH_TTY") || ENV.key?("SSH_CONNECTION")
+    end
+
+    # -----------------------
+    # ncurses capabilities
+    # -----------------------
+
+    def curses_info
+      return {} unless defined?(::Curses)
+
+      {
+        key_min: ::Curses::KEY_MIN,
+        key_max: ::Curses::KEY_MAX,
+      }
+    rescue StandardError
+      {}
+    end
+  end
+end