<p>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</p>
<ul>
<li><strong><code>$message</code> - server message to hook such as PRIVMSG</strong>
</li>
<li><strong><code>$command</code> - command to intercept, without the leading /</strong>
</li>
<li><strong><code>$event</code> - one of the events listed in Settings->Advanced->Text Events</strong>
</li>
<li><strong><code>$timeout</code> - timeout in milliseconds</strong>
</li>
<li><strong><code>$handle</code> - the I/O handle you want to monitor with hook_fd. This must be something that has a fileno. See perldoc -f fileno or <ahref="http://perldoc.perl.org/functions/fileno.html">fileno</a></strong>
</li>
<li><strong><code>$callback</code> - callback function, this is called whenever
the hooked event is trigged, the following are
the conditions that will trigger the different hooks.
This can be either a reference to a
function or an anonymous sub reference.</strong>
</li>
<li><strong>\%options - a hash reference containing addional options for the hooks</strong>
</li>
</ul>
<p>Valid keys for \%options:</p>
<tableborder="1"><tr>
<td>data</td><td>Additional data that is to be associated with the<br/>
hook. For timer hooks this value can be provided either as<br/>
<h3><aname="xchat_printf"/><code>Xchat::printf( $format, LIST )</code></h3>
<ul>
<li><strong><code>$format</code> - a format string, see "perldoc -f <ahref="http://perldoc.perl.org/functions/sprintf.html">sprintf</a>" for further detail</strong>
</li>
<li><strong>LIST - list of values for the format fields</strong>
<li><strong><code>$command</code> - the command to execute, without the leading /</strong>
</li>
<li><strong><code>\@commands</code> - array reference containing a list of commands to execute</strong>
</li>
<li><strong><code>$channel</code> - channel or tab with the given name where <code>$command</code> will be executed</strong>
</li>
<li><strong><code>$server</code> - specifies that the command will be executed in a channel or tab that is associated with <code>$server</code></strong>
</li>
</ul>
<p>The first argument can either be a string or an array reference of strings.
Either or both of <code>$channel</code> and <code>$server</code> can be undef.</p>
<p>If called as <code>Xchat::command( $command )</code>, 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 <code>$channel</code> or <code>$server</code> to undef is the same
as find_context.</p>
<p>
</p>
<h3><aname="xchat_commandf"/><code>Xchat::commandf( $format, LIST )</code></h3>
<ul>
<li><strong><code>$format</code> - a format string, see "perldoc -f <ahref="http://perldoc.perl.org/functions/sprintf.html">sprintf</a>" for further detail</strong>
</li>
<li><strong>LIST - list of values for the format fields</strong>
<li><strong><code>$context</code> - context value as returned from <ahref="#xchat_get_context">get_context</a>,<ahref="#xchat_find_context">find_context</a> or one
of the fields in the list of hashrefs returned by list_get</strong>
</li>
<li><strong><code>$channel</code> - name of a channel you want to switch context to</strong>
</li>
<li><strong><code>$server</code> - name of a server you want to switch context to</strong>
</li>
</ul>
<p>See <ahref="#xchat_find_context">find_context</a> for more details on <code>$channel</code> and <code>$server</code>.</p>
<td>the system wide directory where xchat will look for plugins.
this string is in the same encoding as the local file system</td>
<td></td>
</tr><tr>
<td>modes</td>
<td>the current channels modes or undef if not known</td>
<td>MODE</td>
</tr><tr>
<td>network</td>
<td>current network name or undef, this value is taken from the Network List</td>
<td></td>
</tr><tr>
<td>nick</td>
<td>current nick</td>
<td>NICK</td>
</tr><tr>
<td>nickserv</td>
<td>nickserv password for this network or undef, this value is taken from the Network List</td>
<td></td>
</tr><tr>
<td>server</td><td>current server name <br/>
(what the server claims to be) undef if not connected
</td>
<td></td>
</tr><tr>
<td>state_cursor</td>
<td>current inputbox cursor position in characters</td>
<td>SETCURSOR</td>
</tr><tr>
<td>topic</td>
<td>current channel topic</td>
<td>TOPIC</td>
</tr><tr>
<td>version</td>
<td>xchat version number</td>
<td></td>
</tr><tr>
<td>win_status</td>
<td>status of the xchat window, possible values are "active", "hidden"
and "normal"</td>
<td>GUI</td>
</tr><tr>
<td>win_ptr</td><td>native window pointer, GtkWindow * on Unix, HWND on Win32.<br/>
On Unix if you have the Glib module installed you can use my $window = Glib::Object->new_from_pointer( Xchat::get_info( "win_ptr" ) ); to get a Gtk2::Window object.<br/>
Additionally when you have detached tabs, each of the windows will return a different win_ptr for the different Gtk2::Window objects.<br/>
See <ahref="http://xchat.cvs.sourceforge.net/viewvc/xchat/xchat2/plugins/perl/char_count.pl?view=markup">char_count.pl</a> for a longer example of a script that uses this to show how many characters you currently have in your input box.
</td>
<td></td>
</tr>
<tr>
<td>gtkwin_ptr</td>
<td>similar to win_ptr except it will always be a GtkWindow *</td>
<td></td>
</tr>
<tr>
<td>xchatdir</td><td>xchat config directory encoded in UTF-8<br/>
examples:<br/>
/home/user/.xchat2<br/>
C:\Documents and Settings\user\Application Data\X-Chat 2
</td>
<td></td>
</tr><tr>
<td>xchatdirfs</td><td>same as xchatdir except encoded in the locale file system encoding</td>
<td></td>
</tr>
</table><p>This function is used to retrieve certain information about the current
context. If there is an associated command then that command can be used to change the value for a particular ID.</p><p>
<li><strong><code>$target</code> - a single nick to set the mode on</strong>
</li>
<li><strong><code>\@targets</code> - an array reference of the nicks to set the mode on</strong>
</li>
<li><strong><code>$sign</code> - the mode sign, either '+' or '-'</strong>
</li>
<li><strong><code>$mode</code> - the mode character such as 'o' and 'v', this can only be one character long</strong>
</li>
<li><strong><code>$modes_per_line</code> - an optional argument maximum number of modes to send per at once, pass 0 use the current server's maximum (default)</strong>
</li>
</ul>
<p>Send multiple mode changes for the current channel. It may send multiple MODE lines if the request doesn't fit on one.</p>
</tr></table><p>"notify" - list of people on notify</p>
<tableborder="1">
<trstyle="background-color: #dddddd">
<td>Key</td><td>Value</td>
</tr><tr>
<td>networks</td>
<td>comma separated list of networks where you will be notfified about this user's online/offline status or undef if you will be notificed on every network you are connected to</td>
</tr><tr>
<td>nick</td><td>nickname</td>
</tr><tr>
<td>flags</td><td>0 = is online</td>
</tr><tr>
<td>on</td><td>time when user came online</td>
</tr><tr>
<td>off</td><td>time when user went offline</td>
</tr><tr>
<td>seen</td><td>time when user was last verified still online</td>
</tr>
</table><p>the values indexed by on, off and seen can be passed to localtime
and gmtime, see perldoc -f <ahref="http://perldoc.perl.org/functions/localtime.html">localtime</a> and perldoc -f <ahref="http://perldoc.perl.org/functions/gmtime.html">gmtime</a> for more
detail</p><p>"users" - list of users in the current channel</p>
<td>last time a user was seen talking, this is the an epoch time(number of seconds since a certain date, that date depends on the OS)</td>
</tr><tr>
<td>nick</td><td>nick name</td>
</tr><tr>
<td>host</td>
<td>host name in the form: user@host or undef if not known</td>
</tr><tr>
<td>prefix</td><td>prefix character, .e.g: @ or +</td>
</tr><tr>
<td>realname</td>
<td>Real name or undef</td>
</tr><tr>
<td>selected</td>
<td>selected status in the user list, only works when retrieving the user list of the focused tab. You can use the /USELECT command to select the nicks</td>
</tr>
</table><p>"networks" - list of networks and the associated settings from network list</p>
<td>autojoins</td><td>An object with the following methods:<br/>
<table>
<tr>
<td>Method</td>
<td>Description</td>
</tr><tr>
<td>channels()</td>
<td>returns a list of this networks' autojoin channels in list context, a count of the number autojoin channels in scalar context</td>
</tr><tr>
<td>keys()</td>
<td>returns a list of the keys to go with the channels, the order is the same as the channels, if a channel doesn't have a key, '' will be returned in it's place</td>
</tr><tr>
<td>pairs()</td>
<td>a combination of channels() and keys(), returns a list of (channels, keys) pairs. This can be assigned to a hash for a mapping from channel to key.</td>
</tr><tr>
<td>as_hash()</td>
<td>return the pairs as a hash reference</td>
</tr><tr>
<td>as_string()</td>
<td>the original string that was used to construct this autojoin object, this can be used with the JOIN command to join all the channels in the autojoin list</td>
</tr><tr>
<td>as_array()</td>
<td>return an array reference of hash references consisting of the keys "channel" and "key"</td>
</tr><tr>
<td>as_bool()</td>
<td>returns true if the network has autojoins and false otherwise</td>
</tr>
</table>
</td>
</tr>
<tr>
<td>connect_commands</td><td>An array reference containing the connect commands for a network. An empty array if there aren't any</td>
</tr><tr>
<td>encoding</td><td>the encoding for the network</td>
</tr><tr>
<td>flags</td>
<td>
a hash reference corresponding to the checkboxes in the network edit window
<table>
<tr>
<td>allow_invalid</td>
<td>true if "Accept invalid SSL certificate" is checked</td>
</tr><tr>
<td>autoconnect</td>
<td>true if "Auto connect to this network at startup" is checked</td>
</tr><tr>
<td>cycle</td>
<td>true if "Connect to selected server only" is <strong>NOT</strong> checked</td>
</tr><tr>
<td>use_global</td>
<td>true if "Use global user information" is checked</td>
</tr><tr>
<td>use_proxy</td>
<td>true if "Bypass proxy server" is <strong>NOT</strong> checked</td>
</tr><tr>
<td>use_ssl</td>
<td>true if "Use SSL for all the servers on this network" is checked</td>
</tr>
</table>
</td>
</tr><tr>
<td>irc_nick1</td>
<td>Corresponds with the "Nick name" field in the network edit window</td>
</tr><tr>
<td>irc_nick2</td>
<td>Corresponds with the "Second choice" field in the network edit window</td>
</tr><tr>
<td>irc_real_name</td>
<td>Corresponds with the "Real name" field in the network edit window</td>
</tr><tr>
<td>irc_user_name</td>
<td>Corresponds with the "User name" field in the network edit window</td>
</tr><tr>
<td>network</td>
<td>Name of the network</td>
</tr><tr>
<td>nickserv_password</td>
<td>Corresponds with the "Nickserv password" field in the network edit window</td>
</tr><tr>
<td>selected</td>
<td>Index into the list of servers in the "servers" key, this is used if the "cycle" flag is false</td>
</tr><tr>
<td>server_password</td>
<td>Corresponds with the "Server password" field in the network edit window</td>
</tr><tr>
<td>servers</td>
<td>An array reference of hash references with a "host" and "port" key. If a port is not specified then 6667 will be used.</td>
<li><strong><code>$context</code> - context returned from <ahref="#xchat_get_context">get_context</a>, <ahref="#xchat_find_context">find_context</a> and <ahref="#xchat_get_list">get_list</a>, this is the context that you want infomation about. If this is omitted, it will default to current context.</strong>
</li>
</ul>
<p>This function will return the information normally retrieved with <ahref="#xchat_get_info">get_info</a>, except this is for the context that is passed in. The information will be returned in the form of a hash. The keys of the hash are the <code>$id</code> you would normally supply to <ahref="#xchat_get_info">get_info</a> as well as all the keys that are valid for the items in the "channels" list from <ahref="#xchat_get_list">get_list</a>. Use of this function is more efficient than calling get_list( "channels" ) and searching through the result.</p>
<spanclass="synStatement">use </span>Xchat <spanclass="synStatement">qw(</span><spanclass="synConstant">:all</span><spanclass="synStatement">)</span>; <spanclass="synComment"># imports all the functions documented on this page</span>
<spanclass="synStatement">"</span><spanclass="synConstant">Print out the number of users on the current channel</span><spanclass="synStatement">"</span> );
prnt <spanclass="synStatement">"</span><spanclass="synConstant">There are </span><spanclass="synStatement">"</span> . context_info()->{users} . <spanclass="synStatement">"</span><spanclass="synConstant"> users in this channel.</span><spanclass="synStatement">"</span>;
<li><strong><code>$string</code> - string to remove codes from</strong>
</li>
</ul>
<p>This function will remove bold, color, beep, reset, reverse and underline codes from <code>$string</code>. It will also remove ANSI escape codes which might get used by certain terminal based clients. If it is called in void context <code>$string</code> will be modified otherwise a modified copy of <code>$string</code> is returned.</p>
<p>
</p>
<h2><aname="examples"/>Examples</h2>
<p>
</p>
<h3><aname="asynchronous_dns_resolution_with_hook_fd"/>Asynchronous DNS resolution with hook_fd</h3>
prnt <spanclass="synStatement">"</span><spanclass="synConstant">Unable to resolve </span><spanclass="synIdentifier">$host</span><spanclass="synStatement">"</span>;
