Terminal output and input helper. More...

#include <kaycxx/term/terminal.hpp>

Public Member Functions
	terminal (std::ostream &stream=std::cout, ansi_mode mode=ansi_mode::automatic)
	Creates a terminal helper for an output stream.

	~terminal ()
	Destroys the terminal helper.

	terminal (terminal const &)=delete

terminal &	operator= (terminal const &)=delete

	terminal (terminal &&)=delete

terminal &	operator= (terminal &&)=delete

template<typename T >
terminal &	operator<< (T const &value)
	Writes a raw stream value.

terminal &	operator<< (sgr value)
	Writes an SGR style command.

terminal &	operator<< (color_style value)
	Writes a foreground or background color style.

terminal &	operator<< (hyperlink const &link)
	Writes a terminal hyperlink.

terminal &	operator<< (std::ostream &(*manipulator)(std::ostream &))
	Writes an ostream manipulator.

terminal &	operator<< (std::ios &(*manipulator)(std::ios &))
	Writes an ios manipulator.

terminal &	operator<< (std::ios_base &(*manipulator)(std::ios_base &))
	Writes an ios_base manipulator.

void	clear_screen ()
	Clears the visible screen without moving the cursor.

void	clear_screen_to_end ()
	Clears from the cursor position to the end of the screen.

void	clear_screen_to_start ()
	Clears from the beginning of the screen to the cursor position.

void	clear_scrollback ()
	Clears the terminal scrollback buffer when supported by the terminal.

void	clear_line ()
	Clears the current line without moving the cursor.

void	clear_line_to_end ()
	Clears from the cursor position to the end of the current line.

void	clear_line_to_start ()
	Clears from the beginning of the current line to the cursor position.

void	push_title (std::string_view title)
	Pushes the current terminal title and sets a new title.

void	pop_title ()
	Pops the previously pushed terminal title.

void	hide_cursor ()
	Hides the terminal cursor.

void	show_cursor ()
	Shows the terminal cursor.

void	save_cursor ()
	Saves the current cursor position.

void	restore_cursor ()
	Restores the previously saved cursor position.

void	set_cursor_style (cursor_style style)
	Sets the terminal cursor style.

void	move_to (int column, int row)
	Moves the cursor to an absolute position.

void	move_by (int columns, int rows)
	Moves the cursor relative to its current position.

void	move_to_column (int column)
	Moves the cursor to a column on the current row.

void	enable_wrap ()
	Enables terminal autowrap mode.

void	disable_wrap ()
	Disables terminal autowrap mode.

void	enter_alternate_screen ()
	Enters the alternate screen buffer.

void	leave_alternate_screen ()
	Leaves the alternate screen buffer.

terminal_size	size () const
	Returns the current terminal size.

bool	push_input_mode (input_mode mode)
	Pushes the current input state and applies a new input mode.

bool	pop_input_mode ()
	Pops and restores the previously pushed input state.

std::string	read_key ()
	Reads one key from the terminal.

void	insert_line ()
	Inserts a single line at the cursor row.

void	insert_lines (int lines)
	Inserts multiple lines at the cursor row.

void	delete_line ()
	Deletes a single line at the cursor row.

void	delete_lines (int lines)
	Deletes multiple lines at the cursor row.

void	clear_cell ()
	Clears a cell at the cursor position.

void	clear_cells (int cells)
	Clears cells at the cursor position.

void	insert_cell ()
	Inserts a blank cell at the cursor position.

void	insert_cells (int cells)
	Inserts blank cells at the cursor position.

void	delete_cell ()
	Deletes a cell at the cursor position.

void	delete_cells (int cells)
	Deletes cells at the cursor position.

void	set_scroll_region (int top, int bottom)
	Sets the vertical scrolling region.

void	reset_scroll_region ()
	Resets the vertical scrolling region to the whole screen.

void	scroll_up ()
	Scrolls the current scrolling region up by one line.

void	scroll_up (int lines)
	Scrolls the current scrolling region up by multiple lines.

void	scroll_down ()
	Scrolls the current scrolling region down by one line.

void	scroll_down (int lines)
	Scrolls the current scrolling region down by multiple lines.

bool	formatting_enabled () const noexcept
	Checks whether ANSI/VT formatting is enabled for this terminal.

bool	commands_enabled () const noexcept
	Checks whether ANSI/VT terminal commands are enabled for this terminal.

