Bobot++: A Schemeable IRC Bot

Top

 — The Detailed Node Listing —

Configuration

Configuration Files

bot.conf

Using Bobot++

Concepts

Levels

Built-In Commands

Scripting

Hooks

Hook Types

Sending Messages

Misc. Scripting Stuff

1 Introduction

Bobot++ is a powerful IRC bot written in C++. It can be used standalone as a channel maintenence bot, or extended to do almost anything using Scheme scripts.

FIXME: Fill the intro in more?

2 Configuration

Bobot++ is easy to configure. See the examples directory for an example configuration.

The main configuration file is bot.conf. There are several auxiliary configuration files (a user list, aliases file, ban list, and a script autoexec).

2.1 Configuration File Placement

Bobot++ will look in /etc/bobotpp/default/ for its default config if none is specified on the command line. Put the configuration files you want to be loaded by default in this directory. If you are not root, or you want to have your own personal configuration, put it in ~/.bobotpp/config/default/.

2.2 Configuration Files

2.2.1 bot.conf

bot.conf contains key value pairs separated by =.

<key> = <value>

Comments are started with a # and cause the entire line to be ignored. Note that this only works when the # is the first character of the line.

bot.conf is the main configuration file for a Bobot++. The available configuration variables are listed below in the format “variable <default-value>: description”

A few of the options have more complex syntax, they are documented in their own subsections.

• maxnicklength <9>: The maximum length a valid nickname may be. This should be set before setting the bot’s nickname if it will be more than nine characters long. Most IRC servers support nicknames longer than nine characters, but Bobot++ still follows the old spec and defaults to nine.
• nickname <Bobot>: The nickname of the bot (nick is an alias for nickname)
• username <bobot>: The IRC username of the bot
• cmdchar <!>: The character that prefixes commands given to the bot (command is an alias for cmdchar)
• ircname <I’m a bobot++!>: The IRC name (or ’real name’) of the bot (realname is an alias for ircname)
• userlist <bot.users>: Name of the file where the userlist is stored
• autoexecfile <bot.autoexec>: Name of the file containing Scheme code to be executed when the bot starts (only used if the bot is compiled with scripting support)
• initfile <bot.init>: Name of the file containing the default command aliases
• shitlist <bot.shit>: Name of the file where the shitlist (ban list) is stored
• logfile <$LOGDIR/bot.log>: Location of the bot logfile (set this to /dev/null to disable logging).
• server <None>: This specifies the server to which the bot will connect. Note that this has a special syntax see server syntax.
• channel <None>: This specifies the channels the bot will join when it starts up. This has a special syntax see channel syntax.

2.2.1.1 server syntax

The server syntax in bot.conf allows you to specify an alternate port to connect on, and a password to send the server.

You may use more than one server line; Bobot++ will attempt to connect to the first one, and will connect to the next one in the list if it fails. The bot will continue cycling through the server list until it is able to connect to one. There is a command (!cycle) to make the bot to cycle servers.

server = server_name [port [password]]

This will make Bobot++ attempt to connect to server_name on port port with the password password. server_name should be the address of the server. port and password are optional.

2.2.1.2 channel syntax

The channel syntax in bot.conf allows you to specify the initial modes the bot should set on a channel, the modes the bot should maintain, and a key if the channel needs it.

You may have any number of channel lines. When Bobot++ starts it will attempt to join and gain operator status in every channel listed.

channel = name:initial_modes:modes_to_keep:channel_key

The bot will join name and set the channel modes to initial_modes (e.g. “nt”) if it is able to gain operator status. It will then maintain modes_to_keep. If the channel requires a key to enter simply set channel_key. Every argument except for name is optional.

A few example lines:

channel = #foo:nt:nt:bar

The bot will join #foo with the channel key bar and will then maintain the modes nt.

channel = #bar:::

The bot will join #bar and will not set any modes nor will it attempt to maintain any modes.

2.2.2 bot.users (User List)

