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 Usage
  14 -----
  15
  16 Run botbot from the command line using:
  17
  18     botbot [options] proc-file host nick
  19
  20 The arguments are:
  21
  22     -h/--help: print usage information
  23
  24     -p/--port PORT: specify irc server port
  25         Otherwise the default ports of 6697 (TLS) or 6667 (no TLS) are used.
  26
  27     --notls: disable use of TLS (default is to use TLS)
  28
  29     -c/--channel CHANNEL: specify a channel for the bot to join on connecting
  30         (Default behaviour is to not join any channel.)
  31
  32     proc-file: name of file defining bot logic (see below)
  33
  34     host: irc server hostname
  35
  36     nick: nick to assign to the bot
  37
  38 Proc-file format
  39 ----------------
  40
  41 The proc-file must be a text file containing a single S-expression.
  42 Botbot reads this expresion and expects the evaluation of this expression
  43 to yield a procedure taking three arguments.  Every time the bot receives
  44 a message, this procedure is called.  The three arguments are:
  45
  46   source: a string containing the source of the message (usually a nick)
  47   args: a list containing the arguments of the message
  48   privmsg: a procedure (privmsg dest . strings) to be used to send
  49            messages in response, where dest can be a nick or a channel name.
  50
  51 For example, passing a proc-file containing the following sexp produces
  52 a bot which responds with a private message "Bonjour!" in response to
  53 a user sending "/msg botnick hello".
  54
  55         (lambda (source args privmsg)
  56           (if (string=? (car args) "hello")
  57               (privmsg source "Bonjour!")))
  58
  59 Other examples can be found in the examples/ subdirectory.
  60
  61 License
  62 -------
  63
  64 Botbot is free software.  It is distributed under the terms of the GNU
  65 General Public License version 3.  A copy of this license is available
  66 in the same directory as this README in a file named COPYING.