terminal_rb 0.11.1 → 0.12.1

data/lib/terminal/input.rb

@@ -9,7 +9,8 @@ module Terminal
     # @attribute [r] input_mode
     #
     # @return [:csi_u]
-    #   when CSIu protocol support
+    #   when [CSIu protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol)
+    #   supported
     # @return [:legacy]
     #   for standard terminal
     # @return [:dumb]
@@ -25,40 +26,43 @@ 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
+        AsKeyEvent[raw] if (raw = read_tty)
+      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
@@ -72,35 +76,174 @@ module Terminal
     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(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 = _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))
+      if (key = STDIN.getch) == "\e"
+        while (nc = STDIN.read_nonblock(1, exception: false))
           String === nc ? key << nc : break
         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
+
+  #
+  # 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
+
+      # @!visibility private
+      def new(raw, key = raw, modifier = 0, extra = nil)
+        @cache ? (@cache[raw] ||= super.freeze) : super.freeze
+      end
+
+      # @!visibility private
+      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
+    # @!visibility 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 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/text.rb

@@ -30,7 +30,7 @@ module Terminal
       def width(str, bbcode: true)
         str = bbcode ? Ansi.unbbcode(str) : str.to_s
         return 0 if str.empty?
-        str = str.encode(ENC) if str.encoding != ENC
+        str = str.encode(@encoding) if str.encoding != @encoding
         width = 0
         str.scan(WIDTH_SCANNER) do |sp, gc|
           next width += char_width(gc) if gc
@@ -113,7 +113,7 @@ module Terminal
 
       def char_width(char)
         ord = char.ord
-        return CONTROL_CHAR_WIDTH[ord] || 2 if ord < 0x20
+        return @ctrlchar_width[ord] || 2 if ord < 0x20
         return 1 if char.size < 2 && ord < 0xa1
         width = CharWidth[ord]
         return @ambiguous_char_width if width == -1
@@ -124,7 +124,7 @@ module Terminal
       end
 
       def lim_pairs(snippeds, limit)
-        line = EMPTY.dup
+        line = @empty.dup
         size = 0
         csi = nil
         snippeds.each do |snipped|
@@ -144,7 +144,7 @@ module Terminal
 
           if snipped == :hard_nl
             line[-1] == ' ' ? yield(line.chop, size - 1) : yield(line, size)
-            line = EMPTY.dup
+            line = @empty.dup
             csi = nil
             next size = 0
           end
@@ -190,7 +190,7 @@ module Terminal
       end
 
       def pairs(snippeds)
-        line = EMPTY.dup
+        line = @empty.dup
         size = 0
         csi = nil
         snippeds.each do |snipped|
@@ -208,7 +208,7 @@ module Terminal
 
           if snipped == :hard_nl
             line[-1] == ' ' ? yield(line.chop, size - 1) : yield(line, size)
-            line = EMPTY.dup
+            line = @empty.dup
             csi = nil
             next size = 0
           end
@@ -229,7 +229,7 @@ module Terminal
       end
 
       def lim_lines(snippeds, limit)
-        line = EMPTY.dup
+        line = @empty.dup
         size = 0
         csi = nil
         snippeds.each do |snipped|
@@ -249,7 +249,7 @@ module Terminal
 
           if snipped == :hard_nl
             yield(line[-1] == ' ' ? line.chop : line)
-            line = EMPTY.dup
+            line = @empty.dup
             csi = nil
             next size = 0
           end
@@ -295,7 +295,7 @@ module Terminal
       end
 
       def lines(snippeds)
-        line = EMPTY.dup
+        line = @empty.dup
         size = 0
         csi = nil
         snippeds.each do |snipped|
@@ -313,7 +313,7 @@ module Terminal
 
           if snipped == :hard_nl
             yield(line[-1] == ' ' ? line.chop : line)
-            line = EMPTY.dup
+            line = @empty.dup
             csi = nil
             next size = 0
           end