bot.users is the default file name of the userlist. It may be changed in bot.conf via the userlist option. You must add an entry for yourself manually. You will probably want to add other entries using the IRC command interface as it is more intuitive than editing the file by hand.

The file contains lines with the format:

‘host_mask:channel_mask:level:protection:auto-op:expiration:password’

• host_mask is the host mask (e.g. ‘*!*username
  .domain.com’) of the user
• channel_mask is a channel mask of the channels that the user has priviliges to use the bot in (e.g. ‘*’ for all channels, ‘#*’ for all non-local channel, ‘#foo*’ for all channels starting with “foo,” ‘#bar’ for channel “#bar” only, etc.)
• level is the user level of the user (User Levels).
• protection is the protection level of the user (Protection).
• auto-op is set to control whether a user is automatically given operator priviliges on channel entry (Automatic Op).
• expiration is the UNIX timestamp of when the user entry becomes invalid. Setting this to -1 will make the entry permanent.
• password is the password the user must supply to the bot to authenticate. This can be set to *NONE* to not have a password.

2.2.3 bot.init (Command Aliases)

This file stores a list of IRC command aliases. The filename may be changed in bot.conf via the initfile option. You use this file to set up aliases for IRC commands, e.g. to make !a call !adduser. This way you can save typing for commonly used commands.

The format of a line in the file is: alias command

This will make alias call command. e.g. ‘t topic’ will make !t New Topic set the current channel’s topic to “New Topic,” just as if you had used !topic New Topic.

2.2.4 bot.autoexec (Scheme Init File)

This file is only used when Bobot++ is compiled with scripting support. The name of the autoexec file can be changed in bot.conf via the autoexecfile option.

The contents of this file are evaluated by Guile when the bot starts. You can use this to do things like loading a few default modules when the bot starts.

2.2.5 bot.shit (Ban/Shit List)

This file stores the ban list. The name may be changed in bot.conf via the shitlist option. You will most likely want to use the IRC command interface to edit this file instead of editing it directly.

The file contains lines in the form:

‘host_mask:channel_mask:level:expiration:reason’

• host_mask is the host mask (e.g. ‘*!*username
  .domain.com’) of the user
• channel_mask is a channel mask of the channels that the user is banned on (e.g. ‘*’ for all channels, ‘#*’ for all non-local channel, ‘#foo*’ for all channels starting with “foo,” ‘#bar’ for channel “#bar” only, etc.
• level is a number specifying if the bot should not allow the user to gain ops, to kick the user upon joining, or to prevent the user from being debanned by other users. Shit Levels for information on the available levels.
• expiration is the UNIX timestamp of when the shit entry becomes invalid. This may be set to -1 to make it valid forever.
• reason is text that is sent to the user when they are kicked or banned from the channel.

3 Using Bobot++

Using Bobot++ is easy. This chapter covers starting the bot, a few Bobot++ specific concepts, and using the built-in commands of the bot.

3.1 Starting the Bot

The bot is usually installed with the binary name bobotpp. It accepts the following command line arguments.

• [--help][-h] - Shows detailed help and exits
• [--version][-v] - Shows version information and exits
• [--no-background][-b] - Run bobot++ in the foreground
• [--config-file file][-f] - Use file instead of bot.conf
• [--config-dir dir][-d] - Use dir as dir to load config file from
• [--config dir][-c] - Search your config path (defaults to $HOME/.bobotpp/config/ and then /etc/bobotpp/) for dir and then loads your config data using dir
• [--sys-config dir][-s] - Looks for config in /etc/bobotpp/dir. Note that the user dir is still searched first
• [--user-config dir][-u] - Looks for config in $HOME/.bobotpp/config/dir/. Note that the system dir is still searched after this if dir is not found.
• [--debug][-D] Makes Bobot++ print debugging info and run in the foreground
• [--debug-scripts][-S] Enables the Guile debugging evaluator for verbose script errors and backtraces while still running the bot in the background.

The default configuration is read from $HOME/.bobotpp/config/default/ and then /etc/bobotpp/default/ if the user config is not found.

The bot defaults to running in the background as a daemon.

3.2 Concepts

There are a few general concepts that a user of Bobot++ should know about.

3.2.1 User List

3.2.2 Shit List

3.2.3 Spy List

3.2.4 Levels

3.2.4.1 User Levels

There are several user levels available in Bobot++ to provide gradated access to commands. !adduser and bot.users use the numeric code; Scheme uses the textual name for the level. By default (if the user is not found in the userlist) a user has access to commands with the level bot:user-none.

0. bot:user-none - No built-in commands may be executed by default (commands may be added from Scheme that can be executed by users of level none and the level required to execute a command may be changed from Scheme).
1. bot:user-user - Will be able to execute most commands but not all and cannot use masks on kicks and bans.
2. bot:user-trusted - For built-ins with a default configuration this user has access to the same set of commands as an user but may use masks on kicks and bans. Scheme commands may be added which require a user to be of this level.
3. bot:user-friend - In the default configuration a user who is a friend will be able to do everything short of stopping the bot. Again, there may be user added commands that require a higher user level.
4. bot:user-master - This is the highest user level and has access to every feature of the bot.

3.2.4.2 Protection

A user added via Scheme, the bot.users file, or !adduser may be protected from being deoped, kicked, or banned. The user list and IRC commands use the numeric codes, Scheme uses the symbolic names.

0. bot:protection/none No protection
1. bot:protection/no-ban No ban. If a user is banned the bot will unban him..
2. bot:protection/no-kick No kick. The user may still be kicked but the bot will kickban the user who kicked the protected user.
3. bot:protection/no-deop No deop. The bot will ensure that the user always maintains operator status.

3.2.4.3 Automatic Op

A user may be automatically given operator status upon entering a channel. Scheme uses the symbolic name, the user list (bot.users) and IRC commands use the numeric value.

0. bot:aop/no Do not automatically op the user
1. bot:aop/yes Do automatically op the user

3.2.4.4 Shit Levels

The shit list and shit list related commands use different levels to define how much the bot hates a user. Scheme uses the symbolic names, the shit list and IRC commands use the numbers.

0. bot:shit/none The bot doesn’t hate the user (this is the normal level)
1. bot:shit/no-op The bot will deop the user any time he gains operator priviliges in the channel
2. bot:shit/no-join The bot will kick and ban the user when he joins the channel
3. bot:shit/no-deban The bot will kick and ban usre when he joins the channel, and will prevent other users from debanning him.

3.3 Built-In Commands

Bobot++ has many built-in commands that make it useful without scripting support. The reference leaves off the command char; remember to use whatever you defined the command char to be in bot.conf.

If a command needs the channel name then you must specify the channel as the first argument to the command when private messaging the bot a command. If, however, you are using the command in a channel you may omit the channel argument, and the bot will use the current channel.

3.3.1 Bot Control Commands

These commands are used to control the behaviour of the bot.

Command: cycle channel

Makes the bot leave and join channel.

Command: die

Makes the bot stop immediately.

Command: join channel

Makes the bot join channel.

Command: nick newnick

Makes the bot use nickname new-nick.

Command: setfloodrate messages-per-second

Sets the flood rate to messages-per-second. The bot will consider users sending more than messages-per-second messges in a second to be flooding and will ignore them.

Command: setversion version-info

Sets the string returned when someone requestions the version info of the bot.

3.3.2 Message Commands

These commands cause the bot to send messages (e.g. sending a message to a channel or performing an action). For all commands target may be either a user or a channel.

Command: action target do

Makes the bot to perform the action do in a message sent to target.

Command: do command

Sends a raw irc command. command is the IRC command you wish to send (e.g. ‘PRIVMSG #foo Hello!’).

Command: msg target message

Command: say target message

Makes the bot say message to target.

3.3.3 Channel Control

Command: ban channel mask

Bans mask from channel. You must be a trusted user to ban using a host mask, but a normal user may ban individual nicks.

Command: deban channel mask

Debans mask from channel. You must be a trusted user to deban with a mask.

Command: deop channel mask

Deops mask on channel.

Command: invite nick channel

Invites nick to channel.

Command: keep channel modes

Sets the modes that the bot will keep for channel.

Command: kick channel mask reason

Command: kickban channel mask reason

Kicks mask out of channel, because of reason. kickban also bans mask.You must be a trusted user to use a mask.

Command: lock channel

Locks topic on channel

Command: mode channel modes

Sets mode of channel to the mode string modes.

Command: op channel nick

Ops nick on channel

Command: part channel

Makes the bot leave channel.

Command: tban channel mask time

Command: tkban channel mask time

Bans mask from channel for time seconds. tkban also kicks the user. You must be a trusted user to use a mask.

Command: topic channel [topic]

Sets the topic in channel to topic. If topic is not supplied the current topic is sent as a notice to the user calling the command.

Command: unlock channel

Unlocks the topic on channel

3.3.4 Spylist Commands

• spylist Shows the bot’s spylist.
• spymessage Adds you to the spylist
• rspymessage Removes you from the spy list.

3.3.5 User List Commands

Command: adduser mask

Adds the user

deluser Removes nick or mask from the userlist.

Command: save

Saves the userlist.

userlist Shows the bot’s userlist

3.3.6 Server List Commands

• addserver Adds the server specified by host name or ip address to the server list.
• delserver Deletes server from server list whose number in the server list is server number.
• nextserver Makes the bot connect to the next server in its server list.
• reconnect Makes the bot reconnect to its current server.
• server Select the server to connect to. server number is the number of the server in the serverlist.
• serverlist Shows the bot’s serverlist.

3.3.7 Shit List Commands

• addshit
• delshit Removes nick or mask from the shitlist
• shitlist Shows the bot’s shitlist.

3.3.8 Channel Info

• banlist
• channels Prints the channel(s) where the bot is currently.
• names Yes Shows the nicknames and status of users on channel.
• stats Yes Gives channel’s statistics.

3.3.9 Scripting Commands

• execute Only available if scripting support is enabled
• load Reloads the userlist from disk.
• loadscript Only available if scripting support is enabled

3.3.10 Authentication Commands

• ident Identifies you on the bot. Note that you should not use this command in public …
• password Changes your password on the bot. Use NONE as password if you want to clear it. Do not use this command in public!

3.3.11 Miscellaneous Commands

• alias Makes an alias, and adds the function new name, that will do exactly the same command as old name.
• dcclist Gives the list of all DCC Chat connections.
• help
• nslookup Does a nameserver query about nick host, host or ip address.
• who Yes Show your level on channel
• whois Yes Shows information about nick on channel

4 Scripting

Bobot++’s most powerful feature is its scripting system. You write scripts using Guile Scheme. This manual does not cover how to use Guile or how to learn Scheme. See Guile Reference Manual in The Guile Reference Manual, for the Guile reference manual and http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html for a good tutorial on Scheme.

Note that in previous versions the scripting commands where in the form bot-function. They are now in the form bot:function. The old names are still available, but are deprecated and will be removed in Bobot++ 3.0. New commands are only available with the bot: prefix. The command perl -pi -e ``s/bot-/bot:/g'' your-files should be enough to convert your code to use the new functions.

NOTE: All arguments to functions and hooks called by the bot are strings unless otherwise specified.

4.1 Adding New Commands

Adding a new command is simple. To register a new command use bot:addcommand.

Function: bot:addcommand name func needs-channel? num-of-args min-level

The name is a string representing the name of the command being added. func is a function accepting num-of-args arguments. needs-channel? is a bool that is true if the function needs the channel name as its first arg, and false otherwise. num-of-args is the number of args func will take and must be within zero (0) and twenty (20). min-level is one of the User Levels. A user must be at least a min-level user to use the new command. None of the arguments are guaranteed to be passed; if they aren’t they are set to the empty string "". An example of a new command would be:

(define (hello channel name)
  (if (string=? name "")
    (bot:say channel "Hello world!")
    (bot:say channel (string-append "Hello " name "!")))

(bot:addcommand "hello" hello #t 2 0)

This will display “Hello World!” if called as !hello and “Hello World USER” if called as !hello USER.

4.2 Hooks

Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII and tiny fugue (a MUD bot) hooks with a little bit of extra stuff added in. A hook is called when a regular expression is matched against a message sent to or by the bot.

Bobot++ uses different hook types for each IRC message type, and also includes a hook for accessing raw irc messages. Hooks are tagged with a priority and a flag that specifies whether to call the next hook that matches after calling the current one or to stop processing.

Hooks are processed from the highest to lowest priority, with fallthrough hooks of equal priority to non-fallthrough hooks being executed first.

4.2.1 Creating a Hook

To add a new hook you use the function bot:addhook.

Function: bot:addhook type regex function [pri fall name]

type specifies the type of hook (the types of hooks are listed in Hook Types).

regex is a standard regular expression. If regex is matched, function will be called.

function will take a different number of args depending on the hook type.

pri specifies the priority of the hook—higher priority hooks are executed first. This argument is optional and defaults to 0.

fall is #t if the hook is a fallthrough hook and #f is the hook is not a fallthrough hook. This arg is also optional and defaults to #t.

name is the optional name of the hook that defaults to "DEFAULT". If you set the name then you can have more than one hook that matches the same regexp, as long as they have the same name. E.g. in a log script you could have the regexps for the log function all be ".*" and set their names to "log" to avoid a conflict with other hooks.

4.2.2 Hook Types

The following sections document the different hooks Bobot++ exposes.

The general format of each hook description is as if it were a function to be defined, but these describe the function to be passed to bot:addhook. Do not name your functions these names.

That said, here is the list of available hooks functions. FIXME: write docs

4.2.2.1 Receieved Message Hooks

The following hooks are triggered when a mesage is received by the bot.

Function: hooks/action from to action

This hook is triggered when someone performs an action.

from is the nickname the person that performed the action.

to is the target of the action, which is either a channel or the Bot’s nick if the user private messages the bot.

action is the text of the action. E.g. if someone did ‘* foobar does baz’, then action would be the string "does baz".

Function: hooks/nickname old-nick new-nick

This hook is called when someone changes his nickname from old-nick to new-nick.

Function: hooks/signoff nick message

This hook is called when someone signs off of IRC.

nick is the nickname of the person signing off.

message is his quit message

Function: hooks/ctcp nick to command rest

This hook is called when a CTCP request is received by the bot.

nick is the nickname of the sender.

to is the target of the CTCP request. This will either be a channel the bot is in, or the nickname of the bot.

command is the CTCP command issued.

rest contains the arguments to the CTCP command.

Function: hooks/ctcp-reply nick command rest

This hook is called when a CTCP REPLY is received. This occurs when the bot has sent a CTCP request to another client. The CTCP REPLY is always addressed to the bot directly.

nick is the nickname of the person who replied.

command is the command to which nick is replying.

rest contains the body of the reply.

Function: hooks/disconnect server intentional

This is called when the bot is disconnected from a server.

server is the hostname of the server from which the bot was disconnected.

intentional is a flag set to #t when the bot disonnected from the server as the result of a command (issued by a user from IRC, SIGHUP, or from a script), or #f when the bot disconnected from the server unintentionally..

Function: hooks/invite nick channel

This hook is called when a user invited the bot to join a channel.

nick is the nickname of the user who sent the invite.

channel is the channel to which the bot was invited.

Function: hooks/join nick channel

This is called when a user or the bot joins a channel.

nick is the nickname of the user who joined channel. This may be the bot’s nickname (the IRC server sends the JOIN command back to the the bot after it joins a channel).

channel is the channel that was joined

Function: hooks/kick target from channel reason

This hook is called when a user, including the bot, is kicked out of a channel.

target is the nick of the user who was kicked. This may be the bot’s nick.

from is the nick of the user who issued the kick. This may also be the bot’s nick.

channel is the channel the kick was issued in.

reason is the reason the user was kicked.

Function: hooks/part nick channel

This hook is called when a user parts a channel.

nick is the user who parted the channel. This may be the bot.

channel is the channel from which the user parted.

Function: hooks/mode nick target modes

This hook is called when someone sets the modes of target.

nick is the user who set the modes. This may be the bot.

target is the target of the MODE command. This may be a channel or a user. If it is a user, it may be the bot.

modes is the MODE string.

Function: hooks/message nick message

This hook is called when someone sends a private message to the bot.

nick is the nickname of the user who sent the message.

message is the message the user sent.

Function: hooks/notice nick message

This hook is called when a user send a private notice to the bot.

nick is the user who sent the notice.

message is the message the user sent.

Function: hooks/public nick channel message

This hook is called when a user sends a normal message to a channel.

nick is the user who sent the message.

channel is the channel to which the message was sent.

message is the message that was sent.

Function: hooks/public-notice nick channel message

This hook is called when a user send a notice to a channel.

nick is the user who sent the notice.

channel is the channel to which the notice was sent.

message is the message that was sent.

Function: hooks/raw raw-message

This hook is called every time a message is received. This matches on the raw message text and passes the hook function the raw IRC message.

raw-message is the raw IRC message.

Function: hooks/topic nick channel new-topic

This hook is called when a user changes the topic in a channel.

nick is the user who set the topic. This may be the bot.

channel is the channel that’s topic was changed.

new-topic is the new topic.

4.2.2.2 Sent Message Hooks

These hooks are called when the bot sends a message. mynick is always the bot’s nick and will not be documented in each hook description.

Function: hooks/send/public mynick channel message

This hook is called when the bot sends a normal message to a channel.

channel is the channel to which the bot sent the message.

message is the message the bot sent.

Function: hooks/send/message mynick to message

This hook is called when the bot sends a private message to a user.

to is the nick of the user to whom the message was sent.

message is the message that was sent.

Function: hooks/send/action mynick to message

This hook is called when the bot sents an action to a channel or a user.

to is the channel or nick of the user to which the action was sent.

message is the text of the action.

Function: hooks/send/ctcp mynick to command message

This hook is called when the bot sends a CTCP message other than an ACTION to a channel or user.

to is the channel or nick of the user to which the CTCP was sent.

command is the CTCP command that was sent.

message is a string containing the arguments to the CTCP command.

Function: hooks/send/who who

This is called when the bot sends a WHO message. The regex is matched on who, which is also passed as the only argument to your function.

who is the channel or nick that was WHOed.

Function: hooks/send/whois nick

This is called when the bot sends a WHOIS message. The regex is matched on nick, which is also passed as the only argument to your function.

nick is the nickname of the person who was WHOISed.

4.2.2.3 DCC CHAT Hooks

These hooks are called when a user initializes a DCC CHAT and when the bot receives messages from the user in a DCC CHAT.

Function: hooks/dcc/chat-begin from

This hook is called when a user begins a DCC CHAT with the bot. from is the user’s address in the form ‘nick!user@host’.

Function: hooks/dcc/chat-end address

This hook is called when a DCC CHAT is purged after being idle for a while, or when the user closes the DCC CHAT. As such, you cannot write any more data to the DCC CHAT.

address is the address (nick!user@host) of the person on the other side of the DCC.

Function: hooks/dcc/chat-message from message

This hook is called when a user sends a message to the bot through a DCC CHAT.

from is the user’s address in the form ‘nick!user@host’.

message is the message the user sent to the bot.

4.2.2.4 Miscellaneous Hooks

Function: hooks/flood nick

This hook is called when a user is detected flooding the bot.

nick is the nickname of the user flooding the bot.

Function: hooks/timer time

This hook is called once a minute. The regex is not used.

time is the in zero-padded hh:mm format.

4.3 Sending Messages

There are several types of messages you can send with Bobot++ from scripts. They are split into High and Low level message sending functions. Most bots will only use the high level functions, but the low level ones are provided for when a bot needs to do things like send raw IRC messages or CTCP commands.

4.3.1 “High Level” Message Functions

Function: bot:action channel message

Send an “action” type message to channel

Function: bot:msg target message

Function: bot:say target message

Send a public or private message to target.

target may be a channel or a nickname.

In versions of Bobot++ prior to 2.1.8 bot:say could only send to channels, and bot:msg could only send private messages to users. They are aliases of the same command now, but it may be worth using them as they used to for clarity.

Function: bot:notice target message

Sends message as a NOTICE to target. target may be a user (nick) or a channel.

4.3.2 “Low Level” Message Functions

The “Low Level” messaging functions allow you to do things like send CTCP messages. You probably want to read rfc 2812 and the CTCP spec before using these. If you have no idea what these do, read rfc 2812 (IRC Client Protocol) and CTCP spec. These functions all return *unspecified* always, so don’t use the return value for anything.

Function: bot:ctcp to command message

to is the target of your CTCP message, command is the CTCP command, and message is the message (or arguments) of the command. Make sure to bot:ctcp-quote the message!

Function: bot:ctcp-reply to command message

to is the target of your CTCP reply, command is the CTCP command, and message is the message (or arguments) of the command. Make sure to bot:ctcp-quote the message!

This is used to reply to a ctcp that the bot has received.

4.4 Misc. Scripting Stuff

These are a few useful things that I thought people writing scripts might want to know.

If you want to execute code when the bot exits, just do add-hook! bot:exit-hook thunk where thunk is an argumentless procedure (a thunk). When the bot exits your thunk will be called.

4.5 Scheme Commands

These scheme functions are the same as the commands. They allow you to execute bot commands from scheme scripts.

Function: bot:adduser nick-or-mask cbannel-mask level prot auto-op

Adds an user to the userlist, for a nick!user@host matching the one given, on a channel matching the channelMask given.

The level can be:	The prot can be:	The auto-op can be:
0 - No level	0 - No protection	0 - No auto-op
1 - User	1 - No ban	1 - Op on join
2 - Trusted User	2 - No kick
3 - Friend	3 - No deop
4 - Master

Function: bot:addserver hostname ip-address [portnumber]

Adds the server specified by hostname or ip-address to the server list.

Function: bot:addshit nick-or-mask channel-mask level [time reason]

Adds an user to the shitlist, for a nick!user@host matching the one given, on a channel matching the channelMask given.

The level can be:
  0 - No shit
  1 - No op
  2 - Kick and Ban on join
  3 - Kick and Ban on join, no deban

Function: bot:ban channel mask-or-nick

Bans mask or nick from channel. You must be a trusted user to ban with a mask.

Function: bot:change-command-level nick-or-mask channel-mask new-level

Gives nick or mask level new-level on channel(s) channel-mask. Note that you can not change level for someone whose level is greater than yours, and that you can not give a level greater than yours.

Function: bot:cycle channel

Makes the bot leave and join channel.

Function: bot:deban channel mask-or-nick

Debans mask or nick from channel. You must be a trusted user to deban with a mask.

Function: bot:delserver server-number

Deletes server from server list whose number in the server list is server-number

Function: bot:deluser nick-or-mask channel-mask

Removes nick or mask from the userlist.

Function: bot:delshit nick-or-mask channel-mask

Removes nick or mask from the shitlist.

Function: bot:deop channel mask-or-nick

Deops mask or nick on channel.

Function: bot:die reason

Makes the bot stop immediately.

Function: bot:do ?

Function: bot:invite channel nick

Invites nick on channel.

Function: bot:join channel

Makes the bot join channel.

Function: bot:keep channel modes

Sets the modes that the bot will keep for channel. See also STATS.

Function: bot:kick channel mask-or-nick [reason]

Kicks mask or nick out of channel, because of reason. You must be a trusted user to use a mask.

Function: bot:kickban channel mask-or-nick [reason]

Bans then kicks mask or nick out of channel, because of reason. You must be a trusted user to use a mask.

Function: bot:lock channel

Locks topic on channel.

Function: bot:mode channel mode-string

Sends mode-string as mode for channel.

Function: bot:nextserver

Makes the bot connect to the next server in its server list.

Function: bot:nick nick

Makes the bot use nickname nick.

Function: bot:op channel nick

Ops nick on channel.

Function: bot:part channel

Makes the bot leave channel.

Function: bot:reconnect

Makes the bot reconnect to its current server.

Function: bot:server server-number

Select the server to connect to. server-number is the number of the server in the serverlist.

Function: bot:setfloodrate ?

Function: bot:setversion ?

Function: bot:tban channel nick-or-mask time

Bans nick or mask from channel for time seconds.

Function: bot:tkban channel nick-or-mask time [reason]

Bans nick or mask from channel for time seconds, then kicks him/them because of reason.

Function: bot:topic channel topic

If no topic is given, prints channel’s topic. Otherwise, the bot will change channel’s topic to topic.

Function: bot:unlock channel

Makes the bot unlock topic on channel.

Function: bot:who target

Sends a WHO command to target. target may be either a channel or a user.

Function: bot:whois nick

Sends a WHOIS command to nick. nick must be a nickname, you cannot send a WHOIS to a channel.

Function: bot:delcommand

[ Probably deletes a command added with bot:addcommand ? ]

4.6 Query Functions

[ I didn’t know where to put any of these, so I just stuck them in here.

There probably needs to be several sections added, like dealing with users (kicking, added, etc), dealing with the bot (channels, nickname of the bot, etc), server issues (serverlist), useful tools (nslookup, whois), and do on. ]

These functions allow scripts to get various bits of information.

Function: bot:logport

[ Probably returns the log port? ]

Function: bot:getnickname

[ Gets the bot’s nickname? ]

Function: bot:getserver

Function: bot:getserverlist

Function: bot:getversion

Return the long bot version string (same as returned by a CTCP VERSION request, e.g. “bobotpp version 2.3.1.1-8cd2-dirty by unknown_lamer@FreeNode <clinton@unknownlamer.org>\n1.97 and below by eb@IRCNet <eb@via.ecp.fr>”).

Function: bot:getreleasrevision

Return the bot version only (e.g. “2.3.1.1-8cd2”).

Function: bot:flush

[ Flushes the socket to the server? ]

Function: bot:flushport

[ Flushes the log port? ]

Function: bot:random ?

[ Returns a random number? What range? Why? ]

Function: bot:addtimer ? ?

Function: bot:deltimer ?

Function: bot:dcc-chat-send ? ?

[ And what about the stuff defined in bobot-utils.scm ? I just added it here so it could be somewhere. There should also be a section dealing with modules. How to use them. What module scripts are in. What module bobot++ provided primites are in. And so on. ]

Function: bot:log . messages

Write as many messages as you want to the log. If the arg is a thunk it will be executed and it’s output will be written to the log.

Function: bot:load file

Function: bot:load-module module-spec

Function: bot:use-module module-spec

Function: bot:match-not-channel regex

bot:match-not-channel adds a prefix regex to your regex so it doesn’t match the sender or channel in a PUBLIC message

Function: bot:match-to-me regex

bot:match-to-me matches text that was addressed to the bot with a ’:’, ’,’, or nothing after the bot name.

Function: bot:sent-to-me? message

Function: bot:ctcp-quote message

Returns the CTCP quoted message Input MUST NOT contain the trailing \r\n (it is added by the message sending code).

Variable: %bot:loadpath

Function: %bot:load-extensions

Concept Index

Function Index

Variable Index