HexChat Lua Interface¶

Scripts¶

Just like many other language plugins, the Lua plugin provides the commands /load, /unload, and /reload which operate on Lua scripts. You can forcibly load a Lua script with any extension by using /lua load, /lua unload or /lua reload instead. All files ending in .lua and .luac in the addons directory will be automatically loaded on startup.

Every script gets its own isolated state. The state is initialized with the Lua standard library, and has a global table called hexchat providing the API, which is described below.

Commands¶

/lua load <filename>¶

/load <filename>¶

Loads a script with the given filename. /load will only load files ending in .lua and .luac.

/lua unload <filename>¶

/unload <filename>¶

Unloads a script with the given filename.

/reload <filename>`¶

/lua reload <filename>`¶

Reloads a script with the given filename.

/lua list¶

Lists loaded Lua scripts.

/lua exec <code>¶

Executes given code in the interpreter.

/lua console¶

Opens an interactive console. Messages to that tab are intercepted and interpreted as code.

/lua inject <filename> <code>¶

Executes given code in the context of a given script (which has to be loaded).

/lua reset¶

Reloads the interpreter (but not the scripts).

Environment¶

Note

This only directly applies to Windows since other platforms rely on the Lua version and libraries installed on your system. It is most likely still of use, however.

The embedded Lua implementation is LuaJIT . LuaJIT by itself provides a few extensions, such as the the bit and ffi modules. It generally follows Lua 5.1 and has a few backwards compatible additions from Lua 5.2, which are explained on the extensions page.

Hexchat then provides the global hexchat table, which is described in detail in the API section below.

Additionally, the lgi module is available, which provides GObject-introspection, since it is used by Hexchat internally. For looking up mappings, the Python GObject Introspection API reference can be used, as it is very similar.

References¶

LuaJIT: http://luajit.org/luajit.html
LuaJIT Extensions: http://luajit.org/extensions.html
BitOp Library: http://bitop.luajit.org/api.html
FFI Library: http://luajit.org/ext_ffi.html
LGI project page: https://github.com/pavouk/lgi
LGI User Guide: https://github.com/pavouk/lgi/blob/master/docs/guide.md
Gnome API Reference: https://developer.gnome.org/references
Python GObject Introspection API Reference: http://lazka.github.io/pgi-docs/index.html

API¶

The HexChat API is accessible through the hexchat table.

General functions¶

hexchat.register(name, version, description)¶

Upon initialization every script should introduce itself by calling this function. Failure to do so will result in the script being unloaded immediately.

hexchat.command(cmd)¶

Executes the command cmd in the current context, as if /cmd was typed by the user.

See /help for valid commands and their documentation.

hexchat.print(…)¶

Prints zero or more values to the current tab. This function also replaces the global print function.

hexchat.emit_print(event, …)¶

Emits a text event (can be found in Settings->Text Events) into the current tab. ... are the strings that are passed as arguments to the event. At the moment due to internal limitations, only 5 arguments are passed as there aren’t any text events with more arguments.

hexchat.send_modes(targets, mode[, max])¶

Sets multiple modes in the current context, possibly grouping them together up to the server limit. targets needs to be an array of strings, mode needs to be a string of 2 characters: + or - followed by the mode letter. max is the number of modes on one line, if omitted the serverside limit is used.

hexchat.nickcmp(a, b)¶

Compares 2 strings case-insensitively, in accordance with current server’s casemapping. Returns a negative number if a is less than b, zero if they are equal, and a positive number if a is more than b.

hexchat.strip(string[, keep_colors[, keep_attrs]])¶

Removes color codes from the given string. If keep_colors is a truthy value, colors are not removed. If keep_attrs is a truthy value, attributes such as bold or underline are not removed. Returns the resulting string.

hexchat.get_info(id)¶

Returns information about the current context. id is a string determining the information you want. It can be one of the following (case sensitive):

ID	Return value
away	Away reason or `nil` if you are not away
channel	Current context’s name
charset	Character set used in the current context
configdir	HexChat config directory, e.g. `/home/user/.config/hexchat`
event_text <name>	Text event format string for `<name>`
host	Real hostname of the server you connected to
inputbox	The input box contents, what the user has typed
libdirfs	Library directory. e.g. `/usr/lib/hexchat`. The same directory is used for autoloading plugins
modes	Channel modes, or `nil` if not known
network	Current network name, or `nil` if not known
nick	Your current nickname
password	Password for this network or `nil`
server	Current server name (what the server claims to be) or `nil` if you are not connected
topic	Current channel topic
version	HexChat version number
win_status	Window status: `active`, `hidden` or `normal`
win_ptr	A light userdata pointer to the native window. GtkWindow on unix, HWND on windows
gtkwin_ptr	A light userdata pointer to a GtkWindow. (Usable within lgi)

