Formatter

Turn terminal content into plain text, VT sequences, or HTML. More...

Detailed Description

Turn terminal content into plain text, VT sequences, or HTML.

A formatter is a view of a terminal that you can turn into plain text, VT sequences, or HTML, as many times as you like.

Use one to get text out of a terminal, such as copying a selection or saving what's on the screen. You need a terminal first, and it must outlive the formatter. Each format call reflects the terminal at the time of that call.

Example

  // Create a formatter for the terminal and ask for plain text with
  // trailing whitespace trimmed. A new formatter already does both, but
  // setting them shows how options work and makes the output we want
  // explicit.
  GhosttyFormatter formatter;
  result = ghostty_formatter_terminal_new(NULL, &formatter, terminal);
  assert(result == GHOSTTY_SUCCESS);
 
  GhosttyFormatterFormat emit = GHOSTTY_FORMATTER_FORMAT_PLAIN;
  result = ghostty_formatter_set(formatter, GHOSTTY_FORMATTER_OPT_EMIT, &emit);
  assert(result == GHOSTTY_SUCCESS);
 
  bool trim = true;
  result = ghostty_formatter_set(formatter, GHOSTTY_FORMATTER_OPT_TRIM, &trim);
  assert(result == GHOSTTY_SUCCESS);

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

GhosttyFormatterOption lists the options. See the Selection guide for copying a selection.

Typedefs
typedef uint32_t	GhosttyFormatterExtras
typedef struct GhosttyFormatterImpl *	GhosttyFormatter

Enumerations
enum	GhosttyFormatterOption {   GHOSTTY_FORMATTER_OPT_INVALID = 0 , GHOSTTY_FORMATTER_OPT_EMIT = 1 , GHOSTTY_FORMATTER_OPT_UNWRAP = 2 , GHOSTTY_FORMATTER_OPT_TRIM = 3 ,   GHOSTTY_FORMATTER_OPT_SELECTION = 4 , GHOSTTY_FORMATTER_OPT_EXTRAS = 5 , GHOSTTY_FORMATTER_OPT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }
enum	GhosttyFormatterFormat { GHOSTTY_FORMATTER_FORMAT_PLAIN = 0 , GHOSTTY_FORMATTER_FORMAT_VT = 1 , GHOSTTY_FORMATTER_FORMAT_HTML = 2 , GHOSTTY_FORMATTER_FORMAT_MAX_VALUE = GHOSTTY_ENUM_MAX_VALUE }

Functions
GHOSTTY_API GhosttyResult	ghostty_formatter_terminal_new (const GhosttyAllocator *allocator, GhosttyFormatter *formatter, GhosttyTerminal terminal)
GHOSTTY_API GhosttyResult	ghostty_formatter_set (GhosttyFormatter formatter, GhosttyFormatterOption option, const void *value)
GHOSTTY_API GhosttyResult	ghostty_formatter_get (GhosttyFormatter formatter, GhosttyFormatterOption option, void *out)
GHOSTTY_API GhosttyResult	ghostty_formatter_format (GhosttyFormatter formatter, GhosttyWriter writer)
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)

Macros
#define	GHOSTTY_FORMATTER_EXTRA_PALETTE   (1u << 0)
#define	GHOSTTY_FORMATTER_EXTRA_MODES   (1u << 1)
#define	GHOSTTY_FORMATTER_EXTRA_SCROLLING_REGION   (1u << 2)
#define	GHOSTTY_FORMATTER_EXTRA_TABSTOPS   (1u << 3)
#define	GHOSTTY_FORMATTER_EXTRA_PWD   (1u << 4)
#define	GHOSTTY_FORMATTER_EXTRA_KEYBOARD   (1u << 5)
#define	GHOSTTY_FORMATTER_EXTRA_CURSOR   (1u << 6)
#define	GHOSTTY_FORMATTER_EXTRA_STYLE   (1u << 7)
#define	GHOSTTY_FORMATTER_EXTRA_HYPERLINK   (1u << 8)
#define	GHOSTTY_FORMATTER_EXTRA_PROTECTION   (1u << 9)
#define	GHOSTTY_FORMATTER_EXTRA_KITTY_KEYBOARD   (1u << 10)
#define	GHOSTTY_FORMATTER_EXTRA_CHARSETS   (1u << 11)
#define	GHOSTTY_FORMATTER_EXTRAS_NONE   0u
#define	GHOSTTY_FORMATTER_EXTRAS_ALL   0xFFFu
#define	GHOSTTY_FORMATTER_EXTRAS_DEFAULT

