Module terminal

Terminal library for Lua.

This terminal library builds upon the cross-platform terminal capabilities of LuaSystem. As such it works modern terminals on Windows, Unix, and Mac systems.

It provides a simple and consistent interface to the terminal, allowing for cursor positioning, cursor shape and visibility, text formatting, clearing the screen, scrolling, and more.

For generic instruction please read the introduction.

Info:

  • Copyright: Copyright (c) 2024-2024 Thijs Schreijer
  • License: MIT, see LICENSE.md.
  • Author: Thijs Schreijer

Functions

sequence (...) Create a new sequence object.

stream

flush () Flushes the stream.
print (...) Prints to the stream in chunks.
write (...) Writes to the stream in chunks.

Cursor shapes and visibility

beep () Write a sequence to the terminal to make it beep.
beeps () Returns a string sequence to make the terminal beep.
readansi (timeout[, fsleep]) Same as sys.readansi, but works with the buffer required by terminal.lua.
ready () Returns whether the terminal has been initialized and is ready for use.

cursor_shapes

shape (shape) Sets the cursor shape and writes it to the terminal.
shapes (shape) Returns the ansi sequence for a cursor shape without writing it to the terminal.
visible (visible) Shows or hides the cursor and writes it to the terminal.
visibles (visible) Returns the ansi sequence to show/hide the cursor without writing it to the terminal.

cursor_shape_stack

shape_apply () Re-applies the shape at the top of the stack, and writes it to the terminal.
shape_applys () Re-applies the shape at the top of the stack (returns it, does not write it to the terminal).
shape_pop ([n=1]) Pops n cursor shape(s) off the stack, and writes the last one to the terminal.
shape_pops ([n=1]) Pops n cursor shape(s) off the stack (and returns the last one), without writing it to the terminal.
shape_push (shape) Pushes a cursor shape onto the stack, and writes it to the terminal.
shape_pushs (shape) Pushes a cursor shape onto the stack (and returns it), without writing it to the terminal.
visible_apply () Returns the ansi sequence to show/hide the cursor at the top of the stack, and writes it to the terminal.
visible_applys () Returns the ansi sequence to show/hide the cursor at the top of the stack without writing it to the terminal.
visible_pop ([n=1]) Pops n cursor visibility(ies) off the stack, and writes the last one to the terminal.
visible_pops ([n=1]) Pops n cursor visibility(ies) off the stack (and returns the last one), without writing it to the terminal.
visible_push (visible) Pushes a cursor visibility onto the stack, and writes it to the terminal.
visible_pushs (visible) Pushes a cursor visibility onto the stack (and returns it), without writing it to the terminal.

cursor_position

cursor_get () Requests the current cursor position from the terminal.
cursor_restore () Writes the ansi sequence to restore the cursor position (from the terminal storage, not stacked) to the terminal.
cursor_restores () Returns the ansi sequence to restore the cursor position (from the terminal storage, not stacked).
cursor_save () Writes the ansi sequence to store the current cursor position (in terminal storage, not stacked) to the terminal.
cursor_saves () Returns the ansi sequence to store to backup the current sursor position (in terminal storage, not stacked).
cursor_set (row, column) Sets the cursor position and writes it to the terminal, without pushing onto the stack.
cursor_sets (row, column) Creates ansi sequence to set the cursor position without writing to the terminal or pushing onto the stack.

cursor_position_stack

cursor_pop ([n=1]) Pops the last n cursor position off the stack, and writes an ansi sequence to move to the last one to the terminal.
cursor_pops ([n=1]) Pops the last n cursor positions off the stack, and returns an ansi sequence to move to the last one without writing it to the terminal.
cursor_push (row, column) Pushes the current cursor position onto the stack, and writes an ansi sequence to move to the new position to the terminal.
cursor_pushs (row, column) Pushes the current cursor position onto the stack, and returns an ansi sequence to move to the new position without writing it to the terminal.

cursor_moving

cursor_down ([n=1]) Moves the cursor down and writes it to the terminal.
cursor_downs ([n=1]) Creates an ansi sequence to move the cursor down without writing it to the terminal.
cursor_horizontal ([n=1]) Moves the cursor horizontally and writes it to the terminal.
cursor_horizontals ([n=1]) Creates an ansi sequence to move the cursor horizontally without writing it to the terminal.
cursor_left ([n=1]) Moves the cursor left and writes it to the terminal.
cursor_lefts ([n=1]) Creates an ansi sequence to move the cursor left without writing it to the terminal.
cursor_move ([rows=0[, columns=0]]) Moves the cursor horizontal and vertical and writes it to the terminal.
cursor_moves ([rows=0[, columns=0]]) Creates an ansi sequence to move the cursor horizontal and vertical without writing it to the terminal.
cursor_right ([n=1]) Moves the cursor right and writes it to the terminal.
cursor_rights ([n=1]) Creates an ansi sequence to move the cursor right without writing it to the terminal.
cursor_row_down ([rows=1]) Moves the cursor to the start of the next row and writes it to the terminal.
cursor_row_downs ([rows=1]) Creates an ansi sequence to move the cursor to the start of the next row without writing it to the terminal.
cursor_row_up ([rows=1]) Moves the cursor to the start of the previous row and writes it to the terminal.
cursor_row_ups ([rows=1]) Creates an ansi sequence to move the cursor to the start of the previous row without writing it to the terminal.
cursor_tocolumn (column) Moves the cursor to a column on the current row and writes it to the terminal.
cursor_tocolumns (column) Creates an ansi sequence to move the cursor to a column on the current row without writing it to the terminal.
cursor_torow (row) Moves the cursor to a row on the current column and writes it to the terminal.
cursor_torows (row) Creates an ansi sequence to move the cursor to a row on the current column without writing it to the terminal.
cursor_up ([n=1]) Moves the cursor up and writes it to the terminal.
cursor_ups ([n=1]) Creates an ansi sequence to move the cursor up without writing it to the terminal.
cursor_vertical ([n=1]) Moves the cursor vertically and writes it to the terminal.
cursor_verticals ([n=1]) Creates an ansi sequence to move the cursor vertically without writing it to the terminal.