hexchat.iterate(list)¶

Iterate through the list list. To be used with generic for-loops in the following fashion:

for chan in hexchat.iterate("channels") do
    print(chan.server .. ": " .. chan.channel)
end

List of possible values of list, along with respective keys:

`channels`	List of channels, queries and their servers
Name	Description
channel	Tab name
channelkey	Channel’s key or `nil`
chanmodes	Channel modes, e.g. `beI,k,l` (2.12.2+)
chantypes	Channel types, e.g. `#!&`
context	Tab’s context object
flags	2^0 = Connected 2^1 = Connecting 2^2 = Marked away 2^3 = End of MOTD 2^4 = Has WHOX 2^5 = Has IDMSG 2^6 = Hide Join/Parts 2^7 = Hide Join/Parts unset 2^8 = Beep on Message 2^9 = Beep on Message unset 2^10 = <unused> 2^11 = Logging 2^12 = Logging unset 2^13 = Scrollback 2^14 = Scrollback unset 2^15 = Strip colors 2^16 = Strip colors unset 2^17 = Flash tray 2^18 = Flash tray unset 2^19 = Flash taskbar 2^20 = Flash taskbar unset
id	Unique server ID
lag	Lag in milliseconds
maxmodes	Maximum modes per line
network	Network name
nickprefixes	Nickname prefixes, e.g. `@+`
nickmodes	Nickname mode chars, e.g. `ov`
queue	Number of bytes in the send-queue
server	Server name to which this channel belongs
type	1 = Server 2 = Channel 3 = Dialog 4 = Notice 5 = SNotice
users	Number of users in this channel

`users`	Current contexts users
Name	Description
account	Account name or `nil`
away	Away message or `nil`
host	Host name in form of `user@host` or `nil`
lasttalk	Time stamp of last time they spoke
nick	Nick name
prefix	Prefix character such as `@`
realname	Real name
selected	If they are selected in the userlist

`dcc`	List of DCC file transfers
Name	Description
address32	Address of the remote user (ipv4 address)
cps	Bytes per second (speed)
destfile	Destination full pathname
file	File name
nick	Nickname of person who the file is from/to
port	TCP port number
pos	Bytes sent/received
poshigh	Bytes sent/received, high order 32 bits
resume	Point at which this file was resumed (or zero if it was not resumed)
resumehigh	Point at which this file was resumed, high order 32 bits
size	File size in bytes, low order 32 bits (cast it to unsigned)
sizehigh	File size in bytes, high order 32 bits
status	0 = Queued 1 = Active 2 = Failed 3 = Done 4 = Connecting 5 = Aborted
type	0 = Send 1 = Recieve 1 = ChatRecv 1 = ChatSend

`ignore`	Current ignore list
Name	Description
mask	Ignore mask, .e.g. `\\!\\@\*.aol.com`
flags	2^0 = Private 2^1 = Notice 2^2 = Channel 2^3 = CTCP 2^4 = Invite 2^5 = Unignore 2^6 = NoSave 2^7 = DCC

`notify`	List of people on notify
Name	Description
networks	Networks to which this nick applies. Comma separated. May be `nil`
nick	Nickname
flags	Bit field of flags. 0=Is online.
on	Unix timestamp of when user came online.
off	Unix timestamp of when user went offline.
seen	Unix timestamp of when user the user was last verified still online.

hexchat.props¶

A table containing the values of a "channels" list for the current context.

Preferences¶

hexchat.prefs¶

You can access HexChat’s settings via this pseudo-table, see /set for a list of keys. Note that you cannot modify the table. Instead, you should use hexchat.command("set -quiet <key> <value>")

There are also these special preferences:

id - Unique server id
state_cursor - Location of cursor in input box

Hooks¶

Some hooks are executed in a priority order, and hooks executed earlier can prevent later hooks from being invoked. The following constants determine priorities of such hooks and are passed to the hooking function:

hexchat.PRI_HIGHEST - The highest priority.
hexchat.PRI_HIGH
hexchat.PRI_NORM - The default priority.
hexchat.PRI_LOW
hexchat.PRI_LOWEST - The lowest priority.

The following constants determine whether to pass the event on after the hook has finished. One of these has to be returned from the callback:

hexchat.EAT_NONE - Let other hooks see the event.
hexchat.EAT_HEXCHAT - Let other hooks see the event, but prevent HexChat itself from seeing it.
hexchat.EAT_PLUGIN - Don’t let remaining hooks see the event, but let HexChat know about it.
hexchat.EAT_ALL - Consume this event completely, don’t let anyone else know about it.

All hooking functions return an object which can be later used to remove the hook, but the hooks are also removed automatically when the script is unloaded or reloaded.