Typedef Documentation

GhosttyFormatter

typedef struct GhosttyFormatterImpl* GhosttyFormatter

Opaque handle to a formatter instance.

Examples

c-vt-cmake-cross/src/main.c, c-vt-cmake-static/src/main.c, c-vt-cmake/src/main.c, c-vt-formatter/src/main.c, c-vt-hello/src/main.c, c-vt-selection-gesture/src/main.c, c-vt-selection/src/main.c, and c-vt-stream/src/main.c.

Definition at line 304 of file types.h.

GhosttyFormatterExtras

typedef uint32_t GhosttyFormatterExtras

Terminal state to add to VT output, as a bitmask of GHOSTTY_FORMATTER_EXTRA_* values.

VT output is meant to be written to another terminal to recreate the screen. Without extras, it reproduces the text and how each cell is styled. Each extra adds sequences that restore one more piece of terminal state, such as the cursor position or the colors in the palette. Extras are only written when the format is GHOSTTY_FORMATTER_FORMAT_VT. Plain text and HTML output ignore them.

Set extras with GHOSTTY_FORMATTER_OPT_EXTRAS. A new formatter uses GHOSTTY_FORMATTER_EXTRAS_DEFAULT. Use GHOSTTY_FORMATTER_EXTRAS_ALL to recreate the terminal as closely as possible.

The bits combine with |. To change one extra and keep the rest, read the current value first:

GhosttyFormatterExtras extras;
ghostty_formatter_get(formatter, GHOSTTY_FORMATTER_OPT_EXTRAS, &extras);
 
// Also restore the cursor position, but not the palette.
extras |= GHOSTTY_FORMATTER_EXTRA_CURSOR;
extras &= ~GHOSTTY_FORMATTER_EXTRA_PALETTE;
 
ghostty_formatter_set(formatter, GHOSTTY_FORMATTER_OPT_EXTRAS, &extras);

Definition at line 75 of file formatter.h.

Enumeration Type Documentation

GhosttyFormatterFormat

enum GhosttyFormatterFormat

Terminal content 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.

Examples

c-vt-cmake-cross/src/main.c, c-vt-cmake-static/src/main.c, c-vt-cmake/src/main.c, c-vt-formatter/src/main.c, c-vt-selection-gesture/src/main.c, c-vt-selection/src/main.c, and c-vt-stream/src/main.c.

Definition at line 333 of file types.h.

GhosttyFormatterOption

enum GhosttyFormatterOption

Formatter options, set with ghostty_formatter_set() and read with ghostty_formatter_get().

A new formatter emits plain text with trailing whitespace trimmed. To change that, call ghostty_formatter_set() with a GhosttyFormatterOption and a pointer to the new value. Options stay set across format calls, and a change takes effect on the next one. ghostty_formatter_get() reads an option back.

Option	Value type	Default
GHOSTTY_FORMATTER_OPT_EMIT	GhosttyFormatterFormat	GHOSTTY_FORMATTER_FORMAT_PLAIN
GHOSTTY_FORMATTER_OPT_UNWRAP	bool	false
GHOSTTY_FORMATTER_OPT_TRIM	bool	true
GHOSTTY_FORMATTER_OPT_SELECTION	GhosttySelection	None (the whole screen)
GHOSTTY_FORMATTER_OPT_EXTRAS	GhosttyFormatterExtras	GHOSTTY_FORMATTER_EXTRAS_DEFAULT

