Terminal Support

This document describes extensions to Basic Text adding ANSI-style terminal features. It is experimental.

Terminal Output

Terminal Output uses Basic Text's "strict" conversions.

Output Feature Sets

Terminal output features are grouped into sets, which can be supported independently or in combination:

Line-oriented output, eg. for readline
Full-screen output, eg. for vim
Color, eg. for color ls
Custom Title, eg. for shell command prompts

Line-oriented output

This feature adds line-oriented editing features.

The following control codes are recognized:

Code	Meaning
U+7	Alert
U+8	Move cursor back one column
U+9	Tab
U+A	End of line
U+C	FF Terminal Compatibility
U+D	Carriage Return
U+7F	No Effect

The following escape sequences are recognized:

Sequence	Meaning
`␛[K`	Clear to end of line
`␛[0K`	Clear to end of line
`␛[2K`	Clear entire line

Alert

Produce an acoustic indication or a visual indication if possible, without modifying the state of the terminal.

Move cursor back one column

Move the cursor back one column, but not past the first column.

Tab

Move the cursor back one column, but not past the first column.

End of line

Move the cursor to the beginning of the next line, scrolling the output if needed.

FF Terminal Compatibility

Move the cursor to the next line without changing the column.

Carriage Return

Move the cursor to the first column of the current line.

No Effect

Leave the state of the terminal unmodified.

Clear to end of line

Clear to the end of the line, leaving the cursor where it is.

Clear entire line

Clear the entire line, and move the cursor to the first column.

Full-screen output

This feature set adds a "full screen" mode which may be enabled at runtime, which supports two-dimensional cursor positioning, scrolling, screen clearing, and related features.

In the default mode, the following escape sequences are recognized:

Sequence	Meaning	Notes
`␛[?1049h`	Enter full-screen mode, with a clear screen and default settings

The following escape sequences are recognized within full-screen mode:

Sequence	Meaning	Notes
`␛7`	`save_cursor`	TODO: Do we need this?
`␛8`	`restore_cursor`	Ditto
`␛H`	`set_tab`	Ditto
`␛M`	`scroll_reverse`	TODO: Is this different on Windows?
`␛[«n»@`	`parm_ich(«n»)`	`«n»` may be omitted and defaults to 1
`␛[«n»A`	`parm_up_cursor(«n»)`	Ditto
`␛[«n»B`	`parm_down_cursor(«n»)`	Ditto
`␛[«n»C`	`parm_right_cursor(«n»)`	Ditto
`␛[«n»D`	`parm_left_cursor(«n»)`	Ditto
`␛[«n»G`	`column_address(«n»)`	Ditto
`␛[«line»;«column»H`	`cursor_address(«row», «column»)`	`«line»;«column»` may be omitted and default to `1;1`
`␛[«n»I`	`tab(«n»)`	`«n»` may be omitted and defaults to 1
`␛[0J`	`clr_eos`	The `0` is optional
`␛[1J`	Clear the screen from the beginning to the current cursor position
`␛[2J`	Clear the screen	Unlike `clear_screen`, this doesn't change the cursor position
`␛[«n»L`	`insert_line(«n»)`	`«n»` may be omitted and defaults to 1
`␛[«n»M`	`parm_delete_line(«n»)`	Ditto
`␛[«n»P`	`parm_dch(«n»)`	Ditto
`␛[«n»S`	`parm_index(«n»)`	Ditto
`␛[«n»T`	`parm_rindex(«n»)`	Ditto
`␛[«n»X`	`erase_chars(«n»)`	Ditto
`␛[«n»Z`	`cbt(«n»)`	Ditto
`␛[«n»d`	`row_address(«n»)`	Ditto
`␛[«line»;«column»f`	Same as the similar sequence ending in `H`
`␛[3g`	`clear_all_tabs`	TODO: do we need this?
`␛[?25h`	`cursor_visible`
`␛[?1049h`	Clear the screen and reset full-screen settings to defaults
`␛[?2004h`	Enable bracketed paste mode
`␛[?25l`	`cursor_invisible`
`␛[?1049l`	Exit full-screen mode and restore the terminal to its prior state
`␛[?2004l`	Disable bracketed paste mode
`␛[!p`	Reset the terminal to default settings, without clearing the screen
`␛[«top»;«bottom»r`	`change_scroll_region(«top», «bottom»)`	`«top»;«bottom»` may be omitted and default to `1;«viewpoint-height»`

