Extended & human-friendly keys

See the changelog additions for user-visible changes.

Since we enable/disable terminal protocols whenever we pass terminal ownership,
tests can no longer run in parallel on the same terminal.

For the same reason, readline shortcuts in the gdb REPL will not work anymore.
As a remedy, use gdbserver, or lobby for CSI u support in libreadline.

Add sleep to some tests, otherwise they fall (both in CI and locally).

There are two weird failures on FreeBSD remaining, disable them for now
https://github.com/fish-shell/fish-shell/pull/10359/checks?check_run_id=23330096362

Design and implementation borrows heavily from Kakoune.

In future, we should try to implement more of the kitty progressive
enhancements.

Closes #10359

doc_src/cmds/bind.rst

@@ -7,49 +7,67 @@ Synopsis
 
 .. synopsis::
 
-    bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] [--preset | --user] [-s | --silent] [-k | --key] SEQUENCE COMMAND ...
-    bind [(-M | --mode) MODE] [-k | --key] [--preset] [--user] SEQUENCE
-    bind (-K | --key-names) [-a | --all] [--preset] [--user]
+    bind [(-M | --mode) MODE] [(-m | --sets-mode) NEW_MODE] [--preset | --user] [-s | --silent] KEYS COMMAND ...
+    bind [(-M | --mode) MODE] [--preset] [--user] [KEYS]
+    bind [-a | --all] [--preset] [--user]
     bind (-f | --function-names)
     bind (-L | --list-modes)
-    bind (-e | --erase) [(-M | --mode) MODE] [--preset] [--user] [-a | --all] | [-k | --key] SEQUENCE ...
+    bind (-e | --erase) [(-M | --mode) MODE] [--preset] [--user] [-a | --all] | KEYS ...
 
 Description
 -----------
 
-``bind`` manages bindings.
+``bind`` manages key bindings.
 
-It can add bindings if given a SEQUENCE of characters to bind to. These should be written as :ref:`fish escape sequences <escapes>`. The most important of these are ``\c`` for the control key, and ``\e`` for escape, and because of historical reasons also the Alt key (sometimes also called "Meta").
+If both ``KEYS`` and ``COMMAND`` are given, ``bind`` adds (or replaces) a binding in ``MODE``.
+If only ``KEYS`` is given, any existing binding in the given ``MODE`` will be printed.
 
-For example, :kbd:`Alt`\ +\ :kbd:`W` can be written as ``\ew``, and :kbd:`Control`\ +\ :kbd:`X` (^X) can be written as ``\cx``. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not ``fish``.
+``KEYS`` is a comma-separated list of key names.
+Modifier keys can be specified by prefixing a key name with a combination of ``ctrl-``, ``alt-`` and ``shift-``.
+For example, :kbd:`Alt`\ +\ :kbd:`w` is written as ``alt-w``.
+Key names are case-sensitive; for example ``alt-W`` is the same as ``alt-shift-w``.
 
-The generic key binding that matches if no other binding does can be set by specifying a ``SEQUENCE`` of the empty string (``''``). For most key bindings, it makes sense to bind this to the ``self-insert`` function (i.e. ``bind '' self-insert``). This will insert any keystrokes not specifically bound to into the editor. Non-printable characters are ignored by the editor, so this will not result in control sequences being inserted.
+Some keys have names, usually because they don't have an obvious printable character representation.
+They are:
 
-If the ``-k`` switch is used, the name of a key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key\_' prefix. (See ``terminfo(5)`` for more information, or use ``bind --key-names`` for a list of all available named keys). Normally this will print an error if the current ``$TERM`` entry doesn't have a given key, unless the ``-s`` switch is given.
+``plus`` (``+``),
+``minus`` (``-``),
+``comma`` (``,``),
+``backspace``,
+``delete``,
+``escape``,
+``enter``,
+the arrow keys ``up``, ``down``, ``left`` and ``right``,
+``pageup``,
+``pagedown``,
+``home``,
+``end``,
+``insert``,
+``tab``,
+``space`` and
+``F1`` through ``F12``.
 
