My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** OCaml implementation of the Kitty text sizing protocol.
2
3 This library provides a clean API for generating escape sequences to render
4 text in different sizes within terminals that support the Kitty text sizing
5 protocol (introduced in kitty v0.40.0).
6
7 The protocol allows rendering text at multiple sizes both larger and smaller
8 than the base text, enabling typographic features like headlines, superscripts,
9 and subscripts.
10*)
11
12(** {1 Types} *)
13
14(** Vertical alignment for fractionally scaled text. *)
15type vertical = [ `Bottom | `Center | `Top ]
16
17(** Horizontal alignment for fractionally scaled text. *)
18type horizontal = [ `Left | `Center | `Right ]
19
20(** Abstract metadata for text sizing. *)
21type t
22
23(** {1 Constructor} *)
24
25(** [v ?scale ?width ?fraction ?vertical ?horizontal ()] creates text sizing metadata.
26
27 @param scale Scale factor (1-7)
28 @param width Width in cells (0-7)
29 @param fraction Fractional scaling as (numerator, denominator) where both are 0-15
30 @param vertical Vertical alignment
31 @param horizontal Horizontal alignment
32 @raise Invalid_argument if any parameter is out of range *)
33val v :
34 ?scale:int ->
35 ?width:int ->
36 ?fraction:(int * int) ->
37 ?vertical:vertical ->
38 ?horizontal:horizontal ->
39 unit -> t
40
41(** Empty metadata (all fields set to [None]). Equivalent to [v ()]. *)
42val empty : t
43
44(** {1 Escape Sequence Generation} *)
45
46(** [render t text] generates the complete escape sequence for sized text.
47
48 @param t The sizing metadata
49 @param text The text to render (max 4096 bytes of UTF-8)
50 @return The escape sequence string
51 @raise Invalid_argument if text exceeds 4096 bytes *)
52val render : t -> string -> string
53
54(** [render_to_channel oc t text] writes the escape sequence to a channel.
55
56 @param oc Output channel
57 @param t The sizing metadata
58 @param text The text to render (max 4096 bytes of UTF-8)
59 @raise Invalid_argument if text exceeds 4096 bytes *)
60val render_to_channel : out_channel -> t -> string -> unit
61
62(** {1 Fmt-style Combinators} *)
63
64(** [pp t] creates a Fmt formatter that wraps text with sizing metadata.
65
66 Example:
67 {[
68 Fmt.pr "This is %a" (Textsize.pp (Textsize.with_scale 2 Textsize.empty)) "big"
69 ]}
70*)
71val pp : t -> string Fmt.t
72
73(** [styled t pp_inner] wraps any formatter with sizing metadata.
74
75 Example:
76 {[
77 Fmt.pr "Value: %a" (Textsize.styled (Textsize.with_scale 3 Textsize.empty) Fmt.int) 42
78 ]}
79*)
80val styled : t -> 'a Fmt.t -> 'a Fmt.t
81
82(** Fmt formatter for double-sized text. *)
83val pp_double : string Fmt.t
84
85(** Fmt formatter for triple-sized text. *)
86val pp_triple : string Fmt.t
87
88(** Fmt formatter for quadruple-sized text. *)
89val pp_quadruple : string Fmt.t
90
91(** Fmt formatter for half-sized text. *)
92val pp_half : string Fmt.t
93
94(** Fmt formatter for superscript text. *)
95val pp_superscript : string Fmt.t
96
97(** Fmt formatter for subscript text. *)
98val pp_subscript : string Fmt.t
99
100(** [pp_scaled n] creates a Fmt formatter for text at scale [n].
101 @raise Invalid_argument if [n] is not in range 1-7. *)
102val pp_scaled : int -> string Fmt.t
103
104(** [styled_double pp_inner] wraps any formatter with double sizing. *)
105val styled_double : 'a Fmt.t -> 'a Fmt.t
106
107(** [styled_triple pp_inner] wraps any formatter with triple sizing. *)
108val styled_triple : 'a Fmt.t -> 'a Fmt.t
109
110(** [styled_superscript pp_inner] wraps any formatter with superscript styling. *)
111val styled_superscript : 'a Fmt.t -> 'a Fmt.t
112
113(** [styled_subscript pp_inner] wraps any formatter with subscript styling. *)
114val styled_subscript : 'a Fmt.t -> 'a Fmt.t
115
116(** {1 Convenience Functions} *)
117
118(** [double text] renders text at double size (scale=2). *)
119val double : string -> string
120
121(** [triple text] renders text at triple size (scale=3). *)
122val triple : string -> string
123
124(** [quadruple text] renders text at quadruple size (scale=4). *)
125val quadruple : string -> string
126
127(** [half text] renders text at half size (n=1, d=2). *)
128val half : string -> string
129
130(** [superscript text] renders text as superscript (n=1, d=2, v=Top). *)
131val superscript : string -> string
132
133(** [subscript text] renders text as subscript (n=1, d=2, v=Bottom). *)
134val subscript : string -> string
135
136(** [scaled n text] renders text at scale [n] (1-7).
137 @raise Invalid_argument if [n] is not in range 1-7. *)
138val scaled : int -> string -> string