Formatter

Detailed Description

Format terminal content as plain text, VT sequences, or HTML.

A formatter captures a reference to a terminal and formatting options. It can be used repeatedly to produce output that reflects the current terminal state at the time of each format call.

The terminal must outlive the formatter.

Typedefs
typedef struct GhosttyFormatter *	GhosttyFormatter

Enumerations
enum	GhosttyFormatterFormat { GHOSTTY_FORMATTER_FORMAT_PLAIN , GHOSTTY_FORMATTER_FORMAT_VT , GHOSTTY_FORMATTER_FORMAT_HTML }

Functions
GhosttyResult	ghostty_formatter_terminal_new (const GhosttyAllocator *allocator, GhosttyFormatter *formatter, GhosttyTerminal terminal, GhosttyFormatterTerminalOptions options)
GhosttyResult	ghostty_formatter_format_buf (GhosttyFormatter formatter, uint8_t *buf, size_t buf_len, size_t *out_written)
GhosttyResult	ghostty_formatter_format_alloc (GhosttyFormatter formatter, const GhosttyAllocator *allocator, uint8_t **out_ptr, size_t *out_len)
void	ghostty_formatter_free (GhosttyFormatter formatter)

Data Structures
struct	GhosttyFormatterScreenExtra
struct	GhosttyFormatterTerminalExtra
struct	GhosttyFormatterTerminalOptions

Typedef Documentation

GhosttyFormatter

typedef struct GhosttyFormatter* GhosttyFormatter

Opaque handle to a formatter instance.

Examples

c-vt-formatter/src/main.c.

Definition at line 114 of file formatter.h.

Enumeration Type Documentation

GhosttyFormatterFormat

enum GhosttyFormatterFormat

Output format.

Enumerator
GHOSTTY_FORMATTER_FORMAT_PLAIN	Plain text (no escape sequences).
GHOSTTY_FORMATTER_FORMAT_VT	VT sequences preserving colors, styles, URLs, etc.
GHOSTTY_FORMATTER_FORMAT_HTML	HTML with inline styles.

Definition at line 39 of file formatter.h.

Function Documentation

ghostty_formatter_format_alloc()

GhosttyResult ghostty_formatter_format_alloc	(	GhosttyFormatter	formatter,
		const GhosttyAllocator *	allocator,
		uint8_t **	out_ptr,
		size_t *	out_len )

Run the formatter and return an allocated buffer with the output.

Each call formats the current terminal state. The buffer is allocated using the provided allocator (or the default allocator if NULL). The caller is responsible for freeing the returned buffer. When using the default allocator (NULL), the buffer can be freed with free(). When using a custom allocator, the buffer must be freed using the same allocator.

Parameters

Formatter	The formatter handle (must not be NULL)
Memory Management	Pointer to allocator, or NULL to use the default allocator
out_ptr	Pointer to receive the allocated buffer
out_len	Pointer to receive the length of the output in bytes

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_MEMORY on allocation failure

Examples

c-vt-formatter/src/main.c.

ghostty_formatter_format_buf()

GhosttyResult ghostty_formatter_format_buf	(	GhosttyFormatter	formatter,
		uint8_t *	buf,
		size_t	buf_len,
		size_t *	out_written )

Run the formatter and produce output into the caller-provided buffer.

Each call formats the current terminal state. Pass NULL for buf to query the required buffer size without writing any output; in that case out_written receives the required size and the return value is GHOSTTY_OUT_OF_SPACE.

If the buffer is too small, returns GHOSTTY_OUT_OF_SPACE and sets out_written to the required size. The caller can then retry with a larger buffer.

Parameters

Formatter	The formatter handle (must not be NULL)
buf	Pointer to the output buffer, or NULL to query size
buf_len	Length of the output buffer in bytes
out_written	Pointer to receive the number of bytes written, or the required size on failure

Returns

GHOSTTY_SUCCESS on success, or an error code on failure

ghostty_formatter_free()

void ghostty_formatter_free

(

GhosttyFormatter

formatter

)

Free a formatter instance.

Releases all resources associated with the formatter. After this call, the formatter handle becomes invalid.

Parameters

Formatter

The formatter handle to free (may be NULL)

Examples

c-vt-formatter/src/main.c.

ghostty_formatter_terminal_new()

GhosttyResult ghostty_formatter_terminal_new	(	const GhosttyAllocator *	allocator,
		GhosttyFormatter *	formatter,
		GhosttyTerminal	terminal,
		GhosttyFormatterTerminalOptions	options )

Create a formatter for a terminal's active screen.

The terminal must outlive the formatter. The formatter stores a borrowed reference to the terminal and reads its current state on each format call.

Parameters

Memory Management	Pointer to allocator, or NULL to use the default allocator
Formatter	Pointer to store the created formatter handle
Terminal	The terminal to format (must not be NULL)
options	Formatting options

Returns

GHOSTTY_SUCCESS on success, or an error code on failure

Examples

c-vt-formatter/src/main.c.