Added README.

[botbot.git] / README

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..f64a7fb
--- /dev/null
+++ b/README
@@ -0,0 +1,66 @@
+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.
+
+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.)
+
+    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.
\ No newline at end of file