terminal_rb 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf8062e89f52459ef6bb5e6e61d6142986d43dbec76d223ab16656146e3467a1
-  data.tar.gz: 3656dd6c10b1c2a88697c485daa12d345cd48a128f7c63da92f97f1395780e8c
+  metadata.gz: 357e535e9317609160d54c93a2a106a2a39d86a4c6740e93bbbccc01a2fcd42f
+  data.tar.gz: 746ddada0e50edf61c7220d144d75de46530056138e8a9d1bc1793098fe8a824
 SHA512:
-  metadata.gz: bc2fb13b0b73a329cc4d60c8af62c0e347b551e3ed3d72eac5be4fbbdd823830bc8410487145a49833d2c34f33c2a7d2d5f7bb250ad1608ed384a49f31a4e139
-  data.tar.gz: 874df65c622227f93c081a8d6ff26b18f380ab89a4ffbe76f38b23bc25c81ee33287179b0327c274d5e4a9c30abdf25ebac2fd535b6ea016da296b12d7cd7f14
+  metadata.gz: 90b2db6aa0cd6d3351ae8b7ec0f8df30a37e7bdad87050def22c47cbf48c94246efe927b15a612adbc713ff8b34971adc973721172da4702a1c7a433446db5e9
+  data.tar.gz: f35bafc5ecc52b59360ecec503e32ed173486fa81b42eec99912ef545d64be888ff01f9d584c3a6f34dd45505d449ece87ae033e61f0bb0e9637d481ddb7f310

data/examples/key-codes.rb

@@ -14,9 +14,9 @@ Terminal.hide_cursor
 at_exit { Terminal.show_cursor } # required for some terminals :/
 
 while true
-  raw, name = Terminal.read_key(mode: :both)
-  Terminal.puts(
-    "   [blue]: [yellow]#{raw.inspect}  [bold bright_green]#{name}[/]"
-  )
-  break puts if raw.nil? || name == 'Esc'
+  event = Terminal.read_key_event or break puts
+  str = "[blue]: [yellow]#{event.raw.inspect}"
+  str << " [bold bright_green]#{event.name}[/]" unless event.simple?
+  Terminal.puts(str)
+  break puts if event.name == 'Esc'
 end

data/lib/terminal/ansi/attributes.rb

@@ -2,7 +2,7 @@
 
 module Terminal
   module Ansi
