bot === This is a simple C program to assist writing an IRC bot in whatever language(s) you choose. It is based on the Unix principle that one program should do one thing. Getting Started Quickly ======================= The example handler script, called `newmont`, will get you started right away. It will set its nickname to `newmont`, join the channel `#newmont`, and respond to any channel message containing the substring "strawberry". Start it like so: tcpclient YOUR.IRC.SERVER 6667 ./bot contrib/newmont What's Going On =============== There are three pieces involved. tcpclient --------- `tcpclient' is a program that connects to a TCP port, sets file descriptors 6 and 7 to be the input and output channels to that connection, and hands off control to whatever program you specify (in the example above, the `./bot` program with argument `./newmont`). There also exist a `udpclient`, `sslclient`, and probably others. The advantage to this method is that your network client doesn't have to care about the transport mechanism: TCP, UDP, TCP6, SSL, or whatever else. Other programs which work this way include `socat` and BSD `netcat`. Use whatever you prefer. bot --- `bot` reads one line at a time from fd6 (or 0 as a fallback), parses it up, forks, sets some environment variables, and runs the "handler" program provided as the first argument. Whatever that program prints to stdout is sent back to the server, verbatim. As a convenience, it automatically responds to PING messages from the server. It can also rate-limit messages to the server, so your bot doesn't flood itself off IRC. Lastly, it can monitor a directory and send the contents of any new file to the server, deleting the file after. This allows you to write to IRC from a cron job, git post-update hook, or whatever else you dream up. `bot` sets the following environment variables: prefix you probably don't care about this command IRC command or numeric sender nickname to send "private" replies to this message forum nickname to send "public" replies to this message text command text, like what's sent to the channel Any additional parameters of the message, like with the MODE command, are passed in as arguments to the handler. handler ------- The handler is launched once for each incoming message. It should decide what to do based on the environment variables and argv, possibly writing something to stdout, and then it should exit. Handlers are launched in parallel to each other. IRC is an asynchronous protocol, and while messages do tend to arrive in a particular order, don't count on it, especially with this framework. `newmont` is a very simple handler script to reply to any PRIVMSG with the substring "strawberry", in the (public) forum it was sent. I don't provide any cool handler frameworks because I want you to enjoy designing your own. It's not difficult, you can use any language you want, and you don't even need to restart anything to apply your changes, since a new handler is launched for each message. factoids ======== A program to maintain a low-overhead, read-optimized database file, which can store multiple values for each key. This was written to help develop infobots, but can also be used for any other key/value store needed. The `infobot.py` program in `contrib/` has a simple infobot implementation. Caution ======= Your handler is getting input provided by a potentially malicious adversary. If you're not careful, you could create a remote exploit: a path through your handler script that allows anyone on IRC to do whatever they want on your local computer. You can write handlers in bourne shell: it's really easy. It's equally as easy to accidentally allow remote control. There's nothing I can do in my code I provide to prevent you from creating a remote exploit, all I can do is warn you. If you're not confident in your mastery of bourne shell quoting rules, you should build off of the provided lua example, which will make it much more difficult to accidentally create an exploit. Or create a new handler in Python, Ruby, etc. Author ====== Neale Pickett