terminal_rb 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23d41a32cd285a8ec05dde44ac26131e207f567b4137ff4c1b144171abb72dd6
-  data.tar.gz: 28325ab102a8ecd1ec6e9f2b9196aa85f8bf8d59898b6105a26d6afa2cc1a065
+  metadata.gz: 05eda4c596ad7060b576cb01f6fe7dafd38e114274b44c14c4c90e1b3a2b322a
+  data.tar.gz: '0479860569041d6fb874d38de0d183a2cc778a6803d3eed302425cd795133e06'
 SHA512:
-  metadata.gz: ff88211e6ac2b869db965ef8861ddf312699c4cef971deea0f2b75bfac0f77df8f23936aa2a6870adfd60167391a720e76a089918b1e8b2bb35842d6fd32cb0a
-  data.tar.gz: '091504b7dfebe143f8df736f52db891a08a27d4bac9763706af06def5a9c2e413b620300c4188bd700c529b2446cb1ecb351a4425772bdd051b46332b96ce4bd'
+  metadata.gz: ab038b9b4cc9ed41ba09673be9a2e2d25aa2edc2ffbf1fa0cad826ca7f55c8fef3aab734648f13f63750ea7799bce638479839e5f609e597eeb0bf4508b0f0e7
+  data.tar.gz: b501721dfd7d6d79ceb8821fa5dd9d877e764e235435f3e6441e9b02b424a5873aba1318365a4b064a9430c135882be39470361d0042b56726be3dd2505e9db5

data/README.md

@@ -1,6 +1,6 @@
 # Terminal.rb ![version](https://img.shields.io/gem/v/terminal_rb?label=)
 
-Terminal.rb supports you with input and output on your terminal. Simple [BBCode](https://en.wikipedia.org/wiki/BBCode)-like markup for attributes and coloring, word-wise line breaks, and correct special key recognition enable you to implement your CLI app quickly and easily.
+Terminal.rb supports you with input and output on your terminal. Simple [BBCode](https://en.wikipedia.org/wiki/BBCode)-like markup for attributes and coloring, word-wise line breaks, correct special key recognition and mouse event reporting enable you to implement your CLI app quickly and easily.
 
 - Gem: [rubygems.org](https://rubygems.org/gems/terminal_rb)
 - Source: [codeberg.org](https://codeberg.org/mblumtritt/Terminal.rb)
@@ -16,6 +16,7 @@ Terminal.rb supports you with input and output on your terminal. Simple [BBCode]
 - calculation for correct display width of strings containing Unicdode chars inclusive emojis
 - word-wise line break generator
 - supports [CSIu protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol)
+- mouse events support
 
 ## Examples
 

data/examples/key-codes.rb

@@ -13,10 +13,13 @@ TEXT
 Terminal.hide_cursor
 at_exit { Terminal.show_cursor } # required for some terminals :/
 
-while true
-  event = Terminal.read_key_event or break puts
+# if you like to have mouse position changes reported then use
+# 'mouse_move: true' in next line
+Terminal.on_key_event(mouse: true, focus: true, mouse_move: false) do |event|
   str = "[blue]: [yellow]#{event.raw.inspect}"
   str << " [bold bright_green]#{event.name}[/]" unless event.simple?
+  str << " [dim]#{event.position.inspect}[/]" if event.position
   Terminal.puts(str)
-  break puts if event.name == 'Esc'
+  event.name != 'Esc'
 end
+puts

data/lib/terminal/ansi.rb

@@ -34,8 +34,8 @@ module Terminal
       # @!group ANSI control code generator functions
       #
 
-      # Combine given ANSI {attributes}, {colors}, {named_colors} and color
-      # codes.
+      # Combine given {attributes}, {colors}, {named_colors} and color codes to
+      # an ANSI control code sequence.
       #
       # Colors can specified by their name for ANSI 3-bit and 4-bit colors.
       # For 8-bit ANSI colors use 2-digit hexadecimal values `00`...`ff`.
@@ -96,7 +96,7 @@ module Terminal
         return +'' if attributes.empty?
         "\e[#{
           attributes
-            .map do |arg|
+            .map! do |arg|
               case arg
               when String
                 @attr_map[arg] || _invalid(arg)
@@ -154,8 +154,7 @@ module Terminal
       # @param str [#to_s] string to be modified
       # @return [String] string without ANSI attributes
       def undecorate(str)
-        str = str.to_s
-        str.index("\e") ? str.gsub(@re_test, '') : str.dup
+        (str = str.to_s).index("\e") ? str.gsub(@re_test, '') : str.dup
       end
 
       # Try to combine given ANSI attributes and colors.
@@ -263,8 +262,7 @@ module Terminal
       # @param str [#to_s] string to be modified
       # @return [String] string without BBCode and ANSI control codes.
       def plain(str)
-        str = str.to_s
-        unless str.index('[')
+        unless (str = str.to_s).index('[')
           return str.index("\e") ? str.gsub(@re_test, '') : str.dup
         end
         str =
@@ -289,16 +287,14 @@ module Terminal
         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|
+        (
+          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}"
-          end
-          .join << RESET
+          end << RESET
+        ).join
       end
 
       #
@@ -349,6 +345,21 @@ module Terminal
       # @return (see cursor_up)
       def cursor_column(column = 1) = "\e[#{column}G"
 
+      # Move cursor to given column in the current row relative to the current
+      # position.
+      # (Skip some columns.)
+      #
+      # @param (see cursor_column)
+      # @return (see cursor_up)
+      def cursor_column_rel(column = 1) = "\e[#{column}a"
+
+      # Move cursor to given row relative to the current position.
+      # (Skip some rows.)
+      #
+      # @param row [Integer] row index
+      # @return (see cursor_up)
+      def cursor_row_rel(row = 1) = "\e[#{row}e"
+
       # Move to given row and column.
       #
       # @param row [Integer] row index
@@ -389,20 +400,7 @@ module Terminal
       #
       # @param part [:below, :above, :all, :scrollback] screen part to erase
       # @return (see cursor_up)
-      def screen_erase(part = :all)
-        "\e[#{
-          case part
-          when :below
-            # nop
-          when :above
-            '1'
-          when :scrollback
-            '3'
-          else # all
-            '2'
-          end
-        }J"
-      end
+      def screen_erase(part = :all) = "\e[#{@screen_erase[part]}J"
 
       # Safe current screen.
       #
@@ -442,22 +440,17 @@ module Terminal
       # @!group Other ANSI control functions
       #
 
+      # Repeat last char.
+      #
+      # @param count [Integer] repeat count
+      # @return (see cursor_up)
+      def char_repeat(count = 1) = "\e[#{count}b"
+
       # Erase part of line.
       #
       # @param part [:to_end, :to_start, :all] line part to erase
       # @return (see cursor_up)
-      def line_erase(part = :all)
-        "\e[#{
-          case part
-          when :to_end
-            # nop
-          when :to_start
-            '1'
-          else # :all
-            '2'
-          end
-        }K"
-      end
+      def line_erase(part = :all) = "\e[#{@line_erase[part]}K"
 
       # Set (tab) title.
       # This is not widely supported; works for
@@ -570,27 +563,6 @@ module Terminal
           caller(1)
         )
       end