Detailed Description

Terminal output and input helper.

The terminal writes ANSI/VT formatting and terminal commands when enabled and provides minimal cross-platform input mode and key reading helpers.

Constructor & Destructor Documentation

◆ terminal()

kaycxx::term::terminal::terminal	(	std::ostream &	stream = `std::cout`,
		ansi_mode	mode = `ansi_mode::automatic`
	)

explicit

Creates a terminal helper for an output stream.

The stream defaults to std::cout. All text and all ANSI/VT output is written to this stream. In automatic ANSI mode, the stream is used to detect terminal command support while FORCE_COLOR and NO_COLOR independently control formatting.

Parameters

stream	Output stream to write to. The stream must outlive the terminal.
mode	ANSI output mode. Automatic mode detects terminal commands and separately honors `FORCE_COLOR` and `NO_COLOR` for formatting.

Member Function Documentation

◆ clear_cell()

void kaycxx::term::terminal::clear_cell ( )

Clears a cell at the cursor position.

The current cell is replaced with a blank cell. Text to the right is not shifted and the cursor stays at its position.

◆ clear_cells()

void kaycxx::term::terminal::clear_cells ( int cells )

Clears cells at the cursor position.

The cells are replaced with blank cells. Text to the right is not shifted and the cursor stays at its position. Nothing is written when the cell count is zero or negative.

Parameters

cells Number of cells to clear.

◆ commands_enabled()

bool kaycxx::term::terminal::commands_enabled ( ) const

noexcept

Checks whether ANSI/VT terminal commands are enabled for this terminal.

Terminal commands include cursor movement, screen manipulation, title changes, hyperlinks, and terminal modes. Color environment variables do not affect this state.

Returns: True when ANSI/VT terminal commands are emitted.

◆ delete_cell()

void kaycxx::term::terminal::delete_cell ( )

Deletes a cell at the cursor position.

Existing text to the right is shifted left within the current line.

◆ delete_cells()

void kaycxx::term::terminal::delete_cells ( int cells )

Deletes cells at the cursor position.

Existing text to the right is shifted left within the current line. Nothing is written when the cell count is zero or negative.

Parameters

cells Number of cells to delete.

◆ delete_lines()

void kaycxx::term::terminal::delete_lines ( int lines )

Deletes multiple lines at the cursor row.

Nothing is written when the line count is zero or negative.

Parameters

lines Number of lines to delete.

◆ formatting_enabled()

bool kaycxx::term::terminal::formatting_enabled ( ) const

noexcept

Checks whether ANSI/VT formatting is enabled for this terminal.

Formatting includes colors and SGR text styles. This returns the resolved formatting state from the constructor, not the raw ansi_mode value.

Returns: True when ANSI/VT formatting is emitted.

◆ insert_cell()

void kaycxx::term::terminal::insert_cell ( )

Inserts a blank cell at the cursor position.

Existing text to the right is shifted right within the current line.

◆ insert_cells()

void kaycxx::term::terminal::insert_cells ( int cells )

Inserts blank cells at the cursor position.

Existing text to the right is shifted right within the current line. Nothing is written when the cell count is zero or negative.

Parameters

cells Number of cells to insert.

◆ insert_lines()

void kaycxx::term::terminal::insert_lines ( int lines )

Inserts multiple lines at the cursor row.

Nothing is written when the line count is zero or negative.

Parameters

lines Number of lines to insert.

◆ move_by()

void kaycxx::term::terminal::move_by	(	int	columns,
		int	rows
	)

Moves the cursor relative to its current position.

Positive columns move right, negative columns move left. Positive rows move down, negative rows move up.

Parameters

columns	Relative column movement.
rows	Relative row movement.

◆ move_to()

void kaycxx::term::terminal::move_to	(	int	column,
		int	row
	)

Moves the cursor to an absolute position.

Coordinates are one-based terminal coordinates.

Parameters

column	Target column.
row	Target row.

◆ move_to_column()

void kaycxx::term::terminal::move_to_column ( int column )

Moves the cursor to a column on the current row.

Parameters

column Target column.

◆ operator<<() [1/7]

terminal & kaycxx::term::terminal::operator<< ( color_style value )

Writes a foreground or background color style.

Parameters

value Color style to write.

Returns: This terminal.

◆ operator<<() [2/7]

terminal & kaycxx::term::terminal::operator<< ( hyperlink const & link )

