Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

vandusen
  1. Outdated egg!
  2. vandusen
    1. Description
    2. Author
    3. Usage
    4. API
    5. Available Plugins

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:

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

API

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

[parameter] (config [SETTINGS])

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.

[procedure] ($ SETTING [VALUE])

Convenience procedure for accessing and setting configuration settings.

[procedure] (debug MESSAGE)

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

[procedure] (call-with-connection PROC)

Calls PROC with the current irc connection.

[procedure] (start CONFIG-FILE)

Start vandusen with configuration read from CONFIG-FILE. This allows running vandusen from inside your own program i.e. without the vandusen driver program.

[procedure] (command NAME MATCHER HANDLER #!key PUBLIC)

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.

[procedure] (message-handler PROC #!key COMMAND SENDER RECEIVER BODY TAG CODE)

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

[procedure] (plugin NAME THUNK)

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

[procedure] (reply-to MESSAGE TEXT #!key METHOD PREFIXED)

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.

[procedure] (whisper-to NICK MESSAGE [METHOD])

Sends MESSAGE to NICK via query using METHOD (irc:say by default).

[procedure] (say MESSAGE DESTINATION ...)

This procedure merely calls the irc egg's irc:say procedure with the first argument set to the current connection.

[procedure] (add-finalizer THUNK)

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

[parameter] (after-connect [THUNK])

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. (use 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.