@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
* bot.conf::
* bot.users::
+* bot.shit::
bot.conf
* User Levels::
* Protection::
* Automatic Op::
+* Shit Levels::
* Built-In Commands::
Scripting
* Adding New Commands::
* Hooks::
-* Scheme User Levels::
* Sending Messages::
* Misc Scripting Stuff::
* Creating a Hook::
* Hook Types::
+Hook Types
+
+* Received Message Hooks::
+* Sent Message Hooks::
+* DCC CHAT Hooks::
+* Miscellaneous Hooks::
+
Sending Messages
* High Level Message Functions::
@node Introduction, Configuration, Top, Top
@chapter Introduction
-This manual feels abused and neglected because it has almost no
-content.
+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?
@node Configuration, Using the Bot, Introduction, Top
@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
* bot.conf::
* bot.users::
+* bot.shit::
@end 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{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.
@item @var{nickname} <Bobot>: The nickname of the bot (@var{nick} is an
alias for @var{nickname})
@item @var{username} <bobot>: The IRC username of the bot
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.
-@node bot.users, , bot.conf, Configuration Files
-@subsection bot.users
+@node bot.users, bot.shit, bot.conf, Configuration Files
+@subsection bot.users (User List)
@file{bot.users} is the default file name of the userlist. It may be
-changed in @file{bot.conf}. The file contains lines with the format:
+changed in @file{bot.conf}. 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.
-@samp{@var{mask}:@var{channel}:@var{level}:@var{protection}:@var{auto-op}}
+The file contains lines with the format:
+
+@samp{@var{host_mask}:@var{channel_mask}:@var{level}:@var{protection}:@var{auto-op}:@var{expiration}:@var{password}}
@itemize
-@item @var{mask} is the host mask
+@item @var{host_mask} is the host mask
(e.g. @samp{*!*username@*.domain.com}) of the user
-@item @var{channel} is a channel mask of the channels that the user
+@item @var{channel_mask} is a channel mask of the channels that the user
has priviliges to use the bot in (e.g. @samp{*} for all channels,
@samp{#*} for all non-local channel, @samp{#foo*} for all channels
starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.)
@item @var{auto-op} is set to control whether a user is automatically
given operator priviliges on channel entry (@ref{Automatic Op}).
+@item @var{expiration} is the UNIX timestamp of when the user entry
+becomes invalid. Setting this to -1 will make the entry permanent.
+
+@item @var{password} is the password the user must supply to the bot
+to authenticate. This can be set to @code{*NONE*} to not have a password.
+
@end itemize
-@node Configuration File Placement, , Configuration Files, Configuration
-@section Configuration File Placement
+@node bot.shit, , bot.users, Configuration Files
+@subsection bot.shit (Ban/Shit List)
-@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
+This file stores the ban list. The name may be changed in
+@file{bot.conf}. You will most likely want to use the IRC command
+interface to edit this file instead of editing it directly.
-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/}.
+The file contains lines in the form:
+
+@samp{@var{host_mask}:@var{channel_mask}:@var{level}:@var{expiration}:@var{reason}}
+
+@itemize
+
+@item @var{host_mask} is the host mask
+(e.g. @samp{*!*username@*.domain.com}) of the user
+
+@item @var{channel_mask} is a channel mask of the channels that the user
+is banned on (e.g. @samp{*} for all channels,
+@samp{#*} for all non-local channel, @samp{#foo*} for all channels
+starting with ``foo,'' @samp{#bar} for channel ``#bar'' only, etc.
+
+@item @var{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. @ref{Shit Levels} for
+information on the available levels.
+
+@item @var{expiration} is the UNIX timestamp of when the shit entry
+becomes invalid. This may be set to -1 to make it valid forever.
+
+@item @var{reason} is text that is sent to the user when they are
+kicked or banned from the channel.
+
+@end itemize
@node Using the Bot, Scripting, Configuration, Top
@chapter Using Bobot++
* User Levels::
* Protection::
* Automatic Op::
+* Shit Levels::
* Built-In Commands::
@end menu
@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]} Enables 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
-@node Automatic Op, Built-In Commands, Protection, Using the Bot
+@node Automatic Op, Shit Levels, Protection, Using the Bot
@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 Shit Levels, Built-In Commands, Automatic Op, Using the Bot
+@section 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.
-@node Built-In Commands, , Automatic Op, Using the Bot
+@enumerate 0
+@item @code{bot:shit/none} The bot doesn't hate the user (this is the
+normal level)
+@item @code{bot:shit/no-op} The bot will deop the user any time he
+gains operator priviliges in the channel
+@item @code{bot:shit/no-join} The bot will kick and ban the user when he
+joins the channel
+@item @code{bot:shit/no-deban} The bot will kick and ban usre when he
+joins the channel, and will prevent other users from debanning him.
+@end enumerate
+
+@node Built-In Commands, , Shit Levels, Using the Bot
@section Built-In Commands
Bobot++ has many built-in commands that make it useful without
-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::
-* Scheme User Levels::
* Sending Messages::
* Misc Scripting Stuff::
@end menu
needs the channel name as its first arg, and false otherwise.
@var{num-of-args} is the number of args @var{func} will take and must
be within zero (0) and twenty (20). @var{min-level} is one of the
-@ref{Scheme User Levels}. A user must be at least a @code{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 @code{""}.
-An example of a new command would be:
+@ref{User Levels}. A user must be at least a @var{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 @code{""}. An
+example of a new command would be:
@example
(define (hello channel name)
@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
+@node Hooks, Sending Messages, Adding New Commands, Scripting
@section Hooks
@cindex Background on Hooks
@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
-function to be defined, but these describe the function to be passwd
+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 @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
-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
+
+@defun hooks/send/who who
+This is called when the bot sends a WHO message. The regex is matched
+on @var{who}, which is also passed as the only argument to your
+function.
+
+@var{who} is the channel or nick that was WHOed.
+@end defun
+
+@defun hooks/send/whois nick
+This is called when the bot sends a WHOIS message. The regex is
+matched on @var{nick}, which is also passed as the only argument to
+your function.
+
+@var{nick} is the nickname of the person who was WHOISed.
@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.
-@end defun
-
-@node Scheme User Levels, Sending Messages, Hooks, Scripting
-@section Scheme User Levels
-
-@vindex user-none
-@vindex user-user
-@vindex user-trusted
-@vindex user-friend
-@vindex user-master
-There are five levels that a user may be when interfacing with a bot:
-@var{none}, @var{user}, @var{trusted_user}, @var{friend},
-@var{master}. The Scheme variables for the user levels are
-@code{bot:user-none}, @code{bot:user-user}, @code{bot:user-trusted},
-@code{bot:user-friend}, and @code{bot:user-master}. See @ref{User
-Levels} for more information on User Levels.
-
-When adding a new command, think about who should be able to use
-it. Is your command a general purpose command that helps the channel
-(e.g. @code{!seen}) that everyone should be able to use? Or is it
-something that should be restricted? See @ref{User Levels} for
-information on what level users can do what with the built in bot
-commands and think about what level a user your command is targetted
-towards. You must be @emph{very} careful when giving new commands to
-lower level users because you can do basically everything the bot can
-do with a script. As the scripting interface becomes more powerful,
-you must think more about what users can use new commands you add.
-
-@node Sending Messages, Misc Scripting Stuff, Scheme User Levels, Scripting
+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 Sending Messages, Misc Scripting Stuff, Hooks, Scripting
@section Sending Messages
There are several types of messages you can send with Bobot++ from
-scripts. There is the simple, but rather limited, @code{bot:say},
-@code{bot:action} and @code{bot:msg}, and the more powerful, but lower
-level, @code{bot:send-MESSAGE} functions. Most bots will probably only
-need the higher level functions, but for the sake of why-not Bobot++
-lets you use the lower level functions (in progress).
+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.
@menu
* High Level Message Functions::
Send an ``action'' type @var{message} to @var{channel}
@end defun
-@defun bot:msg nick message
-The same as if a user typed @code{/msg nick message} to their IRC client.
+
+@defun bot:msg target message
+@defunx bot:say target message
+Send a public or private message to @var{target}.
+
+@var{target} may be a channel or a nickname.
+
+In versions of Bobot++ prior to 2.1.8 @code{bot:say} could only send
+to channels, and @code{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.
@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.
+user (nick) or a channel.
@end defun
@node Low Level Message Functions, , High Level Message Functions, Sending Messages
@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: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: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
Makes the bot unlock topic on @var{channel}.
@end defun
+@defun bot:who target
+Sends a WHO command to @var{target}. @var{target} may be either a
+channel or a user.
+@end defun
+
+@defun bot:whois nick
+Sends a WHOIS command to @var{nick}. @var{nick} @strong{must} be a
+nickname, you cannot send a WHOIS to a channel.
+@end defun
+
@c (0, 0, 0)
@defun bot:getnickname
[ Gets the bot's nickname? ]
HCoop / clinton / bobotpp.git / blobdiff