tym

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

Installation

Arch Linux

$ yay -S tym

Other distros

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

Configuration

If $XDG_CONFIG_HOME/tym/config.lua exists, it is executed when the app starts. You can change the path by --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',
})

All available config values are shown below.

Theme customization

When $XDG_CONFIG_HOME/tym/theme.lua exists, it is loaded before loading config. You can change the path by --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

Keymap

Default keymap

Customizing keymap

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 turethy 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,
})

Lua API

Hooks

If turethy value is returned in a callback function, the default action is will be canceled.

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)

Interprocess communication using D-Bus

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.

Signals

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'

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'

Methods

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.

Options

--help -h

$ tym -h

--use=<path> -u <path>

$ 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

--theme=<path> -t <path>

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

If NONE is provided, default theme will be used.

$ tym -t NONE

--signal=<signal name> -s <signal name>

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

--call=<method name> -c <method name>

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'

--<config option>

You can set config value via command line option.

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

Development

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

Pro tips

$ yay -S vte3-git --editmenu

prepare() {
  arch-meson vte build \
      -D sixel=true -D b_lto=false
}

local tym = require('tym')

function update_alpha(delta)
  r, g, b, a = tym.color_to_rgba(tym.get('color_background'))
  a = math.max(math.min(1.0, a + delta), 0.0)
  bg = tym.rgba_to_color(r, g, b, a)
  tym.set('color_background', bg)
  tym.notify(string.format('%s alpha to %f', (delta > 0 and 'Inc' or 'Dec'), a))
end

tym.set_keymaps({
  ['<Ctrl><Shift>Up'] = function()
    update_alpha(0.05)
  end,
  ['<Ctrl><Shift>Down'] = function()
    update_alpha(-0.05)
  end,
})

tym.set_hook('scroll', function(dx, dy, x, y)
  if tym.check_mod_state('<Ctrl>') then
    if dy > 0 then
      s = tym.get('scale') - 10
    else
      s = tym.get('scale') + 10
    end
    tym.set('scale', s)
    tym.notify('set scale: ' .. s .. '%')
    return true
  end
  if tym.check_mod_state('<Shift>') then
    update_alpha(dy < 0 and 0.05 or -0.05)
    return true
  end
end)

local tym = require('tym')

tym.set_config({
  shell = '/bin/bash',
})

tym.set_timeout(coroutine.wrap(function()
  local i = 0
  local message = 'echo "hello World!"'
  while i < #message do
    i = i + 1
    tym.put(message:sub(i, i))
    coroutine.yield(true)
  end
  coroutine.yield(true)
  tym.send_key('<Ctrl>m')
  coroutine.yield(false)
end), 100)

local tym = require('tym')

local remap = function (a, b)
  tym.set_keymap(a, function()
    tym.send_key(b)
  end)
end
remap('<Alt>h', '<Alt>Left') -- remap as meta key inputs
remap('<Alt>l', '<Alt>Right')
remap('<Alt><Shift>h', '<Alt><Shift>Left')
remap('<Alt><Shift>l', '<Alt><Shift>Right')

License

MIT