TODO: Describe the behavior on on the rightmost column and bottom-most line, and other traditionally underspecified things.

TODO: Describe parameters in more detail, including the syntax for numeric and string parameters, and min/max valid values for numeric parameters.

Color

This feature set adds color and display attributes such as bold, underline, and italics.

This feature defines the following escape sequences:

Sequence	Meaning	Notes
`␛[…m`	`set_attributes(…)`	Set text attributes; see below for the meaning of `…`
`␛[38;2;«r»;«g»;«b»m`	Set foreground color to RGB `«r»`, `«g»`, `«b»`	Values are from 0-255
`␛[48;2;«r»;«g»;«b»m`	Set background color to RGB `«r»`, `«g»`, `«b»`	Ditto

In the … form above, the … may be replaced by up to 16 ;-separated sequences from the following:

Sequence	Meaning	Notes
`0`	Normal (default)
`1`	Bold
`2`	Faint	Faint may not appear visually distinct on some platforms
`4`	Underlined	May be "simulated with color". Applications may wish to use U+332 instead.
`7`	Inverse
`22`	Not bold or faint
`23`	Not italicized
`24`	Not underlined (any kind)
`27`	Not inverse
`29`	Not crossed-out
`30`	Foreground Black
`31`	Foreground Red
`32`	Foreground Green
`33`	Foreground Yellow	May appear brown on some platforms
`34`	Foreground Blue
`35`	Foreground Magenta
`36`	Foreground Cyan
`37`	Foreground White
`39`	Foreground default
`40`	Background Black
`41`	Background Red
`42`	Background Green
`43`	Background Yellow
`44`	Background Blue
`45`	Background Magenta
`46`	Background Cyan
`47`	Background White
`49`	Background default
`90`	Foreground bright Black	Bright colors may not appear visually distinct on some platforms
`91`	Foreground bright Red
`92`	Foreground bright Green
`93`	Foreground bright Yellow
`94`	Foreground bright Blue
`95`	Foreground bright Magenta
`96`	Foreground bright Cyan
`97`	Foreground bright White
`100`	Background bright Black
`101`	Background bright Red
`102`	Background bright Green
`103`	Background bright Yellow
`104`	Background bright Blue
`105`	Background bright Magenta
`106`	Background bright Cyan
`107`	Background bright White

Not all terminal support all colors; when a requested color is unavailable, terminals may substitute the closest available color.

Custom Title

This feature set adds the ability to set a custom window title.

This feature defines the following escape sequences:

Sequence	Meaning	Notes
`␛]0;«string»␇`	Sets the terminal's title to `«string»`	Implementations may implicitly add a prefix and/or truncate the string
`␛]2;«string»␇`	Sets the terminal's title to `«string»`	Ditto

Terminal input

Terminal Input uses Basic Text's normal (not "strict") conversions.

Most keys have obvious mappings to Unicode scalar value sequences. This section describes mapping for special keys read from a terminal.

Three modifiers are recognized: Ctrl, Alt, and Shift. In environments with Meta keys, Meta is mapped to Alt.

Terminal input control codes

The following control codes are recognized:

