Helpers for writing to stdout / stderr with optional ANSI styling. More...

Modules
	Terminal colour flags
	Packed foreground / background / attribute bits for terminal styling.

Macros
#define	R_TTY_MAX_CC 32
	Maximum length of a colour-control escape produced by r_tty_clr_to_str.

#define	R_TTY_CSI "\x1B["
	ANSI Control Sequence Introducer: `"ESC["`.

#define	R_TTY_SGR1(param) R_TTY_CSI param "m"
	Build a 1-parameter SGR escape.

#define	R_TTY_SGR_RESET R_TTY_SGR1 (R_TTY_SGR_CLS_ARG)
	Reset all SGR attributes.

#define	R_TTY_SGR(P1) R_TTY_SGR1 (P1)
	Alias for R_TTY_SGR1.

#define	R_TTY_SGR2(P1, P2) R_TTY_SGR1 (P1";"P2)
	2-parameter SGR escape.

#define	R_TTY_SGR3(P1, P2, P3) R_TTY_SGR1 (P1";"P2";"P3)
	3-parameter SGR escape.

#define	R_TTY_SGR4(P1, P2, P3, P4) R_TTY_SGR1 (P1";"P2";"P3";"P4)
	4-parameter SGR escape.

#define	r_isatty isatty

#define	r_fileno fileno

#define	r_printf printf
	Alias for C-library `printf`.

#define	r_vprintf vprintf
	Alias for C-library `vprintf`.

#define	r_fprintf fprintf
	Alias for C-library `fprintf`.

#define	r_vfprintf vfprintf
	Alias for C-library `vfprintf`.

Typedefs
typedef rboolean(*	RPrintFunc) (const rchar *str, rsize size, rpointer data)
	Print-sink signature: receive a chunk of text and decide how to handle it (write to stdio, append to a buffer, ...).

Functions
rchar *	r_tty_clr_to_str (RColorFlags clr, rchar str[R_TTY_MAX_CC])
	Render a colour-flag bitmask into a CSI escape sequence.

int	r_print (const rchar *fmt,...)
	Print to stdout via the currently-installed print handler.

int	r_printerr (const rchar *fmt,...)
	Print to stderr via the currently-installed printerr handler.

void	r_override_print_handler (RPrintFunc func, rpointer data, RPrintFunc oldfunc, rpointer olddata)
	Install a new sink for r_print.

void	r_override_printerr_handler (RPrintFunc func, rpointer data, RPrintFunc oldfunc, rpointer olddata)
	Like r_override_print_handler but for r_printerr.

rboolean	r_print_default (const rchar *str, rsize size, rpointer data)
	Default stdout sink (writes via the C library).

rboolean	r_printerr_default (const rchar *str, rsize size, rpointer data)
	Default stderr sink (writes via the C library).

SGR parameter tokens
String literals that name the standard SGR codes; combine into escape sequences with R_TTY_SGR* macros.
#define	R_TTY_SGR_CLS_ARG "0"

#define	R_TTY_SGR_BOLD_ARG "1"

#define	R_TTY_SGR_NOBOLD_ARG "21"

#define	R_TTY_SGR_FAINT_ARG "2"

#define	R_TTY_SGR_NORMAL_ARG "22"

#define	R_TTY_SGR_ITALIC_ARG "3"

#define	R_TTY_SGR_NOITALIC_ARG "23"

#define	R_TTY_SGR_UNDERLINE_ARG "4"

#define	R_TTY_SGR_NOUNDERLINE_ARG "24"

#define	R_TTY_SGR_BLINK_ARG "5"

#define	R_TTY_SGR_NOBLINK_ARG "25"

#define	R_TTY_SGR_INVERSE_ARG "7"

#define	R_TTY_SGR_NOINVERSE_ARG "27"

#define	R_TTY_SGR_CONCEAL_ARG "8"

#define	R_TTY_SGR_REVEAL_ARG "28"

#define	R_TTY_SGR_FG_ARG(CLR) "3"R_STRINGIFY (CLR)
	Build a foreground colour token (30-39).

#define	R_TTY_SGR_BG_ARG(CLR) "4"R_STRINGIFY (CLR)
	Build a background colour token (40-49).

Detailed Description

Helpers for writing to stdout / stderr with optional ANSI styling.

Two layers:

