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 GhosttyFormatterImpl *	GhosttyFormatter

Enumerations
enum	GhosttyFormatterFormat { GHOSTTY_FORMATTER_FORMAT_PLAIN , GHOSTTY_FORMATTER_FORMAT_VT , GHOSTTY_FORMATTER_FORMAT_HTML , GHOSTTY_FORMATTER_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }

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

Data Structures
struct	GhosttyFormatterScreenExtra
struct	GhosttyFormatterTerminalExtra
struct	GhosttyFormatterTerminalOptions

Typedef Documentation

GhosttyFormatter

typedef struct GhosttyFormatterImpl* GhosttyFormatter

Opaque handle to a formatter instance.

Examples

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

Definition at line 163 of file types.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 40 of file formatter.h.

Function Documentation

ghostty_formatter_format_alloc()

GHOSTTY_API 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 with ghostty_free(), passing the same allocator (or NULL for the default) that was used for the allocation.

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

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

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

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