chickadee » vandusen

vandusen

Description

Vandusen is a cheeky and extensible IRC bot. His natural habitat is #chicken on freenode.

Author

Moritz Heidkamp

Usage

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:

(import 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!

API

The vandusen module exports a few useful functions and parameters that you can use in your config files.

config #!optional SETTINGSparameter

The current vandusen instance's configuration settings. SETTINGS is an alist of setting symbols and values. By default the following settings are available:

debug

boolean, whether to log debug information (default: #f)

host

string, the irc server host to connect to

nick

string, the nick name to use (default: "vandusen")

channels

list of strings, channels to join after connecting (default: ())

operators

list of strings, users who are allowed to control vandusen (default: ())

allow-query

boolean, whether to respond to queries (default: #f)

Note that plugins may define additional settings.

$ SETTING #!optional VALUEprocedure

Convenience procedure for accessing and setting configuration settings.

debug MESSAGEprocedure

Log debug message (only when debug setting is #t).

call-with-connection PROCprocedure

Calls PROC with the current irc connection.

start CONFIG-FILEprocedure

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 PUBLICprocedure

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 CODEprocedure

This procedure merely calls the irc egg's irc:add-message-handler! procedure with the first argument set to the current connection.

plugin NAME THUNKprocedure

Registers plugin NAME (symbol) and executes THUNK when vandusen is (re-)initialized. THUNK would usually define commands.

reply-to MESSAGE TEXT #!key METHOD PREFIXEDprocedure

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 #!optional METHODprocedure

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 THUNKprocedure

Adds THUNK to the list of finalizers which are called right before a re-initialization.

after-connect #!optional THUNKparameter

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.

Available Plugins

Plugins can be activated by loading them from the config file, i.e. (import vandusen-remote). The following plugins are available:

vandusen-control

provides the join CHANNEL and leave CHANNEL commands

vandusen-doc

provides the doc ID ... and wtf ID ... commands (see chicken-doc)

vandusen-eval

provides the eval EXPR command

vandusen-pager

provides the tell USER: MSG ... and messages commands

vandusen-poll

provides the poll, vote and poll-results commands

vandusen-random-talk

allows saying things in random intervals of time

vandusen-remote

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.

Version history

version 0.15 (2024-10-05)

• Initial release for CHICKEN 5