matercan/beer
1
0
Fork 0
forked from NotAShelf/beer
Code Pull requests 1 Activity

beer-protocols: format docs

Browse source 
Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I8870fc54503c7ec033152e23b50df3ff6a6a6964
This commit is contained in:
raf 2026-06-26 17:16:45 +03:00
commit ea3867e8d0
No known key found for this signature in database
GPG key ID: 29D95B64378DB4BF
1 changed files with 142 additions and 121 deletions
Download patch file Download diff file Expand all files Collapse all files

91
crates/beer-protocols/README.md
View file

@ -2,22 +2,23 @@
The terminal-protocol building blocks beer is built on: byte codecs, the The terminal-protocol building blocks beer is built on: byte codecs, the
terminfo capability table, character-set translation, SGR parsing, and the terminfo capability table, character-set translation, SGR parsing, and the
keyboard/mouse wire encoders. Everything here is a pure function or a plain keyboard/mouse wire encoders. Everything here is a pure function or a plain data
data type, with no terminal state, so each protocol detail can be read and type, with no terminal state, so each protocol detail can be read and tested on
tested on its own. beer feeds these into its `vte`-driven dispatcher and its its own. beer feeds these into its `vte`-driven dispatcher and its grid model.
grid model.
This README doubles as the reference for **which escape sequences, OSC This README doubles as the reference for **which escape sequences, OSC commands,
commands, and POSIX behaviours beer actually implements** - the parts a user and POSIX behaviours beer actually implements** - the parts a user notices.
notices. Sequences not listed here are parsed and ignored rather than passed Sequences not listed here are parsed and ignored rather than passed through.
through. Notation: `ESC` is `0x1b`, `CSI` is `ESC [`, `OSC` is `ESC ]`, `DCS` Notation: `ESC` is `0x1b`, `CSI` is `ESC [`, `OSC` is `ESC ]`, `DCS` is `ESC P`,
is `ESC P`, `ST` is the string terminator `ESC \` (a `BEL` is also accepted to `ST` is the string terminator `ESC \` (a `BEL` is also accepted to end an OSC).
end an OSC). `Ps` is a numeric parameter, `Pt` a text parameter. `Ps` is a numeric parameter, `Pt` a text parameter.
## Crate layout ## Crate layout
<!--markdownlint-disable MD013-->
| Module | What it covers | | Module | What it covers |
| --- | --- | | --------- | ------------------------------------------------------------------------------ |
| `codec` | base64 (OSC 52), hex (XTGETTCAP names), `file://` URI percent-decoding (OSC 7) | | `codec` | base64 (OSC 52), hex (XTGETTCAP names), `file://` URI percent-decoding (OSC 7) |
| `caps` | terminfo capabilities answered over XTGETTCAP | | `caps` | terminfo capabilities answered over XTGETTCAP |
| `charset` | G0/G1 designation and DEC special-graphics line drawing | | `charset` | G0/G1 designation and DEC special-graphics line drawing |
@ -26,12 +27,14 @@ end an OSC). `Ps` is a numeric parameter, `Pt` a text parameter.
| `mouse` | X10 / UTF-8 / SGR mouse-report encoding | | `mouse` | X10 / UTF-8 / SGR mouse-report encoding |
| `style` | the enums an SGR/DECSET stream selects | | `style` | the enums an SGR/DECSET stream selects |
--- <!--markdownlint-enable MD013-->
## C0 control characters ## C0 control characters
<!--markdownlint-disable MD013-->
| Byte | Name | Effect | | Byte | Name | Effect |
| --- | --- | --- | | ------------- | -------- | ------------------------------------------------------------- |
| `0x07` | BEL | rings the bell (visual flash / command / urgency, per config) | | `0x07` | BEL | rings the bell (visual flash / command / urgency, per config) |
| `0x08` | BS | backspace | | `0x08` | BS | backspace |
| `0x09` | HT | tab to next stop | | `0x09` | HT | tab to next stop |
@ -40,10 +43,14 @@ end an OSC). `Ps` is a numeric parameter, `Pt` a text parameter.
| `0x0E` | SO | invoke G1 (shift out) | | `0x0E` | SO | invoke G1 (shift out) |
| `0x0F` | SI | invoke G0 (shift in) | | `0x0F` | SI | invoke G0 (shift in) |
<!--markdownlint-enable MD013-->
## Cursor movement and editing (CSI) ## Cursor movement and editing (CSI)
<!--markdownlint-disable MD013-->
| Sequence | Name | Effect | | Sequence | Name | Effect |
| --- | --- | --- | | ------------------------ | ----------- | ------------------------------------------ |
| `CSI Ps A` | CUU | cursor up | | `CSI Ps A` | CUU | cursor up |
| `CSI Ps B` / `CSI Ps e` | CUD | cursor down | | `CSI Ps B` / `CSI Ps e` | CUD | cursor down |
| `CSI Ps C` / `CSI Ps a` | CUF | cursor forward | | `CSI Ps C` / `CSI Ps a` | CUF | cursor forward |
@ -66,10 +73,14 @@ end an OSC). `Ps` is a numeric parameter, `Pt` a text parameter.
| `CSI Ps g` | TBC | clear tab stop (0) or all tabs (3) | | `CSI Ps g` | TBC | clear tab stop (0) or all tabs (3) |
| `CSI s` / `CSI u` | SCOSC/SCORC | save / restore cursor | | `CSI s` / `CSI u` | SCOSC/SCORC | save / restore cursor |
<!--markdownlint-enable MD013-->
## ESC (non-CSI) ## ESC (non-CSI)
<!--markdownlint-disable MD013-->
| Sequence | Name | Effect | | Sequence | Name | Effect |
| --- | --- | --- | | --------------------- | ----------- | ------------------------------------------------------------------- |
| `ESC D` | IND | line feed | | `ESC D` | IND | line feed |
| `ESC M` | RI | reverse index | | `ESC M` | RI | reverse index |
| `ESC E` | NEL | next line | | `ESC E` | NEL | next line |
@ -78,6 +89,8 @@ end an OSC). `Ps` is a numeric parameter, `Pt` a text parameter.
| `ESC c` | RIS | full reset | | `ESC c` | RIS | full reset |
| `ESC ( c` / `ESC ) c` | SCS | designate G0 / G1 charset (`0` = DEC special graphics, `B` = ASCII) | | `ESC ( c` / `ESC ) c` | SCS | designate G0 / G1 charset (`0` = DEC special graphics, `B` = ASCII) |
<!--markdownlint-enable MD013-->
## Graphic rendition (SGR, `CSI Ps m`) ## Graphic rendition (SGR, `CSI Ps m`)
Bold (1), dim (2), italic (3), underline (4), blink (5/6), reverse (7), hidden Bold (1), dim (2), italic (3), underline (4), blink (5/6), reverse (7), hidden
@ -85,16 +98,15 @@ Bold (1), dim (2), italic (3), underline (4), blink (5/6), reverse (7), hidden
Underline styles via `4:x` and SGR 21: single, double, curly, dotted, dashed. Underline styles via `4:x` and SGR 21: single, double, curly, dotted, dashed.
Colours: the 16 ANSI colours (30-37, 90-97 foreground; 40-47, 100-107 Colours: the 16 ANSI colours (30-37, 90-97 foreground; 40-47, 100-107
background) and default (39/49). Extended colour for foreground (38), background) and default (39/49). Extended colour for foreground (38), background
background (48), and underline (58/59), in both the legacy semicolon form (48), and underline (58/59), in both the legacy semicolon form (`38;5;n`,
(`38;5;n`, `38;2;r;g;b`) and the colon-subparameter form (`38:5:n`, `38;2;r;g;b`) and the colon-subparameter form (`38:5:n`, `38:2:r:g:b`, with an
`38:2:r:g:b`, with an ignored colour-space id). 256-colour and 24-bit truecolor ignored colour-space id). 256-colour and 24-bit truecolor are fully supported.
are fully supported.
## Modes (DECSET/DECRST `CSI [?] Ps h` / `l`) ## Modes (DECSET/DECRST `CSI [?] Ps h` / `l`)
| Mode | Name | Effect | | Mode | Name | Effect |
| --- | --- | --- | | --------------- | ------- | -------------------------------------- |
| `4` (ANSI) | IRM | insert/replace | | `4` (ANSI) | IRM | insert/replace |
| `?1` | DECCKM | application cursor keys | | `?1` | DECCKM | application cursor keys |
| `?6` | DECOM | origin mode | | `?6` | DECOM | origin mode |
@ -123,8 +135,10 @@ until an application overrides it.
## Device reports ## Device reports
<!--markdownlint-disable MD013-->
| Sequence | Name | Reply | | Sequence | Name | Reply |
| --- | --- | --- | | -------------------- | --------- | ---------------------------------------------------------- |
| `CSI c` | DA1 | `CSI ?62;22c` (VT220 + ANSI colour) | | `CSI c` | DA1 | `CSI ?62;22c` (VT220 + ANSI colour) |
| `CSI > c` | DA2 | `CSI >0;276;0c` | | `CSI > c` | DA2 | `CSI >0;276;0c` |
| `CSI = c` | DA3 | `DCS !\|00000000 ST` | | `CSI = c` | DA3 | `DCS !\|00000000 ST` |
@ -133,6 +147,8 @@ until an application overrides it.
| `CSI > q` | XTVERSION | `DCS >\|beer(version) ST` | | `CSI > q` | XTVERSION | `DCS >\|beer(version) ST` |
| `DCS + q <names> ST` | XTGETTCAP | per name, `DCS 1 + r name=value ST` or `DCS 0 + r name ST` | | `DCS + q <names> ST` | XTGETTCAP | per name, `DCS 1 + r name=value ST` or `DCS 0 + r name ST` |
<!--markdownlint-enable MD013-->
XTGETTCAP answers `TN` (terminal name `beer`), `Co`/`colors` (256), and `RGB` XTGETTCAP answers `TN` (terminal name `beer`), `Co`/`colors` (256), and `RGB`
(`8/8/8`, i.e. truecolor). (`8/8/8`, i.e. truecolor).
@ -143,8 +159,10 @@ XTGETTCAP answers `TN` (terminal name `beer`), `Co`/`colors` (256), and `RGB`
## OSC commands ## OSC commands
<!--markdownlint-disable MD013-->
| Command | Effect | | Command | Effect |
| --- | --- | | --------------------------------- | ------------------------------------------------ |
| `OSC 0` / `OSC 2` | set window title | | `OSC 0` / `OSC 2` | set window title |
| `OSC 4 ; idx ; spec` | set / query palette entry (`?` queries) | | `OSC 4 ; idx ; spec` | set / query palette entry (`?` queries) |
| `OSC 104 [; idx ...]` | reset palette (all, or listed entries) | | `OSC 104 [; idx ...]` | reset palette (all, or listed entries) |
@ -160,6 +178,8 @@ XTGETTCAP answers `TN` (terminal name `beer`), `Co`/`colors` (256), and `RGB`
| `OSC 52 ; target ; data` | clipboard set (base64) or query (`?`) | | `OSC 52 ; target ; data` | clipboard set (base64) or query (`?`) |
| `OSC 133 ; A/B/C/D` | shell-integration prompt marks | | `OSC 133 ; A/B/C/D` | shell-integration prompt marks |
<!--markdownlint-enable MD013-->
Colour specs follow the X11 forms `#rrggbb` and `rgb:rr/gg/bb` (1-4 hex digits Colour specs follow the X11 forms `#rrggbb` and `rgb:rr/gg/bb` (1-4 hex digits
per channel). Colour queries reply in the `rgb:rrrr/gggg/bbbb` form. per channel). Colour queries reply in the `rgb:rrrr/gggg/bbbb` form.
@ -179,26 +199,27 @@ tracks the working directory so a new window opens in the same place.
## Keyboard ## Keyboard
The legacy xterm/VT encoding covers cursor keys (with DECCKM application mode), The legacy xterm/VT encoding covers cursor keys (with DECCKM application mode),
the editing keypad (Insert/Delete/PageUp/PageDown), F1-F12, and the the editing keypad (Insert/Delete/PageUp/PageDown), F1-F12, and the xterm
xterm modifier parameter (`CSI 1 ; m <letter>`), with Alt sending an ESC modifier parameter (`CSI 1 ; m <letter>`), with Alt sending an ESC (meta)
(meta) prefix. prefix.
The **kitty keyboard protocol** (`CSI > flags u` push, `CSI < flags u` pop, The **kitty keyboard protocol** (`CSI > flags u` push, `CSI < flags u` pop,
`CSI = flags ; mode u` set, `CSI ? u` query) is implemented with the `CSI = flags ; mode u` set, `CSI ? u` query) is implemented with the
disambiguate, report-event-types, report-alternate-keys, report-all-keys, and disambiguate, report-event-types, report-alternate-keys, report-all-keys, and
report-associated-text enhancement flags. Keys are encoded as `CSI report-associated-text enhancement flags. Keys are encoded as
code[:shifted] ; mod[:event] [; text] u`, with a 32-deep push/pop stack. The `CSI
common keys (Enter, Tab, Backspace) keep their legacy bytes when unmodified so code[:shifted] ; mod[:event] [; text] u`, with a 32-deep push/pop stack.
a plain shell stays usable. The common keys (Enter, Tab, Backspace) keep their legacy bytes when unmodified
so a plain shell stays usable.
## Mouse ## Mouse
Reports are framed in the legacy byte form (`CSI M Cb Cx Cy`), the UTF-8 Reports are framed in the legacy byte form (`CSI M Cb Cx Cy`), the UTF-8
coordinate form (DECSET 1005), or the SGR form (`CSI < Cb ; Cx ; Cy M/m`, coordinate form (DECSET 1005), or the SGR form (`CSI < Cb ; Cx ; Cy M/m`, DECSET
DECSET 1006). Shift/Alt/Ctrl modifier bits and the motion bit are encoded; 1006). Shift/Alt/Ctrl modifier bits and the motion bit are encoded; legacy
legacy releases collapse to button code 3. Reporting level is chosen by the releases collapse to button code 3. Reporting level is chosen by the application
application via the mouse modes above; with reporting off the pointer drives via the mouse modes above; with reporting off the pointer drives local selection
local selection and scrollback. and scrollback.
## POSIX / terminal behaviour ## POSIX / terminal behaviour