aboutsummaryrefslogtreecommitdiff
path: root/vendor/libghostty-vt/include/ghostty/vt/sgr.h
diff options
context:
space:
mode:
authorCan Celik <ogulcancelik@gmail.com>2026-04-04 19:22:04 +0300
committerCan Celik <ogulcancelik@gmail.com>2026-04-05 01:23:06 +0300
commit41dd733ca7123c9ac4bfc6c781697a660e95b052 (patch)
tree3fc91815ca139ef2e0b281bba0abda4ef15175f4 /vendor/libghostty-vt/include/ghostty/vt/sgr.h
parent55c138263e190a1e79d4b997bfb9397306c0ec1f (diff)
feat: finish ghostty pane backend integration
Diffstat (limited to 'vendor/libghostty-vt/include/ghostty/vt/sgr.h')
-rw-r--r--vendor/libghostty-vt/include/ghostty/vt/sgr.h358
1 files changed, 358 insertions, 0 deletions
diff --git a/vendor/libghostty-vt/include/ghostty/vt/sgr.h b/vendor/libghostty-vt/include/ghostty/vt/sgr.h
new file mode 100644
index 00000000..01ea3a35
--- /dev/null
+++ b/vendor/libghostty-vt/include/ghostty/vt/sgr.h
@@ -0,0 +1,358 @@
+/**
+ * @file sgr.h
+ *
+ * SGR (Select Graphic Rendition) attribute parsing and handling.
+ */
+
+#ifndef GHOSTTY_VT_SGR_H
+#define GHOSTTY_VT_SGR_H
+
+/** @defgroup sgr SGR Parser
+ *
+ * SGR (Select Graphic Rendition) attribute parser.
+ *
+ * SGR sequences are the syntax used to set styling attributes such as
+ * bold, italic, underline, and colors for text in terminal emulators.
+ * For example, you may be familiar with sequences like `ESC[1;31m`. The
+ * `1;31` is the SGR attribute list.
+ *
+ * The parser processes SGR parameters from CSI sequences (e.g., `ESC[1;31m`)
+ * and returns individual text attributes like bold, italic, colors, etc.
+ * It supports both semicolon (`;`) and colon (`:`) separators, possibly mixed,
+ * and handles various color formats including 8-color, 16-color, 256-color,
+ * X11 named colors, and RGB in multiple formats.
+ *
+ * ## Basic Usage
+ *
+ * 1. Create a parser instance with ghostty_sgr_new()
+ * 2. Set SGR parameters with ghostty_sgr_set_params()
+ * 3. Iterate through attributes using ghostty_sgr_next()
+ * 4. Free the parser with ghostty_sgr_free() when done
+ *
+ * ## Example
+ *
+ * @snippet c-vt-sgr/src/main.c sgr-basic
+ *
+ * @{
+ */
+
+#include <ghostty/vt/allocator.h>
+#include <ghostty/vt/color.h>
+#include <ghostty/vt/types.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Opaque handle to an SGR parser instance.
+ *
+ * This handle represents an SGR (Select Graphic Rendition) parser that can
+ * be used to parse SGR sequences and extract individual text attributes.
+ *
+ * @ingroup sgr
+ */
+typedef struct GhosttySgrParserImpl* GhosttySgrParser;
+
+/**
+ * SGR attribute tags.
+ *
+ * These values identify the type of an SGR attribute in a tagged union.
+ * Use the tag to determine which field in the attribute value union to access.
+ *
+ * @ingroup sgr
+ */
+typedef enum {
+ GHOSTTY_SGR_ATTR_UNSET = 0,
+ GHOSTTY_SGR_ATTR_UNKNOWN = 1,
+ GHOSTTY_SGR_ATTR_BOLD = 2,
+ GHOSTTY_SGR_ATTR_RESET_BOLD = 3,
+ GHOSTTY_SGR_ATTR_ITALIC = 4,
+ GHOSTTY_SGR_ATTR_RESET_ITALIC = 5,
+ GHOSTTY_SGR_ATTR_FAINT = 6,
+ GHOSTTY_SGR_ATTR_UNDERLINE = 7,
+ GHOSTTY_SGR_ATTR_UNDERLINE_COLOR = 8,
+ GHOSTTY_SGR_ATTR_UNDERLINE_COLOR_256 = 9,
+ GHOSTTY_SGR_ATTR_RESET_UNDERLINE_COLOR = 10,
+ GHOSTTY_SGR_ATTR_OVERLINE = 11,
+ GHOSTTY_SGR_ATTR_RESET_OVERLINE = 12,
+ GHOSTTY_SGR_ATTR_BLINK = 13,
+ GHOSTTY_SGR_ATTR_RESET_BLINK = 14,
+ GHOSTTY_SGR_ATTR_INVERSE = 15,
+ GHOSTTY_SGR_ATTR_RESET_INVERSE = 16,
+ GHOSTTY_SGR_ATTR_INVISIBLE = 17,
+ GHOSTTY_SGR_ATTR_RESET_INVISIBLE = 18,
+ GHOSTTY_SGR_ATTR_STRIKETHROUGH = 19,
+ GHOSTTY_SGR_ATTR_RESET_STRIKETHROUGH = 20,
+ GHOSTTY_SGR_ATTR_DIRECT_COLOR_FG = 21,
+ GHOSTTY_SGR_ATTR_DIRECT_COLOR_BG = 22,
+ GHOSTTY_SGR_ATTR_BG_8 = 23,
+ GHOSTTY_SGR_ATTR_FG_8 = 24,
+ GHOSTTY_SGR_ATTR_RESET_FG = 25,
+ GHOSTTY_SGR_ATTR_RESET_BG = 26,
+ GHOSTTY_SGR_ATTR_BRIGHT_BG_8 = 27,
+ GHOSTTY_SGR_ATTR_BRIGHT_FG_8 = 28,
+ GHOSTTY_SGR_ATTR_BG_256 = 29,
+ GHOSTTY_SGR_ATTR_FG_256 = 30,
+} GhosttySgrAttributeTag;
+
+/**
+ * Underline style types.
+ *
+ * @ingroup sgr
+ */
+typedef enum {
+ GHOSTTY_SGR_UNDERLINE_NONE = 0,
+ GHOSTTY_SGR_UNDERLINE_SINGLE = 1,
+ GHOSTTY_SGR_UNDERLINE_DOUBLE = 2,
+ GHOSTTY_SGR_UNDERLINE_CURLY = 3,
+ GHOSTTY_SGR_UNDERLINE_DOTTED = 4,
+ GHOSTTY_SGR_UNDERLINE_DASHED = 5,
+} GhosttySgrUnderline;
+
+/**
+ * Unknown SGR attribute data.
+ *
+ * Contains the full parameter list and the partial list where parsing
+ * encountered an unknown or invalid sequence.
+ *
+ * @ingroup sgr
+ */
+typedef struct {
+ const uint16_t* full_ptr;
+ size_t full_len;
+ const uint16_t* partial_ptr;
+ size_t partial_len;
+} GhosttySgrUnknown;
+
+/**
+ * SGR attribute value union.
+ *
+ * This union contains all possible attribute values. Use the tag field
+ * to determine which union member is active. Attributes without associated
+ * data (like bold, italic) don't use the union value.
+ *
+ * @ingroup sgr
+ */
+typedef union {
+ GhosttySgrUnknown unknown;
+ GhosttySgrUnderline underline;
+ GhosttyColorRgb underline_color;
+ GhosttyColorPaletteIndex underline_color_256;
+ GhosttyColorRgb direct_color_fg;
+ GhosttyColorRgb direct_color_bg;
+ GhosttyColorPaletteIndex bg_8;
+ GhosttyColorPaletteIndex fg_8;
+ GhosttyColorPaletteIndex bright_bg_8;
+ GhosttyColorPaletteIndex bright_fg_8;
+ GhosttyColorPaletteIndex bg_256;
+ GhosttyColorPaletteIndex fg_256;
+ uint64_t _padding[8];
+} GhosttySgrAttributeValue;
+
+/**
+ * SGR attribute (tagged union).
+ *
+ * A complete SGR attribute with both its type tag and associated value.
+ * Always check the tag field to determine which value union member is valid.
+ *
+ * Attributes without associated data (e.g., GHOSTTY_SGR_ATTR_BOLD) can be
+ * identified by tag alone; the value union is not used for these and
+ * the memory in the value field is undefined.
+ *
+ * @ingroup sgr
+ */
+typedef struct {
+ GhosttySgrAttributeTag tag;
+ GhosttySgrAttributeValue value;
+} GhosttySgrAttribute;
+
+/**
+ * Create a new SGR parser instance.
+ *
+ * Creates a new SGR (Select Graphic Rendition) parser using the provided
+ * allocator. The parser must be freed using ghostty_sgr_free() when
+ * no longer needed.
+ *
+ * @param allocator Pointer to the allocator to use for memory management, or
+ * NULL to use the default allocator
+ * @param parser Pointer to store the created parser handle
+ * @return GHOSTTY_SUCCESS on success, or an error code on failure
+ *
+ * @ingroup sgr
+ */
+GHOSTTY_API GhosttyResult ghostty_sgr_new(const GhosttyAllocator* allocator,
+ GhosttySgrParser* parser);
+
+/**
+ * Free an SGR parser instance.
+ *
+ * Releases all resources associated with the SGR parser. After this call,
+ * the parser handle becomes invalid and must not be used. This includes
+ * any attributes previously returned by ghostty_sgr_next().
+ *
+ * @param parser The parser handle to free (may be NULL)
+ *
+ * @ingroup sgr
+ */
+GHOSTTY_API void ghostty_sgr_free(GhosttySgrParser parser);
+
+/**
+ * Reset an SGR parser instance to the beginning of the parameter list.
+ *
+ * Resets the parser's iteration state without clearing the parameters.
+ * After calling this, ghostty_sgr_next() will start from the beginning
+ * of the parameter list again.
+ *
+ * @param parser The parser handle to reset, must not be NULL
+ *
+ * @ingroup sgr
+ */
+GHOSTTY_API void ghostty_sgr_reset(GhosttySgrParser parser);
+
+/**
+ * Set SGR parameters for parsing.
+ *
+ * Sets the SGR parameter list to parse. Parameters are the numeric values
+ * from a CSI SGR sequence (e.g., for `ESC[1;31m`, params would be {1, 31}).
+ *
+ * The separators array optionally specifies the separator type for each
+ * parameter position. Each byte should be either ';' for semicolon or ':'
+ * for colon. This is needed for certain color formats that use colon
+ * separators (e.g., `ESC[4:3m` for curly underline). Any invalid separator
+ * values are treated as semicolons. The separators array must have the same
+ * length as the params array, if it is not NULL.
+ *
+ * If separators is NULL, all parameters are assumed to be semicolon-separated.
+ *
+ * This function makes an internal copy of the parameter and separator data,
+ * so the caller can safely free or modify the input arrays after this call.
+ *
+ * After calling this function, the parser is automatically reset and ready
+ * to iterate from the beginning.
+ *
+ * @param parser The parser handle, must not be NULL
+ * @param params Array of SGR parameter values
+ * @param separators Optional array of separator characters (';' or ':'), or
+ * NULL
+ * @param len Number of parameters (and separators if provided)
+ * @return GHOSTTY_SUCCESS on success, or an error code on failure
+ *
+ * @ingroup sgr
+ */
+GHOSTTY_API GhosttyResult ghostty_sgr_set_params(GhosttySgrParser parser,
+ const uint16_t* params,
+ const char* separators,
+ size_t len);
+
+/**
+ * Get the next SGR attribute.
+ *
+ * Parses and returns the next attribute from the parameter list.
+ * Call this function repeatedly until it returns false to process
+ * all attributes in the sequence.
+ *
+ * @param parser The parser handle, must not be NULL
+ * @param attr Pointer to store the next attribute
+ * @return true if an attribute was returned, false if no more attributes
+ *
+ * @ingroup sgr
+ */
+GHOSTTY_API bool ghostty_sgr_next(GhosttySgrParser parser, GhosttySgrAttribute* attr);
+
+/**
+ * Get the full parameter list from an unknown SGR attribute.
+ *
+ * This function retrieves the full parameter list that was provided to the
+ * parser when an unknown attribute was encountered. Primarily useful in
+ * WebAssembly environments where accessing struct fields directly is difficult.
+ *
+ * @param unknown The unknown attribute data
+ * @param ptr Pointer to store the pointer to the parameter array (may be NULL)
+ * @return The length of the full parameter array
+ *
+ * @ingroup sgr
+ */
+GHOSTTY_API size_t ghostty_sgr_unknown_full(GhosttySgrUnknown unknown,
+ const uint16_t** ptr);
+
+/**
+ * Get the partial parameter list from an unknown SGR attribute.
+ *
+ * This function retrieves the partial parameter list where parsing stopped
+ * when an unknown attribute was encountered. Primarily useful in WebAssembly
+ * environments where accessing struct fields directly is difficult.
+ *
+ * @param unknown The unknown attribute data
+ * @param ptr Pointer to store the pointer to the parameter array (may be NULL)
+ * @return The length of the partial parameter array
+ *
+ * @ingroup sgr
+ */
+GHOSTTY_API size_t ghostty_sgr_unknown_partial(GhosttySgrUnknown unknown,
+ const uint16_t** ptr);
+
+/**
+ * Get the tag from an SGR attribute.
+ *
+ * This function extracts the tag that identifies which type of attribute
+ * this is. Primarily useful in WebAssembly environments where accessing
+ * struct fields directly is difficult.
+ *
+ * @param attr The SGR attribute
+ * @return The attribute tag
+ *
+ * @ingroup sgr
+ */
+GHOSTTY_API GhosttySgrAttributeTag ghostty_sgr_attribute_tag(GhosttySgrAttribute attr);
+
+/**
+ * Get the value from an SGR attribute.
+ *
+ * This function returns a pointer to the value union from an SGR attribute. Use
+ * the tag to determine which field of the union is valid. Primarily useful in
+ * WebAssembly environments where accessing struct fields directly is difficult.
+ *
+ * @param attr Pointer to the SGR attribute
+ * @return Pointer to the attribute value union
+ *
+ * @ingroup sgr
+ */
+GHOSTTY_API GhosttySgrAttributeValue* ghostty_sgr_attribute_value(
+ GhosttySgrAttribute* attr);
+
+#ifdef __wasm__
+/**
+ * Allocate memory for an SGR attribute (WebAssembly only).
+ *
+ * This is a convenience function for WebAssembly environments to allocate
+ * memory for an SGR attribute structure that can be passed to ghostty_sgr_next.
+ *
+ * @return Pointer to the allocated attribute structure
+ *
+ * @ingroup wasm
+ */
+GHOSTTY_API GhosttySgrAttribute* ghostty_wasm_alloc_sgr_attribute(void);
+
+/**
+ * Free memory for an SGR attribute (WebAssembly only).
+ *
+ * Frees memory allocated by ghostty_wasm_alloc_sgr_attribute.
+ *
+ * @param attr Pointer to the attribute structure to free
+ *
+ * @ingroup wasm
+ */
+GHOSTTY_API void ghostty_wasm_free_sgr_attribute(GhosttySgrAttribute* attr);
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
+
+#endif /* GHOSTTY_VT_SGR_H */