clearing

clear () Clears the screen and writes it to the terminal.
clear_bottom () Clears the screen from the cursor position to the right and bottom and writes it to the terminal.
clear_bottoms () Creates an ansi sequence to clear the screen from the cursor position to the right and bottom without writing it to the terminal.
clear_box (height, width) Clears a box from the cursor position (top-left) and writes it to the terminal.
clear_boxs (height, width) Creates an ansi sequence to clear a box from the cursor position (top-left) without writing it to the terminal.
clear_end () Clears the line from the cursor position to the right and writes it to the terminal.
clear_ends () Creates an ansi sequence to clear the line from the cursor position to the right without writing it to the terminal.
clear_line () Clears the line and writes it to the terminal.
clear_lines () Creates an ansi sequence to clear the line without writing it to the terminal.
clear_start () Clears the line from the cursor position to the left and writes it to the terminal.
clear_starts () Creates an ansi sequence to clear the line from the cursor position to the left without writing it to the terminal.
clear_top () Clears the screen from the cursor position to the left and top and writes it to the terminal.
clear_tops () Creates an ansi sequence to clear the screen from the cursor position to the left and top without writing it to the terminal.
clears () Creates an ansi sequence to clear the screen without writing it to the terminal.

scrolling

scroll_ ([n=0]) Scrolls the screen vertically and writes it to the terminal.
scroll_down ([n=1]) Scrolls the screen down and writes it to the terminal.
scroll_downs ([n=1]) Creates an ansi sequence to scroll the screen down without writing it to the terminal.
scroll_region (top, bottom) Sets the scroll region and writes it to the terminal.
scroll_regions (top, bottom) Creates an ansi sequence to set the scroll region without writing it to the terminal.
scroll_s ([n=0]) Creates an ansi sequence to scroll the screen vertically without writing it to the terminal.
scroll_up ([n=1]) Scrolls the screen up and writes it to the terminal.
scroll_ups ([n=1]) Creates an ansi sequence to scroll the screen up without writing it to the terminal.

scrolling_region

scroll_apply () Applies the scroll region at the top of the stack, and writes it to the terminal.
scroll_applys () Applies the scroll region at the top of the stack (returns it, does not write it to the terminal).
scroll_pop ([n=1]) Pops n scroll region(s) off the stack, and writes the last to the terminal.
scroll_pops ([n=1]) Pops n scroll region(s) off the stack (and returns the last), without writing it to the terminal.
scroll_push (top, bottom) Pushes a new scroll region onto the stack, and writes it to the terminal.
scroll_pushs (top, bottom) Pushes a new scroll region onto the stack (and returns it), without writing it to the terminal.

textcolor

blink_off () Unsets the blink attribute and writes it to the terminal.
blink_offs () Creates an ansi sequence to unset the blink attribute without writing it to the terminal.
blink_on () Sets the blink attribute and writes it to the terminal.
blink_ons () Creates an ansi sequence to set the blink attribute without writing it to the terminal.
brightness (brightness) Sets the brightness and writes it to the terminal.
brightnesss (brightness) Creates an ansi sequence to set the brightness without writing it to the terminal.
color_bg (r[, g[, b]]) Sets the background color and writes it to the terminal.
color_bgs (r[, g[, b]]) Creates an ansi sequence to set the background color without writing it to the terminal.
color_fg (r[, g[, b]]) Sets the foreground color and writes it to the terminal.
color_fgs (r[, g[, b]]) Creates an ansi sequence to set the foreground color without writing it to the terminal.
reverse_off () Unsets the reverse attribute and writes it to the terminal.
reverse_offs () Creates an ansi sequence to unset the reverse attribute without writing it to the terminal.
reverse_on () Sets the reverse attribute and writes it to the terminal.
reverse_ons () Creates an ansi sequence to set the reverse attribute without writing it to the terminal.
underline_off () Unsets the underline attribute and writes it to the terminal.
underline_offs () Creates an ansi sequence to unset the underline attribute without writing it to the terminal.
underline_on () Sets the underline attribute and writes it to the terminal.
underline_ons () Creates an ansi sequence to set the underline attribute without writing it to the terminal.

textcolor_stack

