tym.1.in

.TH tym 1 "@DATE@" "@VERSION@" "tym"
.SH DESCRIPTION
\fBtym\fR is a tiny VTE-based terminal emulator, which configurable by Lua.

.SH SYNOPSIS
\fBtym\fR [OPTIONS]

.SH OPTIONS
.IP "\fB\-h\fR, \fB\-\-help\fR"
Show help message.

.IP "\fB\-v\fR, \fB\-\-version\fR"
Show version.

.IP "\fB\-u\fR, \fB\-\-use\fR=\fI<PATH>\fR"
Use <PATH> instead of default config file.

.IP "\fB\-t\fR, \fB\-\-theme\fR=\fI<PATH>\fR"
Use <PATH> instead of default theme file.

.IP "\fB\-\-cwd\fR=\fI<PATH>\fR"
Use <PATH> as the terminal's working directory. Must be an absolute path.

.IP "\fB\-\-\fR\fI<OPTION>\fR=\fI<VALUE>\fR"
Replace <OPTION> config option, where \fI<OPTION>\fR is a config option and
\fI<VALUE>\fR is a value of its option.
.fi
See \fBCONFIGURATION\fR for more information about config options.

.SH AVAILABLE OPTIONS

.IP \fBshell\fR
Type:	\fBstring\fR
.fi
Default:	\fI$SHELL\fR → \fBvte_get_user_shell()\fR → \fB/bin/sh\fR
.fi
Shell to excute.

.IP \fBtitle\fR
Type:	\fBstring\fR
.fi
Default:	\fI'tym'\fR
.fi
Initial window title.

.IP \fBfont\fR
Type:	\fBstring\fR
.fi
Default:	\fI''\fR (empty string)
.fi
You can specify it like \fI'FAMILY-LIST [SIZE]'\fR, for example \fI'Ubuntu Mono 12'\fR. The value is parsed by \fBpango_font_description_from_string()\fR. If you set empty string, the system default fixed width font will be used.

.IP \fBicon\fR
Type:	\fBstring\fR
.fi
Default:	\fI'terminal'\fR
.fi
Name of icon. cf. https://developer.gnome.org/icon-naming-spec/.

.IP \fBcursor_shape\fR
Type:	\fBstring\fR
.fi
Default:	\fI'system'\fR
.fi
\fI'block'\fR, \fI'ibeam'\fR or \fI'underline'\fR are available.

.IP \fBcursor_blink_mode\fR
Type:	\fBstring\fR
.fi
Default:	\fI'system'\fR
.fi
\fI'system'\fR, \fI'on'\fR or \fI'off'\fR are available.

.IP \fBterm\fR
Type:	\fBstring\fR
.fi
Default:	\fI'xterm-256color'\fR
.fi
Default value of `$TERM`.

.IP \fBrole\fR
Type:	\fBstring\fR
.fi
Default:	\fI''\fR
.fi
Unique identifier for the window. If empty string set, no value set. cf. gtk_window_set_role()

.IP \fBcjk_width\fR
Type:	\fBstring\fR
.fi
Default:	\fI'narrow'\fR
.fi
\fI'narrow'\fR or \fI'wide'\fR are available.

.IP \fBuri_schemes\fR
Type:	\fBstring\fR
.fi
Default:	\fI'http https file mailto'\fR
.fi
Space-separated list of URI schemes to be highlighted and clickable. Specify empty string to disable highlighting. Specify \fB'*'\fR to accept any strings valid as schemes (according to RFC 3986).

.IP \fBwidth\fR
Type:	\fBinteger\fR
.fi
Default:	\fI80\fR
.fi
Initial columns.

.IP \fBheight\fR
Type:	\fBinteger\fR
.fi
Default:	\fI22\fR
.fi
Initial rows.

.IP \padding_horizontal\fR
Type:	\fBinteger\fR
.fi
Default:	\fI80\fR
.fi
Horizontal padding.

.IP \padding_vertical\fR
Type:	\fBinteger\fR
.fi
Default:	\fI80\fR
.fi
Vertical padding.

.IP "\ignore_default_keymap\fR"
Type:	\fBboolean\fR
.fi
Default:	\fIfalse\fR
.fi
If it is provided, the default keymap will not be used.

.IP \fBautohide\fR
Type:	\fBboolean\fR
.fi
Default:	\fIfalse\fR
.fi
If it is provided, mouse cursor will be hidden when you presses a key.

.IP \fBbold_is_bright\fR
Type:	\fBboolean\fR
.fi
Default:	\fIfalse\fR
.fi
If it is provided, make bold texts bright..

.IP \fBsilent\fR
Type:	\fBboolean\fR
.fi
Default:	\fIfalse\fR
.fi
If it is provided, beep does not sound when bell sequence is sent.

.IP \fBscrollback_length\fR
Type:	\fBinteger\fR
.fi
Default:	\fI512\fR
.fi
If it is provided, the length of scrollback buffer is resized.

.IP \fBcolor_window_background\fR
Type:	\string\fR
.fi
Default:	\fI''\fR
.fi
Color of the terminal window. It is seen when `padding_horizontal` `padding_vertical` is not `0`. If you specify 'NONE', the window background will not be drawn.

