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
* Creating a Hook::
* Hook Types::
+Hook Types
+
+* Received Message Hooks::
+* Sent Message Hooks::
+* DCC CHAT Hooks::
+* Miscellaneous Hooks::
+
Sending Messages
* High Level Message Functions::
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 were a function to
-be defined, but these describe the function to be passwd to
+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 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.
+
+ 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.
- -- Function: hooks/mode nick channel modes
+ NICK is the user who set the modes. This may be the bot.
- -- Function: hooks/message from message
+ 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 from to message
+ -- Function: hooks/public nick channel message
+ This hook is called when a user sends a normal message to a
+ channel.
- -- Function: hooks/public-notice nick to message
+ 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.
- -- 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
- -- Function: hooks/send/public mynick dest message
+4.2.2.2 Sent Message Hooks
+..........................
- -- Function: hooks/send/message botnick 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/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
(line 145)
* bot:use-module: Misc Scripting Stuff.
(line 188)
-* hooks/action: Hook Types. (line 15)
-* hooks/ctcp: Hook Types. (line 29)
-* hooks/ctcp-reply: Hook Types. (line 31)
-* hooks/dcc/chat-begin: Hook Types. (line 76)
-* hooks/dcc/chat-message: Hook Types. (line 80)
-* hooks/disconnect: Hook Types. (line 33)
-* hooks/flood: Hook Types. (line 39)
-* hooks/invite: Hook Types. (line 41)
-* hooks/join: Hook Types. (line 43)
-* hooks/kick: Hook Types. (line 45)
-* hooks/leave: Hook Types. (line 47)
-* hooks/message: Hook Types. (line 52)
-* hooks/mode: Hook Types. (line 50)
-* hooks/nickname: Hook Types. (line 23)
-* hooks/notice: Hook Types. (line 54)
-* hooks/part: Hook Types. (line 48)
-* hooks/public: Hook Types. (line 56)
-* hooks/public-notice: Hook Types. (line 58)
-* hooks/raw: Hook Types. (line 60)
-* hooks/send/action: Hook Types. (line 72)
-* hooks/send/ctcp: Hook Types. (line 74)
-* hooks/send/message: Hook Types. (line 70)
-* hooks/send/public: Hook Types. (line 68)
-* hooks/signoff: Hook Types. (line 27)
-* hooks/timer: Hook Types. (line 62)
-* hooks/topic: Hook Types. (line 66)
+* 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 File Placement\7f2295
-Node: Configuration Files\7f2795
-Node: bot.conf\7f2988
-Node: server syntax\7f4426
-Node: channel syntax\7f5290
-Node: bot.users\7f6133
-Node: Using the Bot\7f7036
-Node: Starting the Bot\7f7286
-Node: User Levels\7f8795
-Node: Protection\7f10197
-Node: Automatic Op\7f10805
-Node: Built-In Commands\7f11094
-Node: Scripting\7f18073
-Node: Adding New Commands\7f19038
-Node: Hooks\7f20361
-Node: Creating a Hook\7f21201
-Node: Hook Types\7f22384
-Node: Scheme User Levels\7f25151
-Node: Sending Messages\7f26285
-Node: High Level Message Functions\7f26901
-Node: Low Level Message Functions\7f27681
-Node: Misc Scripting Stuff\7f28744
-Node: Concept Index\7f35320
-Node: Function Index\7f35539
-Node: Variable Index\7f45670
+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