# luaposix curses documentation

- NAME
- SYNOPSIS
- DESCRIPTION
- CURSES FUNCTIONS
- WINDOW METHODS

- CONSTANTS
- COMPATIBILITY
- INSTALLATION
- AUTHOR
- SEE ALSO

## NAME

luaposix curses - a C library for Lua 5.1 that wraps the curses API.

## SYNOPSIS

    require 'curses'
    curses.initscr()
    curses.cbreak()
    curses.echo(0)  -- not noecho !
    curses.nl(0)    -- not nonl !
    local stdscr = curses.stdscr()  -- it's a userdatum
    stdscr:clear()
    local a = {};  for k in pairs(curses) do a[#a+1]=k end
    stdscr:mvaddstr(15,20,'print out curses table (y/n) ? ')
    stdscr:refresh()
    local c = stdscr:getch()
    if c < 256 then c = string.char(c) end
    curses.endwin()
    if c == 'y' then
        table.sort(a)
        for i,k in ipairs(a) do print(type(curses[k])..'  '..k) end
    end

## DESCRIPTION

luaposix `curses` is the interface between Lua and your system's `ncurses` or `curses` library. For descriptions on the usage of a given function or constant, consult your system's documentation, starting with `man ncurses` or `man curses`

## CURSES FUNCTIONS

This list of functions can be seen by

      require 'curses' ; local a = {};
      for k in pairs(curses) do
        if type(curses[k]) == 'function' then a[#a+1]=k end
      end
      table.sort(a) ; for i,k in ipairs(a) do print(k) end

and are defined in the static const luaL_reg curseslib section of lcurses.c

`baudrate()`
`beep()`
`cbreak()`
`color_pair()`
`color_pairs()`
`colors()`
`cols()`
`curs_set()`
`delay_output()`
`doupdate()`
`echo()`
`endwin()`
`erasechar()`
`flash()`
`flushinp()`
`halfdelay()`
`has_colors()`
`has_ic()`
`has_il()`
`init_pair()`
`initscr()`
`isendwin()`
`keyname()`
`killchar()`
`lines()`
`longname()`
`napms()`
`new_chstr()`
`newpad()`
`newwin()` see lcurses.c
`nl()`
`pair_content()`
`raw()`
`ripoffline()`
`slk_attroff()`
`slk_attron()`
`slk_attrset()`
`slk_clear()`
`slk_init()`
`slk_label()`
`slk_noutrefresh()`
`slk_refresh()`
`slk_restore()`
`slk_set()`
`slk_touch()`
`start_color()`
`stdscr()`
`termattrs()`
`termname()`
`unctrl()`
`ungetch()`

## WINDOW METHODS

These are defined in the static const luaL_reg windowlib section of lcurses.c

## CONSTANTS

These constants only appear after curses.initscr() is called; they can be seen by:

      require 'curses' ; curses.initscr() ; local a = {};
      for k in pairs(curses) do
        if type(curses[k]) == 'number' then a[#a+1]=k end
      end
      curses.endwin()
      table.sort(a) ; for i,k in ipairs(a) do print(k) end

and are defined in the static void register_curses_constants section of lcurses.c

ACS_BLOCK ACS_BOARD ACS_BTEE ACS_BULLET ACS_CKBOARD ACS_DARROW ACS_DEGREE ACS_DIAMOND ACS_HLINE ACS_LANTERN ACS_LARROW ACS_LLCORNER ACS_LRCORNER ACS_LTEE ACS_PLMINUS ACS_PLUS ACS_RARROW ACS_RTEE ACS_S1 ACS_S9 ACS_TTEE ACS_UARROW ACS_ULCORNER ACS_URCORNER ACS_VLINE

A_ALTCHARSET A_ATTRIBUTES A_BLINK A_BOLD A_CHARTEXT A_DIM A_INVIS A_NORMAL A_PROTECT A_REVERSE A_STANDOUT A_UNDERLINE

COLOR_BLACK COLOR_BLUE COLOR_CYAN COLOR_GREEN COLOR_MAGENTA COLOR_RED COLOR_WHITE COLOR_YELLOW

KEY_A1 KEY_A3 KEY_B2 KEY_BACKSPACE KEY_BEG KEY_BREAK KEY_BTAB KEY_C1 KEY_C3 KEY_CANCEL KEY_CATAB KEY_CLEAR KEY_CLOSE KEY_COMMAND KEY_COPY KEY_CREATE KEY_CTAB KEY_DC KEY_DL KEY_DOWN KEY_EIC KEY_END KEY_ENTER KEY_EOL KEY_EOS KEY_EXIT KEY_F0 KEY_F1 KEY_F10 KEY_F11 KEY_F12 KEY_F2 KEY_F3 KEY_F4 KEY_F5 KEY_F6 KEY_F7 KEY_F8 KEY_F9 KEY_FIND KEY_HELP KEY_HOME KEY_IC KEY_IL KEY_LEFT KEY_LL KEY_MARK KEY_MESSAGE KEY_MOUSE KEY_MOVE KEY_NEXT KEY_NPAGE KEY_OPEN KEY_OPTIONS KEY_PPAGE KEY_PREVIOUS KEY_PRINT KEY_REDO KEY_REFERENCE KEY_REFRESH KEY_REPLACE KEY_RESET KEY_RESIZE KEY_RESTART KEY_RESUME KEY_RIGHT KEY_SAVE KEY_SBEG KEY_SCANCEL KEY_SCOMMAND KEY_SCOPY KEY_SCREATE KEY_SDC KEY_SDL KEY_SELECT KEY_SEND KEY_SEOL KEY_SEXIT KEY_SF KEY_SFIND KEY_SHELP KEY_SHOME KEY_SIC KEY_SLEFT KEY_SMESSAGE KEY_SMOVE KEY_SNEXT KEY_SOPTIONS KEY_SPREVIOUS KEY_SPRINT KEY_SR KEY_SREDO KEY_SREPLACE KEY_SRESET KEY_SRIGHT KEY_SRSUME KEY_SSAVE KEY_SSUSPEND KEY_STAB KEY_SUNDO KEY_SUSPEND KEY_UNDO KEY_UP

## COMPATIBILITY

In the 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(0)` and `curses.nl(1)` instead of `nonl()` and `nl()`, and likewise `curses.echo(0)` and `curses.echo(1)` 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, `addch()` has three other variants: `waddch()`, `mvaddch()`, and `mvwaddch()`.

## INSTALLATION

      luarocks install luaposix

## AUTHOR

luaposix curses was originally written by Tiago Dionizio, and is maintained by Reuben Thomas at http://github.com/luaposix/luaposix
This documentation was created by a script written by Peter Billam.

## SEE ALSO

http://luaforge.net/projects/luaposix/ http://luarocks.org/repositories/rocks/index.html#luaposix http://git.savannah.gnu.org/cgit/zile.git/tree/src/term_curses.lua?h=lua http://search.cpan.org/perldoc?Curses man ncurses man curses