textapply () Re-applies the current attributes, and writes it to the terminal.
textapplys () Re-applies the current attributes (returns it, does not write it to the terminal).
textpop ([n=1]) Pops n attributes off the stack, and writes the last one to the terminal.
textpops ([n=1]) Pops n attributes off the stack (and returns the last one), without writing it to the terminal.
textpush (attr) Pushes the current attributes onto the stack, and writes an ansi sequence to set the new attributes to the terminal.
textpushs (attr) Pushes the current attributes onto the stack, and returns an ansi sequence to set the new attributes without writing it to the terminal.
textset (attr) Sets the text attributes and writes it to the terminal.
textsets (attr) Creates an ansi sequence to set the text attributes without writing it to the terminal.

lines

box (height, width, format, clear[, title=""[, lastcolumn]]) Draws a box and writes it to the terminal.
box_fmt Table with pre-defined box formats.
box_fmt.copy (default) Copy a box format.
boxs (height, width[, format[, clear=" "[, title=""[, lastcolumn=""]]]]) Creates a sequence to draw a box, without writing it to the terminal.
line_horizontal (n[, char="─"]) Draws a horizontal line and writes it to the terminal.
line_horizontals (n[, char="─"]) Creates a sequence to draw a horizontal line without writing it to the terminal.
line_title (title, width[, char="─"[, pre=""[, post=""]]]) Draws a horizontal line with a title centered in it and writes it to the terminal.
line_titles (width[, title=""[, char="─"[, pre=""[, post=""]]]]) Creates a sequence to draw a horizontal line with a title centered in it without writing it to the terminal.
line_vertical (n[, char="│"]) Draws a vertical line and writes it to the terminal.
line_verticals (n[, char="│"[, lastcolumn]]) Creates a sequence to draw a vertical line without writing it to the terminal.

initialization

initialize ([opts]) Initializes the terminal for use.
initwrap ([opts], main, ...) Wrap a function in initialize and shutdown calls.
shutdown () Shuts down the terminal, restoring the terminal settings.


Functions

sequence (...)
Create a new sequence object. A sequence object is an array of items, where each item can be a string or a function. When the sequence is converted to a string, the functions are executed and their return value is used. This allows for dynamic use of the "stack" based functions

Parameters:

  • ... the items to add to the sequence

Returns:

    table the sequence object

stream

flush ()
Flushes the stream.

Returns:

    the return value of the stream's flush function
print (...)
Prints to the stream in chunks. Same as write, but adds a newline at the end.

Parameters:

  • ... the values to write

Returns:

    the return value of the stream's write function
write (...)
Writes to the stream in chunks. Parameters are written to the stream, and flushed after each chunk. A small sleep is added after each chunk to allow the terminal to process the data. This is done to prevent the terminal buffer from overrunning and dropping data.

Important differences: - functions will be called and their first return value will be used. - parameters will be written without tabs separating them.

Parameters:

  • ... the values to write

Returns:

    the return value of the stream's write function

Cursor shapes and visibility

Managing the shape and visibility of the cursor. These functions just generate required ansi sequences, without any stack operations.
beep ()
Write a sequence to the terminal to make it beep.

Returns:

    true
beeps ()
Returns a string sequence to make the terminal beep.

Returns:

    string ansi sequence to write to the terminal
readansi (timeout[, fsleep])
Same as sys.readansi, but works with the buffer required by terminal.lua. This function will read from the buffer first, before calling sys.readansi. This is required because querying the terminal (e.g. getting cursor position) might read data from the keyboard buffer, which would be lost if not buffered. Hence this function must be used instead of sys.readansi, to ensure the previously read buffer is consumed first.

Parameters:

  • timeout number the timeout in seconds
  • fsleep function the sleep function to use (default: the sleep function set by initialize) (optional)
ready ()
Returns whether the terminal has been initialized and is ready for use.

Returns:

    boolean true if the terminal has been initialized

cursor_shapes

shape (shape)
Sets the cursor shape and writes it to the terminal.

Parameters:

  • shape string the shape to set, one of the keys "block", "block_blink", "underline", "underline_blink", "bar", "bar_blink"

Returns:

    true
shapes (shape)
Returns the ansi sequence for a cursor shape without writing it to the terminal.

Parameters:

  • shape string the shape to get, one of the keys "block", "block_blink", "underline", "underline_blink", "bar", "bar_blink"

Returns:

    string ansi sequence to write to the terminal
visible (visible)
Shows or hides the cursor and writes it to the terminal.

Parameters:

  • visible boolean true to show, false to hide

Returns:

    true
visibles (visible)
Returns the ansi sequence to show/hide the cursor without writing it to the terminal.

Parameters:

  • visible boolean true to show, false to hide

Returns:

    string ansi sequence to write to the terminal

cursor_shape_stack

shape_apply ()
Re-applies the shape at the top of the stack, and writes it to the terminal.

Returns:

    true
shape_applys ()
Re-applies the shape at the top of the stack (returns it, does not write it to the terminal).

Returns:

    string ansi sequence to write to the terminal
shape_pop ([n=1])
Pops n cursor shape(s) off the stack, and writes the last one to the terminal.

Parameters:

  • n number number of shapes to pop (default 1)

