README

   1 BotBot
   2 ======
   3
   4 Botbot is a very simple IRC bot written in Chicken Scheme.
   5 It handles connection to an IRC server with a specified
   6 nick, optionally joining a channel, and responding to
   7 messages.
   8
   9 The logic behind message responses is handled by a function
  10 defined in a text file provided at runtime, making the actual
  11 functioning of the bot highly (overly?) configurable.
  12
  13 Installation
  14 ------------
  15
  16 You'll need a Chicken 5 build environment to compile the bot.
  17 With this, and the necessary eggs in place, use
  18
  19      csc bot.scm
  20
  21 to produce the binary.  Move this to wherever makes you happy.
  22
  23 Note: "necessary eggs" includes machable, srfi-1, srfi-13, srfi-18,
  24       tcp6 and openssl.
  25
  26 Usage
  27 -----
  28
  29 Run botbot from the command line using:
  30
  31     botbot [options] proc-file host nick
  32
  33 The arguments are:
  34
  35     -h/--help: print usage information
  36
  37     -p/--port PORT: specify irc server port
  38         Otherwise the default ports of 6697 (TLS) or 6667 (no TLS) are used.
  39
  40     --notls: disable use of TLS (default is to use TLS)
  41
  42     -c/--channel CHANNEL: specify a channel for the bot to join on connecting
  43         (Default behaviour is to not join any channel.)
  44
  45     -v/--verbose: increase verbosity level (default 0, max 2)
  46
  47     -a/--allow-reload: allow hot-reloading of procedure file.
  48         Reloading is initiated when a "bbreload" command is received.
  49
  50     proc-file: name of file defining bot logic (see below)
  51
  52     host: irc server hostname
  53
  54     nick: nick to assign to the bot
  55
  56 Proc-file format
  57 ----------------
  58
  59 The proc-file must be a text file containing a single S-expression.
  60 Botbot reads this expresion and expects the evaluation of this expression
  61 to yield a procedure taking three arguments.  Every time the bot receives
  62 a message, this procedure is called.  The three arguments are:
  63
  64   source: a string containing the source of the message (usually a nick)
  65   args: a list containing the arguments of the message
  66   privmsg: a procedure (privmsg dest . strings) to be used to send
  67            messages in response, where dest can be a nick or a channel name.
  68
  69 For example, passing a proc-file containing the following sexp produces
  70 a bot which responds with a private message "Bonjour!" in response to
  71 a user sending "/msg botnick hello".
  72
  73         (lambda (source args privmsg)
  74           (if (string=? (car args) "hello")
  75               (privmsg source "Bonjour!")))
  76
  77 Other examples can be found in the examples/ subdirectory.
  78
  79 License
  80 -------
  81
  82 Botbot is free software.  It is distributed under the terms of the GNU
  83 General Public License version 3.  A copy of this license is available
  84 in the same directory as this README in a file named COPYING.