fatty 0.99.8.7 → 0.99.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 519b734dc4d7f0897a42e766e58732f13458b7f8f1bfac59f0582b1862006805
-  data.tar.gz: 003edc0102fda74f0b9d530fb2682f9b810a5bd9756eec6464f0e0443a3efb9f
+  metadata.gz: cbc5a3073a513f15a71297dcf4220805d46c82e657dd51f81ebfd6ceca7ed3de
+  data.tar.gz: f3a3d8bcbe0e7ba2ae026f39df002c21c0b86f377595b9a1f86c227cb0eaf21e
 SHA512:
-  metadata.gz: a9691e1dafdd5c714b9e490d91be490bb5d05c591d74ffb8b7421f9092d2b083c7d035d9afeebb933ed096783c9214638059d738caff2441541ead719aa03d8d
-  data.tar.gz: a77da76a84bdbf1a8806fa9f921fbf3c13aa509b7ccfa0a476a4bfc92111d29687b382a10e4d311a4ab59693de1064a8874da804a9ee19077d7bf66e8a7a56f8
+  metadata.gz: 953bf8c8adccb19c96ab7f332c2fa4b75f945605d1aac599597b480d8b82cb1d8b26e28e4e2607413efe185e27819aeac9fb26af848d224e0b45785f28d81909
+  data.tar.gz: 79fa73c37580e337888c86c04aedaf1b5087ba856f6f6f7b06fbfb257de310ff78fdf8e9f9c724bb63db36b4f5efd6803f352153e603822343d1aa5323a68af2

data/README.md

@@ -1472,6 +1472,30 @@ tags:
 
 Most keys are named correctly by curses. Some terminal emulators, multiplexers, or keyboard modes emit numeric keycodes that curses does not name usefully. The `keydefs.yml` file lets you assign names and modifiers to those numeric codes.
 
+Fatty also recognizes raw CSI navigation sequences, including modified arrows, Home/End, Insert/Delete, and PageUp/PageDown. An unsupported complete CSI sequence is reported as an undefined key, rather than inserted into the input line. To name one, copy the suggestion from `keytest` into `keydefs.yml`. For example (replace `xterm` with the detected terminal and the example bytes with yours):
+
+```yaml
+xterm:
+  sequences:
+    custom_navigation:
+      sequence: "\e[99~"
+      key: custom_navigation
+      meta: true
+```
+
+Use double quotes for `sequence` so YAML decodes `\e` as Escape. The label `custom_navigation` identifies the entry for merging configuration layers; use a distinct label for each sequence. Store the bytes in the `sequence` value, not as a YAML key. Numeric definitions may coexist with `sequences` under the same terminal. Sequence definitions override built-in CSI recognition, apply only to that terminal, and leave a standalone Escape unchanged. Paste delimiters cannot be redefined. Invalid sequence entries are ignored with a logged warning. Modifiers default to false; supplied modifiers must be YAML booleans.
+
+Then assign the named key an action in `keybindings.yml`, for example:
+
+```yaml
+- key: custom_navigation
+  meta: true
+  context: input
+  action: move_word_right
+```
+
+Use the same key name and modifiers in both files, and restart the application. Alternatively, naming the sequence `right` with `meta: true` uses the existing Emacs-style word-right binding. Already recognized but unbound keys need only an entry in `keybindings.yml`.
+
 When Fatty runs inside `tmux`, key definitions are looked up under `tmux`, not under the outer terminal emulator. `tmux` translates the outer terminal's input before Fatty sees it, so keycodes observed inside `tmux` may differ from keycodes observed directly under GNOME Terminal, Kitty, Alacritty, or another terminal. Use `keytest` in the same environment where the application will normally run. The same comment applies to `screen`.
 
 A key definition is terminal-specific. For example:

data/README.org

@@ -1366,6 +1366,44 @@ or keyboard modes emit numeric keycodes that curses does not name usefully.
 The =keydefs.yml= file lets you assign names and modifiers to those numeric
 codes.
 