Returns:

    true
shape_pops ([n=1])
Pops n cursor shape(s) off the stack (and returns the last one), without writing it to the terminal.

Parameters:

  • n number number of shapes to pop (default 1)

Returns:

    string ansi sequence to write to the terminal
shape_push (shape)
Pushes a cursor shape onto the stack, and writes it to the terminal.

Parameters:

  • shape string the shape to push, one of the keys "block", "block_blink", "underline", "underline_blink", "bar", "bar_blink"

Returns:

    true
shape_pushs (shape)
Pushes a cursor shape onto the stack (and returns it), without writing it to the terminal.

Parameters:

  • shape string the shape to push, one of the keys "block", "block_blink", "underline", "underline_blink", "bar", "bar_blink"

Returns:

    string ansi sequence to write to the terminal
visible_apply ()
Returns the ansi sequence to show/hide the cursor at the top of the stack, and writes it to the terminal.

Returns:

    true
visible_applys ()
Returns the ansi sequence to show/hide the cursor at the top of the stack without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal
visible_pop ([n=1])
Pops n cursor visibility(ies) off the stack, and writes the last one to the terminal.

Parameters:

  • n number number of visibilities to pop (default 1)

Returns:

    true
visible_pops ([n=1])
Pops n cursor visibility(ies) off the stack (and returns the last one), without writing it to the terminal.

Parameters:

  • n number number of visibilities to pop (default 1)

Returns:

    string ansi sequence to write to the terminal
visible_push (visible)
Pushes a cursor visibility onto the stack, and writes it to the terminal.

Parameters:

  • visible boolean true to show, false to hide

Returns:

    true
visible_pushs (visible)
Pushes a cursor visibility onto the stack (and returns it), without writing it to the terminal.

Parameters:

  • visible boolean true to show, false to hide

Returns:

    string ansi sequence to write to the terminal

cursor_position

cursor_get ()
Requests the current cursor position from the terminal. Will read entire keyboard buffer to empty it, then request the cursor position. The output buffer will be flushed. In case of a keyboard error, the error will be returned here, but also by readansi on a later call, because readansi retains the proper order of keyboard input, whilst this function buffers input.

Returns:

  1. number row
  2. number column

Or

  1. nil
  2. string error message in case of a keyboard read error
cursor_restore ()
Writes the ansi sequence to restore the cursor position (from the terminal storage, not stacked) to the terminal.

Returns:

    true
cursor_restores ()
Returns the ansi sequence to restore the cursor position (from the terminal storage, not stacked).

Returns:

    string ansi sequence to write to the terminal
cursor_save ()
Writes the ansi sequence to store the current cursor position (in terminal storage, not stacked) to the terminal.

Returns:

    true
cursor_saves ()
Returns the ansi sequence to store to backup the current sursor position (in terminal storage, not stacked).

Returns:

    string ansi sequence to write to the terminal
cursor_set (row, column)
Sets the cursor position and writes it to the terminal, without pushing onto the stack.

Parameters:

  • row number
  • column number

Returns:

    true
cursor_sets (row, column)
Creates ansi sequence to set the cursor position without writing to the terminal or pushing onto the stack.

Parameters:

  • row number
  • column number

Returns:

    string ansi sequence to write to the terminal

cursor_position_stack

cursor_pop ([n=1])
Pops the last n cursor position off the stack, and writes an ansi sequence to move to the last one to the terminal.

Parameters:

  • n number number of positions to pop (default 1)

Returns:

    true
cursor_pops ([n=1])
Pops the last n cursor positions off the stack, and returns an ansi sequence to move to the last one without writing it to the terminal.

Parameters:

  • n number number of positions to pop (default 1)

Returns:

    string ansi sequence to write to the terminal
cursor_push (row, column)
Pushes the current cursor position onto the stack, and writes an ansi sequence to move to the new position to the terminal. Calls cursor.get() under the hood.

Parameters:

  • row number
  • column number

Returns:

    true
cursor_pushs (row, column)
Pushes the current cursor position onto the stack, and returns an ansi sequence to move to the new position without writing it to the terminal. Calls cursor.get() under the hood.

Parameters:

  • row number
  • column number

Returns:

    string ansi sequence to write to the terminal

cursor_moving

cursor_down ([n=1])
Moves the cursor down and writes it to the terminal.

Parameters:

  • n number number of lines to move down (default 1)

Returns:

    true
cursor_downs ([n=1])
Creates an ansi sequence to move the cursor down without writing it to the terminal.

Parameters:

  • n number number of lines to move down (default 1)

Returns:

    string ansi sequence to write to the terminal
cursor_horizontal ([n=1])
Moves the cursor horizontally and writes it to the terminal.

Parameters:

  • n number number of columns to move (negative for left, positive for right) (default 1)

Returns:

    true
cursor_horizontals ([n=1])
Creates an ansi sequence to move the cursor horizontally without writing it to the terminal.

Parameters:

  • n number number of columns to move (negative for left, positive for right) (default 1)

Returns:

    string ansi sequence to write to the terminal
cursor_left ([n=1])
Moves the cursor left and writes it to the terminal.