Code	Meaning	Notes
U+0	Ctrl-Space
U+8	Ctrl-`H`	Despite U+8 being historically called "backspace" in ASCII, it isn't the backspace key
U+9	Tab
U+A	Enter	U+A means "end of line"
U+C	Ctrl-`L`	This is only transmitted in immediate mode, and requests applications refresh the screen
U+11	Ctrl-`Q`	When enabled in the terminal input mode
U+13	Ctrl-`S`	When enabled in the terminal input mode
U+1B	Escape	When read in in immediate input mode
U+1C	Ctrl-`\`	When enabled in the terminal input mode
U+1D	Ctrl-`]`
U+1E	Ctrl-`^`
U+1F	Ctrl-`_`
U+7F	Backspace	This is the backspace key

The following control codes are interpreted by the implementation and not passed on to applications:

Code	Commonly typed as	Behavior
U+3	Ctrl-`C`	Terminate the program, when not enabled in the terminal input mode
U+9	Tab	No effect when modifiers include Alt
U+D	Ctrl-`M`	Send U+A to the program, when read in a single input call in immediate input mode
U+11	Ctrl-`Q`	No effect when not enabled in the terminal input mode
U+13	Ctrl-`S`	No effect when not enabled in the terminal input mode
U+1A	Ctrl-`Z`	Suspend the program
U+1C	Ctrl-`\`	Terminate the program, when not enabled in the terminal input mode
U+60	`	No effect when modifiers include Alt

Except as specified otherwise above, U+1 through U+1A are recognized as Ctrl-A through Ctrl-Z, respectively.

Codes with values U+0 through U+7F, except for U+5B ([) and U+5D (]), may be preceded by U+1B indicating the Alt modifier.

When a program is resumed from being suspended, any streams open in immediate input mode are passed a U+C (Ctrl-L). Applications are encouraged to interpret Ctrl-L as a command to redraw the screen.

Terminal input escape sequences

The following escape sequences are recognized when they are read as a single input call in immediate input mode:

Sequence	Meaning	Notes
`␛[A`	Up
`␛[B`	Down
`␛[C`	Right
`␛[D`	Left
`␛[F`	End
`␛[H`	Home
`␛[1«m»A`	Up	Same as above, but with modifiers
`␛[1«m»B`	Down	Ditto
`␛[1«m»C`	Right	Ditto
`␛[1«m»D`	Left	Ditto
`␛[Z`	Shift-Tab
`␛[1«m»~`	Home	Same as above, but with modifiers
`␛[2«m?»~`	Insert
`␛[3«m?»~`	Delete
`␛[4«m»~`	End	Same as above, but with modifiers
`␛[5«m?»~`	Page Up
`␛[6«m?»~`	Page Down
`␛[11«m?»~`	F1	These use the "old xterm"/CSI values, rather than vt102/vt220/SS3/Windows values
`␛[12«m?»~`	F2
`␛[13«m?»~`	F3
`␛[14«m?»~`	F4
`␛[15«m?»~`	F5
`␛[17«m?»~`	F6	(yes, 16 really is skipped)
`␛[18«m?»~`	F7
`␛[19«m?»~`	F8
`␛[20«m?»~`	F9
`␛[21«m?»~`	F10
`␛[23«m?»~`	F11	(yes, 22 really is skipped)
`␛[24«m?»~`	F12
`␛[200«m?»~`	Begin Paste	Only emitted when bracketed paste mode is activated
`␛[201«m?»~`	End Paste	Ditto

«m» is a modifier sequence:

Sequence	Shift	Alt	Ctrl
`;2`	✓
`;3`		✓
`;4`	✓	✓
`;5`			✓
`;6`	✓		✓
`;7`		✓	✓
`;8`	✓	✓	✓

and «m?» is an optional modifier sequence.

In environments with keys F13 through F24, they are mapped to F1 through F12 with the shift modifier.

As special cases, Delete, Insert, Home, End, Page Up and Down, and F1 and F12 with the Ctrl-Alt or Ctrl-Alt-Shift modifiers are reserved and not passed on to the application.

Input Modes

The following options are added to the options for Basic Text:

Name	Type	Applicability
Immediate mode	Boolean	Input
Hidden mode	Boolean	Input

In Immediate input mode, each keypress is treated as if it were followed by U+A and immediately sent to the application without the extra U+A. And as a special case, U+C (FF) is not replaced in immediate mode.

Hidden mode

In Hidden input mode, terminal implementations should not echo input characters back to the terminal.