-    ATTRIBUTES = {
+    @attr = {
       '/' => '',
       '/b' => '22',
       '/blink' => '25',
@@ -109,7 +109,7 @@ module Terminal
       'uu' => '21'
     }.freeze
 
-    COLORS = {
+    @colors = {
       '/bg' => '49',
       '/fg' => '39',
       '/ul' => '59',
@@ -200,10 +200,7 @@ module Terminal
       'yellow' => '33'
     }.freeze
 
-    ATTRIBUTES_S =
-      ATTRIBUTES.transform_keys(&:to_sym).compare_by_identity.freeze
-    COLORS_S = COLORS.transform_keys(&:to_sym).compare_by_identity.freeze
-
-    private_constant :ATTRIBUTES, :COLORS, :ATTRIBUTES_S, :COLORS_S
+    @attr_sym = @attr.transform_keys(&:to_sym).compare_by_identity.freeze
+    @colors_sym = @colors.transform_keys(&:to_sym).compare_by_identity.freeze
   end
 end

data/lib/terminal/ansi.rb

@@ -12,7 +12,7 @@ module Terminal
       #
       # @attribute [r] attributes
       # @return [Array<Symbol>] all attribute names
-      def attributes = ATTRIBUTES_S.keys
+      def attributes = @attr_sym.keys
 
       # Supported 3/4-bit color names.
       #
@@ -20,7 +20,7 @@ module Terminal
       #
       # @attribute [r] colors
       # @return [Array<Symbol>] all color names
-      def colors = COLORS_S.keys
+      def colors = @colors_sym.keys
 
       # Supported basic 24-bit (Kitty compatible) color names.
       #
@@ -99,9 +99,9 @@ module Terminal
             .map do |arg|
               case arg
               when String
-                ATTRIBUTES[arg] || COLORS[arg] || _color(arg) || _invalid(arg)
+                @attr[arg] || @colors[arg] || _color(arg) || _invalid(arg)
               when Symbol
-                ATTRIBUTES_S[arg] || COLORS_S[arg] || _color(arg) ||
+                @attr_sym[arg] || @colors_sym[arg] || _color(arg) ||
                   _invalid(arg)
               when (0..255)
                 "38;5;#{arg}"
@@ -121,7 +121,7 @@ module Terminal
       #
       # @param str [#to_s] object to be tested
       # @return [true, false] whether if attributes are found
-      def ansi?(str) = TEST.match?(str.to_s)
+      def ansi?(str) = @re_test.match?(str.to_s)
 
       # Decorate given argument with ANSI attributes and colors.
       #
@@ -156,7 +156,7 @@ module Terminal
       # @return [String] string without ANSI attributes
       def undecorate(str)
         str = str.to_s
-        str.index("\e") ? str.gsub(TEST, '') : str.dup
+        str.index("\e") ? str.gsub(@re_test, '') : str.dup
       end
 
       # Try to combine given ANSI attributes and colors.
@@ -181,7 +181,7 @@ module Terminal
         return if (attributes = attributes.to_s.split(separator)).empty?
         "\e[#{
           attributes
-            .map! { ATTRIBUTES[_1] || COLORS[_1] || _color(_1) || return }
+            .map! { @attr[_1] || @colors[_1] || _color(_1) || return }
             .join(';')
         }m"
       end
@@ -196,9 +196,9 @@ module Terminal
         attributes.all? do |arg|
           case arg
           when String
-            ATTRIBUTES[arg] || COLORS[arg] || _color(arg)
+            @attr[arg] || @colors[arg] || _color(arg)
           when Symbol
-            ATTRIBUTES_S[arg] || COLORS_S[arg] || _color(arg)
+            @attr_sym[arg] || @colors_sym[arg] || _color(arg)
           when (0..767)
             true
           end
@@ -225,7 +225,7 @@ module Terminal
       def bbcode(str)
         str = str.to_s
         return str.dup unless str.index('[')
-        str.gsub(BBCODE) do |match_str|
+        str.gsub(@re_bbcode) do |match_str|
           match = Regexp.last_match(1) or next match_str
           next "[#{match[1..]}]" if match[0] == '\\'
           try_convert(match) || match_str
@@ -245,11 +245,11 @@ module Terminal
       def unbbcode(str)
         str = str.to_s
         return str.dup unless str.index('[')
-        str.gsub(BBCODE) do |match_str|
+        str.gsub(@re_bbcode) do |match_str|
           match = Regexp.last_match(1) or next match_str
           next "[#{match[1..]}]" if match[0] == '\\'
           next match_str if (match = match.split).empty?
-          next if match.all? { ATTRIBUTES[_1] || COLORS[_1] || _color(_1) }
+          next if match.all? { @attr[_1] || @colors[_1] || _color(_1) }
           match_str
         end
       end
@@ -270,17 +270,17 @@ module Terminal
       def plain(str)
         str = str.to_s
         unless str.index('[')
-          return str.index("\e") ? str.gsub(TEST, '') : str.dup
+          return str.index("\e") ? str.gsub(@re_test, '') : str.dup
         end
         str =
-          str.gsub(BBCODE) do |match_str|
+          str.gsub(@re_bbcode) do |match_str|
             match = Regexp.last_match(1) or next match_str
             next "[#{match[1..]}]" if match[0] == '\\'
             next match_str if (match = match.split).empty?
-            next if match.all? { ATTRIBUTES[_1] || COLORS[_1] || _color(_1) }
+            next if match.all? { @attr[_1] || @colors[_1] || _color(_1) }
             match_str
           end
-        str.index("\e") ? str.gsub!(TEST, '') : str
+        str.index("\e") ? str.gsub!(@re_test, '') : str
       end
 
       # Create nice colored text.
@@ -292,14 +292,16 @@ module Terminal
       # @return [String] fancy text
       def rainbow(str, frequency: 0.3, spread: 0.8, seed: 1.1)
         pos = -1
+        @pi2_third ||= 2.0 * Math::PI / 3.0
+        @pi4_third ||= 4.0 * Math::PI / 3.0
         str
           .to_s
           .chars
           .map! do |char|
             i = (seed + ((pos += 1) / spread)) * frequency
             "\e[38;2;#{(Math.sin(i) * 255).to_i.abs};" \
-              "#{(Math.sin(i + PI2_THIRD) * 255).to_i.abs};" \
-              "#{(Math.sin(i + PI4_THIRD) * 255).to_i.abs}m#{char}"
+              "#{(Math.sin(i + @pi2_third) * 255).to_i.abs};" \
+              "#{(Math.sin(i + @pi4_third) * 255).to_i.abs}m#{char}"
           end
           .join << RESET
       end
@@ -533,7 +535,7 @@ module Terminal
             opts << 'v=0'
           when 1, :bottom
             opts << 'v=1'
-          when 2, :centered, :center
+          when 2, :centered
             opts << 'v=2'
           end
           case horizontal
@@ -541,7 +543,7 @@ module Terminal
             opts << 'h=0'
           when 1, :right
             opts << 'h=1'
-          when 2, :centered, :center
+          when 2, :centered
             opts << 'h=2'
           end
         end
@@ -568,39 +570,34 @@ module Terminal
           return(
             case v.size
             when 1, 2
-              "#{COLOR_BASE[b]};5;#{v.hex}"
+              "#{@cbase[b]};5;#{v.hex}"
             when 3
-              "#{COLOR_BASE[b]};2;#{(v[0] * 2).hex};#{
+              "#{@cbase[b]};2;#{(v[0] * 2).hex};#{
                 (v[1] * 2).hex
               };#{(v[2] * 2).hex}"
             when 6
-              "#{COLOR_BASE[b]};2;#{v[0, 2].hex};#{v[2, 2].hex};#{v[4, 2].hex}"
+              "#{@cbase[b]};2;#{v[0, 2].hex};#{v[2, 2].hex};#{v[4, 2].hex}"
             end
           )
         end
         b, v = /\A(fg|bg|on|ul)?_?([a-z]{3,}[0-9]{0,3})\z/.match(str)&.captures
         return unless v
-        name = NAMED_COLORS[v] and return "#{COLOR_BASE[b]};#{name}"
+        name = NAMED_COLORS[v] and return "#{@cbase[b]};#{name}"
       end
     end
 
-    COLOR_BASE =
+    @cbase =
       { 'bg' => '48', 'on' => '48', 'ul' => '58' }.tap { _1.default = '38' }
         .freeze
 