Each option lists the type its value points to. To set an option, pass a pointer to a value of that type. To read one, pass a pointer to a variable of that type and the formatter writes the current value there.

Enumerator
GHOSTTY_FORMATTER_OPT_INVALID	Not an option. Setting or reading it returns GHOSTTY_INVALID_VALUE.
GHOSTTY_FORMATTER_OPT_EMIT	The output format: plain text, VT sequences, or HTML. Value type: GhosttyFormatterFormat. Default: GHOSTTY_FORMATTER_FORMAT_PLAIN.
GHOSTTY_FORMATTER_OPT_UNWRAP	Join lines that wrapped because they were too long for the screen. When false, each row of the screen is its own line in the output. When true, a line the terminal wrapped onto several rows comes out as one line, the way the program originally wrote it. Value type: bool. Default: false.
GHOSTTY_FORMATTER_OPT_TRIM	Remove spaces from the end of each line that has other text. Blank lines at the end of the output are always removed. The one exception is VT output with trimming turned off, which keeps them so the output fills the same rows as the screen. Value type: bool. Default: true.
GHOSTTY_FORMATTER_OPT_SELECTION	Format only the content inside a selection. The formatter keeps its own copy of the selection, so the GhosttySelection you pass doesn't need to stay around. Like any selection, the copy is only valid until the next call that changes the terminal. After the terminal changes, set the selection again before you format, or clear it. Set NULL to clear the selection and format the whole screen again. When no selection is set, ghostty_formatter_get() returns GHOSTTY_NO_VALUE. To format the terminal's active selection, read it with GHOSTTY_TERMINAL_DATA_SELECTION and set it here. For the same text Ghostty copies to the clipboard, use plain output with GHOSTTY_FORMATTER_OPT_UNWRAP and GHOSTTY_FORMATTER_OPT_TRIM both true. // Format only the selected text. ghostty_formatter_set(formatter, GHOSTTY_FORMATTER_OPT_SELECTION, &selection); ghostty_formatter_format_alloc(formatter, NULL, &buf, &len); // Go back to formatting the whole screen. ghostty_formatter_set(formatter, GHOSTTY_FORMATTER_OPT_SELECTION, NULL); Value type: GhosttySelection. Default: none, so the whole screen is formatted.
GHOSTTY_FORMATTER_OPT_EXTRAS	Terminal state to add to VT output. See GhosttyFormatterExtras. Value type: GhosttyFormatterExtras. Default: GHOSTTY_FORMATTER_EXTRAS_DEFAULT.

Definition at line 141 of file formatter.h.

Function Documentation

ghostty_formatter_format()

GHOSTTY_API GhosttyResult ghostty_formatter_format	(	GhosttyFormatter	formatter,
		GhosttyWriter	writer )

Run the formatter and stream output to a writer.

Each call formats the current terminal state and invokes the writer synchronously as output becomes available. The callback may be called more than once and must not call formatter or terminal APIs using the same formatter or its terminal.

If an error occurs, the writer may already contain a partial formatted output. The operation cannot be resumed from that partial output. This function does not flush or make your destination durable.

Parameters

formatter	The formatter handle (must not be NULL)
writer	Destination writer whose write callback must not be NULL

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_IO_ERROR if the writer rejects output, GHOSTTY_LIMIT_EXCEEDED if output accounting overflows, or GHOSTTY_INVALID_VALUE if an argument is invalid

Examples

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

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). You are responsible for freeing the returned buffer with ghostty_free(), passing the same allocator (or NULL for the default) that was used for the allocation. Empty output returns GHOSTTY_SUCCESS with *out_ptr set to NULL and *out_len set to zero. This result can be passed to ghostty_free().

Parameters