Macros that build SGR ("Select Graphic Rendition") escape sequences at compile time (R_TTY_SGR / R_TTY_SGR_RESET and the R_TTY_SGR_*_ARG token constants).
Function wrappers around the C-library print/printerr that flow through swappable sinks (r_override_print_handler) so the application can capture or redirect output.

The colour-flag conversion helper r_tty_clr_to_str renders a RColorFlags bitmask into a complete CSI escape ready to write.

Macro Definition Documentation

◆ R_TTY_SGR_BLINK_ARG

#define R_TTY_SGR_BLINK_ARG "5"

Blink.

◆ R_TTY_SGR_BOLD_ARG

#define R_TTY_SGR_BOLD_ARG "1"

Bold.

◆ R_TTY_SGR_CLS_ARG

#define R_TTY_SGR_CLS_ARG "0"

Reset / clear all attributes.

◆ R_TTY_SGR_CONCEAL_ARG

#define R_TTY_SGR_CONCEAL_ARG "8"

Conceal.

◆ R_TTY_SGR_FAINT_ARG

#define R_TTY_SGR_FAINT_ARG "2"

Faint.

◆ R_TTY_SGR_INVERSE_ARG

#define R_TTY_SGR_INVERSE_ARG "7"

Swap foreground / background.

◆ R_TTY_SGR_ITALIC_ARG

#define R_TTY_SGR_ITALIC_ARG "3"

Italic.

◆ R_TTY_SGR_NOBLINK_ARG

#define R_TTY_SGR_NOBLINK_ARG "25"

Cancel BLINK.

◆ R_TTY_SGR_NOBOLD_ARG

#define R_TTY_SGR_NOBOLD_ARG "21"

Cancel BOLD.

◆ R_TTY_SGR_NOINVERSE_ARG

#define R_TTY_SGR_NOINVERSE_ARG "27"

Cancel INVERSE.

◆ R_TTY_SGR_NOITALIC_ARG

#define R_TTY_SGR_NOITALIC_ARG "23"

Cancel ITALIC.

◆ R_TTY_SGR_NORMAL_ARG

#define R_TTY_SGR_NORMAL_ARG "22"

Normal intensity (cancel FAINT/BOLD).

◆ R_TTY_SGR_NOUNDERLINE_ARG

#define R_TTY_SGR_NOUNDERLINE_ARG "24"

Cancel UNDERLINE.

◆ R_TTY_SGR_REVEAL_ARG

#define R_TTY_SGR_REVEAL_ARG "28"

Cancel CONCEAL.

◆ R_TTY_SGR_UNDERLINE_ARG

#define R_TTY_SGR_UNDERLINE_ARG "4"

Underline.

Typedef Documentation

◆ RPrintFunc

typedef rboolean(* RPrintFunc) (const rchar *str, rsize size, rpointer data)

Print-sink signature: receive a chunk of text and decide how to handle it (write to stdio, append to a buffer, ...).

Returns: TRUE on success, FALSE to signal an error to the caller.

Function Documentation

◆ r_override_print_handler()

void r_override_print_handler	(	RPrintFunc	func,
		rpointer	data,
		RPrintFunc *	oldfunc,
		rpointer *	olddata
	)

Install a new sink for r_print.

Installing or swapping a sink is atomic with respect to concurrent r_print calls: a reader never observes a new func paired with a previous data. The sink runs outside any lock, however, so a call already in flight may still invoke the previous sink after this returns — data's lifetime is the caller's responsibility. Keep it valid for as long as the sink may be invoked: install before concurrent use, or quiesce printing before freeing replaced data.

Parameters

func	New sink, or `NULL` to restore the default.
data	Opaque pointer forwarded to `func` on every call.
oldfunc	Optional out-pointer: receives the previously-installed sink.
olddata	Optional out-pointer: receives the previous `data`.

◆ r_print()

int r_print	(	const rchar *	fmt,
			...
	)

Print to stdout via the currently-installed print handler.

Returns: Number of bytes written, or -1 on error.

◆ r_printerr()

int r_printerr	(	const rchar *	fmt,
			...
	)

Print to stderr via the currently-installed printerr handler.

Returns: Number of bytes written, or -1 on error.

◆ r_tty_clr_to_str()

rchar * r_tty_clr_to_str	(	RColorFlags	clr,
		rchar	str[R_TTY_MAX_CC]
	)

Render a colour-flag bitmask into a CSI escape sequence.