https://github.com/hoelzro/lua-term
Terminal operations for Lua
https://github.com/hoelzro/lua-term
Last synced: 11 months ago
JSON representation
Terminal operations for Lua
- Host: GitHub
- URL: https://github.com/hoelzro/lua-term
- Owner: hoelzro
- License: mit
- Created: 2012-06-25T21:04:17.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2023-12-29T17:58:44.000Z (about 2 years ago)
- Last Synced: 2024-04-13T09:06:08.613Z (almost 2 years ago)
- Language: Lua
- Size: 27.3 KB
- Stars: 150
- Watchers: 13
- Forks: 23
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES
- License: COPYING
Awesome Lists containing this project
- awesome-lua - lua-term - Terminal operations and manipulations. (Resources / Command-line Utilities)
README
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