+Fatty also recognizes raw CSI navigation sequences, including modified arrows,
+Home/End, Insert/Delete, and PageUp/PageDown. An unsupported complete CSI sequence
+is reported as an undefined key, rather than inserted into the input line.
+To name one, copy the suggestion from =keytest= into =keydefs.yml=. For example
+(replace =xterm= with the detected terminal and the example bytes with yours):
+
+#+begin_src yaml :tangle no
+xterm:
+  sequences:
+    custom_navigation:
+      sequence: "\e[99~"
+      key: custom_navigation
+      meta: true
+#+end_src
+
+Use double quotes for =sequence= so YAML decodes =\e= as Escape. The label
+=custom_navigation= identifies the entry for merging configuration layers; use a
+distinct label for each sequence. Store the bytes in the =sequence= value, not
+as a YAML key. Numeric definitions may coexist with =sequences= under the same
+terminal. Sequence definitions override built-in CSI recognition, apply only to
+that terminal, and leave a standalone Escape unchanged. Paste delimiters cannot
+be redefined. Invalid sequence entries are ignored with a logged warning.
+Modifiers default to false; supplied modifiers must be YAML booleans.
+
+Then assign the named key an action in =keybindings.yml=, for example:
+
+#+begin_src yaml :tangle no
+- key: custom_navigation
+  meta: true
+  context: input
+  action: move_word_right
+#+end_src
+
+Use the same key name and modifiers in both files, and restart the application.
+Alternatively, naming the sequence =right= with =meta: true= uses the existing
+Emacs-style word-right binding. Already recognized but unbound keys need only
+an entry in =keybindings.yml=.
+
 When Fatty runs inside =tmux=, key definitions are looked up under =tmux=, not
 under the outer terminal emulator.  =tmux= translates the outer terminal's input
 before Fatty sees it, so keycodes observed inside =tmux= may differ from

data/lib/fatty/config.rb

@@ -21,7 +21,7 @@ module Fatty
       @config = read_layered("config")
     end
 
-    # Read in the keydefs.yml config file that maps numeric keycodes returned
+    # Read in the keydefs.yml config file that maps numeric keycodes and raw CSI sequences returned
     # by curses but not assigned a key name.  This merges in the per-app
     # keydefs.yml as well.
     def self.keydefs

data/lib/fatty/curses/event_source.rb

@@ -143,6 +143,8 @@ module Fatty
           seq = "[" + suffix
           if seq == BRACKETED_PASTE_START
             [:paste, read_bracketed_paste]
+          elsif suffix.match?(/[\x40-\x7e]\z/)
+            [ch, '[', suffix]
           else
             push_pending_raw(*suffix.chars.reverse)
             push_pending_raw(nxt)
@@ -260,14 +262,20 @@ module Fatty
         suffix = +""
         done = false
 
-        until done
-          ch = with_window_timeout(0) { window.getch }
+        until done || suffix.length >= 64
+          ch = with_window_timeout(escape_lookahead_ms) { window.getch }
 
           if ch == -1 || !ch
             done = true
           else
-            suffix << raw_char_to_s(ch)
-            done = true if suffix.end_with?("~")
+            char = raw_char_to_s(ch)
+            if char.bytesize != 1 || !char.ord.between?(0x20, 0x7e)
+              push_pending_raw(ch)
+              done = true
+            else
+              suffix << char
+              done = char.ord.between?(0x40, 0x7e)
+            end
           end
         end
 

data/lib/fatty/curses/key_decoder.rb

@@ -9,6 +9,10 @@ module Fatty
     # :ctrl, and :meta, in the KeyEvent so that the KeyMap can assign different
     # actions to the modified keys.
     class KeyDecoder
