Editing ANSI escape code (section)

== Terminal input sequences ==
{{More citations needed|section|date=October 2023}}
Pressing special keys on the keyboard, as well as outputting many xterm CSI, DCS, or OSC sequences, often produces a CSI, DCS, or OSC sequence, sent from the terminal to the computer as though the user typed it.

When typing input on a terminal keypresses outside the normal main alphanumeric keyboard area can be sent to the host as ANSI sequences. For keys that have an equivalent output function, such as the cursor keys, these often mirror the output sequences. However, for most keypresses there isn't an equivalent output sequence to use.

There are several encoding schemes, and unfortunately most terminals mix sequences from different schemes, so host software has to be able to deal with input sequences using any scheme. 
To complicate the matter, the VT terminals themselves have two schemes of input, ''normal mode'' and ''application mode'' that can be switched by the application.

(draft section)
<pre>
<char>                                         -> char
<esc> <nochar>                                 -> esc
<esc> <esc>                                    -> esc
<esc> <char>                                   -> Alt-keypress or keycode sequence
<esc> '[' <nochar>                             -> Alt-[
<esc> '[' (<modifier>) <char>                  -> keycode sequence, <modifier> is a decimal
                                                  number and defaults to 1 (xterm)
<esc> '[' (<keycode>) (';'<modifier>) '~'      -> keycode sequence, <keycode> and <modifier>
                                                  are decimal numbers and default to 1 (vt)
</pre>

If the terminating character is '~', the first number must be present and is a
keycode number, the second number is an optional modifier value. If the terminating
character is a letter, the letter is the keycode value, and the optional number is
the modifier value.

The modifier value defaults to 1, and after subtracting 1 is a bitmap of modifier
keys being pressed: {{keypress|Meta|Ctrl|Alt|Shift}}. So, for example, <code>&lt;esc>[4;2~</code> is
{{keypress|Shift|End}}, <code>&lt;esc>[20~</code> is function key {{keypress|F9}}, <code>&lt;esc>[5C</code> is {{keypress|Ctrl|Right}}.

In other words, the modifier is the sum of the following numbers:

{| class="wikitable"
|-
! Key pressed
! Number
! Comment
|-
|
| 1
| always added, the rest are optional
|-
| Shift
| 1
|
|-
| (Left) Alt
| 2
|
|-
| Control
| 4
|
|-
| Meta
| 8
|
|}

<pre>
vt sequences:
<esc>[1~    - Home        <esc>[16~   -             <esc>[31~   - F17
<esc>[2~    - Insert      <esc>[17~   - F6          <esc>[32~   - F18
<esc>[3~    - Delete      <esc>[18~   - F7          <esc>[33~   - F19
<esc>[4~    - End         <esc>[19~   - F8          <esc>[34~   - F20
<esc>[5~    - PgUp        <esc>[20~   - F9          <esc>[35~   - 
<esc>[6~    - PgDn        <esc>[21~   - F10         
<esc>[7~    - Home        <esc>[22~   -             
<esc>[8~    - End         <esc>[23~   - F11         
<esc>[9~    -             <esc>[24~   - F12         
<esc>[10~   - F0          <esc>[25~   - F13         
<esc>[11~   - F1          <esc>[26~   - F14         
<esc>[12~   - F2          <esc>[27~   -             
<esc>[13~   - F3          <esc>[28~   - F15         
<esc>[14~   - F4          <esc>[29~   - F16         
<esc>[15~   - F5          <esc>[30~   -

xterm sequences:
<esc>[A     - Up          <esc>[K     -             <esc>[U     -
<esc>[B     - Down        <esc>[L     -             <esc>[V     -
<esc>[C     - Right       <esc>[M     -             <esc>[W     -
<esc>[D     - Left        <esc>[N     -             <esc>[X     -
<esc>[E     -             <esc>[O     -             <esc>[Y     -
<esc>[F     - End         <esc>[1P    - F1          <esc>[Z     -
<esc>[G     - Keypad 5    <esc>[1Q    - F2       
<esc>[H     - Home        <esc>[1R    - F3       
<esc>[I     -             <esc>[1S    - F4       
<esc>[J     -             <esc>[T     - 
</pre>

<code>&lt;esc>[A</code> to <code>&lt;esc>[D</code> are the same as the ANSI output sequences. The <code>&lt;modifier></code> is normally omitted if no modifier keys are pressed, but most implementations always emit the <code>&lt;modifier></code> for {{keypress|F1|F4|chain=–}}. (draft section)

Xterm has a comprehensive documentation page on the various function-key and mouse input sequence schemes from DEC's VT terminals and various other terminals it emulates.<ref name="xtc">{{cite web |title=XTerm Control Sequences (ctlseqs) |url=https://invisible-island.net/xterm/ctlseqs/ctlseqs.html |first1=Edward |last1=Moy |first2=Stephen |last2=Gildea |first3=Thomas |last3=Dickey |year=2019 |website=Invisible Island}}</ref> Thomas Dickey has added a lot of support to it over time;<ref>{{cite web |last1=Dickey |first1=Thomas |title=XTerm FAQ: Comparing versions, by counting controls |url=https://invisible-island.net/xterm/xterm.faq.html#compare_versions |website=Invisible Island |access-date=25 January 2020}}</ref> he also maintains a list of default keys used by other terminal emulators for comparison.<ref>{{cite web |year=2016 |last1=Dickey |first1=Thomas |title=Table of function-keys for XTerm and other Terminal Emulators |url=https://invisible-island.net/xterm/xterm-function-keys.html |website=Invisible Island |access-date=25 January 2020}}</ref>

* On the Linux console, certain function keys generate sequences of the form <code>CSI [ ''char''</code>. The CSI sequence should terminate on the <code>[</code>.
* Old versions of [[Terminator (terminal emulator)|Terminator]] generate <code>SS3 1; ''modifiers'' ''char''</code> when {{keypress|F1|F4|chain={{sp}}–{{sp}}}} are pressed with modifiers. The faulty behavior was copied from [[GNOME Terminal]].{{Citation needed|date=December 2010}}
* xterm replies <code>CSI ''row'' ; ''column'' R</code> if asked for cursor position and <code>CSI 1 ; ''modifiers'' R</code> if the {{keypress|F3}} key is pressed with modifiers, which collide in the case of <code>''row'' == 1</code>. This can be avoided by using the ''?'' private modifier as <code>CSI ? 6 n</code>, which will be reflected in the response as <code>CSI ? ''row'' ; ''column'' R</code>.
* many terminals prepend <code>ESC</code> to any character that is typed with the alt key down. This creates ambiguity for uppercase letters and symbols <code>@[\]^_</code>, which would form C1 codes.{{clarify|date=November 2010}}
* [[Konsole]] generates <code>SS3 ''modifiers'' ''char''</code> when {{keypress|F1|F4|chain={{sp}}–{{sp}}}} are pressed with modifiers.{{clarify|date=November 2010}}
* [[iTerm2]] supports reporting additional keys via an enhanced CSI u mode.<ref>{{cite web |url=https://iterm2.com/documentation-csiu.html |title=CSI u - Documentation - iTerm2 - macOS Terminal Replacement |author=<!--Not stated--> |website=iTerm2 |access-date=15 Aug 2023}}</ref>