turbo-editors/turbo-python · terminal.md

turbo-editors/turbo-pythonpublic⑂ Fork 0

⑂ v1.0.0

terminal.md · 228 lines · 8.1 KBmarkdown    Blame HistoryRaw
📦 Turbo Python   1# Reference: terminal windows
3> Neutral description of the terminal windows Turbo Python opens, the keys they answer to, and the escape sequences the emulator implements.
5
Route | Condition |
--- | --- |
`F8` | Always |
**Window ▸ New terminal** | Always |
12Neither requires a file to be open.
14## The shell
Property | Value |
--- | --- |
Program | `$SHELL`, or `/bin/sh` when it is unset or empty; on Windows `%COMSPEC%`, or `cmd.exe` |
Working directory | The directory of the file in the front window; the editor's working directory when no file is open |
`TERM` | `xterm-256color`, always — replacing any inherited value |
Environment | The editor's own, with `TERM` replaced |
Controlling terminal | Yes: on Linux and macOS the shell runs in its own session with the pseudo-terminal as its controlling terminal; on Windows it is attached to a pseudo-console. Either way job control and `Ctrl-C` work |
Initial size | The window's, updated whenever the window is resized |
25## Platform support
Platform | Behaviour |
--- | --- |
Linux | Supported (`/dev/ptmx`) |
macOS | Supported (`/dev/ptmx`) |
Windows | Supported (pseudo-console, ConPTY): Windows 10 version 1809 or later. Built and vetted; **not yet run by the authors** on a Windows machine |
Others | `F8` opens a message saying terminal windows are not supported yet; nothing else changes |
36### After the program has gone
38A window whose command has finished keeps its output, but stops behaving like a terminal: only `Shift-PgUp` and `Shift-PgDn` are still taken, and every other key reaches the editor — which is what lets `Ctrl-W` close it.
40### Sent to the shell
42Every key not listed under "kept by the editor" below, encoded as a terminal expects it.
Key | Bytes sent |
--- | --- |
printable character | its UTF-8 encoding |
`Alt-<key>` | `ESC` followed by that key's own bytes |
`Ctrl-A` … `Ctrl-Z` | `0x01` … `0x1a` |
`Enter` | `\r` |
`Tab` | `\t` |
`Shift-Tab` | `ESC [ Z` |
`Backspace` | `0x7f` |
`Escape` | `0x1b` |
`↑` `↓` `→` `←` | `ESC [ A B C D`, or `ESC O A B C D` in application cursor mode |
`Home` `End` | `ESC [ H`, `ESC [ F`, or the `ESC O` forms in application cursor mode |
`Insert` `Delete` | `ESC [ 2~`, `ESC [ 3~` |
`PgUp` `PgDn` | `ESC [ 5~`, `ESC [ 6~` |
`F1` … `F4` | `ESC O P Q R S` |
`F5` … `F12` | `ESC [ 15~ 17~ 18~ 19~ 20~ 21~ 23~ 24~` |
61A key with no terminal meaning sends nothing.
63### Kept by the editor
Key | Action |
--- | --- |
`F1` … `F12` | Their usual editor action |
`Alt-X` | Exit |
`Alt-0` … `Alt-9` | List windows / bring window 1…9 forward |
71Function keys therefore never reach a program inside a terminal window.
73### Handled by the terminal window itself
Key | Action |
--- | --- |
`Shift-PgUp` | Back one screenful through the history |
`Shift-PgDn` | Forward one screenful |
80Any key sent to the shell also returns the view to the live screen.
Action | Effect |
--- | --- |
Wheel up / down | Scroll three lines through the history |
Click | Brings the window forward; not forwarded to the program |
89Mouse reporting is not implemented, so a program is never told about clicks.
91
Property | Value |
--- | --- |
Lines kept | 2000 |
What is kept | Lines scrolled off the top of the primary screen only |
Alternate screen | Not kept — a full-screen program leaves no history behind |
99## Emulation
101`TERM` is `xterm-256color`. What is implemented of it:
103### Control characters
Byte | Effect |
--- | --- |
`0x07` BEL | Noted; the editor does not sound it |
`0x08` BS | Cursor left one column |
`0x09` HT | To the next tab stop, every 8 columns |
`0x0a` `0x0b` `0x0c` | Line feed |
`0x0d` CR | To column 1 |
113### Escape sequences
Sequence | Name | Effect |
--- | --- | --- |
`ESC D` | IND | Line feed |
`ESC E` | NEL | Carriage return and line feed |
`ESC M` | RI | Reverse line feed, keeping the column |
`ESC 7` | DECSC | Save cursor and style |
`ESC 8` | DECRC | Restore cursor and style |
`ESC c` | RIS | Full reset |
124### CSI sequences
Sequence | Name | Effect |
--- | --- | --- |
`CSI n A B C D` | CUU CUD CUF CUB | Move n cells up, down, right, left |
`CSI n E F` | CNL CPL | n lines down / up, to column 1 |
`CSI n G` | CHA | To column n |
`CSI r ; c H`, `CSI r ; c f` | CUP HVP | To row r, column c |
`CSI n d` | VPA | To row n |
`CSI n J` | ED | Erase display: 0 to end, 1 to start, 2 or 3 all |
`CSI n K` | EL | Erase line: 0 to end, 1 to start, 2 all |
`CSI n L` | IL | Insert n blank lines at the cursor |
`CSI n M` | DL | Delete n lines at the cursor |
`CSI n @` | ICH | Insert n blank cells |
`CSI n P` | DCH | Delete n cells |
`CSI n X` | ECH | Erase n cells in place |
`CSI n S` | SU | Scroll the region up n lines |
`CSI n T` | SD | Scroll the region down n lines |
`CSI t ; b r` | DECSTBM | Set the scroll region to rows t…b |
`CSI s`, `CSI u` | SCP RCP | Save / restore the cursor |
`CSI … m` | SGR | Colours and attributes, below |
146`IL` and `DL` do nothing when the cursor is outside the scroll region.
148### Private modes
150Set with `CSI ? n h`, cleared with `CSI ? n l`.
n | Name | Effect |
--- | --- | --- |
1 | DECCKM | Application cursor keys: arrows send `ESC O x` |
7 | DECAWM | Auto-wrap at the right margin |
25 | DECTCEM | Show the cursor |
47, 1047 | | Alternate screen |
1048 | | Save / restore the cursor |
1049 | | Save the cursor, then the alternate screen |
161Any other mode is parsed and ignored.
Code | Effect |
--- | --- |
0 | Reset |
1, 22 | Bold on / off |
2, 22 | Dim on / off |
3, 23 | Italic on / off |
4, 24 | Underline on / off |
5, 6, 25 | Blink on / off |
7, 27 | Reverse on / off |
9, 29 | Strike-through on / off |
30–37, 40–47 | The eight normal colours, foreground / background |
90–97, 100–107 | The eight bright colours, foreground / background |
38;5;n, 48;5;n | Palette colour n of 256 |
38;2;r;g;b, 48;2;r;g;b | 24-bit colour |
39, 49 | Back to the theme's colour |
181The sixteen named colours are tcell's, which means the palette the user's own terminal is configured with, not fixed hex values. An extended colour that runs out of parameters partway leaves the style unchanged. Any other code is ignored.
Sequence | Effect |
--- | --- |
`OSC 0 ; text BEL`, `OSC 2 ; text BEL` | Set the window title |
`OSC … ST` | The `ESC \` terminator is accepted in place of BEL |
190The title is capped at 4096 bytes. Other OSC commands are parsed and ignored.
192### Consumed and ignored
194Parsed correctly, so they never appear as stray characters, but with no effect:
Sequence | Name |
--- | --- |
`ESC P …`, `ESC X …`, `ESC ^ …`, `ESC _ …` | DCS, SOS, PM, APC — read to their string terminator |
`ESC (`, `ESC )`, `ESC *`, `ESC +`, `ESC %`, `ESC #`, `ESC <space>` | Character-set and line-size selectors — the emulator works in UTF-8 regardless |
`CSI ? n h`, `CSI ? n l` for any other n | Private modes not listed above |
Any other CSI final byte, SGR code, or OSC command | |
203### Not implemented
205Mouse reporting, bracketed paste, shift-in / shift-out, double-width lines, sixel and other graphics protocols, and the DEC status and device-attribute reports. A program that asks for one of these gets no reply, so a program that waits for one waits forever.
207
Theme key | What it colours |
--- | --- |
`terminal.text` | Every cell whose colour the program did not choose |
`terminal.cursor` | The cell under the cursor, when the window has the focus |
214See [Theme file format](themes.md).
216
Message | Cause |
--- | --- |
Terminal windows are not supported on this platform yet | The build has no pseudo-terminal support: any platform other than Linux, macOS and Windows |
`openpt: …`, `grantpt: …`, `ptsname: …` | The operating system refused to open a pseudo-terminal |
`fork/exec …: no such file or directory` | `$SHELL` names a program that does not exist |
224## See also
226- [How to run shell commands without leaving the editor](../how-to/use-a-terminal.md)
227- [Terminal windows](../explanation/terminal-windows.md)
228- [Keyboard](keyboard.md)