.IP \fBcolor_foreground\fR
.IP \fBcolor_background\fR
.IP \fBcolor_cursor\fR
.IP \fBcolor_cursor_foreground\fR
.IP \fBcolor_highlight\fR
.IP \fBcolor_highlight_foreground\fR
.IP \fBcolor_bold\fR
.IP "\fBcolor_0\fR .. \fBcolor_15\fR"
Type: \fBstring\fR
.fi
Default:	\fI''\fR (empty string)
.fi
You can specify standard color string such as \fI'#f00'\fR, \fI'#ff0000'\fR, \fI'rgba(22, 24, 33, 0.7)'\fR, or \fI'red'\fR. It will be parsed by \fBgdk_rgba_parse()\fR. If you set empty string, the VTE default color will be used. If you set 'NONE' for `color_background`, the terminal background will not be drawn.


.SH DEFAULT KEYBINDINGS
.TS
left,box;
lB lB
__
l l.
Key	Action
\fBCtrl\fR+\fBShift\fR+\fBc\fR	Copy selection to clipboard
\fBCtrl\fR+\fBShift\fR+\fBv\fR	Paste from clipboard
\fBCtrl\fR+\fBShift\fR+\fBr\fR	Reload config file
.TE

.SH CONFIGURATION

When \fB$XDG_CONFIG_HOME/tym/config.lua\fR exists, it is executed. Here is an example.

.nf
\fB
local tym = require('tym')
tym.set('font', 'DejaVu Sans Mono 11')
tym.set_config({
  shell = '/usr/bin/fish',
  cursor = 'underline',
  autohide = true,
  color_foreground = 'red',
})
tym.set_keymap('<Ctrl><Shift>o', function()
  local h = tym.get('height')
  tym.set('height', h + 1)
  tym.apply() -- needed for applying config value
  tym.notify('Set window height :' .. h)
end)
tym.set_keymaps({
  ['<Ctrl><Shift>y'] = function()
    tym.reload()
    tym.notify('reload config')
  end,
  ['<Ctrl><Shift>v'] = function()
    tym.notify("Overwrite pasting event")
  end,
})
\fR
.fi

.SH LUA API

.IP \fBtym.get(key)\fR
Returns:	\fBany\fR
.fi
Get config value.

.IP "\fBtym.set(key, value)\fR"
Returns:	\fBvoid\fR
.fi
Get config value.

.IP "\fBtym.get_config()\fR"
Returns:	\fBtable\fR
.fi
Get config table.

.IP "\fBtym.set_config(table)\fR"
Returns:	\fBvoid\fR
.fi
Set config by table.

.IP "\fBtym.reset_config()\fR"
Returns:	\fBvoid\fR
.fi
Reset config to default.

.IP "\fBtym.set_keymap(accelerator, func)\fR"
Returns:	\fBvoid\fR
.fi
Set keymap. \accelerator\fB must be in a format parsable by \fBgtk_accelerator_parse()\fR.

.IP "\fBtym.set_keymaps(table)\fR"
Returns:	\fBvoid\fR
.fi
Set keymaps by table.

.IP "\fBtym.reset_keymaps()\fR"
Returns:	\fBvoid\fR
.fi
Reset custom keymaps.

.IP "\fBtym.send_key(accelerator)\fR"
Returns:	\fBvoid\fR
.fi
Send key press event.

.IP \fBtym.reload()\fR
Returns:	\fBvoid\fR
.fi
Reload config file and theme file.

.IP \fBtym.reload_theme()\fR
Returns:	\fBvoid\fR
.fi
Reload theme file.

.IP \fBtym.apply()\fR
Returns:	\fBvoid\fR
.fi
Appyl config to app.

.IP \fBtym.put(text)\fR
Returns:	\fBvoid\fR
.fi
Feed text.

.IP \fBtym.bell()\fR
Returns:	\fBvoid\fR
.fi
Sound bell.

.IP "\fBtym.notify(message, title = \fI'tym'\fB)\fR"
Returns:	\fBvoid\fR
.fi
Show desktop notification.

.IP \fBtym.copy()\fR
Returns:	\fBvoid\fR
.fi
Copy current selection.

.IP \fBtym.paste()\fR
Returns:	\fBvoid\fR
.fi
Paste clipboard.

.IP \fBtym.get_version()\fR
Returns:	\fBstring\fR
.fi
Get version string.

.IP \fBtym.get_config_path()\fR
Returns:	\fBstring\fR
.fi
Get path of config file currently being read.

.IP \fBtym.get_theme_path()\fR
Returns:	\fBstring\fR
.fi
Get path of theme file currently being read.

.SH THEME CUSTOMIZATION

When \fB$XDG_CONFIG_HOME/tym/theme.lua\fR exists, it is executed. Here is an example.

.nf
\fB
local fg = '#d2d4de'
local bg = '#161821'
return {
  color_background = bg,
  color_foreground = fg,
  color_0  = '#161821',
  color_1  = '#e27878',
  -- SNIP
  color_14 = '#95c4ce',
  color_15 = '#d2d4de',
}
\fR
.fi

You need to return table within global context.