This document describes Bobot++ by Clinton Ebadi and Etienne Bernard
(original author, no longer works on program).
- This document applies to version 2.1.5 of the program named Bobot++
+ This document applies to version 2.2 of the program named Bobot++
- Copyright 2002,2004 Clinton Ebadi
+ Copyright 2002,2004,2005 Clinton Ebadi
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
Configuration
-* Configuration Files::
* Configuration File Placement::
+* Configuration Files::
Configuration Files
* Creating a Hook::
* Hook Types::
+Hook Types
+
+* Received Message Hooks::
+* Sent Message Hooks::
+* DCC CHAT Hooks::
+* Miscellaneous Hooks::
+
Sending Messages
* High Level Message Functions::
* Menu:
-* Configuration Files::
* Configuration File Placement::
+* Configuration Files::
\1f
-File: bobot++.info, Node: Configuration Files, Next: Configuration File Placement, Prev: Configuration, Up: Configuration
+File: bobot++.info, Node: Configuration File Placement, Next: Configuration Files, Prev: Configuration, Up: Configuration
-2.1 Configuration Files
+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/'.
+
+\1f
+File: bobot++.info, Node: Configuration Files, Prev: Configuration File Placement, Up: Configuration
+
+2.2 Configuration Files
=======================
* Menu:
\1f
File: bobot++.info, Node: bot.conf, Next: bot.users, Prev: Configuration Files, Up: Configuration Files
-2.1.1 bot.conf
+2.2.1 bot.conf
--------------
* Menu:
\1f
File: bobot++.info, Node: server syntax, Next: channel syntax, Prev: bot.conf, Up: bot.conf
-2.1.1.1 server syntax
+2.2.1.1 server syntax
.....................
SERVER = SERVER_NAME [PORT [PASSWORD]]
\1f
File: bobot++.info, Node: channel syntax, Prev: server syntax, Up: bot.conf
-2.1.1.2 channel syntax
+2.2.1.2 channel syntax
......................
CHANNEL = NAME:INITIAL_MODES:MODES_TO_KEEP:CHANNEL_KEY
\1f
File: bobot++.info, Node: bot.users, Prev: bot.conf, Up: Configuration Files
-2.1.2 bot.users
+2.2.2 bot.users
---------------
`bot.users' is the default file name of the userlist. It may be changed
operator priviliges on channel entry (*Note Automatic Op::).
-\1f
-File: bobot++.info, Node: Configuration File Placement, Prev: Configuration Files, Up: Configuration
-
-2.2 Configuration File Placement
-================================
-
- [ I kinda think this should go before the detailed description of
- the config file. I was didn't see it at first and was very
- frustrated trying to find out _where_ to edit all this wonderful
- stuff. ]
-
- 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/'.
-
\1f
File: bobot++.info, Node: Using the Bot, Next: Scripting, Prev: Configuration, Up: Top
* `[--debug][-D]' Makes Bobot++ print debugging info and run in the
foreground
+ * `[--debug-scripts][-S]' Enabled 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.
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 no catch-all
-setting is found in *Note bot.users::.) a user is not even a
-`bot:user-none' and cannot execute *any* commands, even commands
-available to `bot:user-none'.
+setting is found in *Note bot.users::.) 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
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.
+
* Menu:
* Adding New Commands::
(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'.
+ World USER" if called as `!hello USER'.
\1f
File: bobot++.info, Node: Hooks, Next: Scheme User Levels, Prev: Adding New Commands, Up: Scripting
-- Function: bot:addhook type regex function [pri fall name]
TYPE specifies the type of hook (the types of hooks are listed in
- *Note 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 default 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.
+ *Note 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.
\1f
File: bobot++.info, Node: Hook Types, Prev: Creating a Hook, Up: Hooks
4.2.2 Hook Types
----------------
-Here is a list of the various hooks funtions and notes on each one. The
-general format of each hook description is as if it was was function to
-be defined, but these describe the function to be passwd to
-`bot:add-hook'. Do _not_ name your functions these names.
-
- [ Boy, that's clumsy. I want to say that the hook/xx functions
- that are documented below are not funtions that you call. They
- are the functions that needs to be passed to bot:addhook for that
- kind of hook.
+The following sections document the different hooks Bobot++ exposes.
- Still clumsy. Oh well. ]
+ The general format of each hook description is as if it were a
+function to be defined, but these describe the function to be passwd to
+`bot:add-hook'. Do _not_ name your functions these names.
That said, here is the list of available hooks functions. FIXME:
write docs
+* Menu:
+
+* Received Message Hooks::
+* Sent Message Hooks::
+* DCC CHAT Hooks::
+* Miscellaneous Hooks::
+
+\1f
+File: bobot++.info, Node: Received Message Hooks, Next: Sent Message Hooks, Prev: Hook Types, Up: Hook Types
+
+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 address of the person that performed the action in the form
- `NICK ! USER @ HOST' (without the spaces). TO is the target of
- the action, which is either a channel or the Bot's nick. ACTION
- is the text of the action. E.g. if someone did `* foobar does
- baz', then ACTION would be the string `"does baz"'.
+ 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 gets called when someone changes thir nickname from
+ This hook is called when someone changes his nickname from
OLD-NICK to NEW-NICK.
- -- Function: hooks/signoff nick rest
+ -- 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.
- -- Function: hooks/disconnect server
- This is called when the bot is disconnected from a server
- unintentionally. `hooks/signoff' is called when the bot
- purposefully disconnected. The hook function is passed the
- hostname of the server it was disconnected from.
+ NICK is the nickname of the person who replied.
- -- Function: hooks/flood nick
+ 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/leave nick channel
-- Function: hooks/part nick channel
+ This hook is called when a user parts a channel.
- -- Function: hooks/mode nick channel modes
+ NICK is the user who parted the channel. This may be the bot.
- -- Function: hooks/message from message
+ 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.
- -- Function: hooks/public from to message
+ CHANNEL is the channel to which the notice was sent.
- -- Function: hooks/public-notice nick to message
+ 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.
- -- Function: hooks/timer time
- This hook seems to be called once a minute. TIME is in `hh:mm'
- format.
+ 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.
+
+\1f
+File: bobot++.info, Node: Sent Message Hooks, Next: DCC CHAT Hooks, Prev: Received Message Hooks, Up: Hook Types
+
+4.2.2.2 Sent Message Hooks
+..........................
- -- Function: hooks/send/public mynick dest message
+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/message botnick message
+ -- 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.
+
+\1f
+File: bobot++.info, Node: DCC CHAT Hooks, Next: Miscellaneous Hooks, Prev: Sent Message Hooks, Up: Hook Types
+
+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 triggered when a user begins a DCC CHAT with the bot.
+ 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-message from message
- This hook is triggered 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.
+ 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.
+
+\1f
+File: bobot++.info, Node: Miscellaneous Hooks, Prev: DCC CHAT Hooks, Up: Hook Types
+
+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.
\1f
File: bobot++.info, Node: Scheme User Levels, Next: Sending Messages, Prev: Hooks, Up: Scripting
`*unspecified*' always, so don't use the return value for anything.
-- Function: bot:send-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!
+ 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:send-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.
\1f
File: bobot++.info, Node: Misc Scripting Stuff, Prev: Sending Messages, Up: Scripting
bot:exit-hook THUNK' where THUNK is an argumentless procedure (a
thunk). When the bot exits your thunk will be called.
- [ I didn't know where to put any of these, so I jsut stuck them in
+ [ 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
(line 7)
* bot:send-ctcp: Low Level Message Functions.
(line 13)
+* bot:send-ctcp-reply: Low Level Message Functions.
+ (line 18)
* bot:sent-to-me?: Misc Scripting Stuff.
(line 198)
* bot:server: Misc Scripting Stuff.
(line 145)
* bot:use-module: Misc Scripting Stuff.
(line 188)
-* hooks/action: Hook Types. (line 22)
-* hooks/ctcp: Hook Types. (line 36)
-* hooks/ctcp-reply: Hook Types. (line 38)
-* hooks/dcc/chat-begin: Hook Types. (line 83)
-* hooks/dcc/chat-message: Hook Types. (line 87)
-* hooks/disconnect: Hook Types. (line 40)
-* hooks/flood: Hook Types. (line 46)
-* hooks/invite: Hook Types. (line 48)
-* hooks/join: Hook Types. (line 50)
-* hooks/kick: Hook Types. (line 52)
-* hooks/leave: Hook Types. (line 54)
-* hooks/message: Hook Types. (line 59)
-* hooks/mode: Hook Types. (line 57)
-* hooks/nickname: Hook Types. (line 30)
-* hooks/notice: Hook Types. (line 61)
-* hooks/part: Hook Types. (line 55)
-* hooks/public: Hook Types. (line 63)
-* hooks/public-notice: Hook Types. (line 65)
-* hooks/raw: Hook Types. (line 67)
-* hooks/send/action: Hook Types. (line 79)
-* hooks/send/ctcp: Hook Types. (line 81)
-* hooks/send/message: Hook Types. (line 77)
-* hooks/send/public: Hook Types. (line 75)
-* hooks/signoff: Hook Types. (line 34)
-* hooks/timer: Hook Types. (line 69)
-* hooks/topic: Hook Types. (line 73)
+* hooks/action: Received Message Hooks.
+ (line 9)
+* hooks/ctcp: Received Message Hooks.
+ (line 31)
+* hooks/ctcp-reply: Received Message Hooks.
+ (line 43)
+* hooks/dcc/chat-begin: DCC CHAT Hooks. (line 10)
+* hooks/dcc/chat-message: DCC CHAT Hooks. (line 14)
+* hooks/disconnect: Received Message Hooks.
+ (line 54)
+* hooks/flood: Miscellaneous Hooks. (line 7)
+* hooks/invite: Received Message Hooks.
+ (line 65)
+* hooks/join: Received Message Hooks.
+ (line 72)
+* hooks/kick: Received Message Hooks.
+ (line 81)
+* hooks/message: Received Message Hooks.
+ (line 112)
+* hooks/mode: Received Message Hooks.
+ (line 102)
+* hooks/nickname: Received Message Hooks.
+ (line 20)
+* hooks/notice: Received Message Hooks.
+ (line 120)
+* hooks/part: Received Message Hooks.
+ (line 95)
+* hooks/public: Received Message Hooks.
+ (line 127)
+* hooks/public-notice: Received Message Hooks.
+ (line 137)
+* hooks/raw: Received Message Hooks.
+ (line 146)
+* hooks/send/action: Sent Message Hooks. (line 25)
+* hooks/send/ctcp: Sent Message Hooks. (line 33)
+* hooks/send/message: Sent Message Hooks. (line 18)
+* hooks/send/public: Sent Message Hooks. (line 10)
+* hooks/signoff: Received Message Hooks.
+ (line 24)
+* hooks/timer: Miscellaneous Hooks. (line 12)
+* hooks/topic: Received Message Hooks.
+ (line 153)
\1f
File: bobot++.info, Node: Variable Index, Prev: Function Index, Up: Top
\1f
Tag Table:
Node: Top\7f527
-Node: Introduction\7f1816
-Node: Configuration\7f2008
-Node: Configuration Files\7f2295
-Node: bot.conf\7f2510
-Node: server syntax\7f3948
-Node: channel syntax\7f4812
-Node: bot.users\7f5655
-Node: Configuration File Placement\7f6558
-Node: Using the Bot\7f7260
-Node: Starting the Bot\7f7510
-Node: User Levels\7f8853
-Node: Protection\7f10309
-Node: Automatic Op\7f10917
-Node: Built-In Commands\7f11206
-Node: Scripting\7f18185
-Node: Adding New Commands\7f19150
-Node: Hooks\7f20473
-Node: Creating a Hook\7f21313
-Node: Hook Types\7f22496
-Node: Scheme User Levels\7f25525
-Node: Sending Messages\7f26659
-Node: High Level Message Functions\7f27275
-Node: Low Level Message Functions\7f28055
-Node: Misc Scripting Stuff\7f28823
-Node: Concept Index\7f35399
-Node: Function Index\7f35618
-Node: Variable Index\7f45606
+Node: Introduction\7f1925
+Node: Configuration\7f2117
+Node: Configuration File Placement\7f2404
+Node: Configuration Files\7f2904
+Node: bot.conf\7f3097
+Node: server syntax\7f4535
+Node: channel syntax\7f5399
+Node: bot.users\7f6242
+Node: Using the Bot\7f7145
+Node: Starting the Bot\7f7395
+Node: User Levels\7f8904
+Node: Protection\7f10306
+Node: Automatic Op\7f10914
+Node: Built-In Commands\7f11203
+Node: Scripting\7f18182
+Node: Adding New Commands\7f19254
+Node: Hooks\7f20575
+Node: Creating a Hook\7f21415
+Node: Hook Types\7f22621
+Node: Received Message Hooks\7f23185
+Node: Sent Message Hooks\7f28412
+Node: DCC CHAT Hooks\7f29809
+Node: Miscellaneous Hooks\7f30526
+Node: Scheme User Levels\7f30975
+Node: Sending Messages\7f32109
+Node: High Level Message Functions\7f32725
+Node: Low Level Message Functions\7f33505
+Node: Misc Scripting Stuff\7f34568
+Node: Concept Index\7f41144
+Node: Function Index\7f41363
+Node: Variable Index\7f52526
\1f
End Tag Table
HCoop / clinton / bobotpp.git / blobdiff