@@ -342,7 +342,7 @@ module Terminal
             next ret << (last = :hard_nl)
           end
 
-          txt = txt.encode(ENC) if txt.encoding != ENC
+          txt = txt.encode(@encoding) if txt.encoding != @encoding
 
           txt.scan(SCAN_EXPR) do |nl, csi, osc, space, gc|
             if gc
@@ -445,10 +445,8 @@ module Terminal
     private_constant :Osc, :CsiEnd, :Csi, :Word, :WordEx
 
     @ambiguous_char_width = 1
-
-    ENC = Encoding::UTF_8
-    EMPTY = String.new(encoding: ENC).freeze
-    private_constant :ENC, :EMPTY
+    @encoding = Encoding::UTF_8
+    @empty = String.new(encoding: @encoding).freeze
 
     SCAN_EXPR =
       /\G(?:
@@ -468,7 +466,7 @@ module Terminal
       )/x
     private_constant :SCAN_EXPR, :WIDTH_SCANNER
 
-    CONTROL_CHAR_WIDTH = {
+    @ctrlchar_width = {
       0x00 => 0,
       0x01 => 1,
       0x02 => 1,
@@ -502,7 +500,6 @@ module Terminal
       0x1e => 1,
       0x1f => 1
     }.compare_by_identity.freeze
-    private_constant :CONTROL_CHAR_WIDTH
 
     autoload :CharWidth, "#{__dir__}/text/char_width.rb"
     private_constant :CharWidth

data/lib/terminal/version.rb

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

data/lib/terminal.rb

@@ -11,16 +11,16 @@ 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} and {input_mode}). It calculates the display width for Unicode
-# chars (see {Text.width}) and help you to display text with line formatting
-# (see {Text.each_line}).
+# (see {read_key_event} and {input_mode}).
+# It calculates the display width for Unicode chars (see {Text.width}) and help
+# you to display text with line formatting (see {Text.each_line}).
 #
 module Terminal
   class << self
-    # Return true when the current terminal supports ANSI control codes.
-    # When the terminal does not support it, {colors} will return `2` as color
-    # count and all output methods ({<<}, {print}, {puts}) will not forward
-    # ANSI control codes to the terminal, {read_key} will not support CSIu.
+    # Return true if the current terminal supports ANSI control codes.
+    # When the terminal does not support it, {colors} will return `2` and all
+    # output methods ({<<}, {print}, {puts}) will not forward ANSI control
+    # codes to the terminal, {read_key_event} will not support CSIu.
     #
     # @attribute [r] ansi?
     # @return [Boolean] whether ANSI control codes are supported
@@ -123,8 +123,9 @@ module Terminal
 
     # Screen size as a tuple of {rows} and {columns}.
     #
-    # If the terminal does not support the report for it's dimension or ANSI
-    # is not supported in general then environment variables will be used.
+    # If the terminal does not support the report of it's dimension or ANSI
+    # is not supported in general then environment variables `COLUMNS` and
+    # `LINES` will be used.
     # If this failed `[25, 80]` will be returned as default.
     #
     # Setting the terminal size is not widely supported.
@@ -156,7 +157,8 @@ module Terminal
     # Hide the cursor.
     # Will not send the control code if the cursor is already hidden.
     #
-    # To show the cursor again call {show_cursor}.
+    # When you called {hide_cursor} n-times you need to call {show_cursor}
+    # n-times to show the cursor again.
     #
     # @return [Terminal] itself
     def hide_cursor

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: terminal_rb
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.12.1
 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
@@ -46,10 +44,11 @@ homepage: https://codeberg.org/mblumtritt/Terminal.rb
 licenses:
 - MIT
 metadata:
-  rubygems_mfa_required: 'true'
   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
+  rubygems_mfa_required: 'true'
+  yard.run: yard
 rdoc_options: []
 require_paths:
 - lib