-To find out what sequence a key combination sends, you can use :doc:`fish_key_reader <fish_key_reader>`.
+An empty value (``''``) for ``KEYS`` designates the generic binding. For most bind modes, it makes sense to bind this to the ``self-insert`` function (i.e. ``bind '' self-insert``). This will insert any keystrokes not specifically bound to into the editor. Non-printable characters are ignored by the editor, so this will not result in control sequences being inserted.
+
+To find the name of a key combination you can use :doc:`fish_key_reader <fish_key_reader>`.
 
 ``COMMAND`` can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use ``bind --function-names`` or :ref:`see below <special-input-functions>` for a list of these input functions.
 
 .. note::
     If a script changes the commandline, it should finish by calling the ``repaint`` special input function.
 
-If no ``SEQUENCE`` is provided, all bindings (or just the bindings in the given ``MODE``) are printed. If ``SEQUENCE`` is provided but no ``COMMAND``, just the binding matching that sequence is printed.
+If no ``KEYS`` argument is provided, all bindings (in the given ``MODE``) are printed. If ``KEYS`` is provided but no ``COMMAND``, just the binding matching that sequence is printed.
 
 Key bindings may use "modes", which mimics vi's modal input behavior. The default mode is "default". Every key binding applies to a single mode; you can specify which one with ``-M MODE``. If the key binding should change the mode, you can specify the new mode with ``-m NEW_MODE``. The mode can be viewed and changed via the ``$fish_bind_mode`` variable. If you want to change the mode from inside a fish function, use ``set fish_bind_mode MODE``.
 
+To bind a sequence of keys, separate them with ``,``.
+
 To save custom key bindings, put the ``bind`` statements into :ref:`config.fish <configuration>`. Alternatively, fish also automatically executes a function called ``fish_user_key_bindings`` if it exists.
 
 Options
 -------
 The following options are available:
 
-**-k** or **--key**
-    Specify a key name, such as 'left' or 'backspace' instead of a character sequence
-
-**-K** or **--key-names**
-    Display a list of available key names. Specifying **-a** or **--all** includes keys that don't have a known mapping
-
 **-f** or **--function-names**
     Display a list of available input functions
 
@@ -69,7 +87,7 @@ The following options are available:
     Specifying **-a** or **--all** without **-M** or **--mode** erases all binds in all modes regardless of sequence.
 
 **-a** or **--all**
-    See **--erase** and **--key-names**
+    See **--erase**
 
 **--preset** and **--user**
     Specify if bind should operate on user or preset bindings.
@@ -349,7 +367,7 @@ Examples
 
 Exit the shell when :kbd:`Control`\ +\ :kbd:`D` is pressed::
 
-    bind \cd 'exit'
+    bind ctrl-d 'exit'
 
 Perform a history search when :kbd:`Page Up` is pressed::
 

doc_src/cmds/fish_key_reader.rst

@@ -15,16 +15,11 @@ Description
 
 :program:`fish_key_reader` is used to explain how you would bind a certain key sequence. By default, it prints the :doc:`bind <bind>` command for one key sequence read interactively over standard input.
 
-If the character sequence matches a special key name (see ``bind --key-names``),  both ``bind CHARS ...`` and ``bind -k KEYNAME ...`` usage will be shown. In verbose mode (enabled by passing ``--verbose``), additional details about the characters received, such as the delay between chars, are written to standard error.
-
 The following options are available:
 
 **-c** or **--continuous**
     Begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence.
 
-**-V** or **--verbose**
-    Tells fish_key_reader to output timing information and explain the sequence in more detail.
-
 **-h** or **--help**
     Displays help about using this command.
 
@@ -34,8 +29,6 @@ The following options are available:
 Usage Notes
 -----------
 
-In verbose mode, the delay in milliseconds since the previous character was received is included in the diagnostic information written to standard error. This information may be useful to determine the optimal ``fish_escape_delay_ms`` setting or learn the amount of lag introduced by tools like ``ssh``, ``mosh`` or ``tmux``.
-
 ``fish_key_reader`` intentionally disables handling of many signals. To terminate ``fish_key_reader`` in ``--continuous`` mode do:
 
 - press :kbd:`Control`\ +\ :kbd:`C` twice, or
@@ -51,12 +44,4 @@ Example
    > fish_key_reader
    Press a key:
    # press up-arrow
-   bind \e\[A 'do something'
-
-   > fish_key_reader --verbose
-   Press a key:
-   # press alt+enter
-              hex:   1B  char: \e
-   (  0.027 ms)  hex:    D  char: \cM  (or \r)
-   bind \e\r 'do something'
-
+   bind up 'do something'