osch / lua-nocurses

A terminal screen manipulation library

lua-nocurses

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.

Examples

• 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().

Documentation

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

• Module Functions
  • nocurses.awake()
  • nocurses.clrline()
  • nocurses.clrscr()
  • nocurses.getch()
  • nocurses.peekch()
  • nocurses.skipch()
  • nocurses.getkey()
  • nocurses.gettermsize()
  • nocurses.gotoxy()
  • 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

Module Functions

• 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.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 funtion returns the number of bytes skipped in the input queue.

• nocurses.getkey([timeout])

  Returns the name of the pressed key as string.

  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 timout handling is the same as in the function nocurses.getch().

  If a pressed key could be determined, this functions returns the key name as string and the consumed raw input bytes as string.

  If the pressed key could not be determined from the input byte sequence, this functions returns the boolean value false and the consumed raw input bytes as string.

  See also: example05.lua

• nocurses.gettermsize()

  Gets the columns and rows of the terminal.

• nocurses.gotoxy(x, y)

  Sets the cursor do the position x, y. Where x is the row number and y the line number.

• 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().

Color Names

Valid color names are:

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

Shape Names

Valid shape names are:

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