Good Hello!
The purpose of this page is to give people some quick documentation on the
things that they will encounter when they try to code scripts for X-Chat.
It is not meant to be a comprehensive programming tutorial,
by any means. If that's what you're looking for, then you can just keep on
looking.
If you're going to do any scripting with X-Chat at all, you will
need to know perl. It also won't hurt to have had experience writing tcl for
eggdrops or ircII scripts. Otherwise you're going to have to be very careful
to avoid creating conditions which could flood you offline or do other
not-so-optimal things. ;) Thankfully, it shouldn't take most intelligent
people more than a week (month on the outside) enough perl to do some nice
things in it.
Perl is a very flexible language.
You should probably also go read (or at least skim over and then carefully
bookmark this copy of the thing that defines how IRC works: RFC 1459. Other documents that scripters might
find useful would be this
nice list of server
numerics, and this list of changes
for Hybrid 6 which is something everyone on EFNet should read. In fact, I
strongly suggest saving copies of these documents to your local
hard drive, because you will be back to look at them again soon.
One last thing... While you may hear that RFC 1459 isn't being followed very
well, and this is partly true, do your absolute best to stick with RFC-compliant
behaviours anyway because otherwise there's a good chance that your script will
never interoperate properly with others, or at least just piss off a lot of other
people. Pay special attention to section 2.2 of the RFC.
Unofficial X-Chat Programming Documentation
Version 1.3
By Dagmar d'Surreal
March 26th, 1998
|
----------from perl.c----------
XS(XS_IRC_add_message_handler);
XS(XS_IRC_add_command_handler);
XS(XS_IRC_add_timeout_handler);
XS(XS_IRC_print);
XS(XS_IRC_send_raw);
XS(XS_IRC_command);
XS(XS_IRC_command_with_server);
XS(XS_IRC_channel_list);
XS(XS_IRC_dcc_list);
XS(XS_IRC_get_info);
-------------------------------
newXS("IRC::add_message_handler", XS_IRC_add_message_handler, "IRC");
newXS("IRC::add_command_handler", XS_IRC_add_command_handler, "IRC");
newXS("IRC::add_timeout_handler", XS_IRC_add_timeout_handler, "IRC");
newXS("IRC::print", XS_IRC_print, "IRC");
newXS("IRC::send_raw", XS_IRC_send_raw, "IRC");
newXS("IRC::command", XS_IRC_command, "IRC");
newXS("IRC::command_with_server", XS_IRC_command_with_server, "IRC");
newXS("IRC::channel_list", XS_IRC_channel_list, "IRC");
newXS("IRC::dcc_list", XS_IRC_dcc_list, "IRC");
newXS("IRC::get_info", XS_IRC_get_info, "IRC");
-------------------------------
|
Current version of X-Chat: 0.9.3
Official Homepage: X-Chat Homepage
Author: zED
Necessary Packages:
Glib and GTK+ Stable Tree
(version 1.2.1 recommended)
Optional Packages:
Gnome
|
|
Standard Disclaimer | This documentation is provided on an "as-is" basis and comes with no warranty of accuracy or usefulness, either expressed or implied. It is subject to change without any notice, and may contain omissions or errors which could cause your genitalia to shrivel and fall off, or spontaneously combust. If you have any further questions, please feel free to seek professional help. |
|
Perl
|
X-Chat uses perl for scripting, and pretty much only perl. There's support
for writing modules, now, but it's not quite as simple to stick a module
together in C and make it stable compared to the development time of perl code.
For those of you who are used to ircII's scripting language, or using eggdrop
with tcl, the only thing you will really miss is that the regexps are a lot
different, but they're more powerful in perl. For those of you saddled with
weak languages for too long, regexps means REGular EXPressions, or "pattern
matching wildcard usage" in layman's terms.
|
Handlers
|
There are [currently] three basic ways to make things call the subroutines you
write for X-Chat and they are message handlers, command handlers, and timeout
handlers. Message handlers trigger on messages sent from the IRC server to
your client, command handlers are triggered by / commands typed in by the user
at the keyboard, and timeout handlers are actually triggered by gtk+.
|
Exit Codes
|
These are very important. Every time you set up a handler, it takes precedent
over the built-in functions and commands of X-Chat. That is, whatever thing
which triggered your subroutine will go to your code before it goes to X-Chat
to be dealt with. In this way you can replace almost every built-in function
that the client has with your own routines. The thing to remember is that if
your code exits by hitting the end of your subroutine, or by a plain 'return'
statement, processing of the event will go on to whatever other things have
set up hooks for the event, and then (provided nothing else exits with a
return value of 1) to X-Chat itself. There is only one problem with this,
(which is solved by the brokering handler that I'll explain that later) and
that is that you cannot really control what order the custom routines get
called. Normally they will execute in order of which ones were installed first,
but a single script has no real way of knowing this. Beware.
|
@_
|
If you've never heard of @_ before, then you've obviously not coded in perl.
When a message handler triggers, the raw line from the IRC server is passed
to the subroutine you specify in @_. When a command handler is triggered,
only the arguments are passed to the routine through @_ and they are not broken
into a list, but left as one long string. You'll have to parse those yourself
with split. (I advise using s/\s+/ /g to collapse the blank space to single
space first.) When a timer handler is triggered, I *think* absolutely nothing
is passed in @_, but it's not like anything terrifically important could be
passed along anyway. Be especially careful when setting up message handlers
for mode changes, since the modes are not broken up into individual events like
they are with eggdrop. The upside of this is that X-Chat has no mode hooks of
it's own, so you don't have to worry about it too much. (This is not the case
with the brokering handler, however.)
|
Timeout Handlers
|
Timeout handlers are worthy of special notice to people who are used to coding
for ircII/EPIC/BitchX/etc. They do *not* function the same way in X-Chat.
Timeout handlers are triggered repeatedly, and [currently] there is no way to
remove them once they are installed. If you put in a timeout handler with an
interval of 1000, then your subroutine will be triggered once every second
ad infinitum. Be careful not to use an exceptionally low timer, since this
will drive the CPU load up unnecessarily.
|
Contexts
|
There are some really nice things about coding for X-Chat, and the biggest
one is that it's fairly good about determining the proper context for things.
If a server sends something that triggers a message handler, then you can be
sure that unless you specify otherwise, that your IRC::print or IRC::command
function call will go back to that server and that server alone. If you
really really need to know what the current context is, use the IRC::get_info
function as detailed below.
|
IRC::dcc_list( );
|
This command does essentially the same thing as channel_list, giving you the
details of each DCC connection currently in progress. I have no idea exactly
what is returned because I haven't had a chance to poke at this one much, but
suffice it to say that it's a flat list, and the first time you play with it
the meaning of the returned values should be pretty obvious. (Send me email
if you decide to dig deeply into this command, thanks!)
Here's a fragment from the perl.c file in the source code which may shed some
light as to the nature of the returned values:
if(dcc->nick[0])
{
XST_mPV(i, dcc->nick);
i++;
XST_mPV(i, dcc->file);
i++;
XST_mIV(i, dcc->type);
i++;
XST_mIV(i, dcc->stat);
i++;
XST_mIV(i, dcc->cps);
i++;
XST_mIV(i, dcc->size);
i++;
XST_mIV(i, dcc->resumable);
i++;
XST_mIV(i, dcc->addr);
i++;
XST_mPV(i, dcc->destfile);
i++;
}
Hopefully this will be enough for people to figure out what's going on, but just
in case, check out the dp_misc.pl file which will make this thing output a much
more understandable function through an OO wrapper.
|