Parameters:

  • n number number of columns to move left (default 1)

Returns:

    true
cursor_lefts ([n=1])
Creates an ansi sequence to move the cursor left without writing it to the terminal.

Parameters:

  • n number number of columns to move left (default 1)

Returns:

    string ansi sequence to write to the terminal
cursor_move ([rows=0[, columns=0]])
Moves the cursor horizontal and vertical and writes it to the terminal.

Parameters:

  • rows number number of rows to move (negative for up, positive for down) (default 0)
  • columns number number of columns to move (negative for left, positive for right) (default 0)

Returns:

    true
cursor_moves ([rows=0[, columns=0]])
Creates an ansi sequence to move the cursor horizontal and vertical without writing it to the terminal.

Parameters:

  • rows number number of rows to move (negative for up, positive for down) (default 0)
  • columns number number of columns to move (negative for left, positive for right) (default 0)

Returns:

    string ansi sequence to write to the terminal
cursor_right ([n=1])
Moves the cursor right and writes it to the terminal.

Parameters:

  • n number number of columns to move right (default 1)

Returns:

    true
cursor_rights ([n=1])
Creates an ansi sequence to move the cursor right without writing it to the terminal.

Parameters:

  • n number number of columns to move right (default 1)

Returns:

    string ansi sequence to write to the terminal
cursor_row_down ([rows=1])
Moves the cursor to the start of the next row and writes it to the terminal.

Parameters:

  • rows number the number of rows to move down (default 1)

Returns:

    true
cursor_row_downs ([rows=1])
Creates an ansi sequence to move the cursor to the start of the next row without writing it to the terminal.

Parameters:

  • rows number the number of rows to move down (default 1)

Returns:

    string ansi sequence to write to the terminal
cursor_row_up ([rows=1])
Moves the cursor to the start of the previous row and writes it to the terminal.

Parameters:

  • rows number the number of rows to move up (default 1)

Returns:

    true
cursor_row_ups ([rows=1])
Creates an ansi sequence to move the cursor to the start of the previous row without writing it to the terminal.

Parameters:

  • rows number the number of rows to move up (default 1)

Returns:

    string ansi sequence to write to the terminal
cursor_tocolumn (column)
Moves the cursor to a column on the current row and writes it to the terminal.

Parameters:

  • column number the column to move to

Returns:

    true
cursor_tocolumns (column)
Creates an ansi sequence to move the cursor to a column on the current row without writing it to the terminal.

Parameters:

  • column number the column to move to

Returns:

    string ansi sequence to write to the terminal
cursor_torow (row)
Moves the cursor to a row on the current column and writes it to the terminal.

Parameters:

  • row number the row to move to

Returns:

    true
cursor_torows (row)
Creates an ansi sequence to move the cursor to a row on the current column without writing it to the terminal.

Parameters:

  • row number the row to move to

Returns:

    string ansi sequence to write to the terminal
cursor_up ([n=1])
Moves the cursor up and writes it to the terminal.

Parameters:

  • n number number of lines to move up (default 1)

Returns:

    true
cursor_ups ([n=1])
Creates an ansi sequence to move the cursor up without writing it to the terminal.

Parameters:

  • n number number of lines to move up (default 1)

Returns:

    string ansi sequence to write to the terminal
cursor_vertical ([n=1])
Moves the cursor vertically and writes it to the terminal.

Parameters:

  • n number number of lines to move (negative for up, positive for down) (default 1)

Returns:

    true
cursor_verticals ([n=1])
Creates an ansi sequence to move the cursor vertically without writing it to the terminal.

Parameters:

  • n number number of lines to move (negative for up, positive for down) (default 1)

Returns:

    string ansi sequence to write to the terminal

clearing

clear ()
Clears the screen and writes it to the terminal.

Returns:

    true
clear_bottom ()
Clears the screen from the cursor position to the right and bottom and writes it to the terminal.

Returns:

    true
clear_bottoms ()
Creates an ansi sequence to clear the screen from the cursor position to the right and bottom without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal
clear_box (height, width)
Clears a box from the cursor position (top-left) and writes it to the terminal. Cursor will return to the original position.

Parameters:

  • height number the height of the box in rows
  • width number the width of the box in columns

Returns:

    string ansi sequence to write to the terminal
clear_boxs (height, width)
Creates an ansi sequence to clear a box from the cursor position (top-left) without writing it to the terminal. Cursor will return to the original position.

Parameters:

  • height number the height of the box in rows
  • width number the width of the box in columns

Returns:

    string ansi sequence to write to the terminal
clear_end ()
Clears the line from the cursor position to the right and writes it to the terminal.

Returns:

    true
clear_ends ()
Creates an ansi sequence to clear the line from the cursor position to the right without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal
clear_line ()
Clears the line and writes it to the terminal.

Returns:

    true
clear_lines ()
Creates an ansi sequence to clear the line without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal
clear_start ()
Clears the line from the cursor position to the left and writes it to the terminal.

Returns:

    true
clear_starts ()
Creates an ansi sequence to clear the line from the cursor position to the left without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal
clear_top ()
Clears the screen from the cursor position to the left and top and writes it to the terminal.

Returns:

    true
