xchat lua plugin

X-Chat 2.x LUA-API

Introduction

Download

Installing

Sample script

Predefined constants

Function reference

Contact

Introduction

NOTE: the order of the arguments for xchat.hook_(server|print|command) changed in rev 80:
These can now be written as xchat.hook_command(event, func_name), i.e. the priority is now optional and defaults to xchat.PRI_NORM... or the full form: xchat.hook_command(event, func_name, prio, help, data) if you need to pass prio, data and/or a help text).

Each script runs in it's own lua state. Currently no data can be passed from one script to another (except via commands). The base, table, io, string and math libs are loaded.

All scripts in the xchat dir (usually ~/.xchat2/) ending in ".lua" are autoloaded. After loading of all these scripts, the lua function xchat_register() in each script is called, it must return three strings: script name, description, version.
If you load a script with /LOAD script.lua, xchat_register() is immediately called after loading.

After a script is registered (i.e. nothing was wrong in calling xchat_register()) the lua function xchat_init() is called. You should add your hooks here, open file descriptors, ...
This is an optional call. If your script doesn't have an xchat_init() function, nothing bad happens.

Before unloading (just one script or the plugin) xchat_unload() is called if it exists. You must do cleanup stuff here, like closing all open file descriptors or removing menu entries (see http://xchat.org/docs/plugin20.html#menu). There's no need to unhook explicitly, as it's automa(t|g)ically done when unloading a script/the plugin.
Manually unloading of single scripts is supported with /UNLOAD script.lua.

All constants and functions of the xchat API are located in the table xchat.

One line lua scripts can be executed with the /LUA command, like in this (more or less usless ;-)) example:
/LUA xchat.printf("my nick is %s", tostring(xchat.get_info("nick")))
This line is executed in it's own lua state.

Predefined constants

Return values for callback functions:

xchat.EAT_NONEpass event along
xchat.EAT_XCHATdon't let xchat see this event
xchat.EAT_PLUGINdon't let other plugins see this event
xchat.EAT_ALLdon't let xchat and other plugins see this event

Priority of the event hook

xchat.PRI_HIGHEST
xchat.PRI_HIGH
xchat.PRI_NORM
xchat.PRI_LOW
xchat.PRI_LOWEST

Stripping color codes (for xchat.strip())

xchat.STRIP_COLORstrip just colors
xchat.STRIP_ATTRstrip just attributes
xchat.STRIP_ALLstrip both

Setting tab color (for xchat.commandf("GUI COLOR %d", xchat.TAB_NEWMSG))

new in revision 76
xchat.TAB_DEFAULTset tab color to default color
xchat.TAB_NEWDATAset tab color to "new data arrived"
xchat.TAB_NEWMSGset tab color to "new messages"
xchat.TAB_HILIGHTset tab color to "highlighted messages available"

Misc

xchat.ARCH"Windows" or "Unix" ... depending on system :)

X-Chat API functions

xchat.hook_command(name, func_name, prio, help_str, data)

xchat.hook_server(name, func_name, prio, data)

... both (xchat.hook_command() and xchat.hook_server()) callback functions are called like

func_name(word, word_eol, data)

xchat.hook_print(name, func_name, prio, data)

The callback function for this hook is called like

func_name(word, data)

xchat.hook_timer(timeout, func_name, data)

The callback for hook_timer() is called like

func_name(data)

xchat.unhook(name)

xchat.event()

xchat.command(command)

xchat.commandf(fmt, arg1, ...)

xchat.print(text)

xchat.printf(fmt, arg1, ...)

xchat.emit_print(event, text, [text2, ...])

xchat.send_modes(targets, sign, mode [, modes_per_line])

xchat.find_context(srv, chan)

xchat.get_context()

xchat.get_info(id)

xchat.get_prefs(name)

xchat.set_context(ctx)

xchat.nickcmp(name1, name2)

xchat.strip(text, flags)

xchat.list_fields(name)

xchat.list_get(name)

xchat.gettext(msgid)

xchat.bits(flags)

Sample script

Download

In case you haven't done it already, you can get the latest version from http://ankh-morp.org/~vetinari/projects/xchat-lua/ Earlier versions are available via SVN from http://svn.ankh-morp.org:8080/xc_lua/
Released versions are

Compiling

NOTE: will wonly work with xchat >= 2.0.9, just tested on 2.6.8.
On debian Linux install 
 * liblua50, liblua50-dev, 
 * liblualib50, liblualib50-dev 
 * lua50
and compile with
  gcc $( lua-config --include ) $( lua-config --libs --extralibs ) \
    -Wl,--export-dynamic -Wall -O1 -shared -fPIC \
    -I/path/to/your/xchat-plugin.h/dir \
    -o lua.so lua.c

...else:
  gcc -L/path/to/your/lualibs -llua50 -llualib50 -lm \
    -I/path/to/your/lua/includes/ \
    -Wl,--export-dynamic -Wall -O1 -shared -fPIC \
    -I/path/to/your/xchat-plugin.h/dir \
      -o lua.so lua.c

  lua5.1 (debian etch):
  gcc -I/usr/include/lua5.1 -L/usr/lib  -l"lua5.1" \
    -Wl,--export-dynamic -Wall -O1 -shared -g -fPIC \
    -I/path/to/your/xchat-plugin.h/dir \
    -o lua.so lua.c

Finally, to install: copy the lua.so to the dir, where `xchat -p` wants it ;-)

Contact

Feel free to send feedback and bugreports, patches [*g*] to xchat.lua@ankh-morp.org. In case of problems ALWAYS report the revision number (found at top of the lua.c file or in the "Windows > Plugins and Scripts..." window after loading the plugin).
$Revision: 85 $ $Date: 2007-05-23 06:36:35 +0200 (Wed, 23 May 2007) $