SGR Parser

Parse SGR sequences into text attributes. More...

Detailed Description

Parse SGR sequences into text attributes.

The SGR parser turns the parameters of a Select Graphic Rendition sequence into text attributes, one at a time.

SGR is how programs set bold, italic, underline and colors. In ESC[1;31m, 1;31 is the attribute list. A terminal parses these by itself, so you only need this for SGR sequences outside of one. It accepts semicolons and colons, even mixed. Colors come back as Colors types.

Example

void basic_example() {
  // Create parser
  GhosttySgrParser parser;
  GhosttyResult result = ghostty_sgr_new(NULL, &parser);
  assert(result == GHOSTTY_SUCCESS);
 
  // Parse "bold, red foreground" sequence: ESC[1;31m
  uint16_t params[] = {1, 31};
  result = ghostty_sgr_set_params(parser, params, NULL, 2);
  assert(result == GHOSTTY_SUCCESS);
 
  // Iterate through attributes
  GhosttySgrAttribute attr;
  while (ghostty_sgr_next(parser, &attr)) {
    switch (attr.tag) {
      case GHOSTTY_SGR_ATTR_BOLD:
        printf("Bold enabled\n");
        break;
      case GHOSTTY_SGR_ATTR_FG_8:
        printf("Foreground color: %d\n", attr.value.fg_8);
        break;
      default:
        break;
    }
  }
 
  // Cleanup
  ghostty_sgr_free(parser);
}

Full program: c-vt-sgr/src/main.c

To read the styles of a terminal's cells, see Style.

Typedefs
typedef struct GhosttySgrParserImpl *	GhosttySgrParser

Enumerations
enum	GhosttySgrAttributeTag
enum	GhosttySgrUnderline

Functions
GHOSTTY_API GhosttyResult	ghostty_sgr_new (const GhosttyAllocator *allocator, GhosttySgrParser *parser)
GHOSTTY_API void	ghostty_sgr_free (GhosttySgrParser parser)
GHOSTTY_API void	ghostty_sgr_reset (GhosttySgrParser parser)
GHOSTTY_API GhosttyResult	ghostty_sgr_set_params (GhosttySgrParser parser, const uint16_t *params, const char *separators, size_t len)
GHOSTTY_API bool	ghostty_sgr_next (GhosttySgrParser parser, GhosttySgrAttribute *attr)
GHOSTTY_API size_t	ghostty_sgr_unknown_full (GhosttySgrUnknown unknown, const uint16_t **ptr)
GHOSTTY_API size_t	ghostty_sgr_unknown_partial (GhosttySgrUnknown unknown, const uint16_t **ptr)
GHOSTTY_API GhosttySgrAttributeTag	ghostty_sgr_attribute_tag (const GhosttySgrAttribute *attr)
GHOSTTY_API GhosttySgrAttributeValue *	ghostty_sgr_attribute_value (GhosttySgrAttribute *attr)

Data Structures
struct	GhosttySgrUnknown
union	GhosttySgrAttributeValue
struct	GhosttySgrAttribute

Typedef Documentation

GhosttySgrParser

typedef struct GhosttySgrParserImpl* GhosttySgrParser

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.

Examples

c-vt-sgr/src/main.c.

Definition at line 297 of file types.h.

Enumeration Type Documentation

GhosttySgrAttributeTag

enum GhosttySgrAttributeTag

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.

Definition at line 50 of file sgr.h.

GhosttySgrUnderline

enum GhosttySgrUnderline

Underline style types.

Definition at line 90 of file sgr.h.

Function Documentation

ghostty_sgr_attribute_tag()

GHOSTTY_API GhosttySgrAttributeTag ghostty_sgr_attribute_tag

(

const GhosttySgrAttribute *

attr

)

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.

Parameters

attr	Pointer to the SGR attribute (may be NULL)

Returns

The attribute tag, or GHOSTTY_SGR_ATTR_UNSET if attr is NULL

ghostty_sgr_attribute_value()

GHOSTTY_API GhosttySgrAttributeValue * ghostty_sgr_attribute_value

(

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.

Parameters

attr	Pointer to the SGR attribute

Returns

Pointer to the attribute value union

ghostty_sgr_free()

GHOSTTY_API void ghostty_sgr_free

(

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().

Parameters

parser

The parser handle to free (may be NULL)

Examples

c-vt-sgr/src/main.c.

ghostty_sgr_new()

GHOSTTY_API GhosttyResult ghostty_sgr_new	(	const GhosttyAllocator *	allocator,
		GhosttySgrParser *	parser )

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.

Parameters

allocator	Pointer to the allocator to use for memory management, or NULL to use the default allocator
parser	Pointer to store the created parser handle

Returns

GHOSTTY_SUCCESS on success, or an error code on failure

Examples

c-vt-sgr/src/main.c.

ghostty_sgr_next()

GHOSTTY_API bool ghostty_sgr_next	(	GhosttySgrParser	parser,
		GhosttySgrAttribute *	attr )

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.

Parameters

parser	The parser handle, must not be NULL
attr	Pointer to store the next attribute

Returns

true if an attribute was returned, false if no more attributes

Examples

c-vt-sgr/src/main.c.

ghostty_sgr_reset()

GHOSTTY_API void ghostty_sgr_reset

(

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.

Parameters

parser

The parser handle to reset, must not be NULL

ghostty_sgr_set_params()

GHOSTTY_API GhosttyResult ghostty_sgr_set_params	(	GhosttySgrParser	parser,
		const uint16_t *	params,
		const char *	separators,
		size_t	len )

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 you 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.

Parameters

parser	The parser handle, must not be NULL
params	Array of SGR parameter values
separators	Optional array of separator characters (';' or ':'), or NULL
len	Number of parameters (and separators if provided)

Returns

GHOSTTY_SUCCESS on success, or an error code on failure

Examples

c-vt-sgr/src/main.c.

ghostty_sgr_unknown_full()

GHOSTTY_API size_t ghostty_sgr_unknown_full	(	GhosttySgrUnknown	unknown,
		const uint16_t **	ptr )

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.

Parameters

unknown	The unknown attribute data
ptr	Pointer to store the pointer to the parameter array (may be NULL)

Returns

The length of the full parameter array

ghostty_sgr_unknown_partial()

GHOSTTY_API size_t ghostty_sgr_unknown_partial	(	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.

Parameters

unknown	The unknown attribute data
ptr	Pointer to store the pointer to the parameter array (may be NULL)

Returns

The length of the partial parameter array