clear_tops ()
Creates an ansi sequence to clear the screen from the cursor position to the left and top without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal
clears ()
Creates an ansi sequence to clear the screen without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal

scrolling

scroll_ ([n=0])
Scrolls the screen vertically and writes it to the terminal.

Parameters:

  • n number number of lines to scroll (negative for up, positive for down) (default 0)

Returns:

    true
scroll_down ([n=1])
Scrolls the screen down and writes it to the terminal.

Parameters:

  • n number number of lines to scroll down (default 1)

Returns:

    true
scroll_downs ([n=1])
Creates an ansi sequence to scroll the screen down without writing it to the terminal.

Parameters:

  • n number number of lines to scroll down (default 1)

Returns:

    string ansi sequence to write to the terminal
scroll_region (top, bottom)
Sets the scroll region and writes it to the terminal. If no arguments are given, it resets the scroll region to the whole screen.

Parameters:

  • top number top row of the scroll region
  • bottom number bottom row of the scroll region

Returns:

    true
scroll_regions (top, bottom)
Creates an ansi sequence to set the scroll region without writing it to the terminal. If no arguments are given, it resets the scroll region to the whole screen.

Parameters:

  • top number top row of the scroll region
  • bottom number bottom row of the scroll region

Returns:

    string ansi sequence to write to the terminal
scroll_s ([n=0])
Creates an ansi sequence to scroll the screen vertically without writing it to the terminal.

Parameters:

  • n number number of lines to scroll (negative for up, positive for down) (default 0)

Returns:

    string ansi sequence to write to the terminal
scroll_up ([n=1])
Scrolls the screen up and writes it to the terminal.

Parameters:

  • n number number of lines to scroll up (default 1)

Returns:

    true
scroll_ups ([n=1])
Creates an ansi sequence to scroll the screen up without writing it to the terminal.

Parameters:

  • n number number of lines to scroll up (default 1)

Returns:

    string ansi sequence to write to the terminal

scrolling_region

scroll_apply ()
Applies the scroll region at the top of the stack, and writes it to the terminal.

Returns:

    true
scroll_applys ()
Applies the scroll region at the top of the stack (returns it, does not write it to the terminal).

Returns:

    string ansi sequence to write to the terminal
scroll_pop ([n=1])
Pops n scroll region(s) off the stack, and writes the last to the terminal.

Parameters:

  • n number number of scroll regions to pop (default 1)

Returns:

    true
scroll_pops ([n=1])
Pops n scroll region(s) off the stack (and returns the last), without writing it to the terminal.

Parameters:

  • n number number of scroll regions to pop (default 1)

Returns:

    string ansi sequence to write to the terminal
scroll_push (top, bottom)
Pushes a new scroll region onto the stack, and writes it to the terminal. If no arguments are given, it resets the scroll region to the whole screen.

Parameters:

  • top number top row of the scroll region
  • bottom number bottom row of the scroll region

Returns:

    true
scroll_pushs (top, bottom)
Pushes a new scroll region onto the stack (and returns it), without writing it to the terminal. If no arguments are given, it resets the scroll region to the whole screen.

Parameters:

  • top number top row of the scroll region
  • bottom number bottom row of the scroll region

Returns:

    string ansi sequence to write to the terminal

textcolor

blink_off ()
Unsets the blink attribute and writes it to the terminal.

Returns:

    true
blink_offs ()
Creates an ansi sequence to unset the blink attribute without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal
blink_on ()
Sets the blink attribute and writes it to the terminal.

Returns:

    true
blink_ons ()
Creates an ansi sequence to set the blink attribute without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal
brightness (brightness)
Sets the brightness and writes it to the terminal.

Parameters:

  • brightness string or integer the brightness to set

Returns:

    true
brightnesss (brightness)

Creates an ansi sequence to set the brightness without writing it to the terminal. brightness can be one of the following:

  • 0, "off", or "invisble" for invisible
  • 1, "low", or "dim" for dim
  • 2, "normal" for normal
  • 3, "high", "bright", or "bold" for bright

Parameters:

  • brightness string or integer the brightness to set

Returns:

    string ansi sequence to write to the terminal
color_bg (r[, g[, b]])
Sets the background color and writes it to the terminal.

Parameters:

  • r integer in case of RGB, the red value, a number for extended colors, a string color for base-colors
  • g number in case of RGB, the green value (optional)
  • b number in case of RGB, the blue value (optional)

Returns:

    true
color_bgs (r[, g[, b]])

Creates an ansi sequence to set the background color without writing it to the terminal. This function takes three color types:

  1. base colors: black, red, green, yellow, blue, magenta, cyan, white. Use as color_bgs("red").
  2. extended colors: a number between 0 and 255. Use as color_bgs(123).
  3. RGB colors: three numbers between 0 and 255. Use as color_bgs(123, 123, 123).

Parameters:

  • r integer in case of RGB, the red value, a number for extended colors, a string color for base-colors
  • g number in case of RGB, the green value (optional)
  • b number in case of RGB, the blue value (optional)

Returns:

    string ansi sequence to write to the terminal
color_fg (r[, g[, b]])
Sets the foreground color and writes it to the terminal.

