TerminalCapabilities — terminal capabilities class
TerminalCapabilities class decodes the process environment, passed as a
ProcessEnvironment object, into a suite of terminal capabilities.
These capabilities are used by, for example, the
ECMA48Decode classes, and their users, to determine how to behave.
TERM environment variable is its primary source of information.
Its value is expected to follow the terminfo(5) and termcap(5) convention (laid out in term(7)) of a root name followed by zero or more hyphen-separated feature suffixes (such as, for example,
TerminalCapabilities class only cares about the root name, which it takes to denote a family of terminal types (e.g.
putty), and whether there is a
-256color suffix in the value.
Other feature suffixes are ignored.
The class also uses the values of a few other environment variables, mainly to disambiguate the cases where the
TERM environment variable has been misconfigured as
xterm (which it is far too often):
The existence of this variable signifies extra colour capabilities of some sort.
If it has the value
truecolor or the value
24bit then the terminal is taken to understand ISO 8613-6/ITU T.416 Direct colour SGR 38 and SGR 48 control sequences.
Otherwise it indicates that the terminal understands the additional 8 (de facto) standard colours (from AIXTerm) set by SGR 90–97 and SGR 100–107.
For the terminal type families
teken it signifies that the terminal is a user-space virtual terminal rather than a kernel virtual terminal.
User-space virtual terminals support features extra to what KVTs support; including DEC Locator reports, extended DECSUSR, the HPA and CTC control sequences, the full suite of C1 control characters and their 7-bit aliases, DECFNK reports that contain modifier information, and the invisible attribute.
Set by the XTerm program in the child processes that it spawns for terminal sessions, this indicates the version number of XTerm.
It is used to attempt to determine when a user or a programmer has incorrectly used
xterm when the terminal emulator program is not in fact XTerm, and disable the use of some features that genuine XTerm has that other programs incorrectly ascribed the
xterm terminal type have not.
These include extended DECSCUSR, DEC Locator, XTerm-style ECMA-48-conformant mouse reports, the HPA and CTC control sequences, and the NEL control character.
Set by the VTE library in the child processes that terminal emulators using that library spawn for terminal sessions, this indicates the version number of VTE. From the version number of VTE it can be determined whether it is possible to use DECSCUSR and ISO 8613-6/ITU T.416 SGR sequences using sub-parameters.
Set by the Konsole program in the child processes that it spawns for terminal sessions, this indicates the Konsole profile in use. Its value is ignored. Its existence indicates that it is possible to use XTerm-style ECMA-48-conformant mouse reports.
Set by the iTerm.app program in the child processes that it spawns for terminal sessions, this indicates the name of the terminal program (a convention that only that terminal emulator program actually adheres to).
If it has the value
iTerm.app, then if the terminal type is
xterm it is considered to be
Set by the ROXTerm program in the child processes that it spawns for terminal sessions, this is an internal identifier of the terminal emulator. Its value is ignored. Its existence indicates that it is possible to use ISO 8613-6/ITU T.416 Direct colour SGR control sequences and DECSCUSR.
Terminals are expected to support a popular subset of ECMA-48 and the private control sequences of DEC VT 52x terminals. The capabilities determine variations from this. Some standard control sequences are unimplemented, incompletely implemented, or cause the wrong thing in some terminal emulators. For example: The ECMA control sequence decoders in the Interix terminal emulator and in Konsole do not simply discard CSI control sequences that they do not implement, but instead print parts of them as character output.
The console-terminal-emulator(1) manual describes a mechanism where the automatic line wrap at the right margin is held pending until the next printing character is processed, in order to allow full-screen TUI programs to write right up to the lower-right-hand corner.
This mechanism is formally documented almost nowhere else, but is implemented in almost all terminal types.
The few exceptions are the
interix terminal type families.
Writing in the lower-right-hand corner is not the only situation where applications must be aware of the effect of pending right margin wrap. In the pending state, the terminal cursor is in a different position to where an application would have expected it to wrap to, and relative cursor motions, including BackSpace and Next Line, need to account for this.
interix terminal type families, and erroneously labelled
xterm family terminals that are not genuine XTerm, do not implement the ECMA-48 standard Next Line control character.
Applications must fall back to Carriage Return followed by Line Feed.
interix terminal type families do not implement the ECMA-48 standard Reverse Index control character.
interix terminal type families do not implement the ECMA-48 standard Index control character.
Only genuine XTerm and console-terminal-emulator(1) are capable of the Cursor Tabulation Control control sequence. For others, applications have to fall back on a combination of the TBC control sequence and the HTS control charcter.
Only genuine XTerm and console-terminal-emulator(1) are capable of the Horizontal Position Absolute control sequence. For others, applications have to fall back on the CHA control sequence.
Only genuine XTerm and console-terminal-emulator(1) are capable of the Repeat control sequence. For others, applications have to fall back on explicitly repeating the characters.
teken terminal type families do not implement the ECMA-48 standard invisible attribute, with the exception to the latter twain that console-terminal-emulator(1) implements it.
konsole actively complains about its use.
konsole terminal type families do not implement the ECMA-48 standard strikethrough attribute, and the latter actively complains about its use.
interix terminal type families do not implement the ECMA-48 standard reverse video off SGR control sequence.
rxvt terminal type family does not implement reverse video correctly.
If the foreground and background colours are the same, instead of swapping foreground and background (as a real DEC VT does) it switches to the default colour.
putty terminal type family does not erase properly when characters have the inverse attribute.
It does not use the foreground colour as the erasure colour, but continues to use the background colour.
linux terminal type family, because of a long-standing bug, swaps the DECFNK codes for the Home and End keys on the editing keypad with those for the Find and Select keys.
interix terminal type family reports function keys as Start of Selected Area followed by a character.
To decode function keys from an Interix terminal emulator an ECMA decoder has to (mis)treat the SSA character as another single-character shift, like SS2 and SS3.
It is effectively "Single Shift level A".
teken terminal type families generate the function key sequences that were generated by the SCO Unix Multiscreen virtual terminal.
(In the case of the
teken family, this is part of an admixture of DECFNK and SCO control sequences.)
These SCO function key control sequences overlap with the DECFNK sequences for the cursor keypad and with the function key sequences generated by the
rxvt terminal type family.
Applications must only decode them as function keys when a terminal type that generates these sequences is in effect.
rxvt terminal type family generates erroneous ECMA control sequences for function keys, where "
$" is a final character instead of an intermediate character as the standard says.
Applications must tweak their ECMA control sequence decoders to (mis)handle this character.
interix terminal type family does not correctly handle CSI sequences containing private characters, emitting parts of them as printable output.
In particular, this means that it does not implement any DEC Private modes at all.
Only genuine XTerm and console-terminal-emulator(1) understand DECELR and DECSLE. (Other terminal types actually process the control sequences incorrectly.)
Only genuine XTerm and console-terminal-emulator(1) understand DECSTR.
Only console-terminal-emulator(1) understands DECST8C. (So too does a Windows NT utility named ansicon, outwith the worlds of Linux and the BSDs.)
Only genuine XTerm and console-terminal-emulator(1) are capable of the DEC Set Number of Lines control sequence. For others, applications have to fall back on the DECSLPP control sequence and deal with the fact that DECSLPP 0 to DECSLPP 24 may be DTTerm extensions rather than number of lines.
ROXTerm and the VTE library actively wrongly decode the DEC Set Columns Per Page control sequence, treating parts of it as printable output. For those, applications have to fall back on the DECSLPP 8 control sequence if they can.
ROXTerm and the VTE library actively wrongly decode the DEC Set Left and Right Margins control sequence, treating parts of it as printable output.
PuTTY is known to not support DECNKM, and one has to fall back to DECKPAM and DECKPNM.
Only console-terminal-emulator(1) understands DECECM. For other terminal types, the erase colour mode is fixed.
For terminal types where
has_DECECM is true, this is just the initial DECECM state.
For other terminal types, it is the single fixed DECECM state.
rxvt terminal type families, Konsole, and VTE library terminal emulators are all capable of extensions pioneered by DTTerm that repurpose DECSLPP 0 to DECSLPP 24.
DECSLPP 8 in particular sets both height and width in one control sequence.
For those terminal types, DECSLPP 8 or DECSNLS (if supported) are the only ways to set heights less than 25.
For other terminal types, DECSLPP can set all heights and widths have to be set with DECSCPP (if supported).
dumb terminal type family, the
rxvt terminal type family, and erroneously labelled
xterm family terminals that are not XTerm, not the VTE library, and not Konsole, are not capable of generating XTerm-style ECMA-48-conformant mouse reports.
(Other forms of XTerm-style mouse report are not ECMA control sequences, are problematic to decode, and have been deprecated in favour of the ECMA-48-conformant form since the 2000s.)
Only console-terminal-emulator(1) has a mode where all characters are full-width (i.e. "square"). Others display some characters half-width, and applications have to account for different character widths.
rxvt terminal type families, and console-terminal-emulator(1), effectively perform the action of DECST8C at terminal hard/soft reset, making explicitly setting regular tabs at 8 column intervals superfluous.
(Real DEC VTs do not do this, and the initial state is for all tabstops to be cleared.)
vte terminal type families, and console-terminal-emulator(1) recognize sub-parameters to SGR 4, specifying various types of underline.
There are four different mechanisms for specifying colour: the original 8 SGR foreground and background colour sequences standardized by ECMA-48, an additional 8 SGR sequences (originally from AIXTerm) for a total of 16 (de facto and de jure) standard colours, ISO 8613-6/ITU T.416 Indexed colour (which conventionally has the 16 standard colours as the first 16 entries in the colour palette), and ISO 8613-6/ITU T.416 Direct RGB colour. Compounding this is that there are, because of a historical misreporting of ISO 8613-6/ITU T.416, two forms for the two ISO 8613-6/ITU T.416 mechanisms.
dumb terminal type family is taken to not have any colour support at all.
Interix is taken to only support the 8 ECMA-48 colours.
Where the value of the
TERM environment variable contains the "-24bit" or "-truecolor" feature suffixes, the terminal is taken to support ISO 8613-6/ITU T.416 Direct colour (with the historic error).
Several terminal types are taken to always support ISO 8613-6/ITU T.416 Direct colour even without such a feature suffix.
The VTE Library, iTerm, and (if fake 24-bit colour is permitted) genuine XTerm are taken to always support it, without the historic error.
User-space virtual terminals, Konsole, Simple Terminal, GNOME/MATE/XFCE Terminal, RoXTerm, and (if fake 24-bit colour is permitted) the Linux kernel virtual terminal and rxvt are taken to always support it, but with the historic error.
Some terminal types are taken to support ISO 8613-6/ITU T.416 Indexed colour, but not Direct colour. PuTTY, rxvt, the Linux kernel virtual terminal, Teken, tmux, and anything falsely claiming to be XTerm are taken to support it, with the historic error.
Otherwise, terminals are taken to only support the 8 ECMA-48 colours.
COLORTERM environment variable exists and its value is the string "truecolor" or "24bit", the terminal is taken to support ISO 8613-6/ITU T.416 Direct colour, with the historic error.
COLORTERM environment variable exists, the terminal is taken to support at least the two mechanisms for the 16 standard colours.
Where either the
COLORTERM or the
TERM environment variable value contains the string "256", the terminal is taken to support at least ISO 8613-6/ITU T.416 Indexed colour (with the historic error).
The former comes from a convention of specifying the terminal type without the "-256color" feature suffix in the
TERM environment variable and the "real" terminal type in the
COLORTERM environment variable.
This was to cope with databases to which the "-256color" name variants had not yet spread, back when they were a new idea, and is largely obsolete nowadays.
It is the latter that should nowadays be used.
COLORTERM environment variable is largely obsolete nowadays as a mechanism for specifying ISO 8613-6/ITU T.416 Indexed colour support, and most terminal type families are simply assumed to support it.
It is nowadays pretty much base level functionality for GUI terminal emulators, with most also supporting Direct colour (even without the historic error in the cases of recent versions of the VTE library and iTerm).
Thus even not employing the "-256color" suffix in the value of the
TERM environment variable implies Indexed colour support.
Base level functionality for the
linux terminal type family is both Indexed and Direct colour support, since Linux version 4.8.
Although Linux does not actually implement 24-bit colour, it instead faking it by mapping RGB to its Indexed color palette (oftentimes not particularly well).
Base level functionality for the
teken terminal type family is Indexed colour support; unless it is console-terminal-emulator(1), which supports Direct colour as well.
Base level functionality for the
cons terminal type families is only the original standard 8 colours being supported.
Emulating DEC VTs being the de facto standard of modern (character mode) terminal emulators, the de facto standard way to alter the cursor shape has been the DECSCUSR control sequence since the time of the DEC VT510/VT520/VT525. Being independently developed at around the same time, the Linux kernel's built-in terminal emulator has a quite different and idiosyncratic control sequence (LINUXSCUSR). XTerm extended the DECSCUSR control sequence with more possible cursor shapes.
linux terminal type family is taken to understand only the LINUXSCUSR control sequence, except for console-terminal-emulator(1).
teken terminal type families when they are console-terminal-emulator(1), genuine XTerm, and the
teraterm terminal type families are taken to understand extended DECSCUSR.
screen terminal type families, ROXTerm, and newer versions of the VTE library are taken to understand standard DECSCUSR.
Unfortunately, DECSCUSR is one of the control sequences that several terminals not only do not support but actively decode wrongly, treating parts of it as printable output. So applications cannot just emit it and leave it to be ignored where not implemented.