Overview -------- lua-term is a Lua module for manipulating a terminal. Installation ------------ lua-term is available on Luarocks. ## OpenBSD lua-term is available as an OpenBSD package. Use the proper Lua flavour to get the package for your Lua version: ``` # For Lua 5.1 $ doas pkg_add -r lua-term # For Lua 5.2 $ doas pkg_add -r lua52-term # For Lua 5.3 $ doas pkg_add -r lua53-term ``` Or install from ports: ``` $ cd /usr/ports/devel/lua-term $ env FLAVOR=lua51 doas make install ``` ## openSUSE lua-term is available in the `devel:languages:lua` devel project on [OBS](https://build.opensuse.org/package/show/devel:languages:lua/lua-luaterm). Add the repository and install lua-term via: ``` zypper addrepo http://download.opensuse.org/repositories/devel:/languages:/lua/openSUSE_Tumbleweed/devel:languages:lua.repo zypper refresh zypper in lua-luaterm ``` Adjust the repository URL to your version of openSUSE by substituting `openSUSE_Tumbleweed` with your actual version eg `opensSUSE_42.2`. ## Windows lua-term works on Windows as well when virtual terminal processing is enabled. To have this enabled automatically ensure that [LuaSystem](https://github.com/lunarmodules/luasystem) is installed (version 0.4.0 or newer). If found, that module will be used to enable virtual terminal processing and to switch output to utf-8. Usage ----- ```lua local term = require 'term' local colors = term.colors -- or require 'term.colors' print(term.isatty(io.stdout)) -- true if standard output goes to the terminal print(colors.red 'hello') print(colors.red .. 'hello' .. colors.reset) print(colors.red, 'hello', colors.reset) -- The following functions take an optional IO handle (like io.stdout); -- io.stdout is the default if you don't specify one term.clear() -- clears the screen term.cleareol() -- clears from the cursor to the end of the line --term.cursor.goto(1, 1) -- It will fail in Lua >= 5.2 because goto is a reserved word. term.cursor['goto'](1, 1) -- This will work on Lua >= 5.2, please use jump instead term.cursor.jump(1, 1) -- jump is just an alias for goto term.cursor.jump(io.stdout, 1, 1) term.cursor.goup(1) term.cursor.godown(1) term.cursor.goright(1) term.cursor.goleft(1) term.cursor.save() -- save position term.cursor.restore() -- restore position ``` `term` Functions -------------- Some functions in lua-term take an optional file handle argument; if this is not provided, `io.stdout` is used. ### `term.clear([opt_file])` Clear the terminal's contents. ### `term.cleareol([opt_file])` Clear from the current cursor position to the end of the current line. ### `term.isatty(file)` Returns `true` if `file` is a TTY; `false` otherwise. *NOTE*: This function has been deprecated in favor of luasystem's implementation (or luaposix if you don't need Windows support). If you would like this functionality in the future, please use luasystem. `term.colors` Values ------------------ The following values are available in `term.colors`: ### Terminal Attributes * reset * clear (a synonym for reset) * default (a synonym for reset) * bright * dim * underscore * blink * reverse * hidden ### Foreground Colors * black * red * green * yellow * blue * magenta * cyan * white ### Background Colors * onblack * onred * ongreen * onyellow * onblue * onmagenta * oncyan * onwhite Every value in `term.colors` may be used in several ways: ### As a Function ```lua print(colors.red 'hello') ``` ### As a String ```lua print(colors.red .. 'hello' .. colors.reset) print(colors.red, 'hello', colors.reset) ``` `term.cursor` Functions --------------------- ### `term.cursor.goto([opt_file], x, y)` Place the cursor at (`x`, `y`). ### `term.cursor.jump([opt_file], x, y)` An alias for `term.cursor.goto`. ### `term.cursor.goup([opt_file], nlines)` Moves the cursor up `nlines` lines. ### `term.cursor.godown([opt_file], nlines)` Moves the cursor down `nlines` lines. ### `term.cursor.goright([opt_file], ncols)` Moves the cursor right `ncols` columns. ### `term.cursor.goleft([opt_file], ncols)` Moves the cursor left `ncols` columns. ### `term.cursor.save([opt_file])` Saves the cursor position. ### `term.cursor.restore([opt_file])` Restores the cursor position. Alternatives ------------ If you are looking to simply provide coloration to a terminal application and would like to use a more "tag-like" API (ex. `colors '%{red}hello%{reset}'`), there is a Lua rock named ansicolors: https://github.com/kikito/ansicolors.lua