Document supported escape sequences

Fixes #3440.

3 files changed, 141 insertions, 39 deletions

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 4fd9fde8..802ca57a 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,3 +1,9 @@
-Please make sure to document all user-facing changes in the `CHANGELOG.md` file.
+Please make sure to document all user-facing changes in the
+`CHANGELOG.md` file.
 
-Draft PRs are always welcome, though unless otherwise requested PRs will not be reviewed until all required and optional CI steps are successful and they have left the draft stage.
+If support for a new escape sequence was added, it should be documented
+in `./docs/escape_support.md`.
+
+Draft PRs are always welcome, though unless otherwise requested PRs will
+not be reviewed until all required and optional CI steps are successful
+and they have left the draft stage.
diff --git a/alacritty_terminal/src/ansi.rs b/alacritty_terminal/src/ansi.rs
index 619b1d39..8240ff00 100644
--- a/alacritty_terminal/src/ansi.rs
+++ b/alacritty_terminal/src/ansi.rs
@@ -812,10 +812,6 @@ where
                 unhandled(params);
             },
 
-            // Set icon name.
-            // This is ignored, since alacritty has no concept of tabs.
-            b"1" => (),
-
             // Set color index.
             b"4" => {
                 if params.len() > 1 && params.len() % 2 != 0 {
@@ -970,6 +966,9 @@ where
             ('A', None) => {
                 handler.move_up(Line(arg_or_default!(idx: 0, default: 1) as usize));
             },
+            ('B', None) | ('e', None) => {
+                handler.move_down(Line(arg_or_default!(idx: 0, default: 1) as usize))
+            },
             ('b', None) => {
                 if let Some(c) = self.state.preceding_char {
                     for _ in 0..arg_or_default!(idx: 0, default: 1) {
@@ -979,24 +978,27 @@ where
                     debug!("tried to repeat with no preceding char");
                 }
             },
-            ('B', None) | ('e', None) => {
-                handler.move_down(Line(arg_or_default!(idx: 0, default: 1) as usize))
+            ('C', None) | ('a', None) => {
+                handler.move_forward(Column(arg_or_default!(idx: 0, default: 1) as usize))
             },
             ('c', None) if arg_or_default!(idx: 0, default: 0) == 0 => {
                 handler.identify_terminal(writer)
             },
-            ('C', None) | ('a', None) => {
-                handler.move_forward(Column(arg_or_default!(idx: 0, default: 1) as usize))
-            },
             ('D', None) => {
                 handler.move_backward(Column(arg_or_default!(idx: 0, default: 1) as usize))
             },
+            ('d', None) => {
+                handler.goto_line(Line(arg_or_default!(idx: 0, default: 1) as usize - 1))
+            },
             ('E', None) => {
                 handler.move_down_and_cr(Line(arg_or_default!(idx: 0, default: 1) as usize))
             },
             ('F', None) => {
                 handler.move_up_and_cr(Line(arg_or_default!(idx: 0, default: 1) as usize))
             },
+            ('G', None) | ('`', None) => {
+                handler.goto_col(Column(arg_or_default!(idx: 0, default: 1) as usize - 1))
+            },
             ('g', None) => {
                 let mode = match arg_or_default!(idx: 0, default: 0) {
                     0 => TabulationClearMode::Current,
@@ -1009,14 +1011,19 @@ where
 
                 handler.clear_tabs(mode);
             },
-            ('G', None) | ('`', None) => {
-                handler.goto_col(Column(arg_or_default!(idx: 0, default: 1) as usize - 1))
-            },
             ('H', None) | ('f', None) => {
                 let y = arg_or_default!(idx: 0, default: 1) as usize;
                 let x = arg_or_default!(idx: 1, default: 1) as usize;
                 handler.goto(Line(y - 1), Column(x - 1));
             },
+            ('h', intermediate) => {
+                for arg in args {
+                    match Mode::from_primitive(intermediate, *arg) {
+                        Some(mode) => handler.set_mode(mode),
+                        None => unhandled!(),
+                    }
+                }
+            },
             ('I', None) => handler.move_forward_tabs(arg_or_default!(idx: 0, default: 1)),
             ('J', None) => {
                 let mode = match arg_or_default!(idx: 0, default: 0) {
@@ -1045,13 +1052,6 @@ where
 
                 handler.clear_line(mode);
             },
-            ('S', None) => handler.scroll_up(Line(arg_or_default!(idx: 0, default: 1) as usize)),
-            ('t', None) => match arg_or_default!(idx: 0, default: 1) as usize {
-                22 => handler.push_title(),
-                23 => handler.pop_title(),
-                _ => unhandled!(),
-            },
-            ('T', None) => handler.scroll_down(Line(arg_or_default!(idx: 0, default: 1) as usize)),
             ('L', None) => {
                 handler.insert_blank_lines(Line(arg_or_default!(idx: 0, default: 1) as usize))
             },
@@ -1064,24 +1064,6 @@ where
                 }
             },
             ('M', None) => handler.delete_lines(Line(arg_or_default!(idx: 0, default: 1) as usize)),
-            ('X', None) => {
-                handler.erase_chars(Column(arg_or_default!(idx: 0, default: 1) as usize))
-            },
-            ('P', None) => {
-                handler.delete_chars(Column(arg_or_default!(idx: 0, default: 1) as usize))
-            },
-            ('Z', None) => handler.move_backward_tabs(arg_or_default!(idx: 0, default: 1)),
-            ('d', None) => {
-                handler.goto_line(Line(arg_or_default!(idx: 0, default: 1) as usize - 1))
-            },
-            ('h', intermediate) => {
-                for arg in args {
-                    match Mode::from_primitive(intermediate, *arg) {
-                        Some(mode) => handler.set_mode(mode),
-                        None => unhandled!(),
-                    }
-                }
-            },
             ('m', None) => {
                 if args.is_empty() {
                     handler.terminal_attribute(Attr::Reset);
@@ -1097,6 +1079,9 @@ where
             ('n', None) => {
                 handler.device_status(writer, arg_or_default!(idx: 0, default: 0) as usize)
             },
+            ('P', None) => {
+                handler.delete_chars(Column(arg_or_default!(idx: 0, default: 1) as usize))
+            },
             ('q', Some(b' ')) => {
                 // DECSCUSR (CSI Ps SP q) -- Set Cursor Style.
                 let style = match arg_or_default!(idx: 0, default: 0) {
@@ -1118,8 +1103,19 @@ where
 
                 handler.set_scrolling_region(top, bottom);
             },
+            ('S', None) => handler.scroll_up(Line(arg_or_default!(idx: 0, default: 1) as usize)),
             ('s', None) => handler.save_cursor_position(),
+            ('T', None) => handler.scroll_down(Line(arg_or_default!(idx: 0, default: 1) as usize)),
+            ('t', None) => match arg_or_default!(idx: 0, default: 1) as usize {
+                22 => handler.push_title(),
+                23 => handler.pop_title(),
+                _ => unhandled!(),
+            },
             ('u', None) => handler.restore_cursor_position(),
+            ('X', None) => {
+                handler.erase_chars(Column(arg_or_default!(idx: 0, default: 1) as usize))
+            },
+            ('Z', None) => handler.move_backward_tabs(arg_or_default!(idx: 0, default: 1)),
             _ => unhandled!(),
         }
     }
diff --git a/docs/escape_support.md b/docs/escape_support.md
new file mode 100644
index 00000000..a02848b2
--- /dev/null
+++ b/docs/escape_support.md
@@ -0,0 +1,100 @@
+# Escape Sequence Support
+
+This list includes all escape sequences Alacritty currently supports.
+
+### Legend
+
+The available statuses are `PARTIAL`, `IMPLEMENTED` and `REJECTED`. While a
+status of `PARTIAL` means there is still work left to be done, a status of
+`IMPLEMENTED` for something partially implemented means all other features were
+rejected.
+
+All whitespace in escape sequences is solely for formatting purposes and all
+relevant spaces are denoted as `SP`. The escape parameters are omitted for
+brevity.
+
+### ESC codes - `ESC`
+
+| ESCAPE    | STATUS      | NOTE                                               |
+| --------- | ----------- | -------------------------------------------------- |
+| `ESC (`   | IMPLEMENTED | Only charsets `B` and `0` are supported            |
+| `ESC )`   | IMPLEMENTED | Only charsets `B` and `0` are supported            |
+| `ESC *`   | IMPLEMENTED | Only charsets `B` and `0` are supported            |
+| `ESC +`   | IMPLEMENTED | Only charsets `B` and `0` are supported            |
+| `ESC =`   | IMPLEMENTED |                                                    |
+| `ESC >`   | IMPLEMENTED |                                                    |
+| `ESC 7`   | IMPLEMENTED |                                                    |
+| `ESC 8`   | IMPLEMENTED |                                                    |
+| `ESC # 8` | IMPLEMENTED |                                                    |
+| `ESC D`   | IMPLEMENTED |                                                    |
+| `ESC E`   | IMPLEMENTED |                                                    |
+| `ESC H`   | IMPLEMENTED |                                                    |
+| `ESC M`   | IMPLEMENTED |                                                    |
+| `ESC Z`   | IMPLEMENTED |                                                    |
+
+### CSI (Control Sequence Introducer) - `ESC [`
+
+| ESCAPE     | STATUS      | NOTE                                              |
+| ---------- | ----------- | ------------------------------------------------- |
+| ``CSI ` `` | IMPLEMENTED |                                                   |
+| `CSI @`    | IMPLEMENTED |                                                   |
+| `CSI A`    | IMPLEMENTED |                                                   |
+| `CSI a`    | IMPLEMENTED |                                                   |
+| `CSI B`    | IMPLEMENTED |                                                   |
+| `CSI b`    | IMPLEMENTED |                                                   |
+| `CSI C`    | IMPLEMENTED |                                                   |
+| `CSI c`    | PARTIAL     | No parameter support                              |
+| `CSI D`    | IMPLEMENTED |                                                   |
+| `CSI d`    | IMPLEMENTED |                                                   |
+| `CSI E`    | IMPLEMENTED |                                                   |
+| `CSI e`    | IMPLEMENTED |                                                   |
+| `CSI F`    | IMPLEMENTED |                                                   |
+| `CSI f`    | IMPLEMENTED |                                                   |
+| `CSI G`    | IMPLEMENTED |                                                   |
+| `CSI g`    | IMPLEMENTED |                                                   |
+| `CSI H`    | IMPLEMENTED |                                                   |
+| `CSI h`    | PARTIAL     | Only modes `4` and `20` are supported             |
+| `CSI ? h`  | PARTIAL     | Supported modes:                                  |
+|            |             |   `1`, `3`, `6`, `7`, `12`, `25`, `1000`, `1002`  |
+|            |             |   `1004`, `1005`, `1006`, `1007`, `1049`, `2004`  |
+| `CSI I`    | IMPLEMENTED |                                                   |
+| `CSI J`    | IMPLEMENTED |                                                   |
+| `CSI K`    | IMPLEMENTED |                                                   |
+| `CSI L`    | IMPLEMENTED |                                                   |
+| `CSI l`    | PARTIAL     | See `CSI h` for supported modes                   |
+| `CSI ? l`  | PARTIAL     | See `CSI ? h` for supported modes                 |
+| `CSI M`    | IMPLEMENTED |                                                   |
+| `CSI m`    | PARTIAL     | Colon separators are not supported                |
+| `CSI n`    | IMPLEMENTED |                                                   |
+| `CSI P`    | IMPLEMENTED |                                                   |
+| `CSI SP q` | PARTIAL     | No blinking support                               |
+| `CSI r`    | IMPLEMENTED |                                                   |
+| `CSI S`    | IMPLEMENTED |                                                   |
+| `CSI s`    | IMPLEMENTED |                                                   |
+| `CSI T`    | IMPLEMENTED |                                                   |
+| `CSI t`    | PARTIAL     | Only parameters `22` and `23` are supported       |
+| `CSI u`    | IMPLEMENTED |                                                   |
+| `CSI X`    | IMPLEMENTED |                                                   |
+| `CSI Z`    | IMPLEMENTED |                                                   |
+
+### OSC (Operating System Command) - `ESC ]`
+
+| ESCAPE    | STATUS      | NOTE                                               |
+| --------- | ----------- | -------------------------------------------------- |
+| `OSC 0`   | IMPLEMENTED | Icon names are not supported                       |
+| `OSC 1`   | REJECTED    | Icon names are not supported                       |
+| `OSC 2`   | IMPLEMENTED |                                                    |
+| `OSC 4`   | IMPLEMENTED |                                                    |
+| `OSC 10`  | IMPLEMENTED |                                                    |
+| `OSC 11`  | IMPLEMENTED |                                                    |
+| `OSC 12`  | IMPLEMENTED |                                                    |
+| `OSC 50`  | IMPLEMENTED | Only `CursorShape` is supported                    |
+| `OSC 52`  | IMPLEMENTED | Only Clipboard and primary selection supported     |
+| `OSC 104` | IMPLEMENTED |                                                    |
+| `OSC 110` | IMPLEMENTED |                                                    |
+| `OSC 111` | IMPLEMENTED |                                                    |
+| `OSC 112` | IMPLEMENTED |                                                    |
+
+### DCS (Device Control String) - `ESC P`
+
+Alacritty does not support any DCS escapes.