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 -------- .. program:: lua .. option:: /lua load .. option:: /load Loads a script with the given filename. ``/load`` will only load files ending in ``.lua`` and ``.luac``. .. option:: /lua unload .. option:: /unload Unloads a script with the given filename. .. option:: /reload ` .. option:: /lua reload ` Reloads a script with the given filename. .. option:: /lua list Lists loaded Lua scripts. .. option:: /lua exec Executes given code in the interpreter. .. option:: /lua console Opens an interactive console. Messages to that tab are intercepted and interpreted as code. .. option:: /lua inject Executes given code in the context of a given script (which has to be loaded). .. option:: /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. .. _LuaJIT: http://luajit.org/luajit.html .. _extensions: http://luajit.org/extensions.html Hexchat then provides the global ``hexchat`` table, which is described in detail in the :ref:`lua-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 .. _lua-API: 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 Text event format string for ```` 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: .. code-block:: lua 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 = | | | - 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 ")`` 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.