Parameters:

  • r integer in case of RGB, the red value, a number for extended colors, a string color for base-colors
  • g number in case of RGB, the green value (optional)
  • b number in case of RGB, the blue value (optional)

Returns:

    true
color_fgs (r[, g[, b]])

Creates an ansi sequence to set the foreground color without writing it to the terminal. This function takes three color types:

  1. base colors: black, red, green, yellow, blue, magenta, cyan, white. Use as color_fgs("red").
  2. extended colors: a number between 0 and 255. Use as color_fgs(123).
  3. RGB colors: three numbers between 0 and 255. Use as color_fgs(123, 123, 123).

Parameters:

  • r integer in case of RGB, the red value, a number for extended colors, a string color for base-colors
  • g number in case of RGB, the green value (optional)
  • b number in case of RGB, the blue value (optional)

Returns:

    string ansi sequence to write to the terminal
reverse_off ()
Unsets the reverse attribute and writes it to the terminal.

Returns:

    true
reverse_offs ()
Creates an ansi sequence to unset the reverse attribute without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal
reverse_on ()
Sets the reverse attribute and writes it to the terminal.

Returns:

    true
reverse_ons ()
Creates an ansi sequence to set the reverse attribute without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal
underline_off ()
Unsets the underline attribute and writes it to the terminal.

Returns:

    true
underline_offs ()
Creates an ansi sequence to unset the underline attribute without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal
underline_on ()
Sets the underline attribute and writes it to the terminal.

Returns:

    true
underline_ons ()
Creates an ansi sequence to set the underline attribute without writing it to the terminal.

Returns:

    string ansi sequence to write to the terminal

textcolor_stack

textapply ()
Re-applies the current attributes, and writes it to the terminal.

Returns:

    true
textapplys ()
Re-applies the current attributes (returns it, does not write it to the terminal).

Returns:

    string ansi sequence to write to the terminal
textpop ([n=1])
Pops n attributes off the stack, and writes the last one to the terminal.

Parameters:

  • n number number of attributes to pop (default 1)

Returns:

    true
textpops ([n=1])
Pops n attributes off the stack (and returns the last one), without writing it to the terminal.

Parameters:

  • n number number of attributes to pop (default 1)

Returns:

    string ansi sequence to write to the terminal
textpush (attr)
Pushes the current attributes onto the stack, and writes an ansi sequence to set the new attributes to the terminal. Every element omitted in the attr table will be taken from the current top of the stack.

Parameters:

Returns:

    true
textpushs (attr)
Pushes the current attributes onto the stack, and returns an ansi sequence to set the new attributes without writing it to the terminal. Every element omitted in the attr table will be taken from the current top of the stack.

Parameters:

Returns:

    string ansi sequence to write to the terminal
textset (attr)
Sets the text attributes and writes it to the terminal. Every element omitted in the attr table will be taken from the current top of the stack.

Parameters:

Returns:

    true
textsets (attr)
Creates an ansi sequence to set the text attributes without writing it to the terminal. Only set what you change. Every element omitted in the attr table will be taken from the current top of the stack.

Parameters:

  • attr the attributes to set, with keys:
    • fg string or integer the foreground color to set. Base color (string), or extended color (number). Takes precedence of fg_r, fg_g, fg_b. (optional)
    • fg_r integer the red value of the foreground color to set. (optional)
    • fg_g integer the green value of the foreground color to set. (optional)
    • fg_b integer the blue value of the foreground color to set. (optional)
    • bg string or integer the background color to set. Base color (string), or extended color (number). Takes precedence of bg_r, bg_g, bg_b. (optional)
    • bg_r integer the red value of the background color to set. (optional)
    • bg_g integer the green value of the background color to set. (optional)
    • bg_b integer the blue value of the background color to set. (optional)
    • brightness string or number the brightness level to set (optional)
    • underline boolean whether to set underline (optional)
    • blink boolean whether to set blink (optional)
    • reverse boolean whether to set reverse (optional)

Returns:

    string ansi sequence to write to the terminal

lines

box (height, width, format, clear[, title=""[, lastcolumn]])
Draws a box and writes it to the terminal.

Parameters:

  • height number the height of the box in rows
  • width number the width of the box in columns
  • format table the format for the box, see boxs for details.
  • clear bool whether to clear the box contents
  • title string the title to draw (default "")
  • lastcolumn boolean whether to draw the last column of the terminal (optional)

Returns:

    true
box_fmt
Table with pre-defined box formats.

Fields:

  • single Single line box format
  • double Double line box format
  • copy Function to copy a box format, see box_fmt.copy for details
box_fmt.copy (default)
Copy a box format.

Parameters:

  • default table the default format to copy

Returns:

    table a copy of the default format provided

Usage:

    -- create new format with spaces around the title
local fmt = t.box_fmt.copy(t.box_fmt.single)
fmt.pre = fmt.pre .. " "
fmt.post = " " .. fmt.post
boxs (height, width[, format[, clear=" "[, title=""[, lastcolumn=""]]]])
Creates a sequence to draw a box, without writing it to the terminal. The box is drawn starting from the top-left corner at the current cursor position, after drawing the cursor will be in the same position.

