tym

tym is a Lua-configurable terminal emulator base on VTE.

$ yay -S tym

$ nix-env -iA nixos.tym

Download the latest release from Releases, extract it and run as below

$ ./configure
$ sudo make install

$ 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-devel

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.

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.

local bg = '#161821'
local fg = '#c6c8d1'
return {
  color_background = bg,
  color_foreground = fg,
  color_bold = fg,
  color_cursor = fg,
  color_cursor_foreground = bg,
  color_highlight = fg,
  color_highlight_foreground = bg,
  color_0  = bg,
  color_1  = '#e27878',
  color_2  = '#b4be82',
  color_3  = '#e2a478',
  color_4  = '#84a0c6',
  color_5  = '#a093c7',
  color_6  = '#89b8c2',
  color_7  = fg,
  color_8  = '#6b7089',
  color_9  = '#e98989',
  color_10 = '#c0ca8e',
  color_11 = '#e9b189',
  color_12 = '#91acd1',
  color_13 = '#ada0d3',
  color_14 = '#95c4ce',
  color_15 = '#d2d4de',
}

You need to return the color map as table.

color_0  : black (background)
color_1  : red
color_2  : green
color_3  : brown
color_4  : blue
color_5  : purple
color_6  : cyan
color_7  : light gray (foreground)
color_8  : gray
color_9  : light red
color_10 : light green
color_11 : yellow
color_12 : light blue
color_13 : pink
color_14 : light cyan
color_15 : white

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.

-- also can set keymap
tym.set_keymap('<Ctrl><Shift>o', function()
  local h = tym.get('height')
  tym.set('height', h + 1)
  tym.notify('Set window height :' .. h)
end)

-- set by table
tym.set_keymaps({
  ['<Ctrl><Shift>t'] = function()
    tym.reload()
    tym.notify('reload config')
  end,
  ['<Ctrl><Shift>v'] = function()
    -- reload and notify
    tym.send_key('<Ctrl><Shift>t')
  end,

  ['<Shift>y'] = function()
    tym.notify('Y has been pressed')
    return true -- notification is shown and `Y` will be inserted
  end,
  ['<Shift>w'] = function()
    tym.notify('W has been pressed')
    -- notification is shown but `W` is not inserted
  end,
})

If truthy value is returned in a callback function, the default action will be stopped.

tym.set_hooks({
  title = function(t)
    tym.set('title', 'tym - ' .. t)
    return true -- this is needed to cancenl default title application
  end,
})

--- NOTE:
-- If you set the hook to 'clicked' handler, you need to open URI manually like below,
tym.set_hook('clicked', function(button, uri)
  print('you pressed button:', button) -- 1:left, 2:middle, 3:right

  -- open URI only by middle click
  if button == 2 then
    if uri then
      print('you clicked URI: ', uri)
      tym.open(uri)
      -- disable the default action 'put clipboard' when open URI
      return true
    end
  end
end)

Each tym window has an unique ID, which can be checked by tym.get_id() or $TYM_ID, and also listen to D-Bus signal/method call on the path /me/endaaman/tym<ID> and the interface name me.endaaman.tym.

For example, when you prepare the following config and command,

local tym = require('tym')
tym.set_hook('signal', function (p)
  print('Hello from DBus signal')
  print('param:', p)
end)

$ dbus-send /me/endaaman/tym0 me.endaaman.tym.hook string:'THIS IS PARAM'

or

tym.signal(0, 'hook', {'THIS IS PARAM'}) -- NOTICE: param must be table

you will get an output like below.

Hello from DBus signal
param:  THIS IS PARAM

Alternatively, you can use tym command to send signal.

$ tym --signal hook --dest 0 --param 'THIS IS PARAM'

If the target window is its own one, it will the value of $TYM_ID and --dest can be omitted. So it is enough like below.

$ tym --signal hook --param 'THIS IS PARAM'

For example, when you exec the command,

$ dbus-send --print-reply --type=method_call --dest=me.endaaman.tym /me/endaaman/tym0 me.endaaman.tym.eval string:'return "title is " .. tym.get("title")'

then you will get like below.

method return time=1646287109.007168 sender=:1.3633 -> destination=:1.3648 serial=39 reply_serial=2
   string "title is tym"

As same as signals, you can use tym command to execute method calling.

$ tym --call eval --dest 0 --param 'return "title is " .. tym.get("title")'

Of course, --dest can be omitted as well.

$ tym -h

$ tym --use=/path/to/config.lua

If NONE is provided, all config will be default (user-defined config file will not be loaded).

$ tym -u NONE

$ tym --use=/path/to/theme.lua

If NONE is provided, default theme will be used.

$ tym -t NONE

$ tym --signal hook

Sends a D-Bus signal to the current instance (determined by $TYM_ID environment value). To send to another instance, use --dest (or -d) option.

Calls D-Bus method of the current instance (determined by $TYM_ID environment value). To call it of another instance, provide --dest (or -d) option.

$ tym --call eval --param 'return 1 + 2'

This makes tym a daemon process, which has no window or application context.

$ tym --daemon

To enable the daemon feature, set tym-daemon.desktop as auto-started on the DE's settings or add the line tym --daemon & in your .xinitrc.

This sets the terminal's working directory. <path> must be an absolute path. If unspecified tym will use the current working directory of the terminal invocation.

$ tym --cwd=/home/user/projects

You can set config value via command line option.

$ tym --shell=/bin/zsh --color_background=red --width=40 --ignore_default_keymap

$ tym --isolated

This option enables tym to create a separate process for each instance. Then an app instance will be isolated from D-Bus and no longer have ability to handle D-Bus signals/method calls.

tym also accepts double dash -- option as the command line to spawn.

$ tym -- less -N Dockerfile

Clone this repo and run as below

$ autoreconf -fvi
$ ./configure --enable-debug
$ make && ./src/tym -u ./path/to/config.lua   # for debug
$ make check; cat src/tym-test.log            # for unit tests

Run tests in docker container

$ docker build -t tym .
$ docker run tym

MIT