Lua-configurable terminal emulator
tym is a Lua-configurable terminal emulator base on VTE.
$ yay -S tym$ nix-env -iA nixos.tymDownload the latest release from Releases, extract it and run as below
$ ./configure
$ sudo make installBuild dependencies (click to open)
$ sudo pacman -S vte3 lua53$ sudo apt install libgtk-3-dev libvte-2.91-dev liblua5.3-dev libpcre2-dev$ sudo xbps-install -S vte3-devel lua-develWe did not check which packages are needed to build on other distros or OS. We are waiting for your contribution ;)
If $XDG_CONFIG_HOME/tym/config.lua exists, it is executed when the app starts. You can change the path with the --use/-u option.
-- At first, you need to require tym module
local tym = require('tym')
-- set individually
tym.set('width', 100)
tym.set('font', 'DejaVu Sans Mono 11')
-- set by table
tym.set_config({
shell = '/usr/bin/fish',
cursor_shape = 'underline',
autohide = true,
color_foreground = 'red',
})See wiki to check out the advanced examples.
All available config values are shown below.
| field name | type | default value | description |
|---|---|---|---|
shell |
string | $SHELL → vte_get_user_shell() → '/bin/sh' |
Shell to execute. |
term |
string | 'xterm-256color' |
Value of $TERM. |
title |
string | 'tym' |
Initial window title. |
font |
string | '' |
You can specify font with 'FAMILY-LIST [SIZE]', for example 'Ubuntu Mono 12'. The value is parsed by pango_font_description_from_string(). If empty string is set, the system default fixed width font will be used. |
icon |
string | 'utilities-terminal' |
Name of icon. cf. Icon Naming Specification |
role |
string | '' |
Unique identifier for the window. If empty string is set, no value set. (cf. gtk_window_set_role()) |
cursor_shape |
string | 'block' |
'block', 'ibeam' or 'underline' can be used. |
cursor_blink_mode |
string | 'system' |
'system', 'on' or 'off' can be used. |
cjk_width |
string | 'narrow' |
'narrow' or 'wide' can be used. |
background_image |
string | '' |
Path to background image file. |
uri_schemes |
string | 'http https file mailto' |
Space-separated list of URI schemes to be highlighted and clickable. Specify empty string to disable highlighting. Specify '*' to accept any strings valid as schemes (according to RFC 3986). |
width |
integer | 80 |
Initial columns. |
height |
integer | 22 |
Initial rows. |
scale |
integer | 100 |
Font scale in percent(%) |
cell_width |
integer | 100 |
Cell width scale in percent(%). |
cell_height |
integer | 100 |
Cell height scale in percent(%). |
padding_top |
integer | 0 |
Top padding. |
padding_bottom |
integer | 0 |
Bottom padding. |
padding_left |
integer | 0 |
Left padding. |
padding_right |
integer | 0 |
Right padding. |
scrollback_length |
integer | 512 |
Length of the scrollback buffer. |
scrollback_on_output |
boolean | true |
Whether to scroll the buffer when the new data is output. |
ignore_default_keymap |
boolean | false |
Whether to use default keymap. |
autohide |
boolean | false |
Whether to hide mouse cursor when the user presses a key. |
silent |
boolean | false |
Whether to beep when bell sequence is sent. |
bold_is_bright |
boolean | false |
Whether to make bold texts bright. |
osc_clipboard |
boolean | false |
Whether to let the application write the clipboard. See the next section. Requires VTE >= 0.78. |
color_window_background |
string | '' |
Color of the terminal window. It is seen when 'padding_horizontal' 'padding_vertical' is not 0. If you set 'NONE', the window background will not be drawn. |
color_foreground, color_background, color_cursor, color_cursor_foreground, color_highlight, color_highlight_foreground, color_bold, color_0 ... color_15 |
string | See the next section | You can specify standard color string such as '#f00', '#ff0000', 'rgba(22, 24, 33, 0.7)' or 'red'. It will be parsed by gdk_rgba_parse(). If empty string is set, the VTE default color will be used. If you set 'NONE' for color_background, the terminal background will not be drawn. |
Most terminals let the running application put text into the clipboard with OSC 52, which is what makes copying work over SSH and inside tmux. VTE does not implement it (GNOME/vte#2495) and gives no hook to intercept it, so tym exposes the same capability through a VTE termprop instead.
Set osc_clipboard = true in your config to enable it, then write base64-encoded UTF-8 text to the vte.ext.tym.clipboard termprop:
printf '\033]666;vte.ext.tym.clipboard=%s\033\\' "$(printf 'hello' | base64 | tr -d '\n')"The sequence must end with ST (\033\\). VTE does not accept BEL as the terminator of OSC 666.
Text longer than 2048 bytes is dropped: that is the size limit VTE puts on the termprop. tym logs a warning about it when the tmux setup below is in use, but only as long as the sequence stays within the length limit of OSC 666 itself — past roughly 3000 bytes VTE throws the whole sequence away before tym hears anything, and the copy is lost without a word.
For tmux, point the Ms capability at the same sequence and set-clipboard will use it:
set -g set-clipboard on
set -as terminal-overrides ',*:Ms=\E]666;vte.ext.tym.clipboard.flags=%p1%s;vte.ext.tym.clipboard=%p2%s\E\\'tmux only expands Ms when the capability references its first parameter, which is the selection flags, so they are parked in vte.ext.tym.clipboard.flags (OSC 666 takes several ;-separated termprops at once). tym does not act on the flags themselves — the termprop exists to keep the payload a bare base64 string, and, since it arrives even when VTE has thrown the payload away, to let tym warn that a copy was lost.
This is disabled by default on purpose: any output the terminal receives can then replace your clipboard, so simply cating a hostile file would be enough to overwrite it. Reading the clipboard is not implemented, so the application can never learn its contents.
When $XDG_CONFIG_HOME/tym/theme.lua exists, it is loaded before loading config. You can change the path by using the --theme/-t option. The following is an example, whose color values are built-in default. They were ported from iceberg.
…You need to return the color map as table.
Color correspondence (click to open)
| Key | Action |
|---|---|
| Ctrl Shift c | Copy selection to clipboard. |
| Ctrl Shift v | Paste from clipboard. |
| Ctrl Shift r | Reload config file. |
You can register keymap(s) using tym.set_keymap(accelerator, func) or tym.set_keymaps(table). accelerator must be in a format parsable by gtk_accelerator_parse(). If a truthy value is returned, the event propagation will not be stopped.
…| Name | Return value | Description |
|---|---|---|
tym.get(key) |
any | Get config value. |
tym.set(key, value) |
void | Set config value. |
tym.get_default_value(key) |
any | Get default config value. |
tym.get_config() |
table | Get whole config. |
tym.set_config(table) |
void | Set config by table. |
tym.reset_config() |
void | Reset all config. |
tym.set_keymap(accelerator, func) |
void | Set keymap. |
tym.unset_keymap(accelerator) |
void | Unset keymap. |
tym.set_keymaps(table) |
void | Set keymaps by table. |
tym.reset_keymaps() |
void | Reset all keymaps. |
tym.set_hook(hook_name, func) |
void | Set a hook. |
tym.set_hooks(table) |
void | Set hooks. |
tym.reload() |
void | Reload config file. |
tym.reload_theme() |
void | Reload theme file. |
tym.send_key() |
void | Send key press event. |
tym.signal(id, hook, {param...}) |
void | Send signal to the tym instance specified by id. |
tym.set_timeout(func, interval=0) |
int(tag) | Set timeout. return true in func to execute again. |
tym.clear_timeout(tag) |
void | Clear the timeout. |
tym.put(text) |
void | Feed text. |
tym.bell() |
void | Sound bell. |
tym.open(uri) |
void | Open URI via your system default app like xdg-open(1). |
tym.notify(message, title='tym') |
void | Show desktop notification. |
tym.copy(text, target='clipboard') |
void | Copy text to clipboard. As target, 'clipboard', 'primary' or secondary can be used. |
tym.copy_selection(target='clipboard') |
void | Copy current selection. |
tym.paste(target='clipboard') |
void | Paste clipboard. |
tym.check_mod_state(accelerator) |
bool | Check if the mod key(such as '' or ``) is being pressed. |
tym.color_to_rgba(color) |
r, g, b, a | Convert color string to RGB bytes and alpha float using gdk_rgba_parse(). |
tym.rgba_to_color(r, g, b, a) |
string | Convert RGB bytes and alpha float to color string like rgba(255, 128, 0, 0.5) can be used in color option such as color_background. |
tym.rgb_to_hex(r, g, b) |
string | Convert RGB bytes to 24bit HEX like #ABCDEF. |
tym.hex_to_rgb(hex) |
r, g, b | Convert 24bit HEX like #ABCDEF to RGB bytes. |
tym.get_monitor_model() |
string | Get monitor model on which the window is shown. |
tym.get_cursor_position() |
int, int | Get where column and row the cursor is. |
tym.get_clipboard(target='clipboard') |
string | Get content in the clipboard. |
tym.get_selection() |
string | Get selected text. |
tym.has_selection() |
bool | Get if selected. |
tym.select_all() |
void | Select all texts. |
tym.unselect_all() |
void | Unselect all texts. |
tym.get_text(start_row, start_col, end_row, end_col) |
string | Get text on the terminal screen. If you set -1 to end_row and end_col, the target area will be the size of termianl. |
tym.get_config_path() |
string | Get full path to config file. |
tym.get_theme_path() |
string | Get full path to theme file. |
tym.get_terminal_pid() |
int |
No open issues yet, or sync has not completed.