BotBot
======

Botbot is a very simple IRC bot written in Chicken Scheme.
It handles connection to an IRC server with a specified
nick, optionally joining a channel, and responding to
messages.

The logic behind message responses is handled by a function
defined in a text file provided at runtime, making the actual
functioning of the bot highly (overly?) configurable.

Installation
------------

You'll need a Chicken 5 build environment to compile the bot.
With this, and the necessary eggs in place, use

     csc bot.scm

to produce the binary.  Move this to wherever makes you happy.

Note: "necessary eggs" includes machable, srfi-1, srfi-13, srfi-18,
      tcp6 and openssl.

Usage
-----

Run botbot from the command line using:

    botbot [options] proc-file host nick

The arguments are:

    -h/--help: print usage information

    -p/--port PORT: specify irc server port
        Otherwise the default ports of 6697 (TLS) or 6667 (no TLS) are used.

    --notls: disable use of TLS (default is to use TLS)

    -c/--channel CHANNEL: specify a channel for the bot to join on connecting
        (Default behaviour is to not join any channel.)

    -v/--verbose: increase verbosity level (default 0, max 2)

    -a/--allow-reload: allow hot-reloading of procedure file.
        Reloading is initiated when a "bbreload" command is received.

    proc-file: name of file defining bot logic (see below)

    host: irc server hostname

    nick: nick to assign to the bot

Proc-file format
----------------

The proc-file must be a text file containing a single S-expression.
Botbot reads this expresion and expects the evaluation of this expression
to yield a procedure taking three arguments.  Every time the bot receives
a message, this procedure is called.  The three arguments are:

  source: a string containing the source of the message (usually a nick)
  args: a list containing the arguments of the message
  privmsg: a procedure (privmsg dest . strings) to be used to send
           messages in response, where dest can be a nick or a channel name.

For example, passing a proc-file containing the following sexp produces
a bot which responds with a private message "Bonjour!" in response to
a user sending "/msg botnick hello".

        (lambda (source args privmsg)
          (if (string=? (car args) "hello")
              (privmsg source "Bonjour!")))
                
Other examples can be found in the examples/ subdirectory.

License
-------

Botbot is free software.  It is distributed under the terms of the GNU
General Public License version 3.  A copy of this license is available
in the same directory as this README in a file named COPYING.