HexChat Perl Interface ====================== Introduction ------------ This is the Perl interface for HexChat. If there are any problems, questions, comments or suggestions please email them to the address on the bottom of this page. Constants --------- Priorities ~~~~~~~~~~ - **HexChat::PRI_HIGHEST** - **HexChat::PRI_HIGH** - **HexChat::PRI_NORM** - **HexChat::PRI_LOW** - **HexChat::PRI_LOWEST** Return values ~~~~~~~~~~~~~ - **HexChat::EAT_NONE** - pass the event along - **HexChat::EAT_HEXCHAT** - don't let HexChat see this event - **HexChat::EAT_PLUGIN** - don't let other scripts and plugins see this event but HexChat will still see it - **HexChat::EAT_ALL** - don't let anything else see this event Timer and fd hooks ^^^^^^^^^^^^^^^^^^ - **HexChat::KEEP** - keep the timer going or hook watching the handle - **HexChat::REMOVE** - remove the timer or hook watching the handle hook\_fd flags ~~~~~~~~~~~~~~ - **HexChat::FD_READ** - invoke the callback when the handle is ready for reading - **HexChat::FD_WRITE** - invoke the callback when the handle is ready for writing - **HexChat::FD_EXCEPTION** - invoke the callback if an exception occurs - **HexChat::FD_NOTSOCKET** - indicate that the handle being hooked is not a socket Exports ~~~~~~~ The following tags are supported: - ``:all`` - exports everything - ``:constants`` - exports all the constants - ``:hooks`` - exports ``hook_*`` functions as well us ``unhook`` - ``:util`` - everything else By default only the constants are exported. Functions --------- HexChat::register( $name, $version, [$description,[$callback]] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``$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. HexChat::hook_server( $message, $callback, [\%options] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ HexChat::hook_command( $command, $callback, [\%options] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ HexChat::hook_print( $event,$callback, [\%options] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ HexChat::hook_timer( $timeout,$callback, [\%options | $data] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ HexChat::hook_fd( $handle, $callback, [ \%options ] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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* ``->`` *Text Events*. ``hook_timer`` can be used to create a new timer - **$message** - server message to hook such as PRIVMSG - **$command** - command to intercept, without the leading / - **$event** - one of the events listed in *Settings* ``->`` *Text Events* - **$timeout** - timeout in milliseconds - **$handle** - the I/O handle you want to monitor with hook\_fd. This must be something that has a fileno. See perldoc -f fileno or `fileno `_ - **$callback** - 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. - **\%options** - a hash reference containing addional options for the hooks Valid keys for %options: +------------+--------------------------------------------------------------------------+ | data | Additional data that is to be associated with the hook. For timer hooks | | | this value can be provided either as ``HexChat::hook_timer( $timeout, | | | cb,{data=> data})`` or ``HexChat::hook_timer( $timeout, $cb, $data )``. | | | However, this means that hook\_timer cannot be provided with a hash | | | reference containing data as a key. | | | | | | Example: | | | | | | .. code-block:: none | | | | | | my $options = { data => [@arrayOfStuff] }; | | | HexChat::hook_timer( $timeout, $cb, $options ); | | | | | | In this example, the timer's data will be ``[@arrayOfStuff]`` and not | | | ``{ data => [@arrayOfStuff] }``. This key is valid for all of the hook | | | functions. Default is ``undef``. | +------------+--------------------------------------------------------------------------+ | priority | Sets the priority for the hook. It can be set to one of the | | | ``HexChat::PRI_*`` constants. This key only applies to server, command | | | and print hooks. Default is ``HexChat::PRI_NORM``. | +------------+--------------------------------------------------------------------------+ | help\_text | Text displayed for /help $command. This key only applies to command | | | hooks. Default is "". | +------------+--------------------------------------------------------------------------+ | flags | Specify the flags for a fd hook. See hook fd flags section for valid | | | values. On Windows if the handle is a pipe you specify | | | ``HexChat::FD_NOTSOCKET`` in addition to any other flags you might be | | | using. This key only applies to fd hooks. Default is | | | ``HexChat::FD_READ``. | +------------+--------------------------------------------------------------------------+ When callbacks are invoked ^^^^^^^^^^^^^^^^^^^^^^^^^^ Each of the hooks will be triggered at different times depending on the type of hook. +---------------+------------------------------------------------------------------------------------+ | Hook Type | When the callback will be invoked | +===============+====================================================================================+ | server hooks | A ``$message`` message is received from the server. | +---------------+------------------------------------------------------------------------------------+ | command hooks | The ``$command`` command is executed, either by the user or from a script. | +---------------+------------------------------------------------------------------------------------+ | print hooks | X-Chat is about to print the message for the ``$event`` event. | +---------------+------------------------------------------------------------------------------------+ | timer hooks | Called every ``$timeout`` milliseconds (1000 milliseconds are 1 second). | | | The callback will be executed in the same context where the ``hook_timer`` was | | | called, or if the context no longer exists then it will execute in a random | | | context. | +---------------+------------------------------------------------------------------------------------+ | fd hooks | Depends on the flags that were passed to ``hook_fd``. See ``hook_fd`` flags in the | | | section above. | +---------------+------------------------------------------------------------------------------------+ The value return from these hook functions can be passed to ``HexChat::unhook`` to remove the hook. Callback Arguments ^^^^^^^^^^^^^^^^^^ 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* ``->`` *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 Callback return values ^^^^^^^^^^^^^^^^^^^^^^ All server, command and print callbacks should return one of the ``HexChat::EAT_*`` constants. Timer callbacks can return ``HexChat::REMOVE`` to remove the timer or ``HexChat::KEEP`` to keep it going. Miscellaneous Hook Related Information ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ For server hooks, if ``$message`` is "RAW LINE" then ``$cb`` will be called for every IRC message that HexChat 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* ``->`` *Text Events*, these additional events can be used. +-----------------+--------------------------------------------------------------------------------------------+ | Event | Description | +=================+============================================================================================+ | "Open Context" | a new context is created | +-----------------+--------------------------------------------------------------------------------------------+ | "Close Context" | a context has been closed | +-----------------+--------------------------------------------------------------------------------------------+ | "Focus Tab" | when a tab is brought to the front | +-----------------+--------------------------------------------------------------------------------------------+ | "Focus Window" | when a top level window is focused or the main tab window is focused by the window manager | +-----------------+--------------------------------------------------------------------------------------------+ | "DCC Chat Text" | when text from a DCC Chat arrives. $_[0] will have these values | | | | | | - ``$_[0][0]`` - Address | | | - ``$_[0][1]`` - Port | | | - ``$_[0][2]`` - Nick | | | - ``$_[0][3]`` - Message | +-----------------+--------------------------------------------------------------------------------------------+ | "Key Press" | used for intercepting key presses | | | | | | - ``$_[0][0]`` - key value | | | - ``$_[0][1]`` - state bitfield, 1 - shift, 4 - control, 8 - alt | | | - ``$_[0][2]`` - string version of the key which might be empty for unprintable keys | | | - ``$_[0][3]`` - length of the string in ``$_[0][2]`` | +-----------------+--------------------------------------------------------------------------------------------+ HexChat::unhook( $hook ) ~~~~~~~~~~~~~~~~~~~~~~~~ - **$hook** - the hook that was previously returned by one of the ``HexChat::hook_*`` functions This function is used to removed a hook previously added with one of the ``HexChat::hook_*`` functions. It returns the data that was passed to the HexChat::hook_* function when the hook was added. HexChat::print( $text | \@lines, [$channel,[$server]] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$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``. If called as HexChat::print( $text ), 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 text will not be printed if the context is not found. The meaning of setting ``$channel`` or ``$server`` to ``undef`` is the same as find\_context. HexChat::printf( $format, LIST ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$format** - a format string, see "perldoc -f `sprintf `_" for further details - **LIST** - list of values for the format fields HexChat::command( $command | \@commands, [$channel,[$server]] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$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 HexChat::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. HexChat::commandf( $format, LIST ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$format** - a format string, see "perldoc -f `sprintf `_" for further details - **LIST** - list of values for the format fields HexChat::find_context( [$channel, [$server]] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$channel** - name of a channel - **$server** - name of a server Either or both of ``$channel`` and ``$server`` can be ``undef``. Calling ``HexChat::find_context()`` is the same as calling ``HexChat::find_context( undef, undef)`` and ``HexChat::find_context( $channel )`` is the same as ``HexChat::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. HexChat::get_context() ~~~~~~~~~~~~~~~~~~~~~~ Returns the current context. HexChat::set_context( $context | $channel,[$server] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$context** - context value as returned from ``get_context``, ``find_context`` or one of the fields in the list of hashrefs returned by ``list_get`` - **$channel** - name of a channel you want to switch context to - **$server** - name of a server you want to switch context to See ``find_context`` for more details on ``$channel`` and ``$server``. Returns true on success, false on failure. HexChat::get_info( $id ) ~~~~~~~~~~~~~~~~~~~~~~~~ - **$id** - one of the following case sensitive values +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | ID | Return value | Associated Command(s) | +=========================+=====================================================================================================================+=======================+ | away | away reason or ``undef`` if you are not away | AWAY, BACK | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | channel | the original name of the tab, not affected by SETTAB | SETTAB | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | charset | character-set used in the current context | CHARSET | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | configdir | HexChat config directory encoded in UTF-8. Examples: | | | | /home/user/.config/hexchat | | | | C:\Users\user\Appdata\Roaming\HexChat | | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | event_text | text event format string for | | | | Example: | | | | | | | | ``my $channel_msg_format = HexChat::get_info( "event_text Channel Message" );`` | | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | host | real hostname of the current server | | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | id | connection id | | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | inputbox | contents of the inputbox | SETTEXT | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | libdirfs | the system wide directory where HexChat will look for plugins. this string is in the same encoding | | | | as the local file system | | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | modes | the current channels modes or ``undef`` if not known | MODE | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | network | current network name or ``undef``, this value is taken from the Network List | | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | nick | current nick | NICK | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | nickserv | nickserv password for this network or ``undef``, this value is taken from the Network List | | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | server | current server name | | | | (what the server claims to be) ``undef`` if not connected | | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | state\_cursor | current inputbox cursor position in characters | SETCURSOR | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | topic | current channel topic | TOPIC | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | version | HexChat's version number | | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | win_status | status of the HexChat window, possible values are "active", "hidden" and "normal" | GUI | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | win\_ptr | native window pointer, GtkWindow * on Unix, HWND on Win32. | | | | On Unix if you have the Glib module installed you can use my ``$window = | | | | Glib::Object->new\_from\_pointer( HexChat::get_info( "win\_ptr" ) );`` to get a Gtk2::Window object. | | | | Additionally when you have detached tabs, each of the windows will return a different win\_ptr | | | | for the different ``Gtk2::Window`` objects. | | | | See `char\_count.pl `_ | | | | for a longer example of a script that uses this to show how many characters you currently have in your input box. | | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ | gtkwin_ptr | similar to win_ptr except it will always be a GtkWindow * | | +-------------------------+---------------------------------------------------------------------------------------------------------------------+-----------------------+ 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. HexChat::get_prefs( $name ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$name** - name of a HexChat setting (available through the /set command) This function provides a way to retrieve HexChat's setting information. Returns ``undef`` if there is no setting called called ``$name``. HexChat::emit_print( $event, LIST ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$event** - name from the Event column in *Settings* ``->`` *Text Events* - **LIST** - this depends on the Description column on the bottom of *Settings* ``->`` *Text Events* This functions is used to generate one of the events listed under *Settings* ``->`` *Text Events*. Note: when using this function you **must** return ``HexChat::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. HexChat::send_modes( $target | \@targets, $sign, $mode, [ $modes_per_line ] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$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: .. code-block:: perl use strict; use warnings; use HexChat 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_HEXCHAT; }); HexChat::nickcmp( $nick1, $nick2 ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$nick1, $nick2** - the two nicks or channel names that are to be compared The comparsion is based on the current server. Either an `RFC1459 `_ compliant string compare or plain ascii will be using depending on the server. The comparison is case insensitive. Returns a number less than, equal to or greater than zero if ``$nick1`` is found respectively, to be less than, to match, or be greater than ``$nick2``. HexChat::get_list( $name ) ~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$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 +--------------+-----------------------------------------------------------------------------+ | Key | Description | +==============+=============================================================================+ | channel | tab name | +--------------+-----------------------------------------------------------------------------+ | channelkey | the key used to get into the channel | +--------------+-----------------------------------------------------------------------------+ | chantypes | channel types supported by the server, typically "#&" | +--------------+-----------------------------------------------------------------------------+ | context | can be used with set_context | +--------------+-----------------------------------------------------------------------------+ | flags | Server Bits: | | | | | | - 0 Connected | | | - 1 Connecting | | | - 2 Away | | | - 3 EndOfMotd(Login complete) | | | - 4 Has WHOX | | | - 5 Has IDMSG (FreeNode) | | | | | | The following correspond to the /chanopt command | | | | | | - 6 Hide Join/Part Message (text_hidejoinpart) | | | - 7 unused (was for color paste) | | | - 8 Beep on message (alert_beep) | | | - 9 Blink Tray (alert_tray) | | | - 10 Blink Task Bar (alert_taskbar) | | | | | | Example of checking if the current context has Hide Join/Part messages set: | | | | | | - 1 | | | - 2 | | | - 3 | | | | | | .. code-block:: perl | | | | | | if( HexChat::context_info->{flags} & (1 << 6) ) { | | | HexChat::print( "Hide Join/Part messages is enabled" ); | | | } | +--------------+-----------------------------------------------------------------------------+ | id | Unique server ID | +--------------+-----------------------------------------------------------------------------+ | lag | lag in milliseconds | +--------------+-----------------------------------------------------------------------------+ | maxmodes | Maximum modes per line | +--------------+-----------------------------------------------------------------------------+ | network | network name to which this channel belongs | +--------------+-----------------------------------------------------------------------------+ | nickmodes | Nickname mode chars e.g. "vo" | +--------------+-----------------------------------------------------------------------------+ | nickprefixes | Nickname prefixes e.g. "+@" | +--------------+-----------------------------------------------------------------------------+ | queue | number of bytes in the send queue | +--------------+-----------------------------------------------------------------------------+ | server | server name to which this channel belongs | +--------------+-----------------------------------------------------------------------------+ | type | the type of this context | | | - 1 - server | | | - 2 - channel | | | - 3 - dialog | | | - 4 - notices | | | - 5 - server notices | +--------------+-----------------------------------------------------------------------------+ | users | Number of users in a channel | +--------------+-----------------------------------------------------------------------------+ "dcc" - list of DCC file transfers +------------+------------------------------------------------------------------+ | Key | Value | +============+==================================================================+ | address32 | address of the remote user(ipv4 address) | +------------+------------------------------------------------------------------+ | cps | bytes per second(speed) | +------------+------------------------------------------------------------------+ | destfile | destination full pathname | +------------+------------------------------------------------------------------+ | file | file name | +------------+------------------------------------------------------------------+ | nick | nick of the person this DCC connection is connected 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 | | | (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 | +------------+------------------------------------------------------------------+ | sizehigh | file size in bytes, high order 32 bits (when the files is > 4GB) | +------------+------------------------------------------------------------------+ | status | DCC Status: | | | | | | - 0 - queued | | | | | | - 2 - failed | | | - 3 - done | | | - 4 - connecting | | | - 5 - aborted | +------------+------------------------------------------------------------------+ | type | DCC Type: | | | | | | - 0 - send | | | - 1 - receive | | | - 2 - chatrecv | | | - 3 - chatsend | +------------+------------------------------------------------------------------+ "ignore" - current ignore list +-------+-----------------------------------+ | Key | Value | +=======+===================================+ | mask | ignore mask. e.g: \*!*\@*.aol.com | +-------+-----------------------------------+ | flags | Bit field of flags. | | | | | | - 0 - private | | | - 1 - notice | | | - 2 - channel | | | - 3 - ctcp | | | - 4 - invite | | | - 5 - unignore | | | - 6 - nosave | | | - 7 - dcc | +-------+-----------------------------------+ "notify" - list of people on notify +----------+----------------------------------------------------------------------------------------------+ | Key | Value | +==========+==============================================================================================+ | networks | 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 | +----------+----------------------------------------------------------------------------------------------+ | nick | nickname | +----------+----------------------------------------------------------------------------------------------+ | flags | 0 = is online | +----------+----------------------------------------------------------------------------------------------+ | on | time when user came online | +----------+----------------------------------------------------------------------------------------------+ | off | time when user went offline | +----------+----------------------------------------------------------------------------------------------+ | seen | time when user was last verified still online | +----------+----------------------------------------------------------------------------------------------+ The values indexed by on, off and seen can be passed to localtime and gmtime, see perldoc -f `localtime `_ and perldoc -f `gmtime `_ for more details. "users" - list of users in the current channel +----------+-----------------------------------------------------------------------------------------------------------------------------------+ | Key | Value | +==========+===================================================================================================================================+ | account | account name or ``undef`` (2.9.6+) | +----------+-----------------------------------------------------------------------------------------------------------------------------------+ | away | away status (boolean) | +----------+-----------------------------------------------------------------------------------------------------------------------------------+ | host | host name in the form: user@host or ``undef`` if not known | +----------+-----------------------------------------------------------------------------------------------------------------------------------+ | lasttalk | last time a user was seen talking, this is the an epoch time | +----------+-----------------------------------------------------------------------------------------------------------------------------------+ | nick | nick name | +----------+-----------------------------------------------------------------------------------------------------------------------------------+ | prefix | prefix character, .e.g: @ or + | +----------+-----------------------------------------------------------------------------------------------------------------------------------+ | realname | Real name or ``undef`` | +----------+-----------------------------------------------------------------------------------------------------------------------------------+ | selected | 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 | +----------+-----------------------------------------------------------------------------------------------------------------------------------+ "networks" - list of networks and the associated settings from network list +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Key | Value | +===================+=================================================================================================================================================================================+ | autojoins | An object with the following methods: | | | | | | - ``channels()`` - returns a list of this networks' autojoin channels in list context, a count of the number autojoin channels in scalar context | | | - ``keys()`` - 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 its | | | place | | | - ``pairs()`` - 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. | | | - ``as_hash()`` - return the pairs as a hash reference | | | - ``as_string()`` - 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 | | | - ``as_array()`` - return an array reference of hash references consisting of the keys "channel" and "key" | | | - ``as_bool()`` - returns true if the network has autojoins and false otherwise | | | | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | connect_commands | An array reference containing the connect commands for a network. An empty array if there aren't any | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | encoding | the encoding for the network | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | flags | a hash reference corresponding to the checkboxes in the network edit window | | | | | | | | | - allow_invalid - true if "Accept invalid SSL certificate" is checked | | | - autoconnect - true if "Auto connect to this network at startup" is checked | | | - cycle - true if "Connect to selected server only" is NOT checked | | | - use_global - true if "Use global user information" is checked | | | - use_proxy - true if "Bypass proxy server" is NOT checked | | | - use_ssl - true if "Use SSL for all the servers on this network" is checked | | | | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | irc_nick1 | Corresponds with the "Nick name" field in the network edit window | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | irc_nick2 | Corresponds with the "Second choice" field in the network edit window | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | irc_real_name | Corresponds with the "Real name" field in the network edit window | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | irc_user_name | Corresponds with the "User name" field in the network edit window | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | network | Name of the network | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | nickserv_password | Corresponds with the "Nickserv password" field in the network edit window | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | selected | Index into the list of servers in the "servers" key, this is used if the "cycle" flag is false | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | server_password | Corresponds with the "Server password" field in the network edit window | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | servers | An array reference of hash references with a "host" and "port" key. If a port is not specified then 6667 will be used. | +-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ HexChat::user_info( [$nick] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$nick** - the nick to look for, if this is not given your own nick will be used as default This function is mainly intended to be used as a shortcut for when you need to retrieve some information about only one user in a channel. Otherwise it is better to use ``get_list``. If ``$nick`` is found a hash reference containing the same keys as those in the "users" list of ``get_list`` is returned otherwise ``undef`` is returned. Since it relies on ``get_list`` this function can only be used in a channel context. HexChat::context_info( [$context] ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$context** - context returned from ``get_context``, ``find_context`` and ``get_list``, this is the context that you want infomation about. If this is omitted, it will default to current context. This function will return the information normally retrieved with ``get_info``, except this is for the context that is passed in. The information will be returned in a hashref. The keys of the hash are the ``$id`` you would normally supply to ``get_info`` as well as all the keys that are valid for the items in the "channels" list from ``get_list``. Use of this function is more efficient than calling ``get_list( "channels" )`` and searching through the result. Example: .. code-block:: perl use strict; use warnings; use HexChat qw(:all); # imports all the functions documented on this page register( "User Count", "0.1", "Print out the number of users on the current channel" ); hook_command( "UCOUNT", \&display_count ); sub display_count { prnt "There are " . context_info()->{users} . " users in this channel."; return EAT_HEXCHAT; } HexChat::plugin_pref_set( $setting, $value ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$setting** - name of the setting you want to store - **$value** - value of that setting This function allows you to store settings in addon_perl.conf via HexChat. Returns 1 on success, 0 on failure. HexChat::plugin_pref_get( $setting ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$setting** - name of the setting you want to retrieve Returns the value of the specified setting or undef it is not found. HexChat::plugin_pref_delete( $setting ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$setting** - name of the setting you want to delete Returns 1 on success (including deletion of not existing settings), 0 on failure. HexChat::plugin_pref_list( ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Returns a hashref of all stored settings or an empty hashref on failure. HexChat::strip_code( $string ) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **$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. Examples -------- Asynchronous DNS resolution with hook\_fd ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: perl use strict; use warnings; use HexChat qw(:all); use Net::DNS; hook_command( "BGDNS", sub { my $host = $_[0][1]; my $resolver = Net::DNS::Resolver->new; my $sock = $resolver->bgsend( $host ); hook_fd( $sock, sub { my $ready_sock = $_[0]; my $packet = $resolver->bgread( $ready_sock ); if( $packet->authority && (my @answers = $packet->answer ) ) { if( @answers ) { prnt "$host:"; my $padding = " " x (length( $host ) + 2); for my $answer ( @answers ) { prnt $padding . $answer->rdatastr . ' ' . $answer->type; } } } else { prnt "Unable to resolve $host"; } return REMOVE; }, { flags => FD_READ, }); return EAT_HEXCHAT; }); Contact Information ------------------- Contact Lian Wan Situ at 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.