irc-bot/README

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.

This framework gives you plenty of opportunity to shoot yourself in the foot.
If you're not a seasoned programmer, please stick to a language like Python or
Lua for your handler.  Leave the arcane trivia of proper Bourne Shell quoting
rules to the seasoned experts who've learned the hard way how to do it.


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.

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      IRC line 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        text of this message, 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.


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 the
code I provide to prevent you from really hurting yourself, all I can do is
warn you.



Author
======

Neale Pickett <neale@woozle.org>