* Creating a Hook::
* Hook Types::
+Hook Types
+
+* Received Message Hooks::
+* Sent Message Hooks::
+* DCC CHAT Hooks::
+* Miscellaneous Hooks::
+
Sending Messages
* High Level Message Functions::
-e ``s/bot-/bot:/g'' @var{your-files}} should be enough to convert
your code to use the new functions.
+@strong{NOTE}: All arguments to functions and hooks called by the bot
+are strings unless otherwise specified.
+
@menu
* Adding New Commands::
* Hooks::
@end example
This will display ``Hello World!'' if called as @kbd{!hello} and
-``Hello World @code{USER}'' if called as @kbd{!hello @var{USER}}.
+``Hello World @var{USER}'' if called as @kbd{!hello @var{USER}}.
@end defun
@node Hooks, Scheme User Levels, Adding New Commands, Scripting
@defun bot:addhook type regex function [pri fall name]
@var{type} specifies the type of hook (the types of hooks are listed
-in @ref{Hook Types}). @var{regex} is a standard regular expression. If
-@var{regex} is matched, @var{function} will be called. @var{function}
-will take a different number of args depending on the hook
-type. @var{pri} specifies the priority of the hook---higher priority
-hooks are executed first. This argument is optional and defaults to
-@code{0}. @var{fall} is @code{#t} if the hook is a fallthrough hook
-and @code{#f} is the hook is not a fallthrough hook. This arg is also
-optional and default to @code{#t}. @var{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 @code{".*"} and set their names to
-@code{"log"} to avoid a conflict with other hooks.
+in @ref{Hook Types}).
+
+@var{regex} is a standard regular expression. If
+@var{regex} is matched, @var{function} will be called.
+
+@var{function} will take a different number of args depending on the
+hook type.
+
+@var{pri} specifies the priority of the hook---higher priority hooks
+are executed first. This argument is optional and defaults to
+@code{0}.
+
+@var{fall} is @code{#t} if the hook is a fallthrough hook and
+@code{#f} is the hook is not a fallthrough hook. This arg is also
+optional and defaults to @code{#t}.
+
+@var{name} is the optional name of the hook that defaults to
+@code{"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 @code{".*"} and set their names to @code{"log"} to
+avoid a conflict with other hooks.
@end defun
@node Hook Types, , Creating a Hook, Hooks
@subsection 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
+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 @code{bot:add-hook}. Do @emph{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::
+@end menu
+
+@node Received Message Hooks, Sent Message Hooks, Hook Types, Hook Types
+@subsubsection Receieved Message Hooks
+
+The following hooks are triggered when a mesage is received by the bot.
+
@defun hooks/action from to action
-This hook is triggered when someone performs an action. @var{from} is
-the address of the person that performed the action in the form
-@samp{@var{nick} ! @var{user} @@ @var{host}} (without the spaces).
+This hook is triggered when someone performs an action.
+
+@var{from} is the nickname the person that performed the
+action.
+
@var{to} is the target of the action, which is either a channel or the
-Bot's nick. @var{action} is the text of the action. E.g. if someone
-did @samp{* foobar does baz}, then @var{action} would be the string
-@code{"does baz"}.
-@end defun
+Bot's nick if the user private messages the bot.
+@var{action} is the text of the action. E.g. if someone did @samp{*
+foobar does baz}, then @var{action} would be the string @code{"does
+baz"}.
+@end defun
@defun 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
@var{old-nick} to @var{new-nick}.
@end defun
-@defun hooks/signoff nick rest
+@defun hooks/signoff nick message
+This hook is called when someone signs off of IRC.
+
+@var{nick} is the nickname of the person signing off.
+
+@var{message} is his quit message
@end defun
@defun hooks/ctcp nick to command rest
+This hook is called when a CTCP request is received by the bot.
+
+@var{nick} is the nickname of the sender.
+
+@var{to} is the target of the CTCP request. This will either be a
+channel the bot is in, or the nickname of the bot.
+
+@var{command} is the CTCP command issued.
+
+@var{rest} contains the arguments to the CTCP command.
@end defun
@defun hooks/ctcp-reply nick command rest
-@end defun
+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.
+
+@var{nick} is the nickname of the person who replied.
+
+@var{command} is the command to which @var{nick} is replying.
-@defun hooks/disconnect server
-This is called when the bot is disconnected from a server
-unintentionally. @code{hooks/signoff} is called when the bot purposefully
-disconnected. The hook function is passed the hostname of the
-server it was disconnected from.
+@var{rest} contains the body of the reply.
@end defun
-@defun hooks/flood nick
+@defun hooks/disconnect server intentional
+This is called when the bot is disconnected from a server.
+
+@var{server} is the hostname of the server from which the bot was
+disconnected.
+
+@var{intentional} is a flag set to @code{#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 @code{#f} when the bot disconnected from
+the server unintentionally..
@end defun
@defun hooks/invite nick channel
+This hook is called when a user invited the bot to join a channel.
+
+@var{nick} is the nickname of the user who sent the invite.
+
+@var{channel} is the channel to which the bot was invited.
@end defun
@defun hooks/join nick channel
+This is called when a user or the bot joins a channel.
+
+@var{nick} is the nickname of the user who joined @var{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).
+
+@var{channel} is the channel that was joined
@end defun
@defun hooks/kick target from channel reason
+This hook is called when a user, including the bot, is kicked out of a
+channel.
+
+@var{target} is the nick of the user who was kicked. This may be the
+bot's nick.
+
+@var{from} is the nick of the user who issued the kick. This may also
+be the bot's nick.
+
+@var{channel} is the channel the kick was issued in.
+
+@var{reason} is the reason the user was kicked.
@end defun
-@defun hooks/leave nick channel
-@defunx hooks/part nick channel
+@defun hooks/part nick channel
+This hook is called when a user parts a channel.
+
+@var{nick} is the user who parted the channel. This may be the bot.
+
+@var{channel} is the channel from which the user parted.
@end defun
-@defun hooks/mode nick channel modes
+@defun hooks/mode nick target modes
+This hook is called when someone sets the modes of @var{target}.
+
+@var{nick} is the user who set the modes. This may be the bot.
+
+@var{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.
+
+@var{modes} is the MODE string.
@end defun
-@defun hooks/message from message
+@defun hooks/message nick message
+This hook is called when someone sends a private message to the bot.
+
+@var{nick} is the nickname of the user who sent the message.
+
+@var{message} is the message the user sent.
@end defun
@defun hooks/notice nick message
+This hook is called when a user send a private notice to the bot.
+
+@var{nick} is the user who sent the notice.
+
+@var{message} is the message the user sent.
@end defun
-@defun hooks/public from to message
+@defun hooks/public nick channel message
+This hook is called when a user sends a normal message to a channel.
+
+@var{nick} is the user who sent the message.
+
+@var{channel} is the channel to which the message was sent.
+
+@var{message} is the message that was sent.
@end defun
-@defun hooks/public-notice nick to message
+@defun hooks/public-notice nick channel message
+This hook is called when a user send a notice to a channel.
+
+@var{nick} is the user who sent the notice.
+
+@var{channel} is the channel to which the notice was sent.
+
+@var{message} is the message that was sent.
@end defun
@defun hooks/raw raw-message
-@end defun
+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.
-@defun hooks/timer time
-This hook seems to be called once a minute. @var{time} is in
-@code{hh:mm} format.
+@var{raw-message} is the raw IRC message.
@end defun
@defun hooks/topic nick channel new-topic
+This hook is called when a user changes the topic in a channel.
+
+@var{nick} is the user who set the topic. This may be the bot.
+
+@var{channel} is the channel that's topic was changed.
+
+@var{new-topic} is the new topic.
@end defun
-@defun hooks/send/public mynick dest message
+@node Sent Message Hooks, DCC CHAT Hooks, Received Message Hooks, Hook Types
+@subsubsection Sent Message Hooks
+
+These hooks are called when the bot sends a message. @var{mynick} is
+always the bot's nick and will not be documented in each hook
+description.
+
+@defun hooks/send/public mynick channel message
+This hook is called when the bot sends a normal message to a channel.
+
+@var{channel} is the channel to which the bot sent the message.
+
+@var{message} is the message the bot sent.
@end defun
-@defun hooks/send/message botnick message
+@defun hooks/send/message mynick to message
+This hook is called when the bot sends a private message to a user.
+
+@var{to} is the nick of the user to whom the message was sent.
+
+@var{message} is the message that was sent.
@end defun
@defun hooks/send/action mynick to message
+This hook is called when the bot sents an action to a channel or a
+user.
+
+@var{to} is the channel or nick of the user to which the action was
+sent.
+
+@var{message} is the text of the action.
@end defun
@defun hooks/send/ctcp mynick to command message
+This hook is called when the bot sends a CTCP message @emph{other
+than} an ACTION to a channel or user.
+
+@var{to} is the channel or nick of the user to which the CTCP was
+sent.
+
+@var{command} is the CTCP command that was sent.
+
+@var{message} is a string containing the arguments to the CTCP command.
@end defun
+@node DCC CHAT Hooks, Miscellaneous Hooks, Sent Message Hooks, Hook Types
+@subsubsection 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.
+
@defun 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.
@var{from} is the user's address in the form @samp{nick!user@@host}.
@end defun
@defun hooks/dcc/chat-message from message
-This hook is triggered when a user sends a message to the bot through
-a DCC CHAT @var{from} is the user's address in the form
-@samp{nick!user@@host}. @var{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.
+
+@var{from} is the user's address in the form @samp{nick!user@@host}.
+
+@var{message} is the message the user sent to the bot.
+@end defun
+
+@node Miscellaneous Hooks, , DCC CHAT Hooks, Hook Types
+@subsubsection Miscellaneous Hooks
+
+@defun hooks/flood nick
+This hook is called when a user is detected flooding the bot.
+
+@var{nick} is the nickname of the user flooding the bot.
+@end defun
+
+@defun hooks/timer time
+This hook is called once a minute. The regex is @strong{not} used.
+
+@var{time} is the in zero-padded @code{hh:mm} format.
@end defun
@node Scheme User Levels, Sending Messages, Hooks, Scripting
HCoop / clinton / bobotpp.git / blobdiff