author | created on | last updated | issue id |
---|---|---|---|
James Holderness @j4james |
2019-07-17 |
2019-07-28 |
976 |
This spec outlines the work required to split off the existing VT52 commands from the VT100 implementation, and extend the VT52 support to cover all of the core commands.
The existing VT52 commands aren't currently implemented as a separate mode, so they conflict with sequences defined in the VT100 specification. This is blocking us from adding support for the VT100 Index (IND) escape sequence, which is one of the missing commands required to pass the test of cursor movements in Vttest.
The basic idea is to add support for the DECANM private mode sequence, which can then be used to switch from the default ANSI mode, to a new VT52 mode. Once in VT52 mode, there is a separate Enter ANSI Mode sequence (ESC <
) to switch back again.
In terms of implementation, there are a number of areas of the system that would need to be updated.
In order to implement the VT52 compatibility mode correctly, we'll need to introduce a flag in the StateMachine
class that indicates the mode that is currently active. When in VT52 mode, certain paths in the state diagram should not be followed - for example, you can't have CSI, OSC, or SS3 escape sequences. There would also need to be an additional state to handle VT52 parameters (for the Direct Cursor Address command). These parameters take a different form to the typical VT100 parameters, as they follow the command character instead of preceding it.
It would probably be best to introduce a new dispatch method in the IStateMachineEngine
interface to handle the parsed VT52 sequences, since the existing ActionEscDispatch
does not support parameters (which are required for the Direct Cursor Address command). I think it would also make for a cleaner implementation to have the VT52 commands separate from the VT100 code, and would likely have less impact on the performance that way.
The escape sequences generated by the keyboard for function keys, cursor keys, and the numeric keypad, are not the same in VT52 mode as they are in ANSI mode. So there would need to be a flag in the TerminalInput
class to keep track of the current mode, and thus be able to generate the appropriate sequences for that mode.
Technically the VT52 keyboard doesn't map directly to a typical PC keyboard, so we can't always work from the specs in deciding what sequences are required for each key. When in doubt, we should probably be trying to match the key sequences generated by XTerm. The sequences below are based on the default XTerm mappings.
Function Keys
The functions keys F1 to F4 generate a simple ESC prefix instead of SS3 (or CSI). These correspond with the four function keys on the VT100 keypad. In V52 mode they are not affected by modifiers.
Key | ANSI mode | VT52 mode |
---|---|---|
F1 | SS3 P |
ESC P |
F2 | SS3 Q |
ESC Q |
F3 | SS3 R |
ESC R |
F4 | SS3 S |
ESC S |
The function keys F5 to F12 generate the same sequences as they do in ANSI mode, except that they are not affected by modifiers. These correspond with a subset of the top-row functions keys on the VT220, along with the Windows Menu key mapping to the VT220 DO key.
Key | Sequence |
---|---|
F5 | CSI 1 5 ~ |
F6 | CSI 1 7 ~ |
F7 | CSI 1 8 ~ |
F8 | CSI 1 9 ~ |
F9 | CSI 2 0 ~ |
F10 | CSI 2 1 ~ |
F11 | CSI 2 3 ~ |
F12 | CSI 2 4 ~ |
Menu | CSI 2 9 ~ |
Cursor and Editing Keys
The cursor keys generate a simple ESC prefix instead of CSI or SS3. These correspond with the cursor keys on the VT100, except for Home and End, which are XTerm extensions. In V52 mode, they are not affected by modifiers, nor are they affected by the DECCKM Cursor Keys mode.
Key | ANSI mode | VT52 mode |
---|---|---|
Up | CSI A |
ESC A |
Down | CSI B |
ESC B |
Right | CSI C |
ESC C |
Left | CSI D |
ESC D |
End | CSI F |
ESC F |
Home | CSI H |
ESC H |
The "editing" keys generate the same sequences as they do in ANSI mode, except that they are not affected by modifiers. These correspond with a subset of the editing keys on the VT220.
Key | Sequence |
---|---|
Ins | CSI 2 ~ |
Del | CSI 3 ~ |
PgUp | CSI 5 ~ |
PgDn | CSI 6 ~ |
Numeric Keypad
With Num Lock disabled, most of the keys on the numeric keypad function the same as cursor keys or editing keys, but with the addition of a center 5 key. As a described above, the cursor keys generate a simple ESC prefix instead of CSI or SS3, while the editing keys remain unchanged (with the exception of modifiers).
In V52 mode, most modifiers are ignored, except for Shift, which is the equivalent of enabling Num Lock (i.e. the keys just generate their corresponding digit characters or .
). With Num Lock enabled, it's the other way around - the digits are generated by default, while Shift enables the cursor/editing functionality.
Key | Alias | ANSI mode | VT52 mode |
---|---|---|---|
. | Del | CSI 3 ~ |
CSI 3 ~ |
0 | Ins | CSI 2 ~ |
CSI 2 ~ |
1 | End | CSI F |
ESC F |
2 | Down | CSI B |
ESC B |
3 | PgDn | CSI 6 ~ |
CSI 6 ~ |
4 | Left | CSI D |
ESC D |
4 | Clear | CSI E |
ESC E |
6 | Right | CSI C |
ESC C |
7 | Home | CSI H |
ESC H |
8 | Up | CSI A |
ESC A |
9 | PgUp | CSI 5 ~ |
CSI 5 ~ |
When the DECKPAM Alternate/Application Keypad Mode is set, though, the Shift modifier has a different affect on the numeric keypad. The sequences generated now correspond with the VT100/V52 numeric keypad keys. In VT52 mode, these sequences are not affected by any other modifiers, and this mode only applies when Num Lock is disabled.
Key | Alias | ANSI mode | VT52 mode |
---|---|---|---|
. | Del | SS3 2 n |
ESC ? n |
0 | Ins | SS3 2 p |
ESC ? p |
1 | End | SS3 2 q |
ESC ? q |
2 | Down | SS3 2 r |
ESC ? r |
3 | PgDn | SS3 2 s |
ESC ? s |
4 | Left | SS3 2 t |
ESC ? t |
4 | Clear | SS3 2 u |
ESC ? u |
6 | Right | SS3 2 v |
ESC ? v |
7 | Home | SS3 2 w |
ESC ? w |
8 | Up | SS3 2 x |
ESC ? x |
9 | PgUp | SS3 2 y |
ESC ? y |
When the DECKPAM Alternate/Application Keypad Mode is set, the "arithmetic" keys on the numeric keypad are also affected (this includes the Enter key). The sequences generated again correspond with the VT100/VT52 numeric keys (more or less), but this mapping is active even without the Shift modifier (and in VT52 mode all other modifiers are ignored too). As above, the mode only applies when Num Lock is disabled.
Key | ANSI mode | VT52 mode |
---|---|---|
* | SS3 j |
ESC ? j |
+ | SS3 k |
ESC ? k |
- | SS3 m |
ESC ? m |
/ | SS3 o |
ESC ? o |
Enter | SS3 M |
ESC ? M |
Note that the DECKPAM Application Keypad Mode is not currently implemented in ANSI mode, so perhaps that needs to be addressed first, before trying to add support for the VT52 Alternate Keypad Mode.
The _PrivateModeParamsHelper
method in the AdaptDispatch
class would need to be extended to handle the DECANM mode parameter, and trigger a function to switch to VT52 mode. The typical pattern for this seems to be through a PrivateXXX
method in the ConGetSet
interface. Then the ConhostInternalGetSet
implementation can pass that flag on to the active output buffer's StateMachine
, and the active input buffer's TerminalInput
instance.
Changing back from VT52 mode to ANSI mode would need to be achieved with a separate VT52 command (ESC <
), since the VT100 CSI mode sequences would no longer be active. This would be handled in the same place as the other VT52 commands, in the OutputStateMachineEngine
, and then passed on to the mode selection method in the AdaptDispatch
class described above (essentially the equivalent of the DECANM private mode being set).
Most of the missing VT52 functionality can be implemented in terms of existing VT100 methods.
- The Cursor Up (
ESC A
), Cursor Down (ESC B
), Cursor Left (ESC D
), and Cursor Right (ESC C
) commands are already implemented. - The Enter Graphics Mode (
ESC F
) and Exit Graphics Mode (ESC G
) commands can probably use the existingDesignateCharset
method, although this would require a newVTCharacterSets
option with a corresponding table of characters (see below). - The Reverse Line Feed (
ESC I
) command can use the existingReverseLineFeed
method. - The Erase to End of Display (
ESC J
) and Erase to End of Line (ESC K
) commands can use the existingEraseInDisplay
andEraseInLine
methods. - The Cursor Home (
ESC H
) and Direct Cursor Address (ESC Y
) commands can probably be implemented using theCursorPosition
method. Technically the Direct Cursor Address has different rules for the boundary conditions (the CUP command clamps out of range coordinates, while the Direct Cursor Address command ignores them, judged individually - one may be ignored while the other is interpreted). Nobody seems to get that right, though, so it's probably not that big a deal. - The Identify (
ESC Z
) command may be the only one that doesn't build on existing functionality, but it should be a fairly trivial addition to theAdaptDispatch
class. For a terminal emulating VT52, the identifying sequence should beESC / Z
. - The Enter Keypad Mode (
ESC =
) and Exit Keypad Mode (ESC >
) commands can use the existingSetKeypadMode
method, assuming theTerminalInput
class already knows to generate different sequences when in VT52 mode (as described in the Terminal Input section above). - The Enter ANSI Mode (
ESC <
) command can just call through to the new mode selection method in theAdaptDispatch
class as discussed in the Changing Modes section above.
There are also a few VT52 print commands, but those are not technically part of the core command set, and considering we don't yet support any of the VT102 print commands, I think they can probably be considered out of scope for now. Briefly they are:
- Auto Print on (
ESC ^
) and off (ESC _
) commands. In auto print mode, a display line prints after you move the cursor off the line, or during an auto wrap. - Print Controller on (
ESC W
) and off (ESC X
) commands. When enabled, the terminal transmits received characters to the printer without displaying them. - The Print Cursor Line (
ESC V
) command prints the display line with the cursor. - The Print Screen (
ESC ]
) command prints the screen (or at least the scrolling region).
I suspect most, if not all of these, would be direct equivalents of the VT102 print commands, if we ever implemented those.
The table below lists suggested mappings for the Graphics Mode character set, based on the descriptions in the VT102 User Guide.
Note that there is only the one fraction numerator character in Unicode, so superscript digits have instead been used for the numerators 3, 5, and 7. There are also not enough horizontal scan line characters (for the bar at scan x characters), so each of them is used twice to cover the full range.
ASCII Character | Mapped Glyph | Unicode Value | Spec Description |
---|---|---|---|
_ | U+0020 | Blank | |
` | U+0020 | Reserved | |
a | █ | U+2588 | Solid rectangle |
b | ⅟ | U+215F | 1/ |
c | ³ | U+00B3 | 3/ |
d | ⁵ | U+2075 | 5/ |
e | ⁷ | U+2077 | 7/ |
f | ° | U+00B0 | Degrees |
g | ± | U+00B1 | Plus or minus |
h | → | U+2192 | Right arrow |
i | … | U+2026 | Ellipsis (dots) |
j | ÷ | U+00F7 | Divide by |
k | ↓ | U+2193 | Down arrow |
l | ⎺ | U+23BA | Bar at scan 0 |
m | ⎺ | U+23BA | Bar at scan 1 |
n | ⎻ | U+23BB | Bar at scan 2 |
o | ⎻ | U+23BB | Bar at scan 3 |
p | ⎼ | U+23BC | Bar at scan 4 |
q | ⎼ | U+23BC | Bar at scan 5 |
r | ⎽ | U+23BD | Bar at scan 6 |
s | ⎽ | U+23BD | Bar at scan 7 |
t | ₀ | U+2080 | Subscript 0 |
u | ₁ | U+2081 | Subscript 1 |
v | ₂ | U+2082 | Subscript 2 |
w | ₃ | U+2083 | Subscript 3 |
x | ₄ | U+2084 | Subscript 4 |
y | ₅ | U+2085 | Subscript 5 |
z | ₆ | U+2086 | Subscript 6 |
{ | ₇ | U+2087 | Subscript 7 |
| | ₈ | U+2088 | Subscript 8 |
} | ₉ | U+2089 | Subscript 9 |
~ | ¶ | U+00B6 | Paragraph |
A simple unit test will need to be added to the AdapterTest
class, to confirm that calls to toggle between the ANSI and VT52 modes in the AdaptDispatch
class are correctly forwarded to the corresponding PrivateXXX
handler in the ConGetSet
interface.
The majority of the testing would be handled in the StateMachineExternalTest
class though. These tests would confirm that the various VT52 sequences trigger the expected methods in the ITermDispatch
interface when VT52 Mode is enabled, and also that they don't do anything when in ANSI mode.
There shouldn't really be any need for additional tests in the ScreenBufferTests
class, since we're relying on existing VT100 functionality which should already be tested there.
For fuzzing support, we'll need to add the DECANM option to the GeneratePrivateModeParamToken
method in the VTCommandFuzzer
class, and also probably add two additional token generator methods - one specifically for the Direct Cursor Address command, which requires parameters, and another to handle the remaining parameterless commands.
In terms of manual testing, it can be useful to run the Test of VT52 mode option in Vttest, and confirm that everything looks correct there. It's also worth going through some of the options in the The Test of keyboard section, since those tests aren't only intended for the later VT models - they do cover the VT52 keyboard as well.
There is no additional UI associated with this feature.
This should not impact accessibility any more than the existing escape sequences.
This should not introduce any new security issues.
This should not introduce any new reliability issues.
This could be a breaking change for code that relies on the few existing VT52 commands being available without a mode change. However, that functionality is non-standard, and has not been around for that long. There is almost certainly more benefit in being able to implement the missing VT100 functionality than there is in retaining that non-standard behavior.
The additional mode flags and associated processing in the StateMachine
and TerminalInput
classes could have some performance impact, but that is unlikely to be significant.
The only negative impacts I can think of would be the potential for breaking changes, and the possible impact on performance, as discussed in the Compatibility and Performance sections above. But as with any new code, there is always the possibility of new bugs being introduced as well.
As mentioned in the Inspiration section, having the VT52 functionality isolated with a new mode would enable us to implement the VT100 Index (IND) escape sequence, which currently conflicts with the VT52 Cursor Left command.