Add tests for the disambiguate flag

docs/keyboard-protocol.rst

@@ -199,16 +199,29 @@ oldest entry from the stack must be evicted.
 Disambiguate escape codes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This type of progressive enhancement fixes the problem of some legacy key
+This type of progressive enhancement (``0b1``) fixes the problem of some legacy key press
-press encodings overlapping with other control codes. For instance, pressing
+encodings overlapping with other control codes. For instance, pressing the
-the :kbd:`Esc` key generates the byte ``0x1b`` which also is used to indicate
+:kbd:`Esc` key generates the byte ``0x1b`` which also is used to indicate the
-the start of an escape code. Similarly pressing the key :kbd:`alt+[` will
+start of an escape code. Similarly pressing the key :kbd:`alt+[` will generate
-generate the bytes used for CSI control codes. Turning on this flag will cause
+the bytes used for CSI control codes.
-the terminal to report the :kbd:`Esc, alt+letter, ctrl+letter, ctrl+alt+letter`
+
-keys using ``CSI u`` sequences instead of legacy ones. Here letter is any printable
+Turning on this flag will cause the terminal to report the :kbd:`Esc, alt+key,
-ASCII letter (from 32 (i.e. space) to 126 (i.e. ~)). Additionally, all keypad
+ctrl+key, ctrl+alt+key, shift+alt+key` keys using ``CSI u`` sequences instead
-keys will be reported as separate keys with ``CSI u`` encoding, using dedicated codes
+of legacy ones. Here key is any ASCII key as described in :ref:`legacy_text`.
-from the :ref:`table below <functional>`.
+Additionally, all keypad keys will be reported as separate keys with ``CSI u``
+encoding, using dedicated numbers from the :ref:`table below <functional>`.
+
+With this flag turned on, all key events that do not generate text are
+represented in one of the following two forms::
+
+    CSI number; modifier u
+    CSI 1; modifier [~ABCDFHPQRSZ]
+
+This makes it very easy to parse key events in an application. In particular,
+:kbd:`ctrl+c` will no longer generate the ``SIGINT`` signal, but instead be
+delivers as a ``CSI u`` escape code. This has the nice side effect of making it
+much easier to integrate into the application event loop.
+
 
 Report event types
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -234,8 +247,8 @@ this encoding, only key press and repeat events are sent and there is no
 way to distinguish between them. Text is sent directly as UTF-8 bytes.
 
 Any key events not described in this section are sent using the standard
-``CSI u`` encoding. This includes keys that are not encodeable in the legacy
+``CSI u`` encoding. This includes keys that are not encodable in the legacy
-encoding, thereby increasing the space of useable key combinations even without
+encoding, thereby increasing the space of usable key combinations even without
 progressive enhancement.
 
 Legacy functional keys
@@ -305,6 +318,8 @@ terminals.
 All keypad keys are reported as there equivalent non-keypad keys. To
 distinguish these, use the :ref:`disambiguate <disambiguate>` flag.
 
+.. _legacy_text:
+
 Legacy text keys
 ~~~~~~~~~~~~~~~~~~~
 

kitty/key_encoding.c

@@ -289,16 +289,18 @@ encode_key(const KeyEvent *ev, char *output) {
     bool simple_encoding_ok = !ed.add_actions && !ed.add_alternates;
 
     if (simple_encoding_ok) {
-        if (is_legacy_ascii_key(ev->key)) {
+        if (!ed.has_mods) return encode_utf8(ev->key, output);
-            int ret = encode_printable_ascii_key_legacy(ev, output);
+        if (!ev->disambiguate) {
-            if (ret > 0) return ret;
+            if (is_legacy_ascii_key(ev->key)) {
-        } else if (ev->key == ' ' && ev->mods.value == CTRL) {
+                int ret = encode_printable_ascii_key_legacy(ev, output);
-            output[0] = 0;
+                if (ret > 0) return ret;
-            return 1;
+            } else if (ev->key == ' ' && ev->mods.value == CTRL) {
+                output[0] = 0;
+                return 1;
+            }
         }
     }
 
-    if (simple_encoding_ok && !ed.has_mods) return encode_utf8(ev->key, output);
     return serialize(&ed, output, 'u');
 }
 

kitty_tests/keys.py

@@ -379,6 +379,17 @@ class TestKeys(BaseTest):
         ae(q(action=repeat), 'a')
         ae(q(action=release), '')
 
+        # test disambiguate
+        dq = partial(enc, key_encoding_flags=0b1)
+        ae(dq(ord('a')), 'a')
+        ae(dq(defines.GLFW_FKEY_ESCAPE), csi(num=27))  # esc
+        for mods in (ctrl, alt, ctrl | shift, alt | shift):
+            ae(dq(ord('a'), mods=mods), csi(mods, ord('a')))
+        ae(dq(ord(' '), mods=ctrl), csi(ctrl, ord(' ')))
+        for k in (defines.GLFW_FKEY_KP_PAGE_UP, defines.GLFW_FKEY_KP_0):
+            ae(dq(k), csi(num=k))
+            ae(dq(k, mods=ctrl), csi(ctrl, num=k))
+
     def test_encode_mouse_event(self):
         NORMAL_PROTOCOL, UTF8_PROTOCOL, SGR_PROTOCOL, URXVT_PROTOCOL = range(4)
         L, M, R = 1, 2, 3