X-Chat 2 Perl Interface

This is the new Perl interface for X-Chat 2. However, due to changes in xchat's plugin code you will need xchat 2.0.8 or above to load this. Scripts written using the old interface will continue to work. If there are any problems, questions, comments or suggestions please email them to the address on the bottom of this page.

• Xchat::PRI_HIGHEST
• Xchat::PRI_HIGH
• Xchat::PRI_NORM
• Xchat::PRI_LOW
• Xchat::PRI_LOWEST

• Xchat::EAT_NONE - pass the event along
• Xchat::EAT_XCHAT - don't let xchat see this event
• Xchat::EAT_PLUGIN - don't let other scripts and plugins see this event but xchat will still see it
• Xchat::EAT_ALL - don't let anything else see this event

• Xchat::KEEP - keep the timer going or hook watching the handle
• Xchat::REMOVE - remove the timer or hook watching the handle

• Xchat::FD_READ - invoke the callback when the handle is ready for reading
• Xchat::FD_WRITE - invoke the callback when the handle is ready for writing
• Xchat::FD_EXCEPTION - invoke the callback if an exception occurs
• Xchat::FD_NOTSOCKET - indicate that the handle being hooked is not a socket

• $name - The name of this script
• $version - This script's version
• $description - A description for this script
• $callback - This is a function that will be called when the is script unloaded. This can be either a reference to a function or an anonymous sub reference.

This is the first thing to call in every script.

These functions can be to intercept various events. hook_server can be used to intercept any incoming message from the IRC server. hook_command can be used to intercept any command, if the command doesn't currently exist then a new one is created. hook_print can be used to intercept any of the events listed in Setttings->Advanced->Text Events hook_timer can be used to create a new timer

Each of the hooks will be triggered at different times depending on the type of hook.

The value return from these hook functions can be passed to Xchat::unhook to remove the hook.

All callback functions will receive their arguments in @_ like every other Perl subroutine.

Server and command callbacks

$_[0] - array reference containing the IRC message or command and arguments broken into words
example:
/command arg1 arg2 arg3
$_[0][0] - command
$_[0][1] - arg1
$_[0][2] - arg2
$_[0][3] - arg3

$_[1] - array reference containing the Nth word to the last word
example:
/command arg1 arg2 arg3
$_[1][0] - command arg1 arg2 arg3
$_[1][1] - arg1 arg2 arg3
$_[1][2] - arg2 arg3
$_[1][3] - arg3

$_[2] - the data that was passed to the hook function

Print callbacks

$_[0] - array reference containing the values for the text event see Settings->Advanced->Text Events
$_[1] - the data that was passed to the hook function

Timer callbacks

$_[0] - the data that was passed to the hook function

fd callbacks

$_[0] - the handle that was passed to hook_fd
$_[1] - flags indicating why the callback was called
$_[2] - the data that was passed to the hook function

All server, command and print callbacks should return one of the Xchat::EAT_* constants. Timer callbacks can return Xchat::REMOVE to remove the timer or Xchat::KEEP to keep it going

For server hooks, if $message is "RAW LINE" then $cb will be called for every IRC message than X-Chat receives.

For command hooks if $command is "" then $cb will be called for messages entered by the user that is not a command.

For print hooks besides those events listed in Settings->Advanced->Text Events, these additional events can be used.

• $hook - the hook that was previously returned by one of the Xchat::hook_* functions

This function is used to removed a hook previously added with one of the Xchat::hook_* functions

It returns the data that was passed to the Xchat::hook_* function when the hook was added

• $text - the text to print
• \@lines - array reference containing lines of text to be printed all the elements will be joined together before printing
• $channel - channel or tab with the given name where $text will be printed
• $server - specifies that the text will be printed in a channel or tab that is associated with $server

The first argument can either be a string or an array reference of strings. Either or both of $channel and $server can be undef.

• $command - the command to execute, without the leading /
• \@commands - array reference containing a list of commands to execute
• $channel - channel or tab with the given name where $command will be executed
• $server - specifies that the command will be executed in a channel or tab that is associated with $server

The first argument can either be a string or an array reference of strings. Either or both of $channel and $server can be undef.

If called as Xchat::command( $command ), it will always return true. If called with either the channel or the channel and the server specified then it will return true if a context is found and false otherwise. The command will not be executed if the context is not found. The meaning of setting $channel or $server to undef is the same as find_context.

• $channel - name of a channel
• $server - name of a server

Either or both of $channel and $server can be undef. Calling Xchat::find_context() is the same as calling Xchat::find_context( undef, undef) and Xchat::find_context( $channel ) is the same as Xchat::find_context( $channel, undef ).

If $server is undef, find any channel named $channel. If $channel is undef, find the front most window or tab named $server.If both $channel and $server are undef, find the currently focused tab or window.

Return the context found for one of the above situations or undef if such a context cannot be found.

Returns the current context.

• $id - one of the following case sensitive values

my $channel_msg_format = Xchat::get_info( "event_text Channel Message" );

This function is used to retrieve certain information about the current context.

• $name - name of a X-Chat setting (available through the /set command)

This function provides a way to retrieve X-Chat's setting information.

Returns undef if there is no setting called called $name.

• $event - name from the Event column in Settings->Advanced->Text Events
• LIST - this depends on the Description column on the bottom of Settings->Advanced->Text Events

This functions is used to generate one of the events listed under Settings->Advanced->Text Events

Note: when using this function you MUST return Xchat::EAT_ALL otherwise you will end up with duplicate events. One is the original and the second is the one you emit.

Returns true on success, false on failure

• $target - a single nick to set the mode on
• \@targets - an array reference of the nicks to set the mode on
• $sign - the mode sign, either '+' or '-'
• $mode - the mode character such as 'o' and 'v', this can only be one character long
• $modes_per_line - an optional argument maximum number of modes to send per at once, pass 0 use the current server's maximum (default)

Send multiple mode changes for the current channel. It may send multiple MODE lines if the request doesn't fit on one.

Example:

use strict;
use warning;
use Xchat qw(:all);

hook_command( "MODES", sub {
   my (undef, $who, $sign, $mode) = @{$_[0]};
   my @targets = split /,/, $who;
   if( @targets > 1 ) {
      send_modes( \@targets, $sign, $mode, 1 );
   } else {
      send_modes( $who, $sign, $mode );
   }
   return EAT_XCHAT;
});

• $nick1, $nick2 - the two nicks or channel names that are to be compared

• $name - name of the list, one of the following: "channels", "dcc", "ignore", "notify", "users"

This function will return a list of hash references. The hash references will have different keys depend on the list. An empty list is returned if there is no such list.

"channels" - list of channels, querys and their server

if( Xchat::context_info->{flags} & (1 << 6) ) {
  Xchat::print( "Hide Join/Part messages is enabled" );
}

"dcc" - list of DCC file transfers

"ignore" - current ignore list

"notify" - list of people on notify

• $nick - the nick to look for, if this is not given your own nick will be used as default

• $string - string to remove codes from

This function will remove bold, color, beep, reset, reverse and underline codes from $string. It will also remove ANSI escape codes which might get used by certain terminal based clients. If it is called in void context $string will be modified otherwise a modified copy of $string is returned.

Contact Lian Wan Situ at <atmcmnky [at] yahoo.com> for questions, comments and corrections about this page or the Perl plugin itself. You can also find me in #xchat on FreeNode under the nick Khisanth.