📦 Turbo Python 6fc62ea k33g 10h ago	1	# Reference: terminal windows
	2
	3	> Neutral description of the terminal windows Turbo Python opens, the keys they answer to, and the escape sequences the emulator implements.
	4
	5	## Opening
	6
	7	\| Route \| Condition \|
	8	\| --- \| --- \|
	9	\| `F8` \| Always \|
	10	\| Window ▸ New terminal \| Always \|
	11
	12	Neither requires a file to be open.
	13
	14	## The shell
	15
	16	\| Property \| Value \|
	17	\| --- \| --- \|
	18	\| Program \| `$SHELL`, or `/bin/sh` when it is unset or empty; on Windows `%COMSPEC%`, or `cmd.exe` \|
	19	\| Working directory \| The directory of the file in the front window; the editor's working directory when no file is open \|
	20	\| `TERM` \| `xterm-256color`, always — replacing any inherited value \|
	21	\| Environment \| The editor's own, with `TERM` replaced \|
	22	\| Controlling terminal \| Yes: on Linux and macOS the shell runs in its own session with the pseudo-terminal as its controlling terminal; on Windows it is attached to a pseudo-console. Either way job control and `Ctrl-C` work \|
	23	\| Initial size \| The window's, updated whenever the window is resized \|
	24
	25	## Platform support
	26
	27	\| Platform \| Behaviour \|
	28	\| --- \| --- \|
	29	\| Linux \| Supported (`/dev/ptmx`) \|
	30	\| macOS \| Supported (`/dev/ptmx`) \|
	31	\| Windows \| Supported (pseudo-console, ConPTY): Windows 10 version 1809 or later. Built and vetted; not yet run by the authors on a Windows machine \|
	32	\| Others \| `F8` opens a message saying terminal windows are not supported yet; nothing else changes \|
	33
	34	## Keys
	35
	36	### After the program has gone
	37
	38	A window whose command has finished keeps its output, but stops behaving like a terminal: only `Shift-PgUp` and `Shift-PgDn` are still taken, and every other key reaches the editor — which is what lets `Ctrl-W` close it.
	39
	40	### Sent to the shell
	41
	42	Every key not listed under "kept by the editor" below, encoded as a terminal expects it.
	43
	44	\| Key \| Bytes sent \|
	45	\| --- \| --- \|
	46	\| printable character \| its UTF-8 encoding \|
	47	\| `Alt-<key>` \| `ESC` followed by that key's own bytes \|
	48	\| `Ctrl-A` … `Ctrl-Z` \| `0x01` … `0x1a` \|
	49	\| `Enter` \| `\r` \|
	50	\| `Tab` \| `\t` \|
	51	\| `Shift-Tab` \| `ESC [ Z` \|
	52	\| `Backspace` \| `0x7f` \|
	53	\| `Escape` \| `0x1b` \|
	54	\| `↑` `↓` `→` `←` \| `ESC [ A B C D`, or `ESC O A B C D` in application cursor mode \|
	55	\| `Home` `End` \| `ESC [ H`, `ESC [ F`, or the `ESC O` forms in application cursor mode \|
	56	\| `Insert` `Delete` \| `ESC [ 2~`, `ESC [ 3~` \|
	57	\| `PgUp` `PgDn` \| `ESC [ 5~`, `ESC [ 6~` \|
	58	\| `F1` … `F4` \| `ESC O P Q R S` \|
	59	\| `F5` … `F12` \| `ESC [ 15~ 17~ 18~ 19~ 20~ 21~ 23~ 24~` \|
	60
	61	A key with no terminal meaning sends nothing.
	62
	63	### Kept by the editor
	64
