From /load'ed scripts, as well as from .sircrc.pl, you have the possibility to define subs to be called when specified events occur. This is the equivalent of ircII's /on's.
To declare a hook, you must define a subroutine called "hook_somename" which does whatever you want done when a hook of type "hook_type" is triggered, and then call &addhook("hook_type", "somename");
To remove a hook, you call &remhook("hook_type", "somename");
Numeric hooks are also available, for every 3-digit number; to declare one of those, define a soubroutine called "hook_somename" which does what you want, and call &addhook("xxx", "somename"), where xxx is the number of the numeric reply. To remove one of these, you call &remhook("xxx", "somename");
Subs called from hooks have access to the same functions and variables listed above for functions, plus a few specific ones (wherever applicable):
$who is the nick that triggered the hook $user is the corresponding username $host is the corresponding hostname |
Hooks can also set the variable $silent if they want to provide the display for the event (via &print) and inhibit the default. This is the direct equivalent of the "ˆ" switch on ircII /on's, except for "raw_irc".
Hooks marked with a * can also set the special variable $skip and cause the line to be ignored by the client. This is in general a bad idea, use $silent whenever possible. Only the hooks where this provides some actual additional functionality have this possibility. For "raw_irc" this is the equivalent of the "ˆ" switch on ircII's /on raw_irc.
The following hooks are available, and get called with the following arguments:
action activated by a ctcp action; 1st arg is the nick or channel it was sent to 2nd arg is the message command * activated by the user typing a command (regardless of whether it is a /command or just a line of text) 1st arg is the user's line this hook is special in that (like "print" and "status"), it is explicitly allowed to modify its argument ($_[0]) to change what command should be interpreted. setting $skip=1 in the hook will make sirc ignore the command chat_disconnect activated when a dcc chat is lost (but not when the user closes one with DCC CLOSE CHAT) 1st arg is the nick associated with the chat ctcp * activated by any ctcp, BEFORE the client parses and eventually answers the ctcp. 1st arg is the nick or channel it was sent to 2nd arg is the ctcp command 3rd arg are the arguments ctcp_reply activated by ctcp replies; 1st arg is the nick or channel it was sent to 2nd arg is the ctcp command 3rd arg are the arguments dcc_chat activated by received text over a dcc chat 1st arg is the nick 2nd arg is the text dcc_disconnect activated when a dcc get or send is finished or closed (even when the user closes one with DCC CLOSE GET/SEND) 1st arg is the nick associated with the chat 2nd arg is the filename 3rd arg is the number of bytes transferred 4th arg is the number of seconds the transfer took dcc_request activated by a received dcc chat or send request, and after the client has processed the request. this is the hook to use if you want to implement any kind of auto-dcc. 1st arg is the type ("CHAT" or "SEND") 2nd arg is the machine address (a 32-bit integer) 3rd arg is the port for a DCC SEND offer: 4th arg is the file name 5th arg is the file lenght disconnect activated by losing the connection to the server, or breaking it with /disconnect (but not with /server). no arguments are passed input * activated whenever the client wants to ask the user for a line through &getuserline (i.e. when you got disconnected, or need a new nick, or some script called &getuserline). 1st arg is the "long" prompt 2nd arg is the "short" one if the hook sets $skip, then &getuserline won't ask the user for anything, and the contents of $_ will be returned invite activated by invites; 1st arg is the channel you're invited to join activated by joins; 1st arg is the channel that $who is joining kick activated by kicks; 1st arg is the nick of the person who got kicked 2nd arg is the channel that they got kicked from 3rd arg is the reason leave activated by parts; 1st arg is the channel that $who is leaving mode activated by mode changes; 1st arg is the channel or user the change applies to 2nd arg is the mode change itself msg activated by msgs; 1st arg is the message nick activated by nick changes 1st arg is $who's new nick notice activated by notices 1st arg is the nick or channel it was sent to 2nd arg is the message server_notice activated by notices from servers 1st arg is the nick or channel it was sent to 2nd arg is the message notify_signon activated by a notify signon 1st arg is the nick $user and $host are *not* set to anything meaningful notify_signoff activated by a notify signoff 1st arg is the nick $user and $host are *not* set to anything meaningful print * activated by the printing of any line to the screen 1st arg is the line to print this hook is special in that (like "status" and "command") it is explicitly allowed to modify its argument ($_[0]) to change what line should be printed. setting $skip=1 in the hook will prevent the line from being actually printed public activated by non-ctcp messages to a channel; 1st arg is the channel 2nd arg is the message raw_irc * activated by any server line $who is the originator (user or server) $user is his username ('' if it comes from a server) $host is his hostname (same comment) 1st arg is the command 2nd arg are the arguments send_action activated when we send a /me or a /de ($who, $user and $host do not apply here) 1st arg is the nick/channel 2nd arg is the action send_ctcp activated when we send a ctcp 1st arg is the nick or channel the ctcp is being sent to 2nd arg is the complete ctcp text (type and arguments) send_dcc_chat activated when we send text over a dcc chat ($who, $user and $host do not apply here) 1st arg is the nick we're sending to 2nd arg is the text send_text activated when we send a /msg or speak on a channel ($who, $user and $host do not apply here) 1st arg is the nick/channel 2nd arg is the msg send_notice activated when we send a notice ($who, $user and $host do not apply here) 1st arg is the nick/channel 2nd arg is the notice signoff activated when someone signs off 1st arg is the quitting comment status activated when sirc redraws the status line (as a result of &dostatus being called, either internally or by a script). 1st arg is the proposed status line this hook is special in that (like "print" and "command") it is explicitly allowed to modify its argument ($_[0]) to change what should go to the status line topic activated when someone changes the topic 1st arg is the channel 2nd arg is the new topic <3-digit nb> * activated by that particular server numeric reply 1st arg is whatever the server sent after the number, unparsed (which means there's still a : in front of the last argument) |
Example, which could be put into a file and /load'ed directly, of a hook that will rejoin a channel whenever you are kicked:
# auto-rejoin hook sub hook_kicked { local($kicked, $where_from, $reason)=@_; # local vars with the args if (&eq($kicked, $nick)) { # if *we* got kicked &sl("JOIN $where_from"); # send a JOIN to the server } } &addhook("kick", "kicked"); # activate the hook |
Another example, to display the username and hostname with each message (which is better done with /set printuh anyway):
# userhost-on message hook sub hook_uhmsg { &tell("[\cb${who}!${user}\@${host}\cb] $_[0]"); # print everything $silent=1; # disable the default display } &addhook("msg", "uhmsg"); # activate the hook |