@ifinfo
This file documents Bobot++ by Clinton Ebadi and Etienne Bernard
-(original author, no longer works on program).
+(The original author who no longer works on the program).
Copyright 2002,2004,2005 Clinton Ebadi
@author Clinton Ebadi
@page
-@vskip Opt plus 1filll
+@vskip 0pt plus 1filll
Copyright @copyright{} 2002,2004,2005 Clinton Ebadi
Permission is granted to copy, distribute and/or modify this document
@ifinfo
This document describes Bobot++ by Clinton Ebadi and Etienne Bernard
-(original author, no longer works on program).
+(The original author who no longer works on the 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::
@chapter Configuration
Bobot++ is easy to configure. See the @file{examples} directory for an
-example configuration.
+example configuration.
+
+The main configuration file is @file{bot.conf}. There are several
+auxiliary configuration files (a user list, aliases file, ban list,
+and a script autoexec).
@menu
-* Configuration Files::
* Configuration File Placement::
+* Configuration Files::
@end menu
-@node Configuration Files, Configuration File Placement, Configuration, Configuration
+@node Configuration File Placement, Configuration Files, Configuration, Configuration
+@section Configuration File Placement
+
+Bobot++ will look in @file{/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 @file{~/.bobotpp/config/default/}.
+
+@node Configuration Files, , Configuration File Placement, Configuration
@section Configuration Files
@menu
@node bot.conf, bot.users, Configuration Files, Configuration Files
@subsection bot.conf
-@menu
-* server syntax::
-* channel syntax::
-@end menu
-
@file{bot.conf} contains key value pairs separated by @code{=}.
@code{<key> = <value>}
configuration variables are listed below in the format ``@var{variable}
<default-value>: description''
+A few of the options have more complex syntax, they are documented in
+their own subsections.
+
+@menu
+* server syntax::
+* channel syntax::
+@end menu
+
@itemize @bullet
@item @var{nickname} <Bobot>: The nickname of the bot (@var{nick} is an
the bot (@var{realname} is an alias for @var{ircname})
@item @var{userlist} <bot.users>: Name of the file where the userlist is
stored
-@item @var{shitlist} <bot.shit>: Name of the file where the shitlist is
-stored
+@item @var{shitlist} <bot.shit>: Name of the file where the shitlist
+(ban list) is stored
@item @var{logfile} <$LOGDIR/bot.log>: Location of the bot logfile
(set this to @file{/dev/null} to disable logging).
-@item @var{server} <None>: This specifies the server to connect
-to. Note that this has a special syntax.
-@item @var{channel} <None>: This specifies a channel the bot will join
-when it starts up. This also has a special syntax.
+@item @var{server} <None>: This specifies the server to which the bot
+will connect. Note that this has a special syntax @pxref{server
+syntax}.
+@item @var{channel} <None>: This specifies the channels the bot will join
+when it starts up. This has a special syntax @pxref{channel
+syntax}.
@end itemize
@node server syntax, channel syntax, bot.conf, bot.conf
@subsubsection server syntax
+The server syntax in @file{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 (@code{!cycle}) to make
+the bot to cycle servers.
+
@var{server} = @var{server_name} [@var{port} [@var{password}]]
This will make Bobot++ attempt to connect to @var{server_name} on port
@var{port} with the password @var{password}. @var{server_name} should
be the address of the server. @var{port} and @var{password} are
-optional. You may use more than one server line; Bobot++ will attempt
-to connect to the first one and, if it fails, will connect to the next
-one in the list. There is also a command to cause the bot to cycle
-servers. At the present time Bobot++ cannot connect to more than one
-server at a time. This is a planned feature of 3.0 (which is a very
-long way away; the current structure of the program would make it very
-difficult to add support for connecting to multiple servers at a time
-in a usable manner).
+optional.
@node channel syntax, , server syntax, bot.conf
@subsubsection channel syntax
+The channel syntax in @file{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.
+
@var{channel} =
@var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key}
-You may have any number of channel lines. When Bobot++ starts it will
-attempt to join and gain ops in every channel listed. It will join
-@var{name} and set the channel modes to @var{initial_modes}
-(e.g. ``nt'') if it is able to gain operator status. It will then
-maintain @var{modes_to_keep}. If the channel requires a key to enter
-simply set @var{channel_key}. Every argument except for @var{name} is
-optional.
+The bot will join @var{name} and set the channel modes to
+@var{initial_modes} (e.g. ``nt'') if it is able to gain operator
+status. It will then maintain @var{modes_to_keep}. If the channel
+requires a key to enter simply set @var{channel_key}. Every argument
+except for @var{name} is optional.
A few example lines:
-@code{@var{channel} = #foo:nt:nt:bar}
+@example
+@var{channel} = #foo:nt:nt:bar
+@end example
The bot will join @code{#foo} with the channel key @code{bar} and will
then maintain the modes @code{nt}.
-@code{@var{channel} = #bar:::}
+@example
+@var{channel} = #bar:::
+@end example
The bot will join @code{#bar} and will not set any modes nor will it
attempt to maintain any modes.
@end itemize
-@node Configuration File Placement, , Configuration Files, Configuration
-@section Configuration File Placement
-
-@quotation
-[ 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 @emph{where} to edit all this wonderful stuff. ]
-@end quotation
-
-Bobot++ will look in @file{/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 @file{~/.bobotpp/config/default/}.
-
@node Using the Bot, Scripting, Configuration, Top
@chapter Using Bobot++
@section Starting the Bot
The bot is usually installed with the binary name @file{bobotpp}. It
-accepts the following command line arguments:
+accepts the following command line arguments.
@itemize
@item @code{[--help][-h]} - Shows detailed help and exits
still searched after this if dir is not found.
@item @code{[--debug][-D]} Makes Bobot++ print debugging info and run
in the foreground
+@item @code{[--debug-scripts][-S]} Enabled the Guile debugging
+evaluator for verbose script errors and backtraces while still running
+the bot in the background.
@end itemize
The default configuration is read from
There are several user levels available in Bobot++ to provide gradated
access to commands. @command{!adduser} and @file{bot.users} use the
numeric code; Scheme uses the textual name for the level. By default
-(if no catch-all setting is found in @xref{bot.users}.) a user is not
-even a @code{bot:user-none} and cannot execute @strong{any} commands,
-even commands available to @code{bot:user-none}.
+(if the user is not found in the userlist) a user has access to
+commands with the level @code{bot:user-none}.
@enumerate 0
A user added via Scheme, the @file{bot.users} file, or
@command{!adduser} may be protected from being deoped, kicked, or
-banned. There are currently no symbolic levels in Scheme; just use the
-numeric code.
+banned. The user list and IRC commands use the numeric codes, Scheme
+uses the symbolic names.
@enumerate 0
-@item No protection
-@item No ban. If a user is banned the bot will unban him..
-@item No kick. The user may still be kicked but the bot will kickban
+@item @code{bot:protection/none} No protection
+@item @code{bot:protection/no-ban} No ban. If a user is banned the bot will unban him..
+@item @code{bot:protection/no-kick} No kick. The user may still be kicked but the bot will kickban
the user who kicked the protected user.
-@item No deop. The bot will ensure that the user always maintains
+@item @code{bot:protection/no-deop} No deop. The bot will ensure that the user always maintains
operator status.
@end enumerate
@section Automatic Op
A user may be automatically given operator status upon entering a
-channel. Set the @var{aop} field to ``0'' to disable auto-op or ``1''
-to enable auto-op.
+channel. Scheme uses the symbolic name, the user list
+(@file{bot.users}) and IRC commands use the numeric value.
+
+@enumerate 0
+@item @code{bot:aop/no} Do not automatically op the user
+@item @code{bot:aop/yes} Do automatically op the user
+@end enumerate
@node Built-In Commands, , Automatic Op, Using the Bot
@section Built-In Commands
-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::
@node Adding New Commands, Hooks, Scripting, Scripting
@section Adding New Commands
-Adding a new command is simple. To register a new command use @code{bot:addcommand}.
+Adding a new command is simple. To register a new command use
+@code{bot:addcommand}.
@defun bot:addcommand name func needs-channel? num-of-args min-level
@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
@cindex Background on 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. The basic idea of a hook if that you match a text against
-regular expression and call a function if text in a message matches
-that regex. The different types of hooks provided by Bobot++
-correspond to the different classes of messages that Bobot++ can
-recieve. A Hook also has several properties, including its priority
-and whether or not it is a fallthrough hook. Higher priority hooks are
-executed before lower priority hooks and fallthrough hooks are
-executed before non-fallthrough hooks of the same priority. A
-fallthrough hook can match and processing of hooks will continue; as
-soon as the first non-fallthrough hooks matches processing of hooks
-stops.
+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.
@menu
* Creating a Hook::
@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 was was
+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.
-@quotation
-[ 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.
+That said, here is the list of available hooks functions.
+FIXME: write docs
-Still clumsy. Oh well. ]
-@end quotation
+@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
-That said, here is the list of available hooks functions.
-FIXME: write docs
+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
+@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-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.
+
+@var{address} is the address (nick!user@@host) of the person on the
+other side of the DCC.
+@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
The same as if a user typed @code{/msg nick message} to their IRC client.
@end defun
+@defun bot:notice target message
+Sends @var{message} as a NOTICE to @var{target}. @var{target} may be a
+user (nick) or a channel. This returns 0 on success.
+@end defun
+
@node Low Level Message Functions, , High Level Message Functions, Sending Messages
@subsection ``Low Level'' Message Functions
@code{*unspecified*} always, so don't use the return value for
anything.
-@defun bot:send-CTCP to command message
-@code{to} is the target of your CTCP message, @code{command} is the
-CTCP command, and @code{message} is the message (or arguments) of the
+@defun bot:send-ctcp to command message
+@var{to} is the target of your CTCP message, @var{command} is the
+CTCP command, and @var{message} is the message (or arguments) of the
command. Make sure to @code{bot:ctcp-quote} the message!
@end defun
+@defun bot:send-ctcp-reply to command message
+@var{to} is the target of your CTCP reply, @var{command} is the
+CTCP command, and @var{message} is the message (or arguments) of the
+command. Make sure to @code{bot:ctcp-quote} the message!
+
+This is used to reply to a ctcp that the bot has received.
+@end defun
+
@node Misc Scripting Stuff, , Sending Messages, Scripting
@section Misc. Scripting Stuff
be called.
@quotation
-[ 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 with
HCoop / clinton / bobotpp.git / blobdiff