-
-      def _color(str)
-        b, v = /\A(fg|bg|on|ul)?_?#?([[:xdigit:]]{1,6})\z/.match(str)&.captures
-        if v
-          return(
-            case v.size
-            when 1, 2
-              "#{@cbase[b]};5;#{v.hex}"
-            when 3
-              "#{@cbase[b]};2;#{(v[0] * 2).hex};#{
-                (v[1] * 2).hex
-              };#{(v[2] * 2).hex}"
-            when 6
-              "#{@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 "#{@cbase[b]};#{name}"
-      end
     end
 
     @cbase = { 'bg' => '48', 'on' => '48', 'ul' => '58' }
@@ -606,56 +578,6 @@ module Terminal
 
     @re_bbcode = /(?:\[((?~[\[\]]))\])/
 
-    attr_map = {
-      '' => 'reset',
-      '1' => 'bold',
-      '2' => 'faint',
-      '3' => 'italic',
-      '4' => 'underline',
-      '5' => 'blink',
-      '6' => 'rapid_blink',
-      '7' => 'invert',
-      '8' => 'hide',
-      '9' => 'strike',
-      '10' => 'primary_font',
-      '11' => 'font1',
-      '12' => 'font2',
-      '13' => 'font3',
-      '14' => 'font4',
-      '15' => 'font5',
-      '16' => 'font6',
-      '17' => 'font7',
-      '18' => 'font8',
-      '19' => 'font9',
-      '20' => 'fraktur',
-      '21' => 'double_underline',
-      '22' => 'bold_off', # faint_off
-      '23' => 'italic_off', # fraktur_off
-      '24' => 'underline_off', # double_underline_off
-      '25' => 'blink_off', # rapid_blink_off
-      '26' => 'proportional',
-      '27' => 'invert_off',
-      '28' => 'hide_off',
-      '29' => 'strike_off',
-      # colors ...
-      '50' => 'proportional_off',
-      '51' => 'framed',
-      '52' => 'encircled',
-      '53' => 'overlined',
-      '54' => 'framed_off', # encircled_off
-      '55' => 'overlined_off',
-      # ...
-      '73' => 'superscript',
-      '74' => 'subscript',
-      '75' => 'superscript_off', # subscript_off
-      # special underline
-      '4:3' => 'curly_underline',
-      '4:4' => 'dotted_underline',
-      '4:5' => 'dashed_underline',
-      '4:0' => 'curly_underline_off' # dotted_underline_off, dashed_underline_off
-    }.invert
-    attr_alias = ->(t, s) { attr_map[t] = attr_map[s] }
-
     clr_map = {
       # foreground
       '30' => 'black',
@@ -725,6 +647,56 @@ module Terminal
     clr_alias['fg_default', 'default']
     clr_alias['bg_default', 'on_default']
 
+    attr_map = {
+      '' => 'reset',
+      '1' => 'bold',
+      '2' => 'faint',
+      '3' => 'italic',
+      '4' => 'underline',
+      '5' => 'blink',
+      '6' => 'rapid_blink',
+      '7' => 'invert',
+      '8' => 'hide',
+      '9' => 'strike',
+      '10' => 'primary_font',
+      '11' => 'font1',
+      '12' => 'font2',
+      '13' => 'font3',
+      '14' => 'font4',
+      '15' => 'font5',
+      '16' => 'font6',
+      '17' => 'font7',
+      '18' => 'font8',
+      '19' => 'font9',
+      '20' => 'fraktur',
+      '21' => 'double_underline',
+      '22' => 'bold_off', # faint_off
+      '23' => 'italic_off', # fraktur_off
+      '24' => 'underline_off', # double_underline_off
+      '25' => 'blink_off', # rapid_blink_off
+      '26' => 'proportional',
+      '27' => 'invert_off',
+      '28' => 'hide_off',
+      '29' => 'strike_off',
+      # colors ...
+      '50' => 'proportional_off',
+      '51' => 'framed',
+      '52' => 'encircled',
+      '53' => 'overlined',
+      '54' => 'framed_off', # encircled_off
+      '55' => 'overlined_off',
+      # ...
+      '73' => 'superscript',
+      '74' => 'subscript',
+      '75' => 'superscript_off', # subscript_off
+      # special underline
+      '4:3' => 'curly_underline',
+      '4:4' => 'dotted_underline',
+      '4:5' => 'dashed_underline',
+      '4:0' => 'curly_underline_off' # dotted_underline_off, dashed_underline_off
+    }.invert
+    attr_alias = ->(t, s) { attr_map[t] = attr_map[s] }
+
     attr_alias['faint_off', 'bold_off']
     attr_alias['fraktur_off', 'italic_off']
     attr_alias['double_underline_off', 'underline_off']
@@ -788,7 +760,23 @@ module Terminal
     attr_map['/bg'] = clr_map['on_default']
     attr_map['/ul'] = clr_map['ul_default']
 
-    @attr_map = Hash.new { _color(_2) }
+    @attr_map =
+      Hash.new do |_, str|
+        b, v = /\A(fg|bg|on|ul)?_?#?([[:xdigit:]]{1,6})\z/.match(str)&.captures
+        unless v
+          b = /\A(fg|bg|on|ul)?_?([a-z]{3,}[0-9]{0,3})\z/.match(str) or next
+          name = NAMED_COLORS[b[2]] or next
+          next "#{@cbase[b[1]]};#{name}"
+        end
+        case v.size
+        when 1, 2
+          "#{@cbase[b]};5;#{v.hex}"
+        when 3
+          "#{@cbase[b]};2;#{(v[0] * 2).hex};#{(v[1] * 2).hex};#{(v[2] * 2).hex}"
+        when 6
+          "#{@cbase[b]};2;#{v[0, 2].hex};#{v[2, 2].hex};#{v[4, 2].hex}"
+        end
+      end
     attr_map.merge!(clr_map).keys.sort!.each { @attr_map[_1] = attr_map[_1] }
     @attr_map.freeze
 
@@ -796,21 +784,29 @@ module Terminal
     @attrs_map.default_proc = @attr_map.default_proc
     @attrs_map.compare_by_identity.freeze
 
+    @screen_erase = { below: nil, above: '1', scrollback: '3' }
+    @screen_erase.default = '2'
+    @screen_erase.compare_by_identity.freeze
+
+    @line_erase = { to_end: nil, to_start: '1' }
+    @line_erase.default = '2'
+    @line_erase.compare_by_identity.freeze
+
     autoload :NAMED_COLORS, "#{__dir__}/ansi/named_colors.rb"
     private_constant :NAMED_COLORS
 
     # @private
-    RESET = self[:reset].freeze
+    RESET = -self[:reset]
 
     # @private
     FULL_RESET = "\ec"
 
     # @private
-    CURSOR_HOME = cursor_pos(nil, nil).freeze
+    CURSOR_HOME = -cursor_pos(nil, nil)
     # @private
-    CURSOR_FIRST_ROW = cursor_pos(1).freeze
+    CURSOR_FIRST_ROW = -cursor_pos(1)
     # @private
-    CURSOR_FIRST_COLUMN = cursor_column(1).freeze
+    CURSOR_FIRST_COLUMN = -cursor_column(1)
 
     # @private
     CURSOR_SHOW = "\e[?25h"
@@ -828,13 +824,13 @@ module Terminal
     CURSOR_POS_RESTORE = "\e8"
 
     # @private
-    SCREEN_ERASE = screen_erase.freeze
+    SCREEN_ERASE = -screen_erase
     # @private
-    SCREEN_ERASE_BELOW = screen_erase(:below).freeze
+    SCREEN_ERASE_BELOW = -screen_erase(:below)
     # @private
-    SCREEN_ERASE_ABOVE = screen_erase(:above).freeze
+    SCREEN_ERASE_ABOVE = -screen_erase(:above)
     # @private
-    SCREEN_ERASE_SCROLLBACK = screen_erase(:scrollback).freeze
+    SCREEN_ERASE_SCROLLBACK = -screen_erase(:scrollback)
 
     # @private
     SCREEN_SAVE = "\e[?47h"
@@ -843,7 +839,7 @@ module Terminal
 
     # @private
     # @comment at least Kitty requires CURSOR_HOME too
-    SCREEN_ALTERNATE = "\e[?1049h#{CURSOR_HOME}".freeze
+    SCREEN_ALTERNATE = -"\e[?1049h#{CURSOR_HOME}"
     # @private
     SCREEN_ALTERNATE_OFF = "\e[?1049l"
 
@@ -853,21 +849,19 @@ module Terminal
     SCREEN_REVERSE_MODE_OFF = "\e[?5l"
 
     # @private
-    LINE_ERASE = line_erase.freeze
+    LINE_ERASE = -line_erase
     # @private
-    LINE_ERASE_TO_END = line_erase(:to_end).freeze
+    LINE_ERASE_TO_END = -line_erase(:to_end)
     # @private
-    LINE_ERASE_TO_START = line_erase(:to_start).freeze
+    LINE_ERASE_TO_START = -line_erase(:to_start)
     # @private
-    LINE_ERASE_PREV = "#{cursor_prev_line(nil)}#{LINE_ERASE}".freeze
+    LINE_ERASE_PREV = -"#{cursor_prev_line(nil)}#{LINE_ERASE}"
 
     # @comment seems not widely supported:
     #   doubled: def cursor_column(column = 1) = "\e[#{column}`"
     #   doubled: def cursor_row(row = 1) = "\e[#{row}d"
     #   doubled: def cursor_pos(row, col) = "\e[#{row};#{col}f"
     #
-    #   def cursor_column_rel(columns = 1) = "\e[#{columns}a"
-    #   def cursor_row_rel(rows = 1) = "\e[#{rows}e"
     #   def cursor_tab(count = 1) = "\e[#{column}I"
     #   def cursor_reverse_tab(count = 1) = "\e[#{count}Z"
     #
@@ -878,20 +872,14 @@ module Terminal
     #   def chars_delete(count = 1) = "\e[#{count}P"
     #   def chars_erase(count = 1) = "\e[#{count}X"
     #
-    #   def chars_repeat_last(count = 1) = "\e[#{count}b"
-    #
-    #   def notify(title) = "\e]9;#{title}\a"
-    #
     #   def set_scroll_region(top = nil, bottom = nil) = "\e[#{top};#{bottom}r"
 
     # @comment other:
     #   "\eE" same as "\r\n"
-    #   "\eD" same as "\n" but preserves X coord
+    #   "\eD" same as "\n" but preserves column
     #   "\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[?1004h" report focus lost "\e[O" and focus get "\e[I"
-    #     (disable by "\e[?1004l")
 
     # @comment TODO:
     #   https://sw.kovidgoyal.net/kitty/desktop-notifications

data/lib/terminal/input/key_event.rb

@@ -2,9 +2,85 @@
 
 module Terminal
   #
-  # Key event reported from {read_key_event}.
+  # Key event reported from {read_key_event} and {on_key_event}.
   #
   class KeyEvent
+    # ANSI code sequence received from standard input.
+    # This can be a simple value like `"a"`or more complex input like
+    # `"\e[24;6~"` (for Shift+Ctrl+F12).
+    #
+    # @return [String] received ANSI code sequence
+    attr_reader :raw
+
+    # Pressed key without any modifiers.
+    # This can be a string for simple keys like `"a"` or a Symbol like `:F12`
+    # (see {.key_names}).
+    # @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
+
+    # Mouse event position.
+    #
+    # @return [[Integer,Integer]] row and column
+    # @return nil when no coordinates are assigned
+    attr_reader :position
+
+    # 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 key 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
+
+    # @private
+    def to_ary = simple? ? [@raw] : [@raw, @name]
+
+    # @private
+    def to_s = @name.dup
+
+    # @private
+    def inspect = "<#{self.class.name} #{to_ary.map(&:inspect).join(' ')}>"
+
+    # @private
+    def freeze
+      @raw.freeze
+      @key.freeze
+      @position.freeze
+      @name.freeze
+      super
+    end
+
+    private
+
+    def initialize(raw, key, modifier, position)
+      @raw = raw
+      @key = key
+      @modifier = modifier
+      @position = position
+      @ary = MODIFIERS.filter_map { |b, n| n if modifier.allbits?(b) }
+      @ary << key if key
+      @name = @ary.join('+') # .encode(Encoding::UTF_8)
+    end
+
     class << self
       # @attribute [w] caching
       # @return [true, false] whether {KeyEvent}s should be cached
@@ -12,24 +88,33 @@ module Terminal
 
       # @attribute [w] caching
       def caching=(value)
-        if value
-          @cache ||= {}
-        else
-          @cache = nil
-        end
+        value ? @cache ||= {} : @cache = nil
       end
 
-      # Translate a keyboard input string into a related KeyEvent
+      # @attribute [r] key_names
+      # @return [Array<Symbol>] list of all avilable key names (see {key})
+      def key_names
+        (
+          @names ||=
+            (@csiu.values + @csi.values + @ss3.values)
+              .uniq
+              .keep_if { Symbol === _1 }
+              .sort!
+        ).dup
+      end
+
+      # Translate a ANSI input code sequence into a related KeyEvent.
       #
       # @param raw [String] keyboard input
       # @return [KeyEvent] related key event
       def [](raw)
+        cached = @cache[raw] and return cached if @cache
         return new(raw, *@single_key[raw.ord]) if raw.size == 1
         return 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 "\e"
+          return esc_esc(raw) # ESC ESC ...
         when 'O'
           return new(raw, *@ss3[raw[2].ord]) if raw.size == 3 # ESC O ?
         when '['
@@ -37,15 +122,17 @@ module Terminal
           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 ; ...
+          if raw.size > 4 && raw[2] == '1' && raw[3] == ';'
+            return csi(raw) # ESC [ 1 ; ...
+          end
           case raw[-1]
-          when '~' # ESC [ ... ~
-            return legacy(raw)
-          when 'u' # ESC [ ... u
-            return csi_u(raw)
-          when 'M' # ESC [ ... M
-            return raw[2] == '<' ? mouse_sgr(raw) : mouse_urxvt(raw)
-          when 'm' # ESC [ ... m
+          when '~'
+            return legacy(raw) # ESC [ ... ~
+          when 'u'
+            return csi_u(raw) # ESC [ ... u
+          when 'M', 'm'
+            # ESC [ ... M
+            # ESC [ ... m
             return mouse_sgr(raw) if raw[2] == '<'
           end
         end
@@ -53,40 +140,29 @@ module Terminal
       end
 
       # @private
-      def new(raw, key = raw, modifier = 0, extra = nil)
-        @cache ? (@cache[raw] ||= super.freeze) : super.freeze
+      def new(raw, key = raw, modifier = 0, position = nil)
+        (@cache && position.nil? ? @cache[raw] ||= super : super).freeze
       end
 
       private
 
       def unknown(raw) = new(raw, nil)
 
-      def csi_u(raw)
-        # ESC [ <code> u
-        # ESC [ <code> ; <modifier> u
-        return unknown(raw) if raw.size < 4
-        idx = raw.index(';')
-        code = raw[2..(idx ? idx - 1 : -2)].to_i
-        new(
-          raw,
-          @csiu[code] || code.chr(Encoding::UTF_8),
-          idx ? [raw[(idx + 1)..-2].to_i - 1, 0].max : 0
-        )
+      def esc1(raw, char)
+        # ESC ?
+        key, modifier = @esc1[char.ord]
+        new(raw, key || char, modifier || 2)
       end
 
-      def legacy(raw)
-        # ESC [ <code> ~
-        # ESC [ <code> ; <modifier> ~
-        return unknown(raw) if raw.size < 4
-        idx = raw.index(';')
-        new(
-          raw,
-          @csi[raw[2..(idx ? idx - 1 : -2)].to_i],
-          idx ? [raw[(idx + 1)..-2].to_i - 1, 0].max : 0
-        )
+      def esc_esc(raw)
+        # ESC ESC ?
+        # ESC ESC ...
+        return esc1(raw, raw[2]) if raw.size == 3
+        ret = self[raw[1..]]
+        new(raw, ret.key, ret.modifier | 2)
       end
 
-      def csi1(raw)
+      def csi(raw)
         # ESC [ 1 ; [~ABCDEFHPQRS]
         # ESC [ 1 ; <modifier> [~ABCDEFHPQRS]
         return unknown(raw) if raw.size < 5
@@ -97,19 +173,33 @@ module Terminal
         new(raw, key, modifier)
       end
 
-      def esc_esc(raw)
-        return esc1(raw, raw[2]) if raw.size == 3 # ESC ESC ?
-        ret = self[raw[1..]]
-        new(raw, ret.key, ret.modifier | 2) # ESC ESC ...
+      def legacy(raw)
+        # ESC [ <code> ~
+        # ESC [ <code> ; <modifier> ~
+        return unknown(raw) if raw.size < 4
+        idx = raw.index(';')
+        new(
+          raw,
+          @csi[raw[2..(idx ? idx - 1 : -2)].to_i],
+          idx ? [raw[(idx + 1)..-2].to_i - 1, 0].max : 0
+        )
       end
 
-      def esc1(raw, char)
-        key, modifier = @esc1[char.ord]
-        new(raw, key || char, modifier || 2)
+      def csi_u(raw)
+        # ESC [ <code> u
+        # ESC [ <code> ; <modifier> u
+        return unknown(raw) if raw.size < 4
+        idx = raw.index(';')
+        code = raw[2..(idx ? idx - 1 : -2)].to_i
+        new(
+          raw,
+          @csiu[code] || code.chr(Encoding::UTF_8),
+          idx ? [raw[(idx + 1)..-2].to_i - 1, 0].max : 0
+        )
       end
 
       def mouse_vt200(raw)
-        # ESC [ M b c r
+        # ESC [ M <btn> <col> <row>
         mouse_event(raw, *raw[3..].chars.map! { _1.ord - 32 })
       end
 
@@ -118,117 +208,40 @@ module Terminal
         # ESC [ < <code> ; <col> ; <row> m
         return unknown(raw) if raw.size < 8
         bcr = raw[3..-2].split(';', 3).map!(&:to_i)
-        bcr.size == 3 ? mouse_event(raw, *bcr) : unknown(raw)
+        bcr.size == 3 ? mouse_event(raw, *bcr, raw[-1] == 'm') : unknown(raw)
       end
 
-      def mouse_urxvt(raw)
-        # ESC [ <code> ; <col> ; <row> M
-        return unknown(raw) if raw.size < 8
-        bcr = raw[2..-2].split(';', 3).map!(&:to_i)
-        bcr.size == 3 ? mouse_event(raw, *bcr) : unknown(raw)
-      end
+      # def mouse_urxvt(raw)
+      #   # ESC [ <code> ; <col> ; <row> M
+      #   unknown(raw) # currently not supported
+      # end
 
-      def mouse_event(raw, btn, col, row)
+      def mouse_event(raw, btn, col, row, up = false)
         return unknown(raw) if btn < 0 || col < 1 || row < 1
-        key, btn = kind_of_mouse_event(btn)
+        key = (btn & 1).nonzero? ? 1 : 0
+        key += 2 if btn.allbits?(2)
         modifier = btn.allbits?(4) ? 1 : 0
         modifier += 2 if btn.allbits?(8)
         modifier += 4 if btn.allbits?(16)
-        new(raw, key, modifier, [col, row])
+        modifier += 256 if moved = btn.allbits?(32)
+        key += 4 if btn.allbits?(64)
+        key += 8 if btn.allbits?(128)
+        new(raw, mouse_name(key, up, moved), modifier, [row, col])
       end
 
-      def mouse_event_key(btn)
-        kind = btn & 3
-        key = (btn >= 64 ? @mouse_wheel_kind : @mouse_kind)[kind]
-        # TODO: what about btn >= 128 for more mouse wheel events?
-        [btn - kind, key]
+      def mouse_name(key, up, moved)
+        return up ? :MBLeftUp : :MBLeft if key == 0
+        return up ? :MBMiddleUp : :MBMiddle if key == 1
+        return up ? :MBRightUp : :MBRight if key == 2
+        return moved ? :Mouse : :MBUp if key == 3
+        return :MWUp if key == 4
+        return :MWDown if key == 5
+        return :MWLeft if key == 6
+        return :MWRight if key == 7
+        :"MB_#{key - 8}#{'Up' if up}"
       end
     end
 
-    # Event string received from standard input.
-    # This can be a simple value like `"a"`or more complex input like
-    # `"\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
-    # @private
-    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 key 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
-
-    # @private
-    def to_ary = simple? ? [@raw] : [@raw, @name]
-
-    # @private
-    def to_s = @name.dup
-
-    # @private
-    def inspect = "<#{self.class.name} #{to_ary.map(&:inspect).join(' ')}>"
-
-    # @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
-
-    @mouse_kind = %i[
-      MButton1
-      MButton2
-      MButton3
-      MButtonUp
-      MButton4
-      MButton5
-    ].freeze
-
-    @mouse_wheel_kind = %i[MWheelDown MWheelUp MWheelRight MWheelLeft].freeze
-
     @csiu = {
       0x02 => :Ins,
       0x09 => :Tab,
@@ -357,6 +370,8 @@ module Terminal
       0x44 => :Left, # D
       0x46 => :End, # F
       0x48 => :Home, # H
+      0x49 => :Focus, # I
+      0x4f => :UnFocus, # O
       0x50 => :F1, # P
       0x51 => :F2, # Q
       0x52 => :F3, # R
@@ -421,7 +436,8 @@ module Terminal
       16 => :Hyper,
       32 => :Meta,
       64 => :Caps,
-      128 => :Num
+      128 => :Num,
+      256 => :Move # mouse
     }.freeze
     private_constant :MODIFIERS
   end

data/lib/terminal/input.rb

@@ -16,7 +16,7 @@ module Terminal
     # @return [:dumb]
     #   for non-interactive input (pipes etc.)
     # @return [:error]
-    #   when input device is closed
+    #   when input device is not avail (closed)
     def input_mode
       @input_mode ||= find_input_mode
     end
@@ -34,6 +34,10 @@ module Terminal
     # @return [[String, String]] key code and key name in `:both` mode
     # @return [nil] in error case
     def read_key(mode: :named)
+      warn(
+        'Terminal.read_key is deprecaded; use Terminal.read_key_event instead.',
+        uplevel: 1
+      )
       event = read_key_event or return
       return event.raw if mode == :raw
       key, name = event
@@ -48,25 +52,109 @@ module Terminal
       case input_mode
       when :dumb
         raw = read_dumb or return
-        opts = DUMB_KEYS[raw.ord] if raw.size == 1
+        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
-        KeyEvent[raw] if (raw = read_tty)
+        raw = read_tty or return
+        KeyEvent[raw]
+      end
+    end
+
+    # Event loop for key and mouse events.
+    #
+    # @param mouse [true, false]
+    #   whether mouse buttons should be reported
+    # @param mouse_move [true, false]
+    #   whether mouse movement should be reported
+    # @param focus [true, false]
+    #   whether focus/unfocus of terminal window should be reported
+    # @yieldparam event [KeyEvent]
+    #   next event
+    # @yieldreturn [true, false]
+    #   whether the loop should be continued
+    # @return [true]
+    #   when the loop was started
+    # @return [false]
+    #   when the current input device is not available
+    # @return [nil]
+    #   when no block was given
+    def on_key_event(mouse: false, mouse_move: false, focus: false, &block)
+      return unless block
+      case input_mode
+      when :dumb
+        on_bumb_key_event(&block)
+        true
+      when :csi_u, :legacy
+        on_tty_key_event(mouse, mouse_move, focus, &block)
+        true
+      else
+        false
       end
     end
 
     private
 
+    def on_tty_key_event(mouse, mouse_move, focus)
+      # highlight: '1001'
+      # drag: '1002'
+      # move: '1003'
+      # focus: '1004' - lost: "\e[O", get: "\e[I"
+      # ext: '1005'
+      # sgr: '1006'
+      # urxvt: '1015'
+      # pixel: '1016'
+      opts =
+        if mouse || mouse_move || focus
+          opts = mouse ? +"\e[?1006;1000" : +"\e[?1006"
+          opts << ';1003' if mouse_move
+          opts << ';1004' if focus
+          raw_write("#{opts}h") ? "#{opts}l" : nil
+        end
+      STDIN.noecho do |stdin|
+        while (raw = stdin.getch)
+          if raw != "\e"
+            yield(KeyEvent[raw]) ? next : break
+          end
+          lesci = 0
+          while (nc = stdin.read_nonblock(1, exception: false))
+            break unless String === nc
+            lesci = raw.size if nc == "\e"
+            raw << nc
+          end
+          if lesci < 2
+            yield(KeyEvent[raw]) ? next : break
+          end
+          break unless raw[1..].split("\e").all? { yield(KeyEvent["\e#{_1}"]) }
+        end
+      end
+    rescue Interrupt
+      # nop
+    rescue IOError, SystemCallError
+      @input_mode = :error
+    ensure
+      raw_write(opts) if opts
+    end
+
+    def on_bumb_key_event
+      while (raw = read_dumb)
+        opts = @dumb_keys[raw.ord] if raw.size == 1
+        return unless yield(KeyEvent.new(raw, *opts))
+      end
+    end
+
     def find_input_mode
-      # order is important!
       im = ENV['INPUT_MODE']
-      return :dumb if im == 'dumb'
       return :legacy if im == 'legacy'
-      return :dumb unless STDIN.tty?
-      if ansi? && raw_write("\e[>1u\e[?u\e[c") && csi_u?
-        at_exit { raw_write("\e[<u") }
-        return :csi_u
+      return :dumb if im == 'dumb' || !STDIN.tty?
+      STDIN.noecho do |stdin|
+        if raw_write("\e[>1u\e[?u\e[c")
+          inp = +''
+          inp << stdin.getch until inp.rindex('c')
+          if inp.include?("\e[?1u")
+            at_exit { raw_write("\e[<u") }
+            return :csi_u
+          end
+        end
       end
       :legacy
     rescue Interrupt
@@ -75,12 +163,6 @@ module Terminal
       :error
     end
 
-    def csi_u?
-      inp = +''
-      STDIN.raw { inp << _1.getch until inp.rindex('c') }
-      inp.include?("\e[?1u")
-    end
-
     def read_dumb
       STDIN.getc
     rescue Interrupt
@@ -90,45 +172,31 @@ module Terminal
       nil
     end
 
-    def read_tty_with_mouse(each_move: false)
-      # highlight: '1001'
-      # drag: '1002'
-      # move: '1003'
-      # ext: '1005'
-      # sgr: '1006'
-      # urxvt: '1015'
-      # pixel: '1016'
-      opts = each_move ? '1000;1003;1006;1015' : '1000;1006;1015'
-      opts = raw_write("\e[?#{opts}h") ? "\e[?#{opts}l" : nil
-      read_tty
-    ensure
-      raw_write(opts) if opts
-    end
-
     def read_tty
-      if (key = STDIN.getch) == "\e"
-        while (nc = STDIN.read_nonblock(1, exception: false))
-          String === nc ? key << nc : break
+      STDIN.noecho do |stdin|
+        if (key = stdin.getch) == "\e"
+          while (nc = stdin.read_nonblock(1, exception: false))
+            String === nc ? key << nc : break
+          end
         end
+        key
       end
-      key
     rescue Interrupt
       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
 
+  @dumb_keys = {
+    0x05 => ['c', 4],
+    0x08 => :Back,
+    0x09 => :Tab,
+    0x0a => :Enter,
+    0x0d => :Return,
+    0x1b => :Esc
+  }.compare_by_identity.freeze
+
   autoload :KeyEvent, "#{__dir__}/input/key_event.rb"
 end

data/lib/terminal/shell.rb

@@ -116,12 +116,8 @@ module Terminal
         end
 
         def initialize(enum)
-          @enum =
-            if enum.respond_to?(:enum_for)
-              enum.enum_for(:each)
-            else
-              Enumerator.new { |y| enum.each { y << _1 } }
-            end
+          return @enum = enum.enum_for(:each) if enum.respond_to?(:enum_for)
+          @enum = Enumerator.new { |y| enum.each { y << _1 } }
         end
       end
     end

data/lib/terminal/text.rb

@@ -24,14 +24,14 @@ module Terminal
       # some are ambiguous. The function uses {ambiguous_char_width} for each of
       # these characters.
       #
-      # @param object [#to_s] str to process
+      # @param str [#to_s] str to process
       # @param bbcode [true|false] whether to interpret embedded BBCode
       # @return [Integer] display width
       def width(str, bbcode: true)
         return 0 if (str = bbcode ? Ansi.unbbcode(str) : str.to_s).empty?
         str = str.encode(@encoding) if str.encoding != @encoding
         width = 0
-        str.scan(WIDTH_SCANNER) do |sp, gc|
+        str.scan(@scan_width) do |sp, gc|
           next width += char_width(gc) if gc
           width += 1 if sp
         end
@@ -343,7 +343,7 @@ module Terminal
 
           txt = txt.encode(@encoding) if txt.encoding != @encoding
 
-          txt.scan(SCAN_EXPR) do |nl, csi, osc, space, gc|
+          txt.scan(@scan_snippet) do |nl, csi, osc, space, gc|
             if gc
               next last.add(gc, char_width(gc)) if last.is_a?(word_class)
               next ret << (last = word_class.new(gc, char_width(gc)))
@@ -441,13 +441,10 @@ module Terminal
       end
     end
 
-    private_constant :Osc, :CsiEnd, :Csi, :Word, :WordEx
-
     @ambiguous_char_width = 1
-    @encoding = Encoding::UTF_8
-    @empty = String.new(encoding: @encoding).freeze
+    @empty = String.new(encoding: @encoding = Encoding::UTF_8).freeze
 
-    SCAN_EXPR =
+    @scan_snippet =
       /\G(?:
         (\r?\n)
         | (\e\[[\d;:?]*[ABCDEFGHJKSTfhilmnsu])
@@ -456,14 +453,13 @@ module Terminal
         | (\X)
       )/x
 
-    WIDTH_SCANNER =
+    @scan_width =
       /\G(?:
         (?:\e\[[\d;:?]*[ABCDEFGHJKSTfhilmnsu])
         | (?:\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
         | (\s+)
         | (\X)
       )/x
-    private_constant :SCAN_EXPR, :WIDTH_SCANNER
 
     @ctrlchar_width = {
       0x00 => 0,
@@ -501,6 +497,7 @@ module Terminal
     }.compare_by_identity.freeze
 
     autoload :CharWidth, "#{__dir__}/text/char_width.rb"
-    private_constant :CharWidth
+
+    private_constant :Osc, :Csi, :CsiEnd, :Word, :WordEx, :CharWidth
   end
 end

data/lib/terminal/version.rb

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

data/lib/terminal.rb

@@ -10,7 +10,7 @@ require_relative 'terminal/input'
 # It automagically detects whether your terminal supports ANSI features, like
 # coloring (see {colors}) or the
 # [CSIu protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol) support
-# (see {read_key_event} and {input_mode}).
+# (see {read_key_event}, {on_key_event} and {input_mode}).
 # It calculates the display width for Unicode chars (see {Text.width}) and help
 # you to display text with word-wise line breaks (see {Text.each_line}).
 #
@@ -19,8 +19,8 @@ module Terminal
     # Return true if the current terminal supports ANSI control codes.
     # When the terminal does not support it, {colors} will return 2 (two) and
     # all output methods ({<<}, {print}, {puts}) will not forward ANSI control
-    # codes to the terminal, {read_key_event} will not support extended key
-    # codes.
+    # codes to the terminal, {read_key_event} and {on_key_event} will not
+    # support extended key codes and/or mouse events.
     #
     # @attribute [r] ansi?
     # @return [Boolean] whether ANSI control codes are supported
@@ -290,7 +290,7 @@ module Terminal
 
     # @private
     def raw_write(str)
-      @out&.write(str)
+      @out&.syswrite(str)
     rescue IOError
       @out = nil
     end

data/terminal_rb.gemspec

@@ -5,13 +5,15 @@ require_relative 'lib/terminal/version'
 Gem::Specification.new do |spec|
   spec.name = 'terminal_rb'
   spec.version = Terminal::VERSION
-  spec.summary =
-    'Fast terminal access with ANSI, CSIu, BBCode, word-wise line break support.'
+  spec.summary = <<~SUMMARY.tr("\n", ' ')
+    Fast terminal access with ANSI, CSIu, mouse eventing, BBCode, word-wise
+    line break support and much more.
+  SUMMARY
   spec.description = <<~DESCRIPTION.tr("\n", ' ')
     Terminal.rb supports you with input and output on your terminal.
     Simple BBCode-like markup for attributes and coloring, word-wise line
-    breaks, and correct special key recognition enable you to implement your
-    CLI app quickly and easily.
+    breaks, correct special key recognition and mouse event reporting enable
+    you to implement your CLI app quickly and easily.
   DESCRIPTION
 
   spec.author = 'Mike Blumtritt'
@@ -25,9 +27,8 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '> 3.0'
 
-  spec.files = Dir['lib/**/*.rb']
-  spec.files += Dir['examples/*.rb']
-  spec.files += %w[terminal_rb.gemspec .yardopts]
+  spec.files = Dir['lib/**/*.rb'] + Dir['examples/*.rb']
+  spec.files << 'terminal_rb.gemspec' << '.yardopts'
   spec.executables = %w[bbcode]
   spec.extra_rdoc_files = %w[README.md]
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: terminal_rb
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Mike Blumtritt
@@ -10,8 +10,9 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: 'Terminal.rb supports you with input and output on your terminal. Simple
-  BBCode-like markup for attributes and coloring, word-wise line breaks, and correct
-  special key recognition enable you to implement your CLI app quickly and easily. '
+  BBCode-like markup for attributes and coloring, word-wise line breaks, correct special
+  key recognition and mouse event reporting enable you to implement your CLI app quickly
+  and easily. '
 executables:
 - bbcode
 extensions: []
@@ -68,5 +69,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.7.2
 specification_version: 4
-summary: Fast terminal access with ANSI, CSIu, BBCode, word-wise line break support.
+summary: Fast terminal access with ANSI, CSIu, mouse eventing, BBCode, word-wise line
+  break support and much more.
 test_files: []