formatter	The formatter handle (must not be NULL)
allocator	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-cmake-cross/src/main.c, c-vt-cmake-static/src/main.c, c-vt-cmake/src/main.c, c-vt-hello/src/main.c, c-vt-selection-gesture/src/main.c, c-vt-selection/src/main.c, and c-vt-stream/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 your 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. You 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-cmake-cross/src/main.c, c-vt-cmake-static/src/main.c, c-vt-cmake/src/main.c, c-vt-formatter/src/main.c, c-vt-hello/src/main.c, c-vt-selection-gesture/src/main.c, c-vt-selection/src/main.c, and c-vt-stream/src/main.c.

ghostty_formatter_get()

GHOSTTY_API GhosttyResult ghostty_formatter_get	(	GhosttyFormatter	formatter,
		GhosttyFormatterOption	option,
		void *	out )

Read the current value of a formatter option.

out points to a variable of the type listed on the option. On success the formatter writes the option's value there.

bool trim;
ghostty_formatter_get(formatter, GHOSTTY_FORMATTER_OPT_TRIM, &trim);

Parameters

formatter	The formatter handle (must not be NULL)
option	The option to read
out	Pointer that receives the value (must not be NULL)

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_NO_VALUE if the option is not set (only possible for GHOSTTY_FORMATTER_OPT_SELECTION), GHOSTTY_INVALID_VALUE if Formatter or out is NULL, or GHOSTTY_UNSUPPORTED if option is not known to this version of the library

ghostty_formatter_set()

GHOSTTY_API GhosttyResult ghostty_formatter_set	(	GhosttyFormatter	formatter,
		GhosttyFormatterOption	option,
		const void *	value )

Set a formatter option.

value points to the option's new value. Its type is listed on each GhosttyFormatterOption. The formatter copies the value, so it only has to be valid during the call. The change applies to every format call after this one.

Passing NULL for value puts the option back to its default, the same value a new formatter starts with.

GhosttyFormatterFormat emit = GHOSTTY_FORMATTER_FORMAT_HTML;
ghostty_formatter_set(formatter, GHOSTTY_FORMATTER_OPT_EMIT, &emit);
 
// Later, go back to the default (plain text).
ghostty_formatter_set(formatter, GHOSTTY_FORMATTER_OPT_EMIT, NULL);

If the call fails, the option keeps its previous value.

Parameters

formatter	The formatter handle (must not be NULL)
option	The option to set
value	Pointer to the new value, or NULL to reset the option to its default

Returns

GHOSTTY_SUCCESS on success, GHOSTTY_INVALID_VALUE if Formatter is NULL or the value is not valid for the option (such as an unknown format, an extras bit with no meaning, or a selection with a zeroed grid reference), or GHOSTTY_UNSUPPORTED if option is not known to this version of the library

Examples

c-vt-cmake-cross/src/main.c, c-vt-cmake-static/src/main.c, c-vt-cmake/src/main.c, c-vt-formatter/src/main.c, c-vt-selection-gesture/src/main.c, c-vt-selection/src/main.c, and c-vt-stream/src/main.c.

ghostty_formatter_terminal_new()

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

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.

The new formatter starts with the default for every option, as listed on GhosttyFormatterOption. Change them with ghostty_formatter_set().

Parameters

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

Returns

GHOSTTY_SUCCESS on success, or an error code on failure

Examples

c-vt-cmake-cross/src/main.c, c-vt-cmake-static/src/main.c, c-vt-cmake/src/main.c, c-vt-formatter/src/main.c, c-vt-hello/src/main.c, c-vt-selection-gesture/src/main.c, c-vt-selection/src/main.c, and c-vt-stream/src/main.c.

Macro Definition Documentation

GHOSTTY_FORMATTER_EXTRA_CHARSETS

#define GHOSTTY_FORMATTER_EXTRA_CHARSETS   (1u << 11)

Restore the character sets, such as the line drawing set.