65	\| Key \| Action \|
66	\| --- \| --- \|
67	\| `F1` … `F12` \| Their usual editor action \|
68	\| `Alt-X` \| Exit \|
69	\| `Alt-0` … `Alt-9` \| List windows / bring window 1…9 forward \|
70
71	Function keys therefore never reach a program inside a terminal window.
72
73	### Handled by the terminal window itself
74
75	\| Key \| Action \|
76	\| --- \| --- \|
77	\| `Shift-PgUp` \| Back one screenful through the history \|
78	\| `Shift-PgDn` \| Forward one screenful \|
79
80	Any key sent to the shell also returns the view to the live screen.
81
82	## Mouse
83
84	\| Action \| Effect \|
85	\| --- \| --- \|
86	\| Wheel up / down \| Scroll three lines through the history \|
87	\| Click \| Brings the window forward; not forwarded to the program \|
88
89	Mouse reporting is not implemented, so a program is never told about clicks.
90
91	## History
92
93	\| Property \| Value \|
94	\| --- \| --- \|
95	\| Lines kept \| 2000 \|
96	\| What is kept \| Lines scrolled off the top of the primary screen only \|
97	\| Alternate screen \| Not kept — a full-screen program leaves no history behind \|
98
99	## Emulation
100
101	`TERM` is `xterm-256color`. What is implemented of it:
102
103	### Control characters
104
105	\| Byte \| Effect \|
106	\| --- \| --- \|
107	\| `0x07` BEL \| Noted; the editor does not sound it \|
108	\| `0x08` BS \| Cursor left one column \|
109	\| `0x09` HT \| To the next tab stop, every 8 columns \|
110	\| `0x0a` `0x0b` `0x0c` \| Line feed \|
111	\| `0x0d` CR \| To column 1 \|
112
113	### Escape sequences
114
115	\| Sequence \| Name \| Effect \|
116	\| --- \| --- \| --- \|
117	\| `ESC D` \| IND \| Line feed \|
118	\| `ESC E` \| NEL \| Carriage return and line feed \|
119	\| `ESC M` \| RI \| Reverse line feed, keeping the column \|
120	\| `ESC 7` \| DECSC \| Save cursor and style \|
121	\| `ESC 8` \| DECRC \| Restore cursor and style \|
122	\| `ESC c` \| RIS \| Full reset \|
123
124	### CSI sequences
125
126	\| Sequence \| Name \| Effect \|
127	\| --- \| --- \| --- \|
128	\| `CSI n A B C D` \| CUU CUD CUF CUB \| Move n cells up, down, right, left \|
129	\| `CSI n E F` \| CNL CPL \| n lines down / up, to column 1 \|
130	\| `CSI n G` \| CHA \| To column n \|
131	\| `CSI r ; c H`, `CSI r ; c f` \| CUP HVP \| To row r, column c \|
132	\| `CSI n d` \| VPA \| To row n \|
133	\| `CSI n J` \| ED \| Erase display: 0 to end, 1 to start, 2 or 3 all \|
134	\| `CSI n K` \| EL \| Erase line: 0 to end, 1 to start, 2 all \|
135	\| `CSI n L` \| IL \| Insert n blank lines at the cursor \|
136	\| `CSI n M` \| DL \| Delete n lines at the cursor \|
137	\| `CSI n @` \| ICH \| Insert n blank cells \|
138	\| `CSI n P` \| DCH \| Delete n cells \|
139	\| `CSI n X` \| ECH \| Erase n cells in place \|
140	\| `CSI n S` \| SU \| Scroll the region up n lines \|
141	\| `CSI n T` \| SD \| Scroll the region down n lines \|
142	\| `CSI t ; b r` \| DECSTBM \| Set the scroll region to rows t…b \|
143	\| `CSI s`, `CSI u` \| SCP RCP \| Save / restore the cursor \|
144	\| `CSI … m` \| SGR \| Colours and attributes, below \|
145
146	`IL` and `DL` do nothing when the cursor is outside the scroll region.
147
148	### Private modes
149
150	Set with `CSI ? n h`, cleared with `CSI ? n l`.
151
152	\| n \| Name \| Effect \|
153	\| --- \| --- \| --- \|
154	\| 1 \| DECCKM \| Application cursor keys: arrows send `ESC O x` \|
155	\| 7 \| DECAWM \| Auto-wrap at the right margin \|
156	\| 25 \| DECTCEM \| Show the cursor \|
157	\| 47, 1047 \| \| Alternate screen \|
158	\| 1048 \| \| Save / restore the cursor \|
159	\| 1049 \| \| Save the cursor, then the alternate screen \|
160
161	Any other mode is parsed and ignored.
162
163	### SGR
164
165	\| Code \| Effect \|
166	\| --- \| --- \|
167	\| 0 \| Reset \|
168	\| 1, 22 \| Bold on / off \|
169	\| 2, 22 \| Dim on / off \|
170	\| 3, 23 \| Italic on / off \|
171	\| 4, 24 \| Underline on / off \|
172	\| 5, 6, 25 \| Blink on / off \|
173	\| 7, 27 \| Reverse on / off \|
174	\| 9, 29 \| Strike-through on / off \|
175	\| 30–37, 40–47 \| The eight normal colours, foreground / background \|
176	\| 90–97, 100–107 \| The eight bright colours, foreground / background \|
177	\| 38;5;n, 48;5;n \| Palette colour n of 256 \|
178	\| 38;2;r;g;b, 48;2;r;g;b \| 24-bit colour \|
179	\| 39, 49 \| Back to the theme's colour \|
180
181	The sixteen named colours are tcell's, which means the palette the user's own terminal is configured with, not fixed hex values. An extended colour that runs out of parameters partway leaves the style unchanged. Any other code is ignored.
182
183	### OSC
184
185	\| Sequence \| Effect \|
186	\| --- \| --- \|
187	\| `OSC 0 ; text BEL`, `OSC 2 ; text BEL` \| Set the window title \|
188	\| `OSC … ST` \| The `ESC \` terminator is accepted in place of BEL \|
189
190	The title is capped at 4096 bytes. Other OSC commands are parsed and ignored.
191
192	### Consumed and ignored
193
194	Parsed correctly, so they never appear as stray characters, but with no effect:
195
196	\| Sequence \| Name \|
197	\| --- \| --- \|
198	\| `ESC P …`, `ESC X …`, `ESC ^ …`, `ESC _ …` \| DCS, SOS, PM, APC — read to their string terminator \|
199	\| `ESC (`, `ESC )`, `ESC *`, `ESC +`, `ESC %`, `ESC #`, `ESC <space>` \| Character-set and line-size selectors — the emulator works in UTF-8 regardless \|
200	\| `CSI ? n h`, `CSI ? n l` for any other n \| Private modes not listed above \|
201	\| Any other CSI final byte, SGR code, or OSC command \| \|
202
203	### Not implemented
204
205	Mouse reporting, bracketed paste, shift-in / shift-out, double-width lines, sixel and other graphics protocols, and the DEC status and device-attribute reports. A program that asks for one of these gets no reply, so a program that waits for one waits forever.
206
207	## Colours
208
209	\| Theme key \| What it colours \|
210	\| --- \| --- \|
211	\| `terminal.text` \| Every cell whose colour the program did not choose \|
212	\| `terminal.cursor` \| The cell under the cursor, when the window has the focus \|
213
214	See [Theme file format](themes.md).
215
216	## Errors
217
218	\| Message \| Cause \|
219	\| --- \| --- \|
220	\| Terminal windows are not supported on this platform yet \| The build has no pseudo-terminal support: any platform other than Linux, macOS and Windows \|
221	\| `openpt: …`, `grantpt: …`, `ptsname: …` \| The operating system refused to open a pseudo-terminal \|
222	\| `fork/exec …: no such file or directory` \| `$SHELL` names a program that does not exist \|
223
224	## See also
225
226	- [How to run shell commands without leaving the editor](../how-to/use-a-terminal.md)
227	- [Terminal windows](../explanation/terminal-windows.md)
228	- [Keyboard](keyboard.md)