Utils Namespace Reference

TUI utility functions and constants. More...

Namespaces
namespace	Colours
	ANSI SGR (Select Graphic Rendition) code constants and escape sequence builder.

Functions
bool	stdinReady (int timeout_ms)
	Poll stdin for available data within a timeout.
std::string	stripAnsi (const std::string &s)
	Remove all ANSI escape sequences from a string.
size_t	visualWidth (const std::string &s)
	Compute the visual (display) column width of a UTF-8 string.
Defs::Key	handleEscapeKey ()
	Decode an escape sequence whose leading ESC byte has already been consumed.
Defs::Key	readKey ()
	Read a single keypress from stdin (terminal must be in raw mode).

Detailed Description

TUI utility functions and constants.

Function Documentation

handleEscapeKey()

Defs::Key Utils::handleEscapeKey ( )

inline

Decode an escape sequence whose leading ESC byte has already been consumed.

Polls stdin for the next byte (50 ms timeout). If it reads '[' it polls again for the final letter and maps it to an arrow key via a static lookup table. Any unrecognised sequence or timeout returns Defs::Special::Escape.

Returns

The decoded Defs::Key — one of Defs::Special::Up, Defs::Special::Down, Defs::Special::Left, Defs::Special::Right, or Defs::Special::Escape.

Here is the call graph for this function:

Here is the caller graph for this function:

readKey()

Defs::Key Utils::readKey ( )

inline

Read a single keypress from stdin (terminal must be in raw mode).

Reads one byte and maps it to the appropriate Defs::Key variant:

• \r / \n → Defs::Special::Enter
• 0x1B (ESC) → delegates to handleEscapeKey
• 0x7F / 0x08 → Defs::Special::Backspace
• \t → Defs::Special::Tab
• Any other byte → char variant

Returns

The decoded Defs::Key.

Note

Requires an active Terminal instance (raw mode + cursor hidden). The return value of the underlying read(2) call is intentionally discarded; errors are left to the caller's event loop to detect via subsequent stdinReady checks.

Here is the call graph for this function:

Here is the caller graph for this function:

stdinReady()

bool Utils::stdinReady ( int  timeout_ms )

inline

Poll stdin for available data within a timeout.

Uses poll(2) on POSIX to avoid blocking indefinitely when checking for the second byte of a multi-byte escape sequence. Always returns true on Windows (where poll is not readily available).

Parameters

timeout_ms

Maximum wait time in milliseconds. Pass 0 for a non-blocking check.

Returns

true if at least one byte is ready to read from STDIN_FILENO.

Here is the caller graph for this function:

stripAnsi()

std::string Utils::stripAnsi ( const std::string &  s )

inline

Remove all ANSI escape sequences from a string.

Scans s character-by-character and discards everything between an ESC (0x1B) and the subsequent alphabetic terminator.

Parameters

s	A string that may contain ESC[…m ANSI colour/style codes.

Returns

The plain-text content of s with all escape sequences stripped.

Here is the caller graph for this function:

visualWidth()

size_t Utils::visualWidth ( const std::string &  s )

inline

Compute the visual (display) column width of a UTF-8 string.

Strips ANSI escape codes first, then converts the result to a wide-character string and calls POSIX wcswidth(3) to obtain the number of terminal columns the string occupies (accounting for double-width CJK characters, zero-width combining marks, etc.).

Parameters

s	A UTF-8 string, possibly containing ANSI escape sequences.

Returns

Number of terminal columns the visible content of s occupies. Falls back to the character count if wcswidth returns a negative value (e.g. when the string contains non-printable wide characters).

Note

Currently POSIX-only. A cross-platform alternative using utf8proc is planned (see the TODO comment in the implementation).

Here is the call graph for this function:

Here is the caller graph for this function: