Module posix.curses

Full-screen Text Terminal Manipulation.

In the underlying curses C library, the following functions:

getstr()   (and wgetstr(), mvgetstr(), and mvwgetstr())
inchstr()  (and winchstr(), mvinchstr(), and mvwinchstr())
instr()    (and winstr(), mvinstr(), and mvwinstr())

are subject to buffer overflow attack. This is because you pass in the buffer to be filled in, which has to be of finite length. But in this Lua module, a buffer is assigned automatically and the function returns the string, so there is no security issue. You may still use the alternate functions:

s = stdscr:getnstr()
s = stdscr:inchnstr()
s = stdscr:innstr()

which take an extra "size of buffer" argument, in order to impose a maximum length on the string the user may type in.

Some of the C functions beginning with "no" do not exist in Lua. You should use curses.nl(false) and curses.nl(true) instead of nonl() and nl(), and likewise curses.echo(false) and curses.echo(true) instead of noecho() and echo() .

In this Lua module the stdscr:getch() function always returns an integer. In C, a single character is an integer, but in Lua (and Perl) a single character is a short string. The Perl Curses function getch() returns a char if it was a char, and a number if it was a constant; to get this behaviour in Lua you have to convert explicitly, e.g.:

if c < 256 then c = string.char(c) end

Some Lua functions take a different set of parameters than their C counterparts; for example, you should use str = stdscr.getstr() and y, x = stdscr.getyx() instead of getstr(str) and getyx(y, x), and likewise for getbegyx and getmaxyx and getparyx and pair_content. The Perl Curses module now uses the C-compatible parameters, so be aware of this difference when translating code from Perl into Lua, as well as from C into Lua.

Many curses functions have variants starting with the prefixes w-, mv-, and/or wmv-. These variants differ only in the explicit addition of a window, or by the addition of two coordinates that are used to move the cursor first. For example, in C addch() has three other variants: waddch(), mvaddch() and mvwaddch(). The Lua equivalents, respectively being stdscr:addch(), somewindow:addch(), stdscr:mvaddch() and somewindow:mvaddch(), with the window argument passed implicitly with Lua's : syntax sugar.

Functions

baudrate () Fetch the output speed of the terminal.
beep () Send the terminal audible bell.
cbreak ([on]) Put the terminal into cbreak mode.
color_pair (pair) Return the attributes for the given color pair id.
color_pairs () How may distinct color pairs are supported by this terminal?
colors () How many colors are available for this terminal?
cols () Number of columns in the main screen window.
curs_set (vis) Change the visibility of the cursor.
delay_output (ms) Insert padding characters to force a short delay.
doupdate () Refresh the visible terminal screen.
echo ([on]) Whether characters are echoed to the terminal as they are typed.
endwin () Clean up terminal prior to exiting or escaping curses.
erasechar () Fetch the terminal's current erase character.
flash () Send the terminal visible bell.
flushinp () Throw away any typeahead in the keyboard input buffer.
halfdelay (tenths) Put the terminal into halfdelay mode.
has_colors () Does the terminal have color capability?
has_ic () Fetch the character insert and delete capability of the terminal.
has_il () Fetch the line insert and delete capability of the terminal.
init_pair (pair, f, b) Associate a color pair id with a specific foreground and background color.
initscr () Initialise screen.
isendwin () Has endwin been called more recently than posix.curses.window:refresh?
keyname (c) Return a printable representation of a key.
killchar () Fetch the terminal's current kill character.
lines () Number of lines in the main screen window.
longname () Fetch the verbose name of the terminal.
napms (ms) Sleep for a few milliseconds.
new_chstr (len) Create a new line drawing buffer instance.
newpad (nlines, ncols) Create a new pad.
newwin (nlines, ncols, begin_y, begin_x) Create a new window.
nl ([on]) Whether to translate a return key to newline on input.
pair_content (pair) Return the foreground and background colors associated with a color pair id.
raw ([on]) Put the terminal into raw mode.
resizeterm (nlines, ncols) Change the terminal size.
ripoffline (top_line, callback) Reduce the available size of the main screen.
slk_attroff (attrs) Disable an attribute for soft labels.
slk_attron (attrs) Enable an attribute for soft labels.
slk_attrset (attrs) Set the attributes for soft labels.
slk_clear () Clears the soft labels from the screen.
slk_init (fmt) Initialise the soft label keys area.
slk_label (labnum) Fetch the label for a soft label key.
slk_noutrefresh () Copy the soft label key area backing screen to the virtual screen.
slk_refresh () Refresh the soft label key area.
slk_restore () Restores the soft labels to the screen.
slk_set (labnum, label, fmt) Set the label for a soft label key.
slk_touch () Mark the soft label key area for refresh.
start_color () Initialise color output facility.
stdscr () Retern the main screen window.
termattrs ([a]) Bitwise OR of all (or selected) video attributes supported by the terminal.
termname () Fetch the name of the terminal.
tigetflag (capname) Fetch terminfo boolean capability.
tigetnum (capname) Fetch terminfo numeric capability.
tigetstr (capname) Fetch terminfo string capability.
unctrl (c) Return a printable representation of a character, ignoring attributes.
ungetch (c) Return a character to the keyboard input buffer.
use_default_colors () Reserve -1 to represent terminal default colors.

Constants

posix.curses Curses constants.


Functions

baudrate ()
Fetch the output speed of the terminal.

Returns:

    int output speed of the terminal in bits-per-second

See also:

beep ()
Send the terminal audible bell.

Returns:

    bool true, if successful

See also:

cbreak ([on])
Put the terminal into cbreak mode.

Parameters:

  • on bool (optional)

Returns:

    bool true, if successful

See also:

color_pair (pair)
Return the attributes for the given color pair id.

Parameters:

  • pair int color pair id to act on

Returns:

    int attributes for color pair pair

See also:

color_pairs ()
How may distinct color pairs are supported by this terminal?

Returns:

    int total number of available color pairs

See also:

colors ()
How many colors are available for this terminal?

Returns:

    int total number of available colors

See also:

cols ()
Number of columns in the main screen window.

Returns:

    int number of columns in the main screen

See also:

curs_set (vis)
Change the visibility of the cursor.

Parameters:

  • vis int one of 0 (invisible), 1 (visible) or 2 (very visible)

Returns:

    int previous cursor state

Or

    nil if vis is not supported

See also:

delay_output (ms)
Insert padding characters to force a short delay.

Parameters:

  • ms int delay time in milliseconds

Returns:

    bool true, if successful

See also:

doupdate ()
Refresh the visible terminal screen.

Returns:

    bool true, if successful

See also:

echo ([on])
Whether characters are echoed to the terminal as they are typed.

Parameters:

  • on bool (optional)

Returns:

    bool true, if successful

See also:

endwin ()
Clean up terminal prior to exiting or escaping curses.

Returns:

    bool true, if successful

See also:

erasechar ()
Fetch the terminal's current erase character.

Returns:

    int current erase character

See also:

flash ()
Send the terminal visible bell.

Returns:

    bool true, if successful

See also:

flushinp ()
Throw away any typeahead in the keyboard input buffer.

Returns:

    bool true, if successful

See also:

halfdelay (tenths)
Put the terminal into halfdelay mode.

Parameters:

  • tenths int delay in tenths of a second

Returns:

    bool true, if successful

See also:

has_colors ()
Does the terminal have color capability?

Returns:

    bool true, if the terminal supports colors

See also:

Usage:

    if curses.has_colors () then
      curses.start_color ()
    end
has_ic ()
Fetch the character insert and delete capability of the terminal.

Returns:

    bool true, if the terminal has insert and delete character operations

See also:

has_il ()
Fetch the line insert and delete capability of the terminal.

Returns:

    bool true, if the terminal has insert and delete line operations

See also:

init_pair (pair, f, b)
Associate a color pair id with a specific foreground and background color.

Parameters:

  • pair int color pair id to act on
  • f int foreground color to assign
  • b int background color to assign

Returns:

    bool true, if successful

See also:

initscr ()
Initialise screen.

Returns:

    window main screen

See also:

isendwin ()
Has endwin been called more recently than posix.curses.window:refresh?

Returns:

    bool whether endwin has been called

See also:

keyname (c)
Return a printable representation of a key.

Parameters:

  • c int a key

Returns:

    string key name of c

See also:

killchar ()
Fetch the terminal's current kill character.

Returns:

    int current line kill character

See also:

lines ()
Number of lines in the main screen window.

Returns:

    int number of lines in the main screen

See also:

longname ()
Fetch the verbose name of the terminal.

Returns:

    string verbose description of the current terminal

See also:

napms (ms)
Sleep for a few milliseconds.

Parameters:

  • ms int time to wait in milliseconds

Returns:

    bool true, if successful

See also:

new_chstr (len)
Create a new line drawing buffer instance.

Parameters:

  • len int number of element to allocate

Returns:

    chstr a new char buffer object

See also:

newpad (nlines, ncols)
Create a new pad.

Parameters:

  • nlines int
  • ncols int

Returns:

    bool true, if successful

See also:

newwin (nlines, ncols, begin_y, begin_x)
Create a new window.

Parameters:

  • nlines int number of window lines
  • ncols int number of window columns
  • begin_y int top line of window
  • begin_x int leftmost column of window

Returns:

    window a new window object

See also:

nl ([on])
Whether to translate a return key to newline on input.

Parameters:

  • on bool (optional)

Returns:

    bool true, if successful

See also:

pair_content (pair)
Return the foreground and background colors associated with a color pair id.

Parameters:

  • pair int color pair id to act on

Returns:

  1. int foreground color of pair
  2. int background color of pair

See also:

raw ([on])
Put the terminal into raw mode.

Parameters:

  • on bool (optional)

Returns:

    bool true, if successful

See also:

resizeterm (nlines, ncols)
Change the terminal size.

Parameters:

  • nlines int number of lines
  • ncols int number of columns

Returns:

    bool true, if successful

Raises:

unimplemented
ripoffline (top_line, callback)
Reduce the available size of the main screen.

Parameters:

  • top_line bool
  • callback func

Returns:

    bool true, if successful

See also:

slk_attroff (attrs)
Disable an attribute for soft labels.

Parameters:

  • attrs int

Returns:

    bool true, if successful

See also:

slk_attron (attrs)
Enable an attribute for soft labels.

Parameters:

  • attrs int

Returns:

    bool true, if successful

See also:

slk_attrset (attrs)
Set the attributes for soft labels.

Parameters:

  • attrs int

Returns:

    bool true, if successful

See also:

slk_clear ()
Clears the soft labels from the screen.

Returns:

    bool true, if successful

See also:

slk_init (fmt)
Initialise the soft label keys area. This must be called before initscr.

Parameters:

  • fmt int

Returns:

    bool true, if successful

See also:

slk_label (labnum)
Fetch the label for a soft label key.

Parameters:

  • labnum int

Returns:

    string current label for labnum

See also:

slk_noutrefresh ()
Copy the soft label key area backing screen to the virtual screen.

Returns:

    bool true, if successful

See also:

slk_refresh ()
Refresh the soft label key area.

Returns:

    bool true, if successful

See also:

slk_restore ()
Restores the soft labels to the screen.

Returns:

    bool true, if successful

See also:

slk_set (labnum, label, fmt)
Set the label for a soft label key.

Parameters:

  • labnum int
  • label string
  • fmt int

Returns:

    bool true, if successful

See also:

slk_touch ()
Mark the soft label key area for refresh.

Returns:

    bool true, if successful

See also:

start_color ()
Initialise color output facility.

Returns:

    bool true, if successful

See also:

stdscr ()
Retern the main screen window.

Returns:

    window main screen

See also:

termattrs ([a])
Bitwise OR of all (or selected) video attributes supported by the terminal.

Parameters:

  • a int terminal attribute bits (optional)

Returns:

    bool true, if the terminal supports attribute a

Or

    int bitarray of supported terminal attributes

See also:

termname ()
Fetch the name of the terminal.

Returns:

    string terminal name

See also:

tigetflag (capname)
Fetch terminfo boolean capability.

Parameters:

Returns:

    bool content of terminal boolean capability

See also:

tigetnum (capname)
Fetch terminfo numeric capability.

Parameters:

Returns:

    int content of terminal numeric capability

See also:

tigetstr (capname)
Fetch terminfo string capability.

Parameters:

Returns:

    string content of terminal string capability

See also:

unctrl (c)
Return a printable representation of a character, ignoring attributes.

Parameters:

  • c int character to act on

Returns:

    string printable representation of c

See also:

ungetch (c)
Return a character to the keyboard input buffer.

Parameters:

  • c int

Returns:

    bool true, if successful

See also:

use_default_colors ()
Reserve -1 to represent terminal default colors.

Returns:

    bool true, if successful

See also:

Constants

posix.curses
Curses constants. Any constants not available in the underlying system will be nil valued, see curses.lua. Many of the KEY_ constants cannot be generated by modern keyboards and are mostly for historical compatibility with ancient terminal hardware keyboards.

Note that, unlike the other posix submodules, almost all of these constants remain undefined (nil) until after posix.curses.initscr has returned successfully.

Fields:

  • ACS_BLOCK int alternate character set solid block
  • ACS_BOARD int alternate character set board of squares
  • ACS_BTEE int alternate character set bottom-tee
  • ACS_BULLET int alternate character set bullet
  • ACS_CKBOARD int alternate character set stipple
  • ACS_DARROW int alternate character set down arrow
  • ACS_DEGREE int alternate character set degrees mark
  • ACS_DIAMOND int alternate character set diamond
  • ACS_HLINE int alternate character set horizontal line
  • ACS_LANTERN int alternate character set lantern
  • ACS_LARROW int alternate character set left arrow
  • ACS_LLCORNER int alternate character set lower left corner
  • ACS_LRCORNER int alternate character set lower right corner
  • ACS_LTEE int alternate character set left tee
  • ACS_PLMINUS int alternate character set plus/minus
  • ACS_PLUS int alternate character set plus
  • ACS_RARROW int alternate character set right arrow
  • ACS_RTEE int alternate character set right tee
  • ACS_S1 int alternate character set scan-line 1
  • ACS_S9 int alternate character set scan-line 9
  • ACS_TTEE int alternate character set top tee
  • ACS_UARROW int alternate character set up arrow
  • ACS_ULCORNER int alternate character set upper left corner
  • ACS_URCORNER int alternate character set upper right corner
  • ACS_VLINE int alternate character set vertical line
  • A_ALTCHARSET int alternatate character set attribute
  • A_ATTRIBUTES int attributed character attributes bitmask
  • A_BLINK int blinking attribute
  • A_BOLD int bold attribute
  • A_CHARTEXT int attributed character text bitmask
  • A_COLOR int attributed character color-pair bitmask
  • A_DIM int half-bright attribute
  • A_INVIS int invisible attribute
  • A_NORMAL int normal attribute (all attributes off)
  • A_PROTECT int protected attribute
  • A_REVERSE int reverse video attribute
  • A_STANDOUT int standout attribute
  • A_UNDERLINE int underline attribute
  • COLOR_BLACK int black color attribute
  • COLOR_BLUE int blue color attribute
  • COLOR_CYAN int cyan color attribute
  • COLOR_GREEN int green color attribute
  • COLOR_MAGENTA int magenta color attribute
  • COLOR_RED int red color attribute
  • COLOR_WHITE int white color attribute
  • COLOR_YELLOW int yellow color attribute
  • KEY_A1 int upper-left of keypad key
  • KEY_A3 int upper-right of keypad key
  • KEY_B2 int center of keypad key
  • KEY_BACKSPACE int backspace key
  • KEY_BEG int beginning key
  • KEY_BREAK int break key
  • KEY_BTAB int backtab key
  • KEY_C1 int bottom-left of keypad key
  • KEY_C3 int bottom-right of keypad key
  • KEY_CANCEL int cancel key
  • KEY_CATAB int clear all tabs key
  • KEY_CLEAR int clear screen key
  • KEY_CLOSE int close key
  • KEY_COMMAND int command key
  • KEY_COPY int copy key
  • KEY_CREATE int create key
  • KEY_CTAB int clear tab key
  • KEY_DC int delete character key
  • KEY_DL int delete line key
  • KEY_DOWN int down arrow key
  • KEY_EIC int exit insert char mode key
  • KEY_END int end key
  • KEY_ENTER int enter key
  • KEY_EOL int clear to end of line key
  • KEY_EOS int clear to end of screen key
  • KEY_EXIT int exit key
  • KEY_F0 int f0 key
  • KEY_F1 int f1 key
  • KEY_F2 int f2 key
  • KEY_F3 int f3 key
  • KEY_F4 int f4 key
  • KEY_F5 int f5 key
  • KEY_F6 int f6 key
  • KEY_F7 int f7 key
  • KEY_F8 int f8 key
  • KEY_F9 int f9 key
  • KEY_F10 int f10 key
  • KEY_F11 int f11 key
  • KEY_F12 int f12 key
  • KEY_F13 int f13 key
  • KEY_F14 int f14 key
  • KEY_F15 int f15 key
  • KEY_F16 int f16 key
  • KEY_F17 int f17 key
  • KEY_F18 int f18 key
  • KEY_F19 int f19 key
  • KEY_F20 int f20 key
  • KEY_F21 int f21 key
  • KEY_F22 int f22 key
  • KEY_F23 int f23 key
  • KEY_F24 int f24 key
  • KEY_F25 int f25 key
  • KEY_F26 int f26 key
  • KEY_F27 int f27 key
  • KEY_F28 int f28 key
  • KEY_F29 int f29 key
  • KEY_F30 int f30 key
  • KEY_F31 int f31 key
  • KEY_F32 int f32 key
  • KEY_F33 int f33 key
  • KEY_F34 int f34 key
  • KEY_F35 int f35 key
  • KEY_F36 int f36 key
  • KEY_F37 int f37 key
  • KEY_F38 int f38 key
  • KEY_F39 int f39 key
  • KEY_F40 int f40 key
  • KEY_F41 int f41 key
  • KEY_F42 int f42 key
  • KEY_F43 int f43 key
  • KEY_F44 int f44 key
  • KEY_F45 int f45 key
  • KEY_F46 int f46 key
  • KEY_F47 int f47 key
  • KEY_F48 int f48 key
  • KEY_F49 int f49 key
  • KEY_F50 int f50 key
  • KEY_F51 int f51 key
  • KEY_F52 int f52 key
  • KEY_F53 int f53 key
  • KEY_F54 int f54 key
  • KEY_F55 int f55 key
  • KEY_F56 int f56 key
  • KEY_F57 int f57 key
  • KEY_F58 int f58 key
  • KEY_F59 int f59 key
  • KEY_F60 int f60 key
  • KEY_F61 int f61 key
  • KEY_F62 int f62 key
  • KEY_F63 int f63 key
  • KEY_FIND int find key
  • KEY_HELP int help key
  • KEY_HOME int home key
  • KEY_IC int enter insert char mode key
  • KEY_IL int insert line key
  • KEY_LEFT int cursor left key
  • KEY_LL int home down or bottom key
  • KEY_MARK int mark key
  • KEY_MESSAGE int message key
  • KEY_MOUSE int mouse event available virtual key
  • KEY_MOVE int move key
  • KEY_NEXT int next object key
  • KEY_NPAGE int next page key
  • KEY_OPEN int open key
  • KEY_OPTIONS int options key
  • KEY_PPAGE int previous page key
  • KEY_PREVIOUS int prewious object key
  • KEY_PRINT int print key
  • KEY_REDO int redo key
  • KEY_REFERENCE int reference key
  • KEY_REFRESH int refresh key
  • KEY_REPLACE int replace key
  • KEY_RESET int hard reset key
  • KEY_RESIZE int resize event virtual key
  • KEY_RESTART int restart key
  • KEY_RESUME int resume key
  • KEY_RIGHT int cursor right key
  • KEY_SAVE int save key
  • KEY_SBEG int shift beginning key
  • KEY_SCANCEL int shift cancel key
  • KEY_SCOMMAND int shift command key
  • KEY_SCOPY int shift copy key
  • KEY_SCREATE int shift create key
  • KEY_SDC int shift delete character key
  • KEY_SDL int shift delete line key
  • KEY_SELECT int select key
  • KEY_SEND int send key
  • KEY_SEOL int shift clear to end of line key
  • KEY_SEXIT int shift exit key
  • KEY_SF int scroll one line forward key
  • KEY_SFIND int shift find key
  • KEY_SHELP int shift help key
  • KEY_SHOME int shift home key
  • KEY_SIC int shift enter insert mode key
  • KEY_SLEFT int shift cursor left key
  • KEY_SMESSAGE int shift message key
  • KEY_SMOVE int shift move key
  • KEY_SNEXT int shift next object key
  • KEY_SOPTIONS int shift options key
  • KEY_SPREVIOUS int shift previous object key
  • KEY_SPRINT int shift print key
  • KEY_SR int scroll one line backward key
  • KEY_SREDO int shift redo key
  • KEY_SREPLACE int shift replace key
  • KEY_SRESET int soft reset key
  • KEY_SRIGHT int shift cursor right key
  • KEY_SRSUME int shift resume key
  • KEY_SSAVE int shift save key
  • KEY_SSUSPEND int shift suspend key
  • KEY_STAB int shift tab key
  • KEY_SUNDO int shift undo key
  • KEY_SUSPEND int suspend key
  • KEY_UNDO int undo key
  • KEY_UP int cursor up key

Usage:

      -- Print curses constants supported on this host.
      for name, value in pairs (require "posix.curses") do
        if type (value) == "number" then
          print (name, value)
         end
      end
generated by LDoc 1.4.3 Last updated 2015-03-01 09:06:02