Vandusen is a cheeky and extensible IRC bot. His natural habitat is #chicken on freenode.
To run vandusen you need a config file. A config file is just a Scheme program which loads the vandusen module and runs some code to set him up. At the very least you need to configure the host to connect to. However, since vandusen is configured not to respond to queries by default (i.e. private messages) this is not a very useful setup. So adding a list of channels vandusen should join after connecting is probabaly a sensible thing to do. Thus our minimal config looks something like this:
(use vandusen) (config `((host . "localhost") (channels "#happytimes")))
Now save it as localhost.scm and try it like this:
$ vandusen localhost.scm
This requires that you have an IRC server set up locally, of course, which is recommendable for configuring vandusen and writing plugins for him anyway. If you see vandusen joining #happytimes you are all set and can start tweaking him to your needs!
The vandusen exports a few useful functions and parameters that you can use in your config files.
- (config [SETTINGS]) parameter
The current vandusen instance's configuration settings. SETTINGS is an alist of setting symbols and values. By default the following settings are available:
- boolean, whether to log debug information (default: #f)
- string, the irc server host to connect to
- string, the nick name to use (default: "vandusen")
- list of strings, channels to join after connecting (default: ())
- list of strings, users who are allowed to control vandusen (default: ())
- boolean, whether to respond to queries (default: #f)
Note that plugins may define additional settings.
- ($ SETTING [VALUE]) procedure
Convenience procedure for accessing and setting configuration settings.
- (debug MESSAGE) procedure
Log debug message (only when debug setting is #t).
- (start CONFIG-FILE) procedure
Start vandusen with configuration read from CONFIG-FILE. This allows running vandusen from inside your own program i.e. without the vandusen driver program.
- (command NAME MATCHER HANDLER #!key PUBLIC) procedure
Defines a command NAME (a symbol) which is executed when MATCHER (an unanchored regular expression) matches a message directed at vandusen (i.e. it was prefixed with "vandusen: " in a channel or sent via query and the allow-query setting is #t). HANDLER is a procedure that accepts the matched irc message record and all possible submatches in MATCHER as additional arguments. PUBLIC is a boolean that determines whether this command is available for everyone (#t) or only for operators (#f) and is #f by default.
Commands are tried in the order they have been defined up until one matches. By default, only two commands are available: reload which causes the config file to be reloaded and authorize USER which adds USER to the operators list for the duration of the current run.
- (message-handler PROC #!key COMMAND SENDER RECEIVER BODY TAG CODE) procedure
This procedure merely calls the irc egg's irc:add-message-handler! procedure with the first argument set to the current connection.
- (plugin NAME THUNK) procedure
Registers plugin NAME (symbol) and executes THUNK when vandusen is (re-)initialized. THUNK would usually define commands.
- (reply-to MESSAGE TEXT #!key METHOD PREFIXED) procedure
Sends TEXT as a reply to an irc message. It will send the reply to where it was received from, i.e. when MESSAGE came from a channel the reply will be sent back to that channel, as well, and when it came from a query the reply will be sent via query to the sender. PREFIXED determines whether to prefix TEXT with "<sender>: " when MESSAGE came from a channel. It is #t by default when METHOD is irc:say, that means METHOD is a procedure like irc:say (the default) or irc:action determining the type of reply to be sent.
- (whisper-to NICK MESSAGE [METHOD]) procedure
Sends MESSAGE to NICK via query using METHOD (irc:say by default).
- (say MESSAGE DESTINATION ...) procedure
This procedure merely calls the irc egg's irc:say procedure with the first argument set to the current connection.
- (add-finalizer THUNK) procedure
Adds THUNK to the list of finalizers which are called right before a re-initialization.
- (after-connect [THUNK]) parameter
THUNK is a procedure that is called right after the IRC connection has been established. Useful for authenticating the nick name or things like that.
Plugins can be activated by loading them from the config file, i.e. (use vandusen-remote). The following plugins are available:
- provides the join CHANNEL and leave CHANNEL commands
- provides the doc ID ... and wtf ID ... commands (see chicken-doc)
- provides the eval EXPR command
- provides the tell USER: MSG ... and messages commands
- provides the poll, vote and poll-results commands
- allows saying things in random intervals of time
- makes vandusen listen on a TCP port for things to say
More detailed descriptions will be available in the future. Refer to the source code for more details and on how to write your own plugins.