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.

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.