Simple terminal manipulation capability for the Lua scripting language by the use of VT100 ESC sequences.

This package is based on nocurses by Rahul M. Juliato. It is aimed to simple applications where ncurses is simple "too much".

Supported platforms: Linux, MacOS and Cygwin.

• example01.lua

  Simple Hello World program.

• example02.lua

  Hello World program, that reacts on terminal size changes while waiting for keyboard input.

• example03.lua

  Reacts on messages from a background thread while also evaluating keyboard input.

  Uses llthreads2 for thread creation and connects the nocurses lua module as notifier to a mtmsg buffer object for receiving messages from the background thread. (This is done by implementing the Notify C API, see: src/notify_capi.h)

• example04.lua

  Demonstrates how to read keystrokes with multibyte sequences (arrow keys).

• example05.lua

  Demonstrates how to read keystrokes with multibyte sequences (arrow keys) using the convenience method nocurses.getkey().

See also original documentation at https://github.com/LionyxML/nocurses.

• Module Functions
  • nocurses.awake()
  • nocurses.clrline()
  • nocurses.clrscr()
  • nocurses.clrtoeol()
  • nocurses.clrtoeos()
  • nocurses.setraw()
  • nocurses.israw()
  • nocurses.getch()
  • nocurses.peekch()
  • nocurses.skipch()
  • nocurses.getkey()
  • nocurses.getxy()
  • nocurses.gettermsize()
  • nocurses.gotoxy()
  • nocurses.gotox)
  • nocurses.up()
  • nocurses.down()
  • nocurses.left()
  • nocurses.right()
  • nocurses.resetcolors()
  • nocurses.setbgrcolor()
  • nocurses.setblink()
  • nocurses.setcurshape()
  • nocurses.setfontbold()
  • nocurses.setfontcolor()
  • nocurses.setinvert()
  • nocurses.settitle()
  • nocurses.setunderline()
  • nocurses.wait()
  • nocurses.hidecursor()
  • nocurses.showcursor()
• Color Names
• Shape Names
• Control Sequences

• nocurses.awake()

  May be called from any thread to interrupt nocurses.getch() on the main thread. The main thread is the first thread that loads the nocurses module.

• nocurses.clrline()

  Clears the row contents.

• nocurses.clrscr()

  Clears the screen.

• nocurses.clrtoeol()

  Clears from cursor position to the end of the line.

• nocurses.clrtoeos()

  Clears from cursor position to the end of the screen.

• nocurses.setraw([enable])

  Sets terminal to raw input mode.

  • enable - optional boolean, true to enable raw mode, false to disable raw mode, default value is true.

  Raw input mode is needed to get keystrokes from the operation system. If you invoke nocurses.getch() without explicitly setting the raw mode via setraw(true), the raw mode is enabled implicitly by the function getch() and disabled on exit of this function. This is suitable for playing around on the lua commandline interactively but for real world programs it is recommended to enter the raw mode at program and keep this mode until program termination.

  On normal program termination (i.e. destruction of the lua_State) the raw mode is disabled automatically by nocurses.

• nocurses.israw()

  Returns true if setraw(true) was invoked, otherwise false.

• nocurses.getch([timeout])

  Gets a character byte without waiting for enter.

  • timeout - optional float, timeout in seconds.

  If timeout is given and not nil, this function returns nil if no input is available after timeout seconds.

  If timeout is not given or nil this function waits without timeout until input becomes available.

  This function returns nil if:

  • nocurses.awake() is called from any other thread.

  • the nocurses module is notified from native C code running in any other thread. This is done by implementing the Notify C API, see: src/notify_capi.h.

  • the terminal size changes.

  Otherwise this function returns the obtained character byte as integer value.

• nocurses.peekch([cnt])

  Obtains next character byte from the input queue without consuming the character, i.e. a subsequent call to nocurses.getch() will deliver this byte again.

  • cnt - optional integer, number of the byte in the input queue to obtain, first byte has number 1. If not given, the default value is 1, i.e. the first byte in the input queue is obtained.

  This function does not wait and will return nil if the specified input byte is not available.

  The input character byte is returned as integer value.

• nocurses.skipch([cnt])

  Discards bytes in the input queue.

  • cnt - optional integer, number of bytes in the input queue to discard. If not given, the default value is 1, i.e. the first byte in the input queue is skipped, if available..

  This function does not wait and will skip only input bytes in the queue that are immediately available.

  This function returns the number of bytes skipped in the input queue.

• nocurses.getkey([timeout])

  Returns the name of the pressed key as string and the input bytes for this key.

  This function is implemented in Lua (see getkey.lua) using the low level functions getch(), peekch() and skipch() and heuristically determines the pressed key for the current input byte sequence.

  • timeout - optional float, timeout in seconds.

  The timeout handling is the same as in the function nocurses.getch().

  If a special control key is recognized (e.g. arrow keys) , this function returns the key name as string and the consumed raw input bytes as string.

  If a special key name could not be determined (e.g. normal letter key) from the input byte sequence, this function returns the boolean value false and the consumed raw input bytes as string.

  See also: example05.lua

• nocurses.getxy()

  Returns the current cursor position x, y. Where x is the column number and y the row number.

  This function is implemented in Lua (see getxy.lua) using the function getkey().

• nocurses.gettermsize()

  Gets the columns and rows of the terminal.

• nocurses.gotoxy(x, y)

  Sets the cursor to the position x, y. Where x is the column number and y the row number.

• nocurses.gotox(x)

  Sets the cursor to the column x.

• nocurses.up([d])

  Moves the cursor upward.

  • d - optional integer, number of rows the cursor should be moved, default value is 1. May be negative for moving the cursor downward.

• nocurses.down([d])

  Moves the cursor downward.

  • d - optional integer, number of rows the cursor should be moved, default value is 1. May be negative for moving the cursor upward.

• nocurses.left([d])

  Moves the cursor leftward.

  • d - optional integer, number of columns the cursor should be moved, default value is 1. May be negative for moving the cursor rightward.

• nocurses.right([d])

  Moves the cursor rightward.

  • d - optional integer, number of columns the cursor should be moved, default value is 1. May be negative for moving the cursor leftward.

• nocurses.resetcolors()

  Reset terminal to default colors.

• nocurses.setbgrcolor(colorName)

  Sets the background color to one of the colors described on the color table below.

• nocurses.setblink(status)

  Sets the blink attribute on or off. status can be true or false.

• nocurses.setcurshape(shapeName)

  Sets the shape of the cursor in the terminal in the shape table below.

• nocurses.setfontbold(status)

  Sets the bold attribute on or off. status can be true or false.

• nocurses.setfontcolor(colorName)

  Sets the text color to one of the colors described on the color table below.

• nocurses.setinvert(status)

  Sets the invert attribute on or off. status can be true or false.

• nocurses.settitle(title)

  Sets the title of the terminal.

• nocurses.setunderline(status)

  Sets the underline attribute on or off. status can be true or false.

• nocurses.wait()

  Waits for the user to hit [ENTER].

• nocurses.hidecursor()

  Hides the cursor. If the program exits, a hidden cursor is automatically made visible again.

  See also: example05.lua

• nocurses.showcursor()

  Makes the cursor visible. To be called after nocurses.hidecursor().

Valid color names are:

• DEFAULT
• BLACK
• RED
• GREEN
• YELLOW
• BLUE
• MAGENTA
• CYAN
• WHITE

Valid shape names are:

• DEFAULT
• BLOCK_BLINK
• BLOCK
• UNDERLINE_BLINK
• UNDERLINE
• BAR_BLINK
• BAR

The nocurses.seq table contains predefined VT100 escape sequences for terminal control. These sequences can be used directly via io.write() or other output functions for advanced terminal manipulation.

Screen Control Sequences:

• clear_screen - Clear entire screen (ESC[2J)
• clear_to_eol - Clear from cursor to end of line (ESC[0K)
• clear_to_eos - Clear from cursor to end of screen (ESC[0J)
• clear_line - Clear current line (ESC[2K)
• use_alt_buff - Switch to alternate screen buffer (ESC[?1049h)
• use_main_buff - Switch to main screen buffer (ESC[?1049l)

Cursor Positioning Sequences:

• goto_row_col - Move cursor to row and column, format: ESC[%d;%dH (row, col)
• goto_col - Move cursor to column, format: ESC[%dG (column)
• go_home - Move cursor to home position (ESC[H)
• go_up - Move cursor up, format: ESC[%dA (distance)
• go_down - Move cursor down, format: ESC[%dB (distance)
• go_left - Move cursor left, format: ESC[%dD (distance)
• go_right - Move cursor right, format: ESC[%dC (distance)

Cursor Shape and Visibility Sequences:

• set_cur_shape - Set cursor shape, format: ESC[%d q (shape code)
• set_cur_shape_default - Set cursor to default shape (ESC[0 q)
• set_cur_shape_block_blink - Set cursor to blinking block (ESC[1 q)
• set_cur_shape_block - Set cursor to solid block (ESC[2 q)
• set_cur_shape_underline_blink - Set cursor to blinking underline (ESC[3 q)
• set_cur_shape_underline - Set cursor to solid underline (ESC[4 q)
• set_cur_shape_bar_blink - Set cursor to blinking bar (ESC[5 q)
• set_cur_shape_bar - Set cursor to solid bar (ESC[6 q)
• show_cur - Show cursor (ESC[?25h)
• hide_cur - Hide cursor (ESC[?25l)

Text Attributes (Building Blocks):

• attrs_begin - Start attribute sequence (ESC[)
• attrs_next - Separator between attributes (;)
• attrs_end - End attribute sequence (m)
• attr_bold - Bold attribute (1)
• attr_dim - Dim attribute (2)
• attr_italic - Italic attribute (3)
• attr_underline - Underline attribute (4)
• attr_blink - Blink attribute (5)
• attr_inverse - Inverse/reverse video attribute (7)
• attr_reset - Reset all attributes (0)

Foreground Color Codes (for building attributes):

• attr_foregrd_black - Black (30)
• attr_foregrd_red - Red (31)
• attr_foregrd_green - Green (32)
• attr_foregrd_yellow - Yellow (33)
• attr_foregrd_blue - Blue (34)
• attr_foregrd_magenta - Magenta (35)
• attr_foregrd_cyan - Cyan (36)
• attr_foregrd_white - White (37)
• attr_foregrd_default - Default foreground color (39)

Background Color Codes (for building attributes):

• attr_backgrd_black - Black (40)
• attr_backgrd_red - Red (41)
• attr_backgrd_green - Green (42)
• attr_backgrd_yellow - Yellow (43)
• attr_backgrd_blue - Blue (44)
• attr_backgrd_magenta - Magenta (45)
• attr_backgrd_cyan - Cyan (46)
• attr_backgrd_white - White (47)
• attr_backgrd_default - Default background color (49)

Convenience Sequences (pre-formatted):

• reset_attrs - Reset all attributes (ESC[0m)
• set_foregrd_color - Set foreground color, format: ESC[3%dm (color code 0-7)
• set_backgrd_color - Set background color, format: ESC[4%dm (color code 0-7)
• set_attr_bold - Set bold (ESC[1m)
• set_attr_underline - Set underline (ESC[4m)
• set_attr_blink - Set blink (ESC[5m)
• set_attr_inverse - Set inverse video (ESC[7m)
• set_title - Set terminal window title, format: ESC]0;%s\x7 (title string)

Cursor Position Query:

• request_cur_pos - Request current cursor position (ESC[6n)
• response_cur_pos - Parse cursor position response, pattern: ESC[(%d+);(%d+)R (row; col)

Example Usage:

local nocurses = require('nocurses')
io.write(nocurses.seq.clear_screen)      -- Clear screen
io.write(nocurses.seq.set_attr_bold)     -- Make text bold
io.write("Bold text")
io.write(nocurses.seq.reset_attrs)       -- Reset to normal