1/**
2 * @file sgr.h
3 *
4 * SGR (Select Graphic Rendition) attribute parsing and handling.
5 */
6
7#ifndef GHOSTTY_VT_SGR_H
8#define GHOSTTY_VT_SGR_H
9
10/** @defgroup sgr SGR Parser
11 *
12 * SGR (Select Graphic Rendition) attribute parser.
13 *
14 * SGR sequences are the syntax used to set styling attributes such as
15 * bold, italic, underline, and colors for text in terminal emulators.
16 * For example, you may be familiar with sequences like `ESC[1;31m`. The
17 * `1;31` is the SGR attribute list.
18 *
19 * The parser processes SGR parameters from CSI sequences (e.g., `ESC[1;31m`)
20 * and returns individual text attributes like bold, italic, colors, etc.
21 * It supports both semicolon (`;`) and colon (`:`) separators, possibly mixed,
22 * and handles SGR color attributes including 8-color, 16-color, 256-color,
23 * direct RGB, underline color, and reset forms. Color values are returned
24 * using the shared @ref color types; applications that need to parse Ghostty
25 * config/theme color strings, generate palettes, inspect X11 color names, or
26 * calculate luminance and contrast should use the @ref color APIs directly.
27 *
28 * ## Basic Usage
29 *
30 * 1. Create a parser instance with ghostty_sgr_new()
31 * 2. Set SGR parameters with ghostty_sgr_set_params()
32 * 3. Iterate through attributes using ghostty_sgr_next()
33 * 4. Free the parser with ghostty_sgr_free() when done
34 *
35 * ## Example
36 *
37 * @snippet c-vt-sgr/src/main.c sgr-basic
38 *
39 * @{
40 */
41
42#include <ghostty/vt/allocator.h>
43#include <ghostty/vt/color.h>
44#include <ghostty/vt/types.h>
45#include <stdbool.h>
46#include <stddef.h>
47#include <stdint.h>
48
49#ifdef __cplusplus
50extern "C" {
51#endif
52
53/**
54 * SGR attribute tags.
55 *
56 * These values identify the type of an SGR attribute in a tagged union.
57 * Use the tag to determine which field in the attribute value union to access.
58 *
59 * @ingroup sgr
60 */
61typedef enum GHOSTTY_ENUM_TYPED {
62 GHOSTTY_SGR_ATTR_UNSET = 0,
63 GHOSTTY_SGR_ATTR_UNKNOWN = 1,
64 GHOSTTY_SGR_ATTR_BOLD = 2,
65 GHOSTTY_SGR_ATTR_RESET_BOLD = 3,
66 GHOSTTY_SGR_ATTR_ITALIC = 4,
67 GHOSTTY_SGR_ATTR_RESET_ITALIC = 5,
68 GHOSTTY_SGR_ATTR_FAINT = 6,
69 GHOSTTY_SGR_ATTR_UNDERLINE = 7,
70 GHOSTTY_SGR_ATTR_UNDERLINE_COLOR = 8,
71 GHOSTTY_SGR_ATTR_UNDERLINE_COLOR_256 = 9,
72 GHOSTTY_SGR_ATTR_RESET_UNDERLINE_COLOR = 10,
73 GHOSTTY_SGR_ATTR_OVERLINE = 11,
74 GHOSTTY_SGR_ATTR_RESET_OVERLINE = 12,
75 GHOSTTY_SGR_ATTR_BLINK = 13,
76 GHOSTTY_SGR_ATTR_RESET_BLINK = 14,
77 GHOSTTY_SGR_ATTR_INVERSE = 15,
78 GHOSTTY_SGR_ATTR_RESET_INVERSE = 16,
79 GHOSTTY_SGR_ATTR_INVISIBLE = 17,
80 GHOSTTY_SGR_ATTR_RESET_INVISIBLE = 18,
81 GHOSTTY_SGR_ATTR_STRIKETHROUGH = 19,
82 GHOSTTY_SGR_ATTR_RESET_STRIKETHROUGH = 20,
83 GHOSTTY_SGR_ATTR_DIRECT_COLOR_FG = 21,
84 GHOSTTY_SGR_ATTR_DIRECT_COLOR_BG = 22,
85 GHOSTTY_SGR_ATTR_BG_8 = 23,
86 GHOSTTY_SGR_ATTR_FG_8 = 24,
87 GHOSTTY_SGR_ATTR_RESET_FG = 25,
88 GHOSTTY_SGR_ATTR_RESET_BG = 26,
89 GHOSTTY_SGR_ATTR_BRIGHT_BG_8 = 27,
90 GHOSTTY_SGR_ATTR_BRIGHT_FG_8 = 28,
91 GHOSTTY_SGR_ATTR_BG_256 = 29,
92 GHOSTTY_SGR_ATTR_FG_256 = 30,
93 GHOSTTY_SGR_ATTR_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
94} GhosttySgrAttributeTag;
95
96/**
97 * Underline style types.
98 *
99 * @ingroup sgr
100 */
101typedef enum GHOSTTY_ENUM_TYPED {
102 GHOSTTY_SGR_UNDERLINE_NONE = 0,
103 GHOSTTY_SGR_UNDERLINE_SINGLE = 1,
104 GHOSTTY_SGR_UNDERLINE_DOUBLE = 2,
105 GHOSTTY_SGR_UNDERLINE_CURLY = 3,
106 GHOSTTY_SGR_UNDERLINE_DOTTED = 4,
107 GHOSTTY_SGR_UNDERLINE_DASHED = 5,
108 GHOSTTY_SGR_UNDERLINE_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE,
109} GhosttySgrUnderline;
110
111/**
112 * Unknown SGR attribute data.
113 *
114 * Contains the full parameter list and the partial list where parsing
115 * encountered an unknown or invalid sequence.
116 *
117 * @ingroup sgr
118 */
119typedef struct {
120 const uint16_t* full_ptr;
121 size_t full_len;
122 const uint16_t* partial_ptr;
123 size_t partial_len;
124} GhosttySgrUnknown;
125
126/**
127 * SGR attribute value union.
128 *
129 * This union contains all possible attribute values. Use the tag field
130 * to determine which union member is active. Attributes without associated
131 * data (like bold, italic) don't use the union value.
132 *
133 * @ingroup sgr
134 */
135typedef union {
136 GhosttySgrUnknown unknown;
137 GhosttySgrUnderline underline;
138 GhosttyColorRgb underline_color;
139 GhosttyColorPaletteIndex underline_color_256;
140 GhosttyColorRgb direct_color_fg;
141 GhosttyColorRgb direct_color_bg;
142 GhosttyColorPaletteIndex bg_8;
143 GhosttyColorPaletteIndex fg_8;
144 GhosttyColorPaletteIndex bright_bg_8;
145 GhosttyColorPaletteIndex bright_fg_8;
146 GhosttyColorPaletteIndex bg_256;
147 GhosttyColorPaletteIndex fg_256;
148 uint64_t _padding[8];
149} GhosttySgrAttributeValue;
150
151/**
152 * SGR attribute (tagged union).
153 *
154 * A complete SGR attribute with both its type tag and associated value.
155 * Always check the tag field to determine which value union member is valid.
156 *
157 * Attributes without associated data (e.g., GHOSTTY_SGR_ATTR_BOLD) can be
158 * identified by tag alone; the value union is not used for these and
159 * the memory in the value field is undefined.
160 *
161 * @ingroup sgr
162 */
163typedef struct {
164 GhosttySgrAttributeTag tag;
165 GhosttySgrAttributeValue value;
166} GhosttySgrAttribute;
167
168/**
169 * Create a new SGR parser instance.
170 *
171 * Creates a new SGR (Select Graphic Rendition) parser using the provided
172 * allocator. The parser must be freed using ghostty_sgr_free() when
173 * no longer needed.
174 *
175 * @param allocator Pointer to the allocator to use for memory management, or
176 * NULL to use the default allocator
177 * @param parser Pointer to store the created parser handle
178 * @return GHOSTTY_SUCCESS on success, or an error code on failure
179 *
180 * @ingroup sgr
181 */
182GHOSTTY_API GhosttyResult ghostty_sgr_new(const GhosttyAllocator* allocator,
183 GhosttySgrParser* parser);
184
185/**
186 * Free an SGR parser instance.
187 *
188 * Releases all resources associated with the SGR parser. After this call,
189 * the parser handle becomes invalid and must not be used. This includes
190 * any attributes previously returned by ghostty_sgr_next().
191 *
192 * @param parser The parser handle to free (may be NULL)
193 *
194 * @ingroup sgr
195 */
196GHOSTTY_API void ghostty_sgr_free(GhosttySgrParser parser);
197
198/**
199 * Reset an SGR parser instance to the beginning of the parameter list.
200 *
201 * Resets the parser's iteration state without clearing the parameters.
202 * After calling this, ghostty_sgr_next() will start from the beginning
203 * of the parameter list again.
204 *
205 * @param parser The parser handle to reset, must not be NULL
206 *
207 * @ingroup sgr
208 */
209GHOSTTY_API void ghostty_sgr_reset(GhosttySgrParser parser);
210
211/**
212 * Set SGR parameters for parsing.
213 *
214 * Sets the SGR parameter list to parse. Parameters are the numeric values
215 * from a CSI SGR sequence (e.g., for `ESC[1;31m`, params would be {1, 31}).
216 *
217 * The separators array optionally specifies the separator type for each
218 * parameter position. Each byte should be either ';' for semicolon or ':'
219 * for colon. This is needed for certain color formats that use colon
220 * separators (e.g., `ESC[4:3m` for curly underline). Any invalid separator
221 * values are treated as semicolons. The separators array must have the same
222 * length as the params array, if it is not NULL.
223 *
224 * If separators is NULL, all parameters are assumed to be semicolon-separated.
225 *
226 * This function makes an internal copy of the parameter and separator data,
227 * so the caller can safely free or modify the input arrays after this call.
228 *
229 * After calling this function, the parser is automatically reset and ready
230 * to iterate from the beginning.
231 *
232 * @param parser The parser handle, must not be NULL
233 * @param params Array of SGR parameter values
234 * @param separators Optional array of separator characters (';' or ':'), or
235 * NULL
236 * @param len Number of parameters (and separators if provided)
237 * @return GHOSTTY_SUCCESS on success, or an error code on failure
238 *
239 * @ingroup sgr
240 */
241GHOSTTY_API GhosttyResult ghostty_sgr_set_params(GhosttySgrParser parser,
242 const uint16_t* params,
243 const char* separators,
244 size_t len);
245
246/**
247 * Get the next SGR attribute.
248 *
249 * Parses and returns the next attribute from the parameter list.
250 * Call this function repeatedly until it returns false to process
251 * all attributes in the sequence.
252 *
253 * @param parser The parser handle, must not be NULL
254 * @param attr Pointer to store the next attribute
255 * @return true if an attribute was returned, false if no more attributes
256 *
257 * @ingroup sgr
258 */
259GHOSTTY_API bool ghostty_sgr_next(GhosttySgrParser parser, GhosttySgrAttribute* attr);
260
261/**
262 * Get the full parameter list from an unknown SGR attribute.
263 *
264 * This function retrieves the full parameter list that was provided to the
265 * parser when an unknown attribute was encountered. Primarily useful in
266 * WebAssembly environments where accessing struct fields directly is difficult.
267 *
268 * @param unknown The unknown attribute data
269 * @param ptr Pointer to store the pointer to the parameter array (may be NULL)
270 * @return The length of the full parameter array
271 *
272 * @ingroup sgr
273 */
274GHOSTTY_API size_t ghostty_sgr_unknown_full(GhosttySgrUnknown unknown,
275 const uint16_t** ptr);
276
277/**
278 * Get the partial parameter list from an unknown SGR attribute.
279 *
280 * This function retrieves the partial parameter list where parsing stopped
281 * when an unknown attribute was encountered. Primarily useful in WebAssembly
282 * environments where accessing struct fields directly is difficult.
283 *
284 * @param unknown The unknown attribute data
285 * @param ptr Pointer to store the pointer to the parameter array (may be NULL)
286 * @return The length of the partial parameter array
287 *
288 * @ingroup sgr
289 */
290GHOSTTY_API size_t ghostty_sgr_unknown_partial(GhosttySgrUnknown unknown,
291 const uint16_t** ptr);
292
293/**
294 * Get the tag from an SGR attribute.
295 *
296 * This function extracts the tag that identifies which type of attribute
297 * this is. Primarily useful in WebAssembly environments where accessing
298 * struct fields directly is difficult.
299 *
300 * @param attr The SGR attribute
301 * @return The attribute tag
302 *
303 * @ingroup sgr
304 */
305GHOSTTY_API GhosttySgrAttributeTag ghostty_sgr_attribute_tag(GhosttySgrAttribute attr);
306
307/**
308 * Get the value from an SGR attribute.
309 *
310 * This function returns a pointer to the value union from an SGR attribute. Use
311 * the tag to determine which field of the union is valid. Primarily useful in
312 * WebAssembly environments where accessing struct fields directly is difficult.
313 *
314 * @param attr Pointer to the SGR attribute
315 * @return Pointer to the attribute value union
316 *
317 * @ingroup sgr
318 */
319GHOSTTY_API GhosttySgrAttributeValue* ghostty_sgr_attribute_value(
320 GhosttySgrAttribute* attr);
321
322#ifdef __wasm__
323/**
324 * Allocate memory for an SGR attribute (WebAssembly only).
325 *
326 * This is a convenience function for WebAssembly environments to allocate
327 * memory for an SGR attribute structure that can be passed to ghostty_sgr_next.
328 *
329 * @return Pointer to the allocated attribute structure
330 *
331 * @ingroup wasm
332 */
333GHOSTTY_API GhosttySgrAttribute* ghostty_wasm_alloc_sgr_attribute(void);
334
335/**
336 * Free memory for an SGR attribute (WebAssembly only).
337 *
338 * Frees memory allocated by ghostty_wasm_alloc_sgr_attribute.
339 *
340 * @param attr Pointer to the attribute structure to free
341 *
342 * @ingroup wasm
343 */
344GHOSTTY_API void ghostty_wasm_free_sgr_attribute(GhosttySgrAttribute* attr);
345#endif
346
347#ifdef __cplusplus
348}
349#endif
350
351/** @} */
352
353#endif /* GHOSTTY_VT_SGR_H */