Add support for xterm's modifyOtherKeys CSI

Given that an example of the translation table is not present by xterm
and they provide only script to generate one from the running X11
system, the example of the output is also included in the repository
now.

Co-authored-by: Christian Duerr <contact@christianduerr.com>

1 files changed, 68 insertions, 0 deletions

diff --git a/src/ansi.rs b/src/ansi.rs
index 918e35b..4ca2fa6 100644
--- a/src/ansi.rs
+++ b/src/ansi.rs
@@ -652,6 +652,14 @@ pub trait Handler {
     /// [`keyboard mode`]: crate::ansi::KeyboardModes
     /// [`behavior`]: crate::ansi::KeyboardModesApplyBehavior
     fn set_keyboard_mode(&mut self, _mode: KeyboardModes, _behavior: KeyboardModesApplyBehavior) {}
+
+    /// Set XTerm's [`ModifyOtherKeys`] option.
+    fn set_modify_other_keys(&mut self, _mode: ModifyOtherKeys) {}
+
+    /// Report XTerm's [`ModifyOtherKeys`] state.
+    ///
+    /// The output is of form `CSI > 4 ; mode m`.
+    fn report_modify_other_keys(&mut self) {}
 }
 
 bitflags! {
@@ -678,6 +686,50 @@ bitflags! {
     }
 }
 
+/// XTMODKEYS modifyOtherKeys state.
+///
+/// This only applies to keys corresponding to ascii characters.
+///
+/// For the details on how to implement the mode handling correctly, consult [`XTerm's
+/// implementation`] and the [`output`] of XTerm's provided [`perl script`]. Some libraries and
+/// implementations also use the [`fixterms`] definition of the `CSI u`.
+///
+/// The end escape sequence has a `CSI char; modifiers u` form while the original
+/// `CSI 27 ; modifier ; char ~`. The clients should prefer the `CSI u`, since it has
+/// more adoption.
+///
+/// [`XTerm's implementation`]: https://invisible-island.net/xterm/modified-keys.html
+/// [`perl script`]: https://github.com/ThomasDickey/xterm-snapshots/blob/master/vttests/modify-keys.pl
+/// [`output`]: https://github.com/alacritty/vte/blob/master/doc/modifyOtherKeys-example.txt
+/// [`fixterms`]: http://www.leonerd.org.uk/hacks/fixterms/
+#[repr(u8)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ModifyOtherKeys {
+    /// Reset the state.
+    Reset,
+    /// Enables this feature except for keys with well-known behavior, e.g., Tab, Backspace and
+    /// some special control character cases which are built into the X11 library (e.g.,
+    /// Control-Space to make a NUL, or Control-3 to make an Escape character).
+    ///
+    /// Escape sequences shouldn't be emitted under the following circumstances:
+    /// - When the key is in range of `[64;127]` and the modifier is either Control or Shift
+    /// - When the key combination is a known control combination alias
+    ///
+    /// For more details, consult the [`example`] for the suggested translation.
+    ///
+    /// [`example`]: https://github.com/alacritty/vte/blob/master/doc/modifyOtherKeys-example.txt
+    EnableExceptWellDefined,
+    /// Enables this feature for all keys including the exceptions of
+    /// [`Self::EnableExceptWellDefined`].  XTerm still ignores the special cases built into the
+    /// X11 library. Any shifted (modified) ordinary key send an escape sequence. The Alt- and
+    /// Meta- modifiers cause XTerm to send escape sequences.
+    ///
+    /// For more details, consult the [`example`] for the suggested translation.
+    ///
+    /// [`example`]: https://github.com/alacritty/vte/blob/master/doc/modifyOtherKeys-example.txt
+    EnableAll,
+}
+
 /// Describes how the new [`KeyboardModes`] should be applied.
 #[repr(u8)]
 #[derive(Default, Clone, Copy, PartialEq, Eq)]
@@ -1481,6 +1533,22 @@ where
                     }
                 }
             },
+            ('m', [b'>']) => {
+                let mode = match (next_param_or(1) == 4).then(|| next_param_or(0)) {
+                    Some(0) => ModifyOtherKeys::Reset,
+                    Some(1) => ModifyOtherKeys::EnableExceptWellDefined,
+                    Some(2) => ModifyOtherKeys::EnableAll,
+                    _ => return unhandled!(),
+                };
+                handler.set_modify_other_keys(mode);
+            },
+            ('m', [b'?']) => {
+                if params_iter.next() == Some(&[4]) {
+                    handler.report_modify_other_keys();
+                } else {
+                    unhandled!()
+                }
+            },
             ('n', []) => handler.device_status(next_param_or(0) as usize),
             ('P', []) => handler.delete_chars(next_param_or(1) as usize),
             ('q', [b' ']) => {