-    TEST =
+    @re_test =
       /
       (?:\e\[[\d;:\?]*[ABCDEFGHJKSTfminsuhl])
       |
       (?:\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
     /x
 
-    BBCODE = /(?:\[((?~[\[\]]))\])/
-
-    PI2_THIRD = 2.0 * Math::PI / 3.0
-    PI4_THIRD = 4.0 * Math::PI / 3.0
-
-    private_constant :COLOR_BASE, :TEST, :BBCODE, :PI2_THIRD, :PI4_THIRD
+    @re_bbcode = /(?:\[((?~[\[\]]))\])/
 
     require_relative 'ansi/attributes'
 
@@ -706,15 +703,7 @@ module Terminal
     #   "\eM" reverse "\n"
     #   "\e[6n" report Cursor Position as "ESC \[ row ; col R"
     #   "\e[21t report window’s title as ESC ] l title ESC \"
-    #   "\e[?Xl" set mouse mode "X":
-    #     9: X10_MOUSE
-    #     1000: VT200_MOUSE
-    #     1002: BTN_EVENT_MOUSE
-    #     1003: ANY_EVENT_MOUSE
-    #     1004: FOCUS_EVENT_MOUSE
-    #     1005: Xterm’s UTF8
-    #     1006: Xterm’s CSI-style
-    #     1015: Urxvt’s CSI-style
-    #   "\e[?Xl" reset mouse mode "X"
+    #   "\e[?1004h" report focus lost "\e[O" and focus get "\e[I"
+    #     (disable by "\e[?1004l")
   end
 end

data/lib/terminal/detect.rb

@@ -11,9 +11,6 @@ module Terminal
 
       def colors
         return 16_777_216 if ENV['COLORTERM'] == 'truecolor'
-        if %i[ghostty iterm kitty rio vscode wezterm tabby].include?(app_by_tp)
-          return 16_777_216
-        end
         term = ENV['TERM'] or return 8
         return 16_777_216 if /[+-]direct/.match?(term)
         match = /[-+](\d+)color/.match(term) and return match[1].to_i
@@ -32,24 +29,27 @@ module Terminal
       private
 
       def app_by_tp
-        {
-          'Apple_Terminal' => :macos,
-          'CodeEditApp_Terminal' => :code_edit,
-          'FluentTerminal' => :fluent,
-          'ghostty' => :ghostty,
-          'Hyper' => :hyper,
-          'HyperTerm' => :hyper,
-          'iTerm.app' => :iterm,
-          'rio' => :rio,
-          'Tabby' => :tabby,
-          'Terminus' => :terminus,
-          'tmux' => :tmux,
-          'vscode' => :vscode,
-          'WarpTerminal' => :warp,
-          'WezTerm' => :wezterm
-        }[
-          ENV['TERM_PROGRAM']
-        ]
+        tp = ENV['TERM_PROGRAM']
+        return if tp.nil? || (tp = tp.strip).empty?
+        case tp
+        when 'Apple_Terminal'
+          :macos
+        when 'CodeEditApp_Terminal'
+          :code_edit
+        when 'docker_desktop'
+          :docker
+        when 'FluentTerminal'
+          :fluent
+        when 'HyperTerm'
+          :hyper
+        when 'iTerm.app'
+          :iterm
+        when 'WarpTerminal'
+          :warp
+        else
+          tp = tp.tr(' \\/?!', '_').downcase
+          tp.empty? ? nil : tp.to_sym
+        end
       end
 
       def app_by_term

data/lib/terminal/input/as_key_event.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+module Terminal
+  module AsKeyEvent
+    class << self
+      def [](raw)
+        return KeyEvent.new(raw, *@single_key[raw.ord]) if raw.size == 1
+        return KeyEvent.unknown(raw) if raw[0] != "\e"
+        return esc1(raw, raw[1]) if raw.size == 2 # ESC ?
+        case raw[1]
+        when "\e" # ESC ESC ...
+          return esc_esc(raw)
+        when 'O'
+          if raw.size == 3
+            # ESC O ?
+            return KeyEvent.new(raw, *@ss3[raw[2].ord])
+          end
+        when '[' # ESC [ ...
+          if raw.size == 3
+            # ESC [ ?
+            return KeyEvent.new(raw, *@ss3[raw[2].ord])
+          end
+          if raw.size == 6 && raw[2] == 'M'
+            # ESC [ M b c r
+            return mouse_vt200(raw)
+          end
+          return csi1(raw) if raw.start_with?("\e[1;") # ESC [ 1 ; ...
+          case raw[-1]
+          when '~'
+            return legacy(raw)
+          when 'u'
+            return csi_u(raw)
+          when 'M'
+            return raw[2] == '<' ? mouse_sgr(raw) : mouse_urxvt(raw)
+          when 'm'
+            return mouse_sgr(raw) if raw[2] == '<'
+          end
+        end
+        KeyEvent.unknown(raw)
+      end
+
+      private
+
+      def mouse_vt200(raw)
+        # ESC [ M b c r
+        mouse_event(raw, *raw[3..].chars.map! { _1.ord - 32 })
+      end
+
+      def mouse_sgr(raw)
+        # ESC [ < <code> ; <col> ; <row> M
+        # ESC [ < <code> ; <col> ; <row> m
+        return KeyEvent.unknown(raw) if raw.size < 8
+        bcr = raw[3..-2].split(';', 3).map!(&:to_i)
+        bcr.size == 3 ? mouse_event(raw, *bcr) : KeyEvent.unknown(raw)
+      end
+
+      def mouse_urxvt(raw)
+        # ESC [ <code> ; <col> ; <row> M
+        return KeyEvent.unknown(raw) if raw.size < 8
+        bcr = raw[2..-2].split(';', 3).map!(&:to_i)
+        bcr.size == 3 ? mouse_event(raw, *bcr) : KeyEvent.unknown(raw)
+      end
+
+      def mouse_event(raw, btn, col, row)
+        return KeyEvent.unknown(raw) if btn < 0 || col < 1 || row < 1
+        kind = btn & 3
+        ka = btn >= 64 ? @mouse_wheel_kind : @mouse_kind
+        btn -= kind
+        modifier = btn.allbits?(4) ? 1 : 0
+        modifier += 2 if btn.allbits?(8)
+        modifier += 4 if btn.allbits?(16)
+        KeyEvent.new(raw, ka[kind], modifier, [col, row])
+      end
+
+      def csi_u(raw)
+        # ESC [ <code> u
+        # ESC [ <code> ; <modifier> u
+        return KeyEvent.unknown(raw) if raw.size < 4
+        idx = raw.index(';')
+        code = raw[2..(idx ? idx - 1 : -2)].to_i
+        KeyEvent.new(
+          raw,
+          @csiu[code] || code.chr(Encoding::UTF_8),
+          idx ? [raw[(idx + 1)..-2].to_i - 1, 0].max : 0
+        )
+      end
+
+      def legacy(raw)
+        # ESC [ <code> ~
+        # ESC [ <code> ; <modifier> ~
+        return KeyEvent.unknown(raw) if raw.size < 4
+        idx = raw.index(';')
+        KeyEvent.new(
+          raw,
+          @csi[raw[2..(idx ? idx - 1 : -2)].to_i],
+          idx ? [raw[(idx + 1)..-2].to_i - 1, 0].max : 0
+        )
+      end
+
+      def csi1(raw)
+        # ESC [ 1 ; [~ABCDEFHPQRS]
+        # ESC [ 1 ; <modifier> [~ABCDEFHPQRS]
+        return KeyEvent.unknown(raw) if raw.size < 5
+        key, modifier = @ss3[raw[-1].ord]
+        modifier ||= 0
+        return KeyEvent.new(raw, nil, modifier) unless key
+        modifier |= [raw[4..-2].to_i - 1, 0].max if raw.size > 5
+        KeyEvent.new(raw, key, modifier)
+      end
+
+      def esc_esc(raw)
+        return esc1(raw, raw[2]) if raw.size == 3 # ESC ESC ?
+        ret = self[raw[1..]]
+        KeyEvent.new(raw, ret.key, ret.modifier | 2) # ESC ESC ...
+      end
+
+      def esc1(raw, char)
+        key, modifier = @esc1[char.ord]
+        KeyEvent.new(raw, key || char, modifier || 2)
+      end
+    end
+
+    @mouse_kind = %i[
+      MButton1
+      MButton2
+      MButton3
+      MButtonUp
+      MButton4
+      MButton5
+    ].freeze
+
+    @mouse_wheel_kind = %i[MWheelDown MWheelUp MWheelRight MWheelLeft].freeze
+
+    @csiu = {
+      0x02 => :Ins,
+      0x09 => :Tab,
+      0x0d => :Enter,
+      0x1b => :Esc,
+      0x20 => :Space,
+      0x7f => :Back,
+      57_376 => :F13,
+      57_377 => :F14,
+      57_378 => :F15,
+      57_379 => :F16,
+      57_380 => :F17,
+      57_381 => :F18,
+      57_382 => :F19,
+      57_383 => :F20,
+      57_384 => :F21,
+      57_385 => :F22,
+      57_386 => :F23,
+      57_387 => :F24,
+      57_388 => :F25,
+      57_389 => :F26,
+      57_390 => :F27,
+      57_391 => :F28,
+      57_392 => :F29,
+      57_393 => :F30,
+      57_394 => :F31,
+      57_395 => :F32,
+      57_396 => :F33,
+      57_397 => :F34,
+      57_398 => :F35,
+      57_399 => :Kp0,
+      57_400 => :Kp1,
+      57_401 => :Kp2,
+      57_402 => :Kp3,
+      57_403 => :Kp4,
+      57_404 => :Kp5,
+      57_405 => :Kp6,
+      57_406 => :Kp7,
+      57_407 => :Kp8,
+      57_408 => :Kp9,
+      57_409 => :KpDecimal,
+      57_410 => :KpDivide,
+      57_411 => :KpMultiply,
+      57_412 => :KpSubtract,
+      57_413 => :KpAdd,
+      57_414 => :Return, # :KpEnter
+      57_415 => :KpEqual,
+      57_416 => :KpSeparator,
+      57_417 => :KpLeft,
+      57_418 => :KpRight,
+      57_419 => :KpUp,
+      57_420 => :KpDown,
+      57_421 => :KpPageUp,
+      57_422 => :KpPageDown,
+      57_423 => :KpHome,
+      57_424 => :KpEnd,
+      57_425 => :KpInsert,
+      57_426 => :KpDelete,
+      57_428 => :MediaPlay,
+      57_429 => :MediaPause,
+      57_430 => :MediaPlayPause,
+      57_431 => :MediaReverse,
+      57_432 => :MediaStop,
+      57_433 => :MediaFastForward,
+      57_434 => :MediaRewind,
+      57_435 => :MediaTrackNext,
+      57_436 => :MediaTrackPrevious,
+      57_437 => :MediaRecord,
+      57_438 => :LowerVolume,
+      57_439 => :RaiseVolume,
+      57_440 => :MuteVolume,
+      57_441 => :LeftShift,
+      57_442 => :LeftControl,
+      57_443 => :LeftAlt,
+      57_444 => :LeftSuper,
+      57_445 => :LeftHyper,
+      57_446 => :LeftMeta,
+      57_447 => :RightShift,
+      57_448 => :RightControl,
+      57_449 => :RightAlt,
+      57_450 => :RightSuper,
+      57_451 => :RightHyper,
+      57_452 => :RightMeta,
+      57_453 => :IsoLevel3Shift,
+      57_454 => :IsoLevel5Shift
+    }.compare_by_identity.freeze
+
+    @csi = {
+      0x02 => :Ins,
+      0x03 => :Del,
+      0x05 => :PageUp,
+      0x06 => :PageDown,
+      0x07 => :Home,
+      0x08 => :End,
+      0x09 => :Tab,
+      0x0b => :F1,
+      0x0c => :F2,
+      0x0d => :F3,
+      0x0e => :F4,
+      0x0f => :F5,
+      0x11 => :F6,
+      0x12 => :F7,
+      0x13 => :F8,
+      0x14 => :F9,
+      0x15 => :F10,
+      0x17 => :F11,
+      0x18 => :F12,
+      0x19 => :F13,
+      0x1a => :F14,
+      0x1b => :F15,
+      0x1c => :F16,
+      0x1d => :F17,
+      0x1e => :F18,
+      0x1f => :F19,
+      0x20 => :F20,
+      0x21 => :F21,
+      0x22 => :F22,
+      0x23 => :F23,
+      0x24 => :F24
+    }.compare_by_identity.freeze
+
+    @ss3 = {
+      0x41 => :Up, # A
+      0x42 => :Down, # B
+      0x43 => :Right, # C
+      0x44 => :Left, # D
+      0x46 => :End, # F
+      0x48 => :Home, # H
+      0x50 => :F1, # P
+      0x51 => :F2, # Q
+      0x52 => :F3, # R
+      0x53 => :F4, # S
+      0x5a => [:Tab, 1] # Z - not widely used
+    }.compare_by_identity.freeze
+
+    @esc1 = {
+      0x08 => [:Back, 2],
+      0x09 => [:Tab, 2],
+      0x10 => ['?', 6],
+      0x0d => [:Enter, 2],
+      0x1b => [:Esc, 2],
+      0x20 => [:Space, 2],
+      0x7f => [:Back, 2]
+    }.compare_by_identity.freeze
+
+    @single_key = {
+      0x00 => [:Space, 4],
+      0x01 => ['a', 4],
+      0x02 => ['b', 4],
+      0x03 => ['c', 4],
+      0x04 => ['d', 4],
+      0x05 => ['e', 4],
+      0x06 => ['f', 4],
+      0x07 => ['g', 4],
+      0x08 => [:Back, 4],
+      0x09 => :Tab,
+      0x0a => ['j', 4],
+      0x0b => ['k', 4],
+      0x0c => ['l', 4],
+      0x0d => :Enter,
+      0x0e => ['n', 4],
+      0x0f => ['o', 4],
+      0x10 => ['p', 4],
+      0x11 => ['q', 4],
+      0x12 => ['r', 4],
+      0x13 => ['s', 4],
+      0x14 => ['t', 4],
+      0x15 => ['u', 4],
+      0x16 => ['v', 4],
+      0x17 => ['w', 4],
+      0x18 => ['x', 4],
+      0x19 => ['y', 4],
+      0x1a => ['z', 4],
+      0x1b => :Esc,
+      0x1c => ['4', 4],
+      0x1d => ['5', 4],
+      0x1e => ['6', 4],
+      0x1f => ['7', 4],
+      0x20 => :Space,
+      0x7f => :Back
+    }.compare_by_identity.freeze
+  end
+  private_constant :AsKeyEvent
+end

data/lib/terminal/input.rb

@@ -25,82 +25,221 @@ module Terminal
     # The input will be returned as named key codes like "Ctrl+c" by default.
     # This can be changed by `mode`.
     #
+    # @deprecated Use arther {read_key_event} for better input handling.
+    #
     # @param [:named, :raw, :both] mode modifies the result
     # @return [String] key code ("as is") in `:raw` mode
     # @return [String] key name in `:named` mode
     # @return [[String, String]] key code and key name in `:both` mode
+    # @return [nil] in any error case
     def read_key(mode: :named)
-      return if input_mode == :error
-      return read_dumb(mode == :both) if @input_mode == :dumb
-      return read_tty&.join if mode == :raw
-      key, name = read_tty_with(@input_mode == :csi_u ? CSIuKeys : LegacyKeys)
-      return unless key
+      event = read_key_event or return
+      return event.raw if mode == :raw
+      key, name = event
       mode == :both ? [key, name] : name || key
     end
 
-    private
-
-    def read_dumb(both)
-      inp = STDIN.getc
-      name = DumbKeys.key_name(inp)
-      both ? [inp, name] : name || inp
-    rescue Interrupt
-      DumbKeys.key_name("\x05")
+    # Read next {KeyEvent} from standard input.
+    #
+    # @return [KeyEvent] next event
+    # @return [nil] on any error
+    def read_key_event
+      case input_mode
+      when :dumb
+        raw = read_dumb or return
+        opts = DUMB_KEYS[raw.ord] if raw.size == 1
+        KeyEvent.new(raw, *opts)
+      when :csi_u, :legacy
+        # raw = with_mouse ? read_tty_with_mouse : read_tty
+        raw = read_tty
+        AsKeyEvent[raw] if raw
+      end
     end
 
-    def read_tty_with(trans)
-      key, *esc = read_tty
-      return unless key
-      return key, trans.key_name(key) if esc.empty?
-      [key + esc.join, trans.translate(esc)]
-    end
+    private
 
     def find_input_mode
       im = ENV['INPUT_MODE']
-      return :dumb if im == 'dumb' || !STDIN.tty?
+      return :dumb if im == 'dumb'
       return :legacy if im == 'legacy'
+      return :dumb unless STDIN.tty?
       if ansi? && _write("\e[>1u\e[?u\e[c") && csi_u?
         at_exit { _write("\e[<u") }
         :csi_u
       else
         :legacy
       end
-    rescue Interrupt
+    rescue SignalException
       :legacy
     rescue IOError, SystemCallError
       :error
     end
 
     def csi_u?
-      # iTerm2 returns result in two chunks :/
-      found = false
-      while true
-        inp = read_tty&.join or return false
-        found = true if inp.include?("\e[?1u")
-        return found if inp[-1] == 'c'
-      end
+      inp = +''
+      STDIN.raw { inp << _1.getch until inp.rindex('c') }
+      inp.include?("\e[?1u")
+    end
+
+    def read_dumb
+      STDIN.getc
+    rescue Interrupt
+      "\x05"
+    rescue IOError, SystemCallError
+      @input_mode = :error
+      nil
+    end
+
+    def read_tty_with_mouse(any_move: false)
+      # highlight: '1001'
+      # drag: '1002'
+      # move: '1003'
+      # ext: '1005'
+      # sgr: '1006'
+      # urxvt: '1015'
+      # pixel: '1016'
+      opts = any_move ? '1000;1003;1006;1015' : '1000;1006;1015'
+      opts = _write("\e[?#{opts}h") ? "\e[?#{opts}l" : nil
+      read_tty
+    ensure
+      _write(opts) if opts
     end
 
     def read_tty
-      STDIN.raw do |raw|
-        key = [raw.getch]
-        return key if key[0] != "\e"
-        while (nc = raw.read_nonblock(1, exception: false))
-          String === nc ? key << nc : break
-        end
-        key
+      key = STDIN.getch
+      return key if key != "\e"
+      while (nc = STDIN.read_nonblock(1, exception: false))
+        String === nc ? key << nc : break
       end
-    rescue Interrupt
+      key
+    rescue SignalException
       nil
     rescue IOError, SystemCallError
       @input_mode = :error
       nil
     end
+
+    DUMB_KEYS = {
+      0x05 => ['c', 4],
+      0x08 => :Back,
+      0x09 => :Tab,
+      0x0a => :Enter,
+      0x0d => :Return,
+      0x1b => :Esc
+    }.compare_by_identity.freeze
+    private_constant :DUMB_KEYS
+  end
+
+  #
+  # Key event reported from {read_key_event}.
+  #
+  class KeyEvent
+    class << self
+      # @attribute [w] caching
+      # @return [true, false] whether KeyCodes should be cached
+      def caching = !!@cache
+
+      # @attribute [w] caching
+      def caching=(value)
+        if value
+          @cache ||= {}
+        else
+          @cache = nil
+        end
+      end
+
+      def new(raw, key = raw, modifier = 0, extra = nil)
+        @cache ? super.freeze : @cache[raw] || (@cache[raw] = super.freeze)
+      end
+
+      def unknown(raw) = new(raw, nil)
+    end
+
+    # Event string received from standard input.
+    # This can be a simple value like `"a"`or `"\e[24;6~"` (for Shift+Ctrl+F12).
+    #
+    # @return [String] received event string
+    attr_reader :raw
+
+    # Pressed key without any modifiers.
+    # This can be a string for simple keys like `"a"` or a Symbol like `:F12`.
+    # @return [String, Symbol] key without modifiers
+    attr_reader :key
+
+    # Modifier key code. This represents the encoded key modifier like `Shift`
+    # or `Alt`.
+    #
+    # @return [Integer] modifier key code
+    attr_reader :modifier
+
+    # @comment for mouse events? attr_reader :extra
+
+    # Name of the key event.
+    # This can be a simple name like `"a"` or `"Shift+Ctrl+F12"` for combined
+    # keys.
+    #
+    # @return [String] key name
+    attr_reader :name
+
+    # @attribute [r] modifier?
+    # @return [true, false] whether a key modifier was pressed
+    def modifier? = @modifier != 0
+
+    # @attribute [r] simple?
+    # @return [true, false] whether a simple char was pressed
+    def simple? = @raw == @name
+
+    # All pressed keys.
+    # This is composed by all {modifier} and the {key}.
+    #
+    # @return [Array<Symbol, String>] all pressed keys
+    def to_a = @ary.dup
+
+    # @!visibility private
+    def to_ary = simple? ? [@raw] : [@raw, @name]
+
+    # @!visibility private
+    def to_s = @name.dup
+
+    # @!visibility private
+    def inspect = "<#{self.class.name} #{to_ary.map(&:inspect).join(' ')}>"
+
+    # @!visibility private
+    def freeze
+      @raw.freeze
+      @key.freeze
+      @extra.freeze
+      @name.freeze
+      super
+    end
+
+    private
+
+    def initialize(raw, key, modifier, extra)
+      @raw = raw
+      @key = key
+      @modifier = modifier
+      @extra = extra
+      @ary = MODIFIERS.filter_map { |b, n| n if modifier.allbits?(b) }
+      @ary << key if key
+      @name = @ary.join('+').encode(Encoding::UTF_8)
+    end
+
+    @cache = {}
+
+    MODIFIERS = {
+      1 => :Shift,
+      2 => :Alt,
+      4 => :Ctrl,
+      8 => :Super,
+      16 => :Hyper,
+      32 => :Meta,
+      64 => :Caps,
+      128 => :Num
+    }.freeze
+    private_constant :MODIFIERS
   end
 
-  dir = __dir__
-  autoload :CSIuKeys, "#{dir}/input/csiu_keys.rb"
-  autoload :DumbKeys, "#{dir}/input/dumb_keys.rb"
-  autoload :LegacyKeys, "#{dir}/input/legacy_keys.rb"
-  private_constant :CSIuKeys, :DumbKeys, :LegacyKeys
+  autoload :AsKeyEvent, "#{__dir__}/input/as_key_event.rb"
+  private_constant :AsKeyEvent
 end

data/lib/terminal/rspec/helper.rb

@@ -17,14 +17,13 @@ RSpec.shared_context 'with Terminal.rb' do |ansi: true, application: :kitty, col
     allow(Terminal).to receive(:hide_cursor).with(no_args).and_return(Terminal)
     allow(Terminal).to receive(:show_cursor).with(no_args).and_return(Terminal)
 
-    bbc =
-      if ansi
-        ->(s) { Terminal::Ansi.bbcode(s) }
-      else
-        ->(s) { Terminal::Ansi.plain(s) }
-      end
-
-    nobbc = ansi ? lambda(&:to_s) : ->(s) { Terminal::Ansi.undecorate(s) }
+    if ansi
+      bbc = ->(s) { Terminal::Ansi.bbcode(s) }
+      nobbc = lambda(&:to_s)
+    else
+      bbc = ->(s) { Terminal::Ansi.plain(s) }
+      nobbc = ->(s) { Terminal::Ansi.undecorate(s) }
+    end
 
     allow(Terminal).to receive(:<<) do |object|
       stdout.push(bbcode[object]) unless object.nil?

data/lib/terminal/text/char_width.rb

@@ -6,9 +6,9 @@ module Terminal
     # Generated file; based on Unicode v16.0.0
     #
     module CharWidth
-      def self.[](ord) = WIDTH[LAST.bsearch_index { ord <= _1 }]
+      def self.[](ord) = @width[@last.bsearch_index { ord <= _1 }]
 
-      LAST = [
+      @last = [
         0xa0,
         0xa1,
         0xa3,
@@ -1293,7 +1293,7 @@ module Terminal
         0x7fffffff
       ].freeze
 
-      WIDTH = [
+      @width = [
         1,
         -1,
         1,
@@ -2578,6 +2578,7 @@ module Terminal
         1
       ].freeze
     end
+
     private_constant :CharWidth
   end
 end

data/lib/terminal/version.rb

@@ -2,5 +2,5 @@
 
 module Terminal
   # The version number of the gem.
-  VERSION = '0.11.1'
+  VERSION = '0.12.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: terminal_rb
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.12.0
 platform: ruby
 authors:
 - Mike Blumtritt
@@ -34,9 +34,7 @@ files:
 - lib/terminal/ansi/named_colors.rb
 - lib/terminal/detect.rb
 - lib/terminal/input.rb
-- lib/terminal/input/csiu_keys.rb
-- lib/terminal/input/dumb_keys.rb
-- lib/terminal/input/legacy_keys.rb
+- lib/terminal/input/as_key_event.rb
 - lib/terminal/rspec/helper.rb
 - lib/terminal/text.rb
 - lib/terminal/text/char_width.rb
@@ -47,9 +45,10 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  yard.run: yard
   source_code_uri: https://codeberg.org/mblumtritt/Terminal.rb
   bug_tracker_uri: https://codeberg.org/mblumtritt/Terminal.rb/issues
-  documentation_uri: https://rubydoc.info/gems/terminal_rb/0.11.1/Terminal
+  documentation_uri: https://rubydoc.info/gems/terminal_rb/Terminal
 rdoc_options: []
 require_paths:
 - lib

data/lib/terminal/input/csiu_keys.rb

@@ -1,198 +0,0 @@
-# frozen_string_literal: true
-
-module Terminal
-  module CSIuKeys
-    class << self
-      def key_name(key)
-        @key_name[key.ord] if key.size == 1
-      end
-
-      def translate(esc)
-        return if esc[0] != '[' # ESC [ ...
-        return @csi1[esc[1].ord] if esc.size == 2 # ESC [ ?
-        return csi1(esc) if esc[1] == '1' && esc[2] == ';'
-        if esc[-1] == '~'
-          # ESC [ <code> ~
-          # ESC [ <code> ; <modifier> ~
-          return with_modifier(esc) { @csi[_1] }
-        end
-        return if esc[-1] != 'u'
-        # ESC [ <code> u
-        # ESC [ <code> ; <modifier> u
-        with_modifier(esc) { @csiu[_1] || _1.chr(Encoding::UTF_8) }
-      end
-
-      private
-
-      def csi1(esc)
-        # ESC [ 1 ; <modifier> [~ABCDEFHPQRS]
-        return if esc.size < 5
-        key = @csi1[esc[-1].ord] or return
-        return key if (mod = esc[3..-2].join.to_i - 1) < 1
-        (@mods.filter_map { |b, n| n if mod.allbits?(b) } << key).join('+')
-      end
-
-      def with_modifier(esc)
-        return yield(esc[1..-2].join.to_i) if (idx = esc.index(';')).nil?
-        key = yield(esc[1..(idx - 1)].join.to_i) or return
-        return key if (mod = esc[(idx + 1)..-2].join.to_i - 1) < 1
-        (@mods.filter_map { |b, n| n if mod.allbits?(b) } << key).join('+')
-      end
-    end
-
-    @csiu = {
-      0x02 => 'Ins',
-      0x09 => 'Tab',
-      0x0d => 'Enter',
-      0x1b => 'Esc',
-      0x20 => 'Space',
-      0x7f => 'Back',
-      57_376 => 'F13',
-      57_377 => 'F14',
-      57_378 => 'F15',
-      57_379 => 'F16',
-      57_380 => 'F17',
-      57_381 => 'F18',
-      57_382 => 'F19',
-      57_383 => 'F20',
-      57_384 => 'F21',
-      57_385 => 'F22',
-      57_386 => 'F23',
-      57_387 => 'F24',
-      57_388 => 'F25',
-      57_389 => 'F26',
-      57_390 => 'F27',
-      57_391 => 'F28',
-      57_392 => 'F29',
-      57_393 => 'F30',
-      57_394 => 'F31',
-      57_395 => 'F32',
-      57_396 => 'F33',
-      57_397 => 'F34',
-      57_398 => 'F35',
-      57_399 => 'Kp0',
-      57_400 => 'Kp1',
-      57_401 => 'Kp2',
-      57_402 => 'Kp3',
-      57_403 => 'Kp4',
-      57_404 => 'Kp5',
-      57_405 => 'Kp6',
-      57_406 => 'Kp7',
-      57_407 => 'Kp8',
-      57_408 => 'Kp9',
-      57_409 => 'KpDecimal',
-      57_410 => 'KpDivide',
-      57_411 => 'KpMultiply',
-      57_412 => 'KpSubtract',
-      57_413 => 'KpAdd',
-      57_414 => 'Return', # 'KpEnter'
-      57_415 => 'KpEqual',
-      57_416 => 'KpSeparator',
-      57_417 => 'KpLeft',
-      57_418 => 'KpRight',
-      57_419 => 'KpUp',
-      57_420 => 'KpDown',
-      57_421 => 'KpPage_up',
-      57_422 => 'KpPage_down',
-      57_423 => 'KpHome',
-      57_424 => 'KpEnd',
-      57_425 => 'KpInsert',
-      57_426 => 'KpDelete',
-      57_428 => 'MediaPlay',
-      57_429 => 'MediaPause',
-      57_430 => 'MediaPlay Pause',
-      57_431 => 'MediaReverse',
-      57_432 => 'MediaStop',
-      57_433 => 'MediaFast Forward',
-      57_434 => 'MediaRewind',
-      57_435 => 'MediaTrack Next',
-      57_436 => 'MediaTrack Previous',
-      57_437 => 'MediaRecord',
-      57_438 => 'LowerVolume',
-      57_439 => 'RaiseVolume',
-      57_440 => 'MuteVolume',
-      57_441 => 'LeftShift',
-      57_442 => 'LeftControl',
-      57_443 => 'LeftAlt',
-      57_444 => 'LeftSuper',
-      57_445 => 'LeftHyper',
-      57_446 => 'LeftMeta',
-      57_447 => 'RightShift',
-      57_448 => 'RightControl',
-      57_449 => 'RightAlt',
-      57_450 => 'RightSuper',
-      57_451 => 'RightHyper',
-      57_452 => 'RightMeta',
-      57_453 => 'IsoLevel3Shift',
-      57_454 => 'IsoLevel5Shift'
-    }.compare_by_identity.freeze
-
-    @csi1 = {
-      0x41 => 'Up', # A
-      0x42 => 'Down', # B
-      0x43 => 'Right', # C
-      0x44 => 'Left', # D
-      0x46 => 'End', # F
-      0x48 => 'Home', # H
-      0x50 => 'F1', # P
-      0x51 => 'F2', # Q
-      0x52 => 'F3', # R
-      0x53 => 'F4' # S
-    }.compare_by_identity.freeze
-
-    @csi = {
-      0x02 => 'Ins',
-      0x03 => 'Del',
-      0x05 => 'PageUp',
-      0x06 => 'PageDown',
-      0x07 => 'Home',
-      0x08 => 'End',
-      0x09 => 'Tab',
-      0x0b => 'F1',
-      0x0c => 'F2',
-      0x0d => 'F3',
-      0x0e => 'F4',
-      0x0f => 'F5',
-      0x11 => 'F6',
-      0x12 => 'F7',
-      0x13 => 'F8',
-      0x14 => 'F9',
-      0x15 => 'F10',
-      0x17 => 'F11',
-      0x18 => 'F12',
-      0x19 => 'F13',
-      0x1a => 'F14',
-      0x1b => 'F15',
-      0x1c => 'F16',
-      0x1d => 'F17',
-      0x1e => 'F18',
-      0x1f => 'F19',
-      0x20 => 'F20',
-      0x21 => 'F21',
-      0x22 => 'F22',
-      0x23 => 'F23',
-      0x24 => 'F24'
-    }.compare_by_identity.freeze
-
-    @key_name = {
-      0x04 => 'Del',
-      0x09 => 'Tab',
-      0x0d => 'Enter',
-      0x1b => 'Esc',
-      0x20 => 'Space',
-      0x7f => 'Back'
-    }.compare_by_identity.freeze
-
-    @mods = {
-      1 => 'Shift',
-      2 => 'Alt',
-      4 => 'Ctrl',
-      8 => 'Super',
-      16 => 'Hyper',
-      32 => 'Meta',
-      64 => 'Caps',
-      128 => 'Num'
-    }.freeze
-  end
-  private_constant :CSIuKeys
-end

data/lib/terminal/input/dumb_keys.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Terminal
-  module DumbKeys
-    def self.key_name(key)
-      @key_name[key.ord] if key.size == 1
-    end
-
-    @key_name = {
-      0x05 => 'Ctrl+c',
-      0x08 => 'Back',
-      0x09 => 'Tab',
-      0x0a => 'Enter',
-      0x0d => 'Return',
-      0x1b => 'Esc'
-    }.compare_by_identity.freeze
-  end
-  private_constant :DumbKeys
-end

data/lib/terminal/input/legacy_keys.rb

@@ -1,149 +0,0 @@
-# frozen_string_literal: true
-
-module Terminal
-  module LegacyKeys
-    class << self
-      def key_name(key)
-        @key_name[key.ord] if key.size == 1
-      end
-
-      def translate(esc)
-        return "Alt+#{@esc1[esc[0].ord] || esc[0]}" if esc.size == 1 # ESC ?
-        if esc.size == 2 && (esc[0] == 'O' || esc[0] == '[')
-          return @ss3[esc[1].ord] # ESC O ? || ESC [ ?
-        end
-        if esc[0] == "\e" # ESC ESC ...
-          return "Alt+#{@esc1[esc[1].ord] || esc[1]}" if esc.size == 1
-          esc.shift
-          return (name = translate(esc)) ? "Alt+#{name}" : nil
-        end
-        return if esc[0] != '[' # ESC [ ...
-        return csi1(esc) if esc[1] == '1' && esc[2] == ';'
-        csi(esc) if esc[-1] == '~'
-      end
-
-      private
-
-      def csi(esc)
-        # ESC [ <code> ~
-        # ESC [ <code> ; <modifier> ~
-        return @csi[esc[1..-2].join.to_i] if (idx = esc.index(';')).nil? # no mod
-        key = @csi[esc[1..(idx - 1)].join.to_i] or return
-        return key if (mod = esc[(idx + 1)..-2].join.to_i - 1) < 1 # no mod
-        (@mods.filter_map { |b, n| n if mod.allbits?(b) } << key).join('+')
-      end
-
-      def csi1(esc)
-        # ESC [ 1 ; <modifier> [~ABCDEFHPQRS]
-        return if esc.size < 5
-        key = @ss3[esc[-1].ord] or return
-        return key if (mod = esc[3..-2].join.to_i - 1) < 1 # no mod
-        (@mods.filter_map { |b, n| n if mod.allbits?(b) } << key).join('+')
-      end
-    end
-
-    @csi = {
-      0x02 => 'Ins',
-      0x03 => 'Del',
-      0x05 => 'PageUp',
-      0x06 => 'PageDown',
-      0x07 => 'Home',
-      0x08 => 'End',
-      0x09 => 'Tab',
-      0x0b => 'F1',
-      0x0c => 'F2',
-      0x0d => 'F3',
-      0x0e => 'F4',
-      0x0f => 'F5',
-      0x11 => 'F6',
-      0x12 => 'F7',
-      0x13 => 'F8',
-      0x14 => 'F9',
-      0x15 => 'F10',
-      0x17 => 'F11',
-      0x18 => 'F12',
-      0x19 => 'F13',
-      0x1a => 'F14',
-      0x1b => 'Enter',
-      0x1c => 'F15',
-      0x1d => 'F16',
-      0x1f => 'F17',
-      0x20 => 'F18',
-      0x21 => 'F19',
-      0x22 => 'F20'
-    }.compare_by_identity.freeze
-
-    @ss3 = {
-      0x41 => 'Up', # A
-      0x42 => 'Down', # B
-      0x43 => 'Right', # C
-      0x44 => 'Left', # D
-      0x46 => 'End', # F
-      0x48 => 'Home', # H
-      0x50 => 'F1', # P
-      0x51 => 'F2', # Q
-      0x52 => 'F3', # R
-      0x53 => 'F4', # S
-      0x5a => 'Shift+Tab' # Z - not widely used
-    }.compare_by_identity.freeze
-
-    @esc1 = {
-      0x08 => 'Back',
-      0x09 => 'Tab',
-      0x10 => 'Ctrl+?',
-      0x0d => 'Enter',
-      0x1b => 'Esc',
-      0x20 => 'Space',
-      0x7f => 'Back'
-    }.compare_by_identity.freeze
-
-    @key_name = {
-      0x00 => 'Ctrl+Space',
-      0x01 => 'Ctrl+a',
-      0x02 => 'Ctrl+b',
-      0x03 => 'Ctrl+c',
-      0x04 => 'Ctrl+d',
-      0x05 => 'Ctrl+e',
-      0x06 => 'Ctrl+f',
-      0x07 => 'Ctrl+g',
-      0x08 => 'Ctrl+Back',
-      0x09 => 'Tab',
-      0x0a => 'Ctrl+j',
-      0x0b => 'Ctrl+k',
-      0x0c => 'Ctrl+l',
-      0x0d => 'Enter',
-      0x0e => 'Ctrl+n',
-      0x0f => 'Ctrl+o',
-      0x10 => 'Ctrl+p',
-      0x11 => 'Ctrl+q',
-      0x12 => 'Ctrl+r',
-      0x13 => 'Ctrl+s',
-      0x14 => 'Ctrl+t',
-      0x15 => 'Ctrl+u',
-      0x16 => 'Ctrl+v',
-      0x17 => 'Ctrl+w',
-      0x18 => 'Ctrl+x',
-      0x19 => 'Ctrl+y',
-      0x1a => 'Ctrl+z',
-      0x1b => 'Esc',
-      0x1c => 'Ctrl+4',
-      0x1d => 'Ctrl+5',
-      0x1e => 'Ctrl+6',
-      0x1f => 'Ctrl+7',
-      0x20 => 'Space',
-      0x7f => 'Back'
-    }.compare_by_identity.freeze
-
-    @mods = {
-      1 => 'Shift',
-      2 => 'Alt',
-      4 => 'Ctrl',
-      8 => 'Super',
-      16 => 'Hyper',
-      32 => 'Meta',
-      64 => 'Caps',
-      128 => 'Num'
-    }.freeze
-  end
-  private_constant :LegacyKeys
-end