terminal.lua

• Index

Contents

• Functions
• Initialization

Modules

• terminal
• terminal.clear
• terminal.cursor
• terminal.cursor.position
• terminal.cursor.position.stack
• terminal.cursor.shape
• terminal.cursor.shape.stack
• terminal.cursor.visible
• terminal.cursor.visible.stack
• terminal.draw
• terminal.draw.line
• terminal.input
• terminal.input.keymap
• terminal.output
• terminal.progress
• terminal.scroll
• terminal.scroll.stack
• terminal.text
• terminal.text.color
• terminal.text.stack
• terminal.text.width
• terminal.utils

Classes

• Sequence
• Utf8edit
• cli.Prompt
• cli.Select

Topics

• 1. Introduction
• 2. Terminal handling
• CHANGELOG
• CONTRIBUTING
• MIT License

Examples

• async.lua
• colors.lua
• copas.lua
• cow.lua
• headers.lua
• keymap.lua
• progress.lua
• prompt.lua
• readline_old.lua
• sequence.lua
• testscreen.lua

Module terminal

Terminal library for Lua.

This terminal library builds upon the cross-platform terminal capabilities of LuaSystem. As such it works in 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, 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

bell ()	Write a sequence to the terminal to make it beep.
bell_seq ()	Returns a string sequence to make the terminal beep.
size ()	Returns the terminal size in rows and columns.

Initialization

initialize ([opts])	Initializes the terminal for use.
initwrap (main[, opts])	Wrap a function in initialize and shutdown calls.
preload_widths ([str])	Preload known characters into the width-cache.
ready ()	Returns whether the terminal has been initialized and is ready for use.
shutdown ()	Shuts down the terminal, restoring the terminal settings.

Functions

bell ()

Write a sequence to the terminal to make it beep.

Returns:

true

bell_seq ()

Returns a string sequence to make the terminal beep.

Returns:

string ansi sequence to write to the terminal

size ()

Returns the terminal size in rows and columns. Just a convenience, maps 1-on-1 to system.termsize.

Returns:

1. number number of rows
2. number number of columns

Or

1. nil on error
2. string error message

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 terminal.cursor.position.get when reading the cursor position. (default sys.sleep)
  • sleep function the default sleep function to use for terminal.input.readansi. In an async application (coroutines), this should be a yielding sleep function, eg. copas.pause. (default sys.sleep)
  • autotermrestore boolean if false, the terminal settings will not be restored. See luasystem.autotermrestore. (default true)
  • disable_sigint boolean if true, the terminal will not send a SIGINT signal on Ctrl-C. Disables Ctrl-C, Ctrl-Z, and Ctrl-\, which allows the application to handle them. (default false)

Returns:

true

initwrap (main[, opts])

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. If an error is caught, it first shutsdown the terminal and then rethrows the error.

Parameters:

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

Returns:

function wrapped function

Usage:

local function main(param1, param2)

  -- your main app functionality here
  error("oops...")

end

main = t.initwrap(main, {
  filehandle = io.stderr,
  displaybackup = true,
})

main("one", "two") -- rethrows any error after termimal restore

preload_widths ([str])

Preload known characters into the width-cache. Typically this should be called right after initialization. It will check default characters in use by this library, and the optional specified characters in str. Characters loaded will be the terminal.draw.box_fmt formats, and the progress spinner sprites. Uses terminal.text.width.test to test the widths of the characters.

Parameters:

• str string additional character string to preload (optional)

Returns:

true

ready ()

Returns whether the terminal has been initialized and is ready for use.

Returns:

boolean true if the terminal has been initialized

shutdown ()

Shuts down the terminal, restoring the terminal settings.

Returns:

true