terminfo.lua

NAME
SYNOPSIS

DESCRIPTION
FUNCTIONS

DOWNLOAD
CHANGES

AUTHOR
SEE ALSO

NAME

terminfo - access the terminfo database

SYNOPSIS

 local T = require 'terminfo'  -- see:  man terminfo
 print("Can a vt100 do overstrike ? ",
    tostring(T.getflag('os','vt100')))
 print("Tabs on this terminal are initially every ",
    T.getnum('it'))
 print("Can this terminal do overstrike ? ",
    tostring(T.flag_by_varname('over_strike')))
 print("Tabs on xterm are initially every ",
    T.num_by_varname('init_tabs', 'xterm'))
 if T.get('km') then  -- this kbd has a Meta-Key :-)
    if T.get('init_tabs') < 8 then
       print('someone changed the tabstop setting !')
    end
    print('testing the Home key:'..T.get('key_home'))
    if T.get('cud1') ~= T.get('cursor_down') then
       print('BUG: capname and varname gave different answers')
    end
 end
 local P = require 'posix'
 local tty = io.open(P.ctermid(), 'a+') -- the controlling terminal
 tty:write(T.tparm(T.get('cup'),20,30))
 tty:write(T.tparm(T.get('setaf'), 1)) -- set foreground colour to red

DESCRIPTION

This module provides access to terminfo database entries, see man terminfo.

This database provides information about a terminal, in three separate sets of capabilities. Flag capabilities are boolean (more accurately, they are either true or nil); they indicate the presence of a particular ability, feature, or bug. Number capabilities give the size, count or other numeric detail of some feature of the terminal. String capabilities are usually control strings that the terminal will recognise, or send.

String capabilities involving no parameters (e.g. clear_screen) can be printed directly to the screen and will work as expected. Any parameters (e.g. with cursor_address) are represented, using % characters, in a notation documented in the Parameterized Strings section of man terminfo; these parameters must be put in place with the function tparm(capability, parameters...) This function is not present in the Perl module.

Each capability has two names; a short name called the capname, and a longer name called the varname; for details, see man terminfo. This module, like the Perl Term::Terminfo module, provides two sets of functions, one that works on capnames, one that works on varnames. It also, unlike the Perl module, provides a general-purpose function get(name) which returns the capability whether it is a flag, number or string, and whether the name is a capname or a varname.

Some of the many useful capnames are: cols (number of columns), lines (number of lines)
el (clear to end of line), ed (clear to end of screen)
cub1 (cursor left), cud1 (cursor down), cuf1 (cursor right), cuu1 (cursor up)
cup (move the cursor : line and column are numbered from 0,0 in the top left corner, and remember the parameters are needed in line,column order, so if you're thinking in x,y then it's tty:write(T.tparm(T.get('cup'),y,x) )
civis (make cursor invisible), cnorm (cursor normal)
rev (reverse video), setaf (set foreground color), setbf (set background color), sgr0 (exit attribute mode)
For more details, see man terminfo.

Unlike the Perl Term::Terminfo module, there is no separate constructor. The term parameter is passed as an optional second argument. If it is not present, the current terminal, from the environment variable TERM, is used.

FUNCTIONS

T.get( name [, term] )
Returns the value of the capability of the given name, whether the capability is a flag, number or string, and whether the name is a capname or a varname. This function is not present in the Perl Term::Terminfo module.

T.tparm( capability, <param1, param2, ...> )
Substitutes the parameters according to the notation documented in the Parameterized Strings section of man terminfo, and returns the resulting string, for example,
io.stderr:write(T.tparm(T.get('cursor_address'),20,30))
So that you remain in control of your input/output at the Lua level, no tputs function is provided; thus, as a side effect, any padding information will be lost. This is very rarely a problem nowadays, but it could mean that for example: the flash capability may not work as expected. If you really need this, you can resort to: os.execute('tput flash')
This function is not present in the Perl Term::Terminfo module.

bool = T.getflag( capname [, term] )
num = T.getnum( capname [, term] )
str = T.getstr( capname [, term] )
Return the value of the flag, number or string capability respectively, of the given capname.

bool = T.flag_by_varname( varname [, term] )
num = T.num_by_varname( varname [, term] )
str = T.str_by_varname( varname [, term] )
Return the value of the flag, number or string capability respectively, of the given varname.

capnames = T.flag_capnames( [term] )
capnames = T.num_capnames( [term] )
capnames = T.str_capnames( [term] )
Return arrays of the capnames of the supported flags, numbers, and strings respectively.

varnames = T.flag_varnames( [term] )
varnames = T.num_varnames( [term] )
varnames = T.str_varnames( [term] )
Return arrays of the varnames of the supported flags, numbers, and strings respectively.

DOWNLOAD

This module is available as a LuaRock in luarocks.org/modules/peterbillam so you should be able to install it with the command:

 $ su
 Password:
 # luarocks install terminfo

or:

 # luarocks install http://www.pjb.com.au/comp/lua/terminfo-1.8-0.rockspec

It depends on a term.h header-file; so for example, on Debian you may also need:

 # aptitude install libncurses5-dev

CHANGES

 20211118 1.8 works with lua5.4
 20191031 1.7 minor performance improvements
 20191030 1.6 fixed a bad bug in tparm
 20150422 1.5 works with lua5.3
 20150216 1.4 termcap specified as an external dependency
 20140519 1.3 switch pod and doc over to using moonrocks
 20140519 1.2 installs as terminfo not Terminfo under luarocks 2.1.2
 20130917 1.1 introduce tparm()
 20130915 1.0 first working version

AUTHOR

Translated into Lua by Peter Billam (www.pjb.com.au/comp/contact.html) from the Perl CPAN module (search.cpan.org/perldoc?Term::Terminfo) by Paul Evans