Kitty Graphics Protocol in OCaml
anil.recoil.org
terminal
graphics
ocaml
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Response Suppression Level
7
8 Controls which terminal responses are sent back to the application.
9
10 {2 Protocol Details}
11
12 The quiet level is specified via the [q] key in the control data:
13 - [q=0] or no [q] key: send all responses (default)
14 - [q=1]: suppress OK responses, only send errors
15 - [q=2]: suppress all responses
16
17 {2 Terminal Responses}
18
19 Normally, when an [image_id] is specified, the terminal responds:
20 - On success: [ESC _Gi=ID;OK ESC]
21 - On failure: [ESC _Gi=ID;ECODE:message ESC]
22
23 Response processing requires reading from the terminal, which can be complex
24 in some applications.
25
26 {2 Use Cases}
27
28 [{`Noisy}] (default): Use when you need to verify operations succeeded or
29 want to handle errors programmatically.
30
31 [{`Errors_only}]: Use when you want to detect failures but don't need
32 confirmation of success. Reduces response traffic.
33
34 [{`Silent}]: Use in fire-and-forget scenarios like shell scripts or when the
35 application cannot easily read terminal responses. Also useful for
36 high-frequency animation updates where response processing would add
37 latency. *)
38
39type t = [ `Noisy | `Errors_only | `Silent ]
40(** Response suppression levels.
41
42 - [`Noisy] - Send all responses including OK confirmations (default).
43 Required for detecting success and getting assigned image IDs.
44 - [`Errors_only] - Suppress OK responses, only send error messages. Useful
45 when success is expected but errors should be caught.
46 - [`Silent] - Suppress all responses including errors. Useful for shell
47 scripts or when response handling is not possible. *)
48
49val to_int : t -> int
50(** Convert to protocol integer.
51
52 Returns 0 for [`Noisy], 1 for [`Errors_only], or 2 for [`Silent]. These
53 values are used in the [q=] control data key. *)