Definition at line 100 of file formatter.h.

GHOSTTY_FORMATTER_EXTRA_CURSOR

#define GHOSTTY_FORMATTER_EXTRA_CURSOR   (1u << 6)

Restore the cursor position with CUP.

Definition at line 90 of file formatter.h.

GHOSTTY_FORMATTER_EXTRA_HYPERLINK

#define GHOSTTY_FORMATTER_EXTRA_HYPERLINK   (1u << 8)

Restore the hyperlink the cursor writes new text with, using OSC 8.

Definition at line 94 of file formatter.h.

GHOSTTY_FORMATTER_EXTRA_KEYBOARD

#define GHOSTTY_FORMATTER_EXTRA_KEYBOARD   (1u << 5)

Restore keyboard modes such as modifyOtherKeys.

Definition at line 88 of file formatter.h.

GHOSTTY_FORMATTER_EXTRA_KITTY_KEYBOARD

#define GHOSTTY_FORMATTER_EXTRA_KITTY_KEYBOARD   (1u << 10)

Restore the Kitty keyboard protocol flags.

Definition at line 98 of file formatter.h.

GHOSTTY_FORMATTER_EXTRA_MODES

#define GHOSTTY_FORMATTER_EXTRA_MODES   (1u << 1)

Restore terminal modes that differ from their defaults with CSI h and l.

Definition at line 80 of file formatter.h.

GHOSTTY_FORMATTER_EXTRA_PALETTE

#define GHOSTTY_FORMATTER_EXTRA_PALETTE   (1u << 0)

Restore the color palette with OSC 4.

Definition at line 78 of file formatter.h.

GHOSTTY_FORMATTER_EXTRA_PROTECTION

#define GHOSTTY_FORMATTER_EXTRA_PROTECTION   (1u << 9)

Restore character protection with DECSCA.

Definition at line 96 of file formatter.h.

GHOSTTY_FORMATTER_EXTRA_PWD

#define GHOSTTY_FORMATTER_EXTRA_PWD   (1u << 4)

Restore the working directory with OSC 7.

Definition at line 86 of file formatter.h.

GHOSTTY_FORMATTER_EXTRA_SCROLLING_REGION

#define GHOSTTY_FORMATTER_EXTRA_SCROLLING_REGION   (1u << 2)

Restore the scrolling region with DECSTBM and DECSLRM.

Definition at line 82 of file formatter.h.

GHOSTTY_FORMATTER_EXTRA_STYLE

#define GHOSTTY_FORMATTER_EXTRA_STYLE   (1u << 7)

Restore the style the cursor writes new text with, using SGR.

Definition at line 92 of file formatter.h.

GHOSTTY_FORMATTER_EXTRA_TABSTOPS

#define GHOSTTY_FORMATTER_EXTRA_TABSTOPS   (1u << 3)

Restore tab stops by clearing them all and setting each one again.

Definition at line 84 of file formatter.h.

GHOSTTY_FORMATTER_EXTRAS_ALL

#define GHOSTTY_FORMATTER_EXTRAS_ALL   0xFFFu

Every extra.

Definition at line 106 of file formatter.h.

GHOSTTY_FORMATTER_EXTRAS_DEFAULT

#define GHOSTTY_FORMATTER_EXTRAS_DEFAULT

Value:

(GHOSTTY_FORMATTER_EXTRA_PALETTE | GHOSTTY_FORMATTER_EXTRA_STYLE |         \
 GHOSTTY_FORMATTER_EXTRA_HYPERLINK)

The extras a new formatter starts with: the palette, the cursor style and the cursor hyperlink. These are the extras that affect how output looks.

Definition at line 113 of file formatter.h.

GHOSTTY_FORMATTER_EXTRAS_NONE

#define GHOSTTY_FORMATTER_EXTRAS_NONE   0u

No extras. VT output has only the text and its styles.

Definition at line 103 of file formatter.h.