+      CSI_CURSOR_KEYS = { 'A' => :up, 'B' => :down, 'C' => :right, 'D' => :left,
+                          'H' => :home, 'F' => :end }.freeze
+      CSI_TILDE_KEYS = { '1' => :home, '2' => :insert, '3' => :delete, '4' => :end,
+                         '5' => :page_up, '6' => :page_down, '7' => :home, '8' => :end }.freeze
       SS3_TO_EVENT = {
         "j" => KeyEvent.new(key: :keypad_multiply),
         "k" => KeyEvent.new(key: :keypad_plus),
@@ -34,6 +38,7 @@ module Fatty
       def initialize(env: Env.detect)
         @env = env
         @map = {}
+        @sequence_map = {}
         load_builtin_map
         load_user_config
       end
@@ -46,7 +51,9 @@ module Fatty
         result =
           case raw
           when Array
-            if raw.length == 3 && ss3_sequence?(raw)
+            if raw.length == 3 && raw[0] == 27 && raw[1] == '['
+              decode_csi(raw)
+            elsif raw.length == 3 && ss3_sequence?(raw)
               decode_ss3(raw)
             else
               decode_meta(raw)
@@ -62,6 +69,30 @@ module Fatty
 
       # simplecov:disable
 
+      def decode_csi(raw)
+        if (spec = @sequence_map["\e[#{raw.last}"])
+          return KeyEvent.new(**spec, raw: raw)
+        end
+
+        if (match = raw.last.match(/\A(?:1(?:;(\d+))?)?([ABCDHF])\z/))
+          key = CSI_CURSOR_KEYS.fetch(match[2])
+          modifier = match[1]
+        elsif (match = raw.last.match(/\A([1-8])(?:;(\d+))?~\z/))
+          key = CSI_TILDE_KEYS.fetch(match[1])
+          modifier = match[2]
+        end
+        modifier = (modifier || '1').to_i
+        if key && modifier.between?(1, 16)
+          bits = modifier - 1
+          KeyEvent.new(key: key, raw: raw,
+                       shift: (bits & 1).positive?, meta: (bits & 10).positive?,
+                       ctrl: (bits & 4).positive?)
+        else
+          # Preserve one nonprinting unknown event for the normal key alert.
+          KeyEvent.new(key: "\e[#{raw.last}".inspect, raw: raw)
+        end
+      end
+
       def ss3_sequence?(raw)
         raw[0] == 27 && raw[1] == "O"
       end
@@ -202,7 +233,37 @@ module Fatty
         return unless section
 
         section.each do |code, spec|
-          register_user_keydef(code.to_i, spec)
+          if code.to_s == "sequences"
+            register_user_sequences(spec)
+          else
+            register_user_keydef(code, spec)
+          end
+        end
+      end
+
+      # Labels survive config-key normalization; the sequence stays a value.
+      def register_user_sequences(definitions)
+        unless definitions.is_a?(Hash)
+          Fatty.warn("keydefs sequences must be a mapping of labels to definitions", tag: :keycode)
+          return
+        end
+
+        definitions.each do |label, value|
+          begin
+            spec = normalize_spec(value)
+            sequence = spec.delete(:sequence)
+            unless sequence.is_a?(String) && sequence.match?(/\A\e\[[0-?]*[ -\/]*[@-~]\z/) &&
+                   sequence.bytesize <= 66 && !["\e[200~", "\e[201~"].include?(sequence)
+              raise ArgumentError, "sequence must be a complete CSI key sequence (not a paste delimiter)"
+            end
+            unless spec[:key].is_a?(Symbol) && (spec.keys - [:key, :ctrl, :meta, :shift]).empty? &&
+                   [:ctrl, :meta, :shift].all? { |flag| !spec.key?(flag) || [true, false].include?(spec[flag]) }
+              raise ArgumentError, "supply a key name and optional boolean ctrl/meta/shift modifiers"
+            end
+            @sequence_map[sequence] = spec
+          rescue ArgumentError => e
+            Fatty.warn("Ignoring keydefs sequence #{label.inspect}: #{e.message}", tag: :keycode)
+          end
         end
       end
 

data/lib/fatty/key_event.rb

@@ -89,6 +89,8 @@ module Fatty
     end
 
     def code
+      return if csi_sequence
+
       case raw
       when Integer
         raw
@@ -163,6 +165,12 @@ module Fatty
 
     private
 
+    def csi_sequence
+      return unless raw.is_a?(Array) && raw.length == 3 && raw[0] == 27 && raw[1] == "["
+
+      "\e[#{raw.last}"
+    end
+
     def bytes_from_raw(value)
       case value
       when Array
@@ -293,6 +301,29 @@ module Fatty
     end
 
     def suggested_keydef(terminal_name)
+      if (sequence = csi_sequence)
+        return <<~TEXT
+
+          No key name is associated with sequence #{sequence.inspect}.
+
+          Suggested keydefs.yml entry (choose a name and modifiers):
+
+          ............>8 snip here 8<....................
+          #{terminal_name}:
+            sequences:
+              custom_key:
+                sequence: #{sequence.inspect}
+                key: key_name
+                shift: false
+                ctrl: false
+                meta: false
+          ............>8 snip here 8<....................
+
+          Use a distinct label for each sequence. Bind the key name in keybindings.yml,
+          then restart the application to load your changes.
+        TEXT
+      end
+
       return "" unless code
 
       <<~TEXT

data/lib/fatty/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fatty
-  VERSION = "0.99.8.7"
+  VERSION = "0.99.9.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fatty
 version: !ruby/object:Gem::Version
-  version: 0.99.8.7
+  version: 0.99.9.0
 platform: ruby
 authors:
 - Daniel E. Doherty