Writes a terminal hyperlink.

Parameters

link	Hyperlink to write.

Returns: This terminal.

◆ operator<<() [3/7]

terminal & kaycxx::term::terminal::operator<< ( sgr value )

Writes an SGR style command.

Parameters

value SGR command to write.

Returns: This terminal.

◆ operator<<() [4/7]

terminal & kaycxx::term::terminal::operator<< ( std::ios &(*)(std::ios &) manipulator )

Writes an ios manipulator.

Parameters

manipulator Manipulator to apply.

Returns: This terminal.

◆ operator<<() [5/7]

terminal & kaycxx::term::terminal::operator<< ( std::ios_base &(*)(std::ios_base &) manipulator )

Writes an ios_base manipulator.

Parameters

manipulator Manipulator to apply.

Returns: This terminal.

◆ operator<<() [6/7]

terminal & kaycxx::term::terminal::operator<< ( std::ostream &(*)(std::ostream &) manipulator )

Writes an ostream manipulator.

Parameters

manipulator Manipulator to apply.

Returns: This terminal.

◆ operator<<() [7/7]

template<typename T >

terminal & kaycxx::term::terminal::operator<< ( T const & value )

inline

Writes a raw stream value.

This overload forwards the value unchanged to the wrapped stream.

Template Parameters

T	Value type to write.

Parameters

value Value to write.

Returns: This terminal.

◆ pop_input_mode()

bool kaycxx::term::terminal::pop_input_mode ( )

Pops and restores the previously pushed input state.

Returns: True when a previous input state was restored.

◆ push_input_mode()

bool kaycxx::term::terminal::push_input_mode ( input_mode mode )

Pushes the current input state and applies a new input mode.

Parameters

mode	Input mode to apply.

Returns: True when the input state was saved and the requested mode was applied.

◆ push_title()

void kaycxx::term::terminal::push_title ( std::string_view title )

Pushes the current terminal title and sets a new title.

Parameters

title New terminal title.

◆ read_key()

std::string kaycxx::term::terminal::read_key ( )

Reads one key from the terminal.

The returned string contains the raw key byte sequence. POSIX terminals return their native byte sequences. Windows console key events are mapped to POSIX-style escape sequences for cursor and function keys.

Returns: Raw key byte sequence, or an empty string on failure.

◆ scroll_down()

void kaycxx::term::terminal::scroll_down ( int lines )

Scrolls the current scrolling region down by multiple lines.

Nothing is written when the line count is zero or negative.

Parameters

lines Number of lines to scroll.

◆ scroll_up()

void kaycxx::term::terminal::scroll_up ( int lines )

Scrolls the current scrolling region up by multiple lines.

Nothing is written when the line count is zero or negative.

Parameters

lines Number of lines to scroll.

◆ set_cursor_style()

void kaycxx::term::terminal::set_cursor_style ( cursor_style style )

Sets the terminal cursor style.

Parameters

style Cursor style to apply.

◆ set_scroll_region()

void kaycxx::term::terminal::set_scroll_region	(	int	top,
		int	bottom
	)

Sets the vertical scrolling region.

Coordinates are one-based terminal rows. Nothing is written when the range is invalid.

Parameters

top	First row in the scrolling region.
bottom	Last row in the scrolling region.

◆ size()

terminal_size kaycxx::term::terminal::size ( ) const

Returns the current terminal size.

Returns: Terminal size, or zero columns and rows when the size could not be read.

The documentation for this class was generated from the following file:

kaycxx/term/terminal.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ terminal()

Member Function Documentation

◆ clear_cell()

◆ clear_cells()

◆ commands_enabled()

◆ delete_cell()

◆ delete_cells()

◆ delete_lines()

◆ formatting_enabled()

◆ insert_cell()

◆ insert_cells()

◆ insert_lines()

◆ move_by()

◆ move_to()

◆ move_to_column()

◆ operator<<() [1/7]

◆ operator<<() [2/7]

◆ operator<<() [3/7]

◆ operator<<() [4/7]

◆ operator<<() [5/7]

◆ operator<<() [6/7]

◆ operator<<() [7/7]

◆ pop_input_mode()

◆ push_input_mode()

◆ push_title()

◆ read_key()

◆ scroll_down()

◆ scroll_up()

◆ set_cursor_style()

◆ set_scroll_region()

◆ size()