programming your sirc client
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Warning: to understand this you need to know perl (the programming language; type "man perl" for more info on it), and to have read the README thoroughly. For a real usable example of sirc script, look at the file zer0.pl; if you wonder how you could do something in sirc script, try understanding the functions defined in there. Functions: From /loaded scripts and .sircrc.pl, you can define new functions and give their implementation in perl. These scripts are actually files of perl code, and they get loaded right into sirc's context. To define a new command, all you need to do is define a sub with the name cmd_yourcommandname which does whatever you want it to do, and call &addcmd("yourcommandname"); You can also define some help for the command, by calling &addhelp("yourcommandname", "First line of help\nSecond line of help..."); Your sub gets all of its arguments in the global variable $args (unparsed), its own name in $cmd, and the whole command line in $line. It can also use a number of routines from the sirc client: &dosplat; turns a * into the current channel name, if it's the first word of $args &getarg; to get the first word of $args in $newarg and the rest in $args &yetonearg; same thing, removing a trailing : in $args if there's one &eq("txt1", "txt2"); tests case-insensitive equality &sl("text"); to send a line of text to the server (the trailing "\n" gets added automatically) &tell("txt"); sends text to the screen, adding a "\n", and only if not in silent mode &print("txt"); sends text to the screen, adding a "\n", regardless of silent mode &getuserline("str", "prompt"); prints "str" on the screen, puts "prompt" as a temporary prompt if using ssfe, and prompts the users for a line, returning it in $_ &dostatus; redisplays the status line &msg("nck", "msg"); sends a message, printing it ¬ice("nck", "msg"); sends a notice, printing it &say("msg"); says somethign on the current channel, printing it &describe("nck", "msg"); sends a /describe, printing it &me("msg"); does an action on the current channel, printing it &docommand("command"); interprets a command line as if it were typed at the keyboard. no leading / is needed (or accepted). *warning* this calls the command dispatcher recursively from itself, and it's up to *you* to make sure you don't loop infinitely. perl being a language with strong and powerful control structures (unlike ircII...), recursion should be avoided whenever possible. And you have access to the following global variables (don't modify them without really *good* reasons or sirc will get all confused): $version sirc's version - should always be a number, and never be modified by a user function $add_ons additional modules loaded; scripts can add a "+scriptname" to it $nick your current nick $ircname your ircname - you can change it, it will take effect on the next server reconnect $server your current server $finger your reply to /ctcp finger - you can modify this one @channels list of channels you're on $talkchannel your current channel (or '' if none) %mode associative array with the modes of the different channels we're on. the channel names are all in lower case, and the mode is a string of letters without +'s or -'s, and without 'k' or 'l' either since those are treated separately. the value for channels without any mode is '', while the value for channels we're not on is undef. %chankey keys to channels, undef if none or we're not on the channel. channel names are in lower case. %limit limits to channels, undef if none or we're not on the channel. channel names in lower case. %haveops associative array of booleans, true if we have ops on the channel. channel names are... you know how $umode user mode, string of letters without +'s or -'s $lastmsg nick of the person who you last sent a message to $query whoever you're querying, or '' if no-one %aliases associative array of defined substitution aliases; the alias name is in CAPS %notify associative array of the notify list; the value for a given nick is 0 for "absent", or the time of the most recent notification for this nick $logfile name of the log file; you can change this $logging flag that tells if we're logging or not; don't change it because you'd also need to open/close the logfile Warning: functions and hooks should *not* modify the parameters that are passed to them (i.e. do somethign like $_[1]="some value"); if they wish to modify local copies of them, they should start with local($somename1, $somename2)=@_; (replacing "2" with the actual number of parameters). Also, if your script is going to use global variables, please make sure they're not likely to clash with sirc's own (same goes for file descriptor names, and procedures). A good convention would be to give all these variables and procedures a name that starts with the script name, or with a few letters from it. For example, in zer0.pl all the script's global variables and internal procedures have names that start with "z_". Example, which could be put into a file and /load'ed directly, of a command that will yeek on a channel if you specify one, and at a nick if you do too: ~~~~~~~~~~~~~~~~~~~~~~~~~~~ [snip snip] ~~~~~~~~~~~~~~~~~~~~~~~~~~~ sub cmd_yeek { &dosplat; # if the 1st arg is *, replace it with $talkchannel &getarg; # get 1st arg in $newarg local($channel)=($talkchannel); # by default we talk to $talkchannel if ($newarg =~ /^[\#\&]/) { # if the 1st arg starts with # or & $channel=$newarg; # talk there instead &getarg; # and get an extra arg } if ($newarg) { # look at whether we specified who we're yeeking at &describe($channel, "look at $newarg and *yeeeks*"); } else { # or not &describe($channel, "*yeeks* at the crowd"); } } # \cb is the way to specify ^B in perl &addcmd("yeek"); &addhelp("yeek", "Usage: \cbYEEK\cb [] [] Yeeks at the given nickname or at the whole channel. Examples: /yeek someone /yeek * someone /yeek #channel /yeek #channel someone"); ~~~~~~~~~~~~~~~~~~~~~~~~~~~ [snip snip] ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Hooks: 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 "^" 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 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_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 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 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 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_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 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: ~~~~~~~~~~~~~~~~~~~~~~~~~~~ [snip snip] ~~~~~~~~~~~~~~~~~~~~~~~~~~~ # 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ [snip snip] ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Another example, to display the username and hostname with each message: ~~~~~~~~~~~~~~~~~~~~~~~~~~~ [snip snip] ~~~~~~~~~~~~~~~~~~~~~~~~~~~ # 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ [snip snip] ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Userhost requests: Sometimes in a function you need to know the full username and hostname for some nick. If this happens in a hook, and the nick is the one who did the action, then the nick is in $who and the userhost data is already in $user and $host. Otherwise, you have to call the perl function &userhost giving it three arguments: the nickname, what you want evaluated when the data is available, and what you want evaluated if the nick is not found on IRC; if the third argument is ommited, sirc will print the default message "*?* somenickname not found on IRC". Unlike with earlier versions of sirc, it is possible to do more than one userhost request in a short time before getting the answers from the server. Example: a function that prints someone's country code ~~~~~~~~~~~~~~~~~~~~~~~~~~~ [snip snip] ~~~~~~~~~~~~~~~~~~~~~~~~~~~ # country code sub printcountry { # prints $host's country code if ($host =~ /\.([^.]+)$/) { # match the last part of the host local($c)=($1); # put it in local var $c $c="USA" if $c =~ /^edu$/i; # if it's a .edu, say it's USA $c="USA (probably)" if $c =~ /^com$/i || $c =~ /^org$/i || $c =~ /^net$/i; # if it's a .org, .com or .net, it's # probably in the USA too if ($c =~ /^\d+$/) { # if it's a number &tell("*** out of luck, $who has an IP address :p"); # complain, it's an IP } else { # otherwise &tell("*** $who is in $c"); # announce the result } } } sub cmd_country { # this is the command &getarg; # get the argument in $newarg if ($newarg) { # if it's there &userhost($newarg, "&printcountry;"); # request a userhost with &printcountry as # action to take } else { # otherwise &tell("*** Whose?"); # complain } } &addcmd("country"); # install the command ~~~~~~~~~~~~~~~~~~~~~~~~~~~ [snip snip] ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Timers: It is possible in sirc to specify an action to be done but delayed, a certain number of seconds later, just like with ircII's /timer function. This is only precise up to the second. To do this, you call the function &timer with the number of seconds to wait as the first argument, and the string to be evaluated as the second argument. This is simple enough, but if you really need an example, here comes: to print "hello" in 10 seconds, you'd do &timer(10, "&tell('hello')); Bots: It is possible to make bots in sirc script, just like you make bots in ircII. It's even probably not a bad idea, since you have a proper and powerful programming language (perl) at your disposition, with all the boring network programming and parsing of server stuff already done for you. However, sirc was never meant as a bot client, and I have no intention of filling it up with bells and whistles for bot support, so I've only provided minimal support for this, with the -l and -q options. The idea is, you program your bot as a set of internal functions and hooks and a calls to &addhook and to &docommand, and then load the sirc this way (obviously without ssfe): nohup sirc -d -q -l -i >/dev/null & All of this without the <>'s, of course. The >/dev/null is there to suppress the output, since you won't be reading it on the screen anyway. In the bot, make sure you catch (with a numeric hook) the lines that tell "nick in use" or "invalid nick", and send lines to the server with some random nick, and get them skipped, or the bot will freeze trying to ask the user for a nick. You should also set up a hook on "input", and make it returns a server name in $_ and set $skip, since &getuserline gets called whenever the current server connection is lost. Also remember that the file gets loaded even before the server connection is made, so calls to &sl and most &docommand's at that point will fail. Here's an example of a bot that connects, joins a channel, reconnects if disconnected, responds to a few commands, ops its owner, and logs all it sees except public stuff to a file; you'd load this one, assuming you saved it in a file called "mybot" and want to call it BubbleBot, with: nohup sirc -d -q -l mybot -i "bot in sirc" BubbleBot some.server.edu >/dev/null ~~~~~~~~~~~~~~~~~~~~~~~~~~~ [snip snip] ~~~~~~~~~~~~~~~~~~~~~~~~~~~ $botowner="espel\@clipper.ens.fr"; # change it to your address $logfile=$ENV{'HOME'}."/.botlog"; &docommand("log on"); sub hook_publicstuff { # don't print the public stuff (so it $silent=1; # doesn't fill the logfile } &addhook("public", "publicstuff"); sub hook_connected { &sl("JOIN #BotTub"); } &addhook("376", "connected"); # join on the "end of MOTD" numeric srand; # init random number generator sub hook_badnick { local($n); $n="B".(int(rand(1000000))+4587454); # send a garbage nick... &sl("NICK $n"); $skip=1; } &addhook("432", "badnick"); # if told that ours is taken &addhook("433", "badnick"); sub hook_input { # if asked for a line, it means we got disconnected # (since we've caught the badnick thing) sleep(30); # wait 30 seconds (so we don't bring the machine # down to a crawl if the server is down) $_="0"; # return '0' : reconnect to the initial server $skip=1; # and don't actually ask for a line } &addhook("input", "input"); sub hook_joined { # whenever someone joins local($ch)=($_[0]); $ch =~ tr/A-Z/a-z/; # put channel in lowercase if (&eq($botowner, "$user\@$host") && $haveops{$ch}) { &sl("MODE $ch +o $who"); # op if that's the owner and we have ops } } &addhook("join", "joined"); sub hook_message { if (&eq($botowner, "$user\@$host")) { # if it's a msg from the owner if ($_[0] =~ /^die$/i) { # die -> die close LOGFILE; &docommand("quit"); } elsif ($_[0] =~ /^say /i) { # say -> say it &say($'); } elsif ($_[0] =~ /^nick /i) { # nick -> change nicks &sl("NICK $'"); } # add more commands here } } &addhook("msg", "message"); ~~~~~~~~~~~~~~~~~~~~~~~~~~~ [snip snip] ~~~~~~~~~~~~~~~~~~~~~~~~~~~