Unlike the C and Python APIs, there isn’t a userdata value passed to the hooks. Instead you should use upvalues, closures, and/or anonymous functions.

hexchat.hook_command(command, callback[, help[, priority]])¶

Hooks the function callback to be executed whenever /command is entered. help is the helptext for the /help command. Returns a hook object. The callback receives an array of words, and an array of word_eols as arguments.

If command is nil, then all non-command text is hooked instead, including /say.

hexchat.hook_print(event, callback[, priority])¶

Hooks the function callback to be executed whenever the text event event is to be printed. Returns a hook object. The callback receives the array of event’s arguments as its only argument.

There are also a few extra events you can hook using this function:

Open Context - Emitted when a new context is created.
Close Context - Emitted when a context is closed.
Focus Tab - Emitted when a tab is brought to the front.
Focus Window - Emitted when a toplevel window is focused, or the main tab-window is focused by the window manager.
DCC Chat Text - Emitted when some text from a DCC Chat arrives. It provides these elements in the word list:
- Address
- Port
- Nick
- Message
Key Press - Emitted when some keys are pressed in the input box. It provides these elements in the word list:
- Key Value
- Modifier bitfield (Shift, CapsLock, Alt, etc)
- String version of the key
- Length of the string (may be 0 for unprintable keys)

hexchat.hook_server(command, callback[, priority])¶

Hooks the function callback to be executed whenever command is received from the server. Returns a hook object. The callback receives an array of words, and an array of word_eols as arguments.

If command is nil, then the callback is called for every received line.

hexchat.hook_timer(interval, callback)¶

Hooks the function callback to be executed after inverval milliseconds. Returns a hook object. As long as the callback returns a truthy value, it is scheduled to happen after the same preiod of time.

hexchat.hook_unload(callback)¶

Hooks the function callback to be executed when the current script is unloaded. Returns a hook object.

hook:unhook() and hexchat.unhook(hook)¶

Removes the given hook. A hook can only be removed once.

Contexts¶

A context corresponds to a HexChat window or tab. Some of the functions in hexchat.* will do something in the current tab. Using contexts you can perform such actions in other tabs instead. Two context objects can be tested for equality using the == operator, which will return true if the contexts refer to the same tab. All methods of a context object will error if the object is invalidated and points to a tab that is closed.

hexchat.get_context()¶

Returns a context object for the current context.

hexchat.find_context(server_name, channel_name)¶

Finds a context object for a tab on the given channel of the given channel. If server_name is nil, it searches for the given channel or query across all servers. If channel_name is nil, finds the frontmost tab of the given server. If both are nil, returns current context. In any case, if the specified tab was not found, the function returns nil.

ctx:set() and hexchat.set_context(ctx)¶

Makes ctx the “current” context. All hexchat.* functions will be using this context. This setting only persists within one event. Next time any of the callbacks is called, the current context will be set to the actual one.

Returns a boolean indicating whether the context was successfully set. Failure will only occur if the context has been closed.

ctx:find_context(server_name, channel_name)¶

Identical to hexchat.find_context, except the defaults are based on the current context.

ctx:print(…)¶

Prints zero or more values in the given context.

ctx:emit_print(event, …)¶

Emits a text event into the given context. See hexchat.emit_print.

Returns a boolean indicating success.

ctx:command(cmd)¶

Executes the command /cmd in the given context. See hexchat.command.

ctx:nickcmp(a, b)¶

Compares 2 strings using casemapping from the given context. See hexchat.nickcmp.

ctx:get_info(id)¶

Returns information about the given context. See hexchat.get_info.

ctx:iterate(list)¶

Iterate through a list within the given context. See hexchat.iterate.

Plugin preferences¶

hexchat.pluginprefs¶

To persistently store your script’s settings, you can use this pseudo-table. The values inside will persist across script reloads, HexChat restarts, and reboots. Currently, you can only store and read strings and numbers associated to string keys, and iterate through the table with pairs().

Attributes¶

Attributes correspond to extra metadata for messages, such as server-time (currently the only supported attribute). Some functions have attributes-enhanced versions.

hexchat.attrs()¶

Returns a new attributes object. It has only one field: server_time_utc.

hexchat.emit_print_attrs(attrs, event, …) and ctx:emit_print_attrs(attrs, event, …)¶

Analogous to hexchat.emit_print and ctx:emit_print respectively, but passes an extra attributes argument.

hexchat.hook_print_attrs(event, callback[, priority])¶

Identical to hexchat.hook_print, except that the callback receives an additional second argument with an attributes object and that the aforementioned extra events cannot be hooked.

hexchat.hook_server_attrs(command, callback[, priority])¶

Identical to hexchat.hook_server, except that the callback receives an additional third argument with an attributes object.