Parameters:

  • height number the height of the box in rows
  • width number the width of the box in columns
  • format the format for the box (default is single line), with keys:
    • h string the horizontal line character (default " ")
    • v string the vertical line character (default "")
    • tl string the top left corner character (default "")
    • tr string the top right corner character (default "")
    • bl string the bottom left corner character (default "")
    • br string the bottom right corner character (default "")
    • pre string the title-prefix character(s) (default "")
    • post string the left-postfix character(s) (default "")
  • clear bool whether to clear the box contents (default false)
  • title string the title to draw (default "")
  • lastcolumn boolean whether to draw the last column of the terminal (default false)

Returns:

    string ansi sequence to write to the terminal
line_horizontal (n[, char="─"])
Draws a horizontal line and writes it to the terminal. Line is drawn left to right. Returned sequence might be shorter than requested if the character is a multi-byte character and the number of columns is not a multiple of the character width.

Parameters:

  • n number number of columns to draw
  • char string the character to draw (default "─")

Returns:

    true
line_horizontals (n[, char="─"])
Creates a sequence to draw a horizontal line without writing it to the terminal. Line is drawn left to right. Returned sequence might be shorter than requested if the character is a multi-byte character and the number of columns is not a multiple of the character width.

Parameters:

  • n number number of columns to draw
  • char string the character to draw (default "─")

Returns:

    string ansi sequence to write to the terminal
line_title (title, width[, char="─"[, pre=""[, post=""]]])
Draws a horizontal line with a title centered in it and writes it to the terminal. Line is drawn left to right. If the width is too small for the title, the title is truncated with "trailing "...". If less than 4 characters are available for the title, the title is omitted alltogether.

Parameters:

  • title string the title to draw
  • width number the total width of the line in columns
  • char string the line-character to use (default "─")
  • pre string the prefix for the title, eg. "┤ " (default "")
  • post string the postfix for the title, eg. " ├" (default "")

Returns:

    true
line_titles (width[, title=""[, char="─"[, pre=""[, post=""]]]])
Creates a sequence to draw a horizontal line with a title centered in it without writing it to the terminal. Line is drawn left to right. If the width is too small for the title, the title is truncated with "trailing "...". If less than 4 characters are available for the title, the title is omitted alltogether.

Parameters:

  • width number the total width of the line in columns
  • title string the title to draw (if empty or nil, only the line is drawn) (default "")
  • char string the line-character to use (default "─")
  • pre string the prefix for the title, eg. "┤ " (default "")
  • post string the postfix for the title, eg. " ├" (default "")

Returns:

    string ansi sequence to write to the terminal
line_vertical (n[, char="│"])
Draws a vertical line and writes it to the terminal. Line is drawn top to bottom. Cursor is left to the right of the last character (so not below it).

Parameters:

  • n number number of rows/lines to draw
  • char string the character to draw (default "│")

Returns:

    true
line_verticals (n[, char="│"[, lastcolumn]])
Creates a sequence to draw a vertical line without writing it to the terminal. Line is drawn top to bottom. Cursor is left to the right of the last character (so not below it).

Parameters:

  • n number number of rows/lines to draw
  • char string the character to draw (default "│")
  • lastcolumn boolean whether to draw the last column of the terminal (optional)

Returns:

    string ansi sequence to write to the terminal

initialization

initialize ([opts])
Initializes the terminal for use. Makes a backup of the current terminal settings. Sets input to non-blocking, disables canonical mode and echo, and enables ANSI processing. The preferred way to initialize the terminal is through initwrap, since that ensures settings are properly restored in case of an error, and don't leave the terminal in an inconsistent state for the user after exit.

Parameters:

  • opts options table, with keys:
    • displaybackup boolean if true, the current terminal display is also backed up (by switching to the alternate screen buffer). (default false)
    • filehandle filehandle the stream to use for output (default io.stderr)
    • bsleep function the blocking sleep function to use. This should never be set to a yielding sleep function! This function will be used by the terminal.write and terminal.print to prevent buffer-overflows and truncation when writing to the terminal. And by cursor_get when reading the cursor position. (default sys.sleep)
    • sleep function the default sleep function to use for readansi. In an async application (coroutines), this should be a yielding sleep function, eg. copas.pause. (default sys.sleep)

Returns:

    true
initwrap ([opts], main, ...)
Wrap a function in initialize and shutdown calls. When an error occurs, and the application exits, the terminal might not be properly shut down. This function wraps a function in calls to initialize and shutdown, ensuring the terminal is properly shut down.

Parameters:

  • opts table options table, to pass to initialize. (optional)
  • main function the function to wrap
  • ... any parameters to pass to the main function

Returns:

    any the return values of the wrapped function, or nil+err in case of an error

Usage:

    local function main(param1, param2)
  -- your main app functionality here

  return true -- return truthy to pass assertion below
end

local opts = {
  filehandle = io.stderr,
  displaybackup = true,
}
assert(t.initwrap(opts, main, "one", "two")) -- assert to rethrow any error after termimal restore
shutdown ()
Shuts down the terminal, restoring the terminal settings.

Returns:

    true
generated by LDoc 1.5.0 Last updated 2025-03-03 09:04:53