@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 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
@author Clinton Ebadi
@page
-@vskip Opt plus 1filll
-Copyright @copyright{} 2002 Clinton Ebadi
+@vskip 0pt plus 1filll
+Copyright @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
@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.0 of the program named
-Bobot++
+This document applies to version 2.2 of the program named
+Bobot++.
+
+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
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.
@end ifinfo
@menu
* Introduction::
* Configuration::
+* Using the Bot::
* Scripting::
* Concept Index::
* Function Index::
* Variable Index::
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Configuration
+
+* Configuration File Placement::
+* Configuration Files::
+
+Configuration Files
+
+* bot.conf::
+* bot.users::
+* bot.shit::
+
+bot.conf
+
+* server syntax::
+* channel syntax::
+
+Using Bobot++
+
+* Starting the Bot::
+* User Levels::
+* Protection::
+* Automatic Op::
+* Shit Levels::
+* Built-In Commands::
+
+Scripting
+
+* Adding New Commands::
+* Hooks::
+* Sending Messages::
+* Misc Scripting Stuff::
+
+Hooks
+
+* Creating a Hook::
+* Hook Types::
+
+Hook Types
+
+* Received Message Hooks::
+* Sent Message Hooks::
+* DCC CHAT Hooks::
+* Miscellaneous Hooks::
+
+Sending Messages
+
+* High Level Message Functions::
+* Low Level Message Functions::
+
+@end detailmenu
@end menu
@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.
-@node Configuration, Scripting, Introduction, Top
+FIXME: Fill the intro in more?
+
+@node Configuration, Using the Bot, Introduction, Top
@chapter Configuration
-Bobot++ is easy to configure. The configuration file format may be
-changing in the 2.1 series, so it is not documented for now. See the
-@file{examples} directory for an example configuration.
+Bobot++ is easy to configure. See the @file{examples} directory for an
+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 File Syntax::
-* Configure File Placement::
+* Configuration File Placement::
+* Configuration Files::
@end menu
-@node Configuration File Syntax, Configure File Placement, Configuration, Configuration
-@section Configuration File Syntax
-
-Not here yet.
-
-@node Configure File Placement, , Configuration File Syntax, 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 configration, put it in
-@file{~/.bobotpp/config/default/}.
+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
+
+@file{bot.conf} contains key value pairs separated by @code{=}.
+
+@code{<key> = <value>}
+
+Comments are started with a @code{#} and cause the entire line to be
+ignored. @emph{Note that this only works when the @code{#} is the first
+character of the line}.
+
+bot.conf is the main configuration file for a Bobot++. The available
+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
+@item @var{cmdchar} <!>: The character that prefixes commands given to
+the bot (@var{command} is an alias for @var{cmdchar})
+@item @var{ircname} <I'm a bobot++!>: The IRC name (or 'real name') of
+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
+(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 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.
+
+@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}
+
+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:
+
+@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}.
+
+@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.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}. 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.
+
+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{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
+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{level} is the user level of the user (@ref{User Levels}).
+
+@item @var{protection} is the protection level of the user
+(@ref{Protection}).
+
+@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 bot.shit, , bot.users, Configuration Files
+@subsection bot.shit (Ban/Shit List)
+
+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.
+
+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++
+
+FIXME: stuff here...
+
+@menu
+* Starting the Bot::
+* User Levels::
+* Protection::
+* Automatic Op::
+* Shit Levels::
+* Built-In Commands::
+@end menu
+
+@node Starting the Bot, User Levels, Using the Bot, Using the Bot
+@section Starting the Bot
+
+The bot is usually installed with the binary name @file{bobotpp}. It
+accepts the following command line arguments.
+
+@itemize
+@item @code{[--help][-h]} - Shows detailed help and exits
+@item @code{[--version][-v]} - Shows version information and exits
+@item @code{[--no-background][-b]} - Run bobot++ in the foreground
+@item @code{[--config-file file][-f]} - Use file instead of @file{bot.conf}
+@item @code{[--config-dir dir][-d]} - Use dir as dir to load config file from
+@item @code{[--config dir][-c]} - Search your config path (defaults to
+@file{@var{$HOME}/.bobotpp/config/} and then @file{/etc/bobotpp/}) for
+dir and then loads your config data using dir
+@item @code{[--sys-config dir][-s]} - Looks for config in
+@file{/etc/bobotpp/dir}. Note that the user dir is still searched
+first
+@item @code{[--user-config dir][-u]} - Looks for config in
+@file{@var{$HOME}/.bobotpp/config/dir/}. Note that the system dir is
+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
+@file{@var{$HOME}/.bobotpp/config/default/} and then
+@file{/etc/bobotpp/default/} if the user config is not found.
+
+The bot defaults to running in the background as a daemon.
+
+@node User Levels, Protection, Starting the Bot, Using the Bot
+@section User Levels
+
+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 the user is not found in the userlist) a user has access to
+commands with the level @code{bot:user-none}.
+
+@enumerate 0
-@node Scripting, Concept Index, Configuration, Top
+@item @code{bot:user-none} - No @strong{built-in} commands may be
+executed @emph{by default} (commands may be added from Scheme that can
+be executed by users of level none and the level required to execute a
+command may be changed from Scheme).
+
+@item @code{bot:user-user} - Will be able to execute most commands but
+not all and cannot use masks on kicks and bans.
+
+@item @code{bot:user-trusted} - For built-ins with a default
+configuration this user has access to the same set of commands as an
+@code{user} but may use masks on kicks and bans. Scheme commands may
+be added which require a user to be of this level.
+
+@item @code{bot:user-friend} - In the default configuration a user who
+is a friend will be able to do everything short of stopping the
+bot. Again, there may be user added commands that require a higher
+user level.
+
+@item @code{bot:user-master} - This is the highest user level and has
+access to every feature of the bot.
+
+@end enumerate
+
+@node Protection, Automatic Op, User Levels, Using the Bot
+@section Protection
+
+A user added via Scheme, the @file{bot.users} file, or
+@command{!adduser} may be protected from being deoped, kicked, or
+banned. The user list and IRC commands use the numeric codes, Scheme
+uses the symbolic names.
+
+@enumerate 0
+@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 @code{bot:protection/no-deop} No deop. The bot will ensure that the user always maintains
+operator status.
+@end enumerate
+
+@node Automatic Op, Shit Levels, Protection, Using the Bot
+@section Automatic Op
+
+A user may be automatically given operator status upon entering a
+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.
+
+@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
+scripting support. The reference leaves off the command char; remember
+to use whatever you defined the command char to be in
+@file{bot.conf}. If a command needs the channel name then you must
+specify the channel as the first argument to the command when private
+messaging the bot a command.
+
+@multitable @columnfractions 0.20 0.15 0.15 0.50
+@item @sc{command} @tab @sc{Needs Channel} @tab @sc{Min Level to Use} @tab @sc{Description}
+
+@item @command{action} @option{do} @tab Yes @tab @var{USER} @tab
+Causes the bot to perform the action @option{do} in the current
+channel.
+
+@item @command{adduser} @tab @tab @tab
+
+@item @command{addserver} @tab @tab @tab Adds the server specified by
+@var{host name} or @var{ip address} to the server list.
+
+@item @command{addshit} @tab @tab @tab
+
+@item @command{alias} @tab @tab @tab Makes an alias, and adds the
+function @var{new name}, that will do exactly the same command as
+@var{old name}.
+
+@item @command{ban} @tab @tab @tab Bans @var{mask} or @var{nick} from
+@var{channel}. You need to be a trusted user to ban with a
+@var{mask}.
+
+@item @command{banlist} @tab @tab @tab
+
+@item @command{channels} @tab @tab @tab Prints the channel(s) where
+the bot is currently.
+
+@item @command{cycle} @tab Yes @tab @tab Makes the bot leave and join
+@var{channel}.
+
+@item @command{dcclist} @tab @tab @tab Gives the list of all DCC Chat
+connections.
+
+@item @command{deban} @tab Yes @tab @tab Debans @var{mask} or
+@var{nick} from @var{channel}. You need to be a trusted user to deban
+with a @var{mask}.
+
+@item @command{delserver} @tab @tab @tab Deletes server from server
+list whose number in the server list is @var{server number}.
+
+@item @command{deluser} @tab @tab @tab Removes @var{nick} or
+@var{mask} from the userlist.
+
+@item @command{delshit} @tab @tab @tab Removes @var{nick} or
+@var{mask} from the shitlist.
+
+@item @command{deop} @tab Yes @tab @tab Deops @var{mask} or @var{nick}
+on @var{channel}.
+
+@item @command{die} @tab @tab @tab Makes the bot stop immediately.
+
+@item @command{do} @tab @tab @tab
+
+@item @command{execute} @tab @tab @tab @strong{Only available if
+scripting support is enabled}
+
+@item @command{help} @tab @tab @tab
+
+@item @command{ident} @tab @tab @tab Identifies you on the bot. Note
+that you should not use this command in public @dots{}
+
+@item @command{invite} @tab Yes @tab @tab Invites @var{nick} on
+@var{channel}.
+
+@item @command{join} @tab @tab @tab Makes the bot join @var{channel}.
+
+@item @command{keep} @tab Yes @tab @tab Sets the @var{modes} that the
+bot will keep for @var{channel}.
+
+@item @command{kick} @tab Yes @tab @tab Kicks @var{mask} or @var{nick}
+out of @var{channel}, because of @var{reason}. You need to be a
+trusted user to use a @var{mask}.
+
+@item @command{kickban} @tab Yes @tab @tab Bans then kicks @var{mask}
+or @var{nick} out of @var{channel}, because of @var{reason}. You need
+to be a trusted user to use a @var{mask}.
+
+@item @command{load} @tab @tab @tab Reloads the userlist from disk.
+
+@item @command{loadscript} @tab @tab @tab @strong{Only available if
+scripting support is enabled}
+
+@item @command{lock} @tab @tab @tab Locks topic on @var{channel}.
+
+@item @command{mode} @tab Yes @tab @tab Sends @var{mode string} as
+mode for @var{channel}.
+
+@item @command{msg} @tab @tab @tab
+
+@item @command{names} @tab Yes @tab @tab Shows the nicknames and
+status of users on @var{channel}.
+
+@item @command{nextserver} @tab @tab @tab Makes the bot connect to the
+next server in its server list.
+
+@item @command{nick} @tab @tab @tab Makes the bot use nickname @var{nick}.
+
+@item @command{nslookup} @tab @tab @tab Does a nameserver query about
+@var{nick} host, @var{host} or @var{ip address}.
+
+@item @command{op} @tab Yes @tab @tab Ops @var{nick} on @var{channel}.
+
+@item @command{part} @tab Yes @tab @tab Makes the bot leave @var{channel}.
+
+@item @command{password} @tab @tab @tab Changes your password on the
+bot. Use @code{NONE} as password if you want to clear it. Do not use this
+command in public!
+
+@item @command{reconnect} @tab @tab @tab Makes the bot reconnect to
+its current server.
+
+@item @command{rspymessage} @tab @tab @tab Removes you from the spy
+list.
+
+@item @command{save} @tab @tab @tab Saves the userlist.
+
+@item @command{say} @tab Yes @tab @tab Makes the bot say @var{message}
+on @var{channel}.
+
+@item @command{server} @tab @tab @tab Select the server to connect
+to. @var{server number} is the number of the server in the serverlist.
+
+@item @command{serverlist} @tab @tab @tab Shows the bot's serverlist.
+
+@item @command{setfloodrate} @tab @tab @tab
+
+@item @command{setversion} @tab @tab @tab
+
+@item @command{shitlist} @tab @tab @tab Shows the bot's shitlist.
+
+@item @command{spylist} @tab @tab @tab Shows the bot's spylist.
+
+@item @command{spymessage} @tab @tab @tab Adds you to the spylist
+
+@item @command{stats} @tab Yes @tab @tab Gives @var{channel}'s statistics.
+
+@item @command{tban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
+from @var{channel} for @var{time} seconds.
+
+@item @command{tkban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
+from @var{channel} for @var{time} seconds, then kicks him/them because
+of @var{reason}.
+
+@item @command{topic} @tab Yes @tab @tab If no @var{topic}is given,
+prints @var{channel}'s topic. Otherwise, the bot will change
+@var{channel}'s topic to @var{topic}.
+
+@item @command{unlock} @tab Yes @tab @tab Makes the bot unlock topic
+on @var{channel}
+
+@item @command{userlist} @tab @tab @tab Shows the bot's userlist
+
+@item @command{who} @tab Yes @tab @tab Show your level on @var{channel}
+
+@item @command{whois} @tab Yes @tab @tab Shows information about
+@var{nick} on @var{channel}
+
+@end multitable
+
+@node Scripting, Concept Index, Using the Bot, Top
@chapter Scripting
Bobot++'s most powerful feature is its scripting system. You write
@url{http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html} for
a good tutorial on Scheme.
+Note that in previous versions the scripting commands where in the
+form @code{bot-@var{function}}. They are now in the form
+@code{bot:@var{function}}. The old names are still available, but are
+deprecated and will be removed in Bobot++ 3.0. New commands are only
+available with the @code{bot:} prefix. The command @command{perl -pi
+-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::
+* Sending Messages::
+* Misc Scripting Stuff::
+@end menu
+
+@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}.
+
+@defun bot:addcommand name func needs-channel? num-of-args min-level
+
+The @var{name} is a string representing the name of the command being
+added. @var{func} is a function accepting @var{num-of-args}
+arguments. @var{needs-channel?} is a bool that is true if the function
+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{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)
+ (if (string=? name "")
+ (bot:say channel "Hello world!")
+ (bot:say channel (string-append "Hello " name "!")))
+
+(bot:addcommand "hello" hello #t 2 0)
+@end example
+
+This will display ``Hello World!'' if called as @kbd{!hello} and
+``Hello World @var{USER}'' if called as @kbd{!hello @var{USER}}.
+@end defun
+
+@node Hooks, Sending Messages, Adding New Commands, Scripting
+@section Hooks
+
+@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. 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::
+* Hook Types::
+@end menu
+
+@node Creating a Hook, Hook Types, Hooks, Hooks
+@subsection Creating a Hook
+
+To add a new hook you use the function @code{bot:addhook}.
+
+@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 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
+
+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.
+
+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 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 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 is called when someone changes his nickname from
+@var{old-nick} to @var{new-nick}.
+@end defun
+
+@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
+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.
+
+@var{rest} contains the body of the reply.
+@end defun
+
+@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/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 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 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 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 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
+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.
+
+@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
+
+@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 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 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 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. 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::
+* Low Level Message Functions::
+@end menu
+
+@node High Level Message Functions, Low Level Message Functions, Sending Messages, Sending Messages
+@subsection ``High Level'' Message Functions
+
+@defun bot:say channel message
+Send a public or private @var{message} to @var{channel}.
+
+Sends a normal text message, as if a user had typed it in. The
+@var{dest} can be a nickname or a channel.
+@end defun
+
+@defun bot:action channel message
+Send an ``action'' type @var{message} to @var{channel}
+@end defun
+
+
+@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.
+@end defun
+
+@node Low Level Message Functions, , High Level Message Functions, Sending Messages
+@subsection ``Low Level'' Message Functions
+
+@c Add a url for rfc2812
+The ``Low Level'' messaging functions allow you to do things like send
+CTCP messages. You probably want to read rfc 2812 and the CTCP spec
+before using these. If you have no idea what these do, read rfc 2812
+(IRC Client Protocol) and CTCP spec. These functions all return
+@code{*unspecified*} always, so don't use the return value for
+anything.
+
+@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
+
+These are a few useful things that I thought people writing scripts
+might want to know.
+
+@vindex exit-hook
+If you want to execute code when the bot exits, just do
+@code{add-hook! bot:exit-hook @var{thunk}} where @var{thunk} is an
+argumentless procedure (a thunk). When the bot exits your thunk will
+be called.
+
+@quotation
+[ 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
+users (kicking, added, etc), dealing with the bot (channels, nickname
+of the bot, etc), server issues (serverlist), useful tools (nslookup,
+whois), and do on. ]
+@end quotation
+
+
+@defun bot:adduser nick-or-mask cbannel-mask level prot auto-op
+Adds an user to the userlist, for a @code{nick!user@@host} matching the
+one given, on a channel matching the @var{channelMask} given.
+
+@multitable @columnfractions 0.33 0.33 0.33
+@item The @var{level} can be: @tab The @var{prot} can be: @tab The @var{auto-op} can be:
+@item 0 - No level @tab 0 - No protection @tab 0 - No auto-op
+@item 1 - User @tab 1 - No ban @tab 1 - Op on join
+@item 2 - Trusted User @tab 2 - No kick @tab
+@item 3 - Friend @tab 3 - No deop @tab
+@item 4 - Master @tab @tab
+@end multitable
+
+@end defun
+
+@c (3, 4, 0)
+@defun bot:addserver hostname ip-address [portnumber]
+Adds the server specified by @var{hostname} or @var{ip-address} to
+the server list.
+@end defun
+
+@c (3, 2, 0)
+@defun bot:addshit nick-or-mask channel-mask level [time reason]
+Adds an user to the shitlist, for a nick!user@@host matching the
+one given, on a channel matching the @var{channelMask} given.
+
+@display
+The @var{level} can be:
+ 0 - No shit
+ 1 - No op
+ 2 - Kick and Ban on join
+ 3 - Kick and Ban on join, no deban
+@end display
+
+@end defun
+
+@c (2, 0, 0)
+@defun bot:ban channel mask-or-nick
+Bans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
+user to ban with a @var{mask}.
+@end defun
+
+@c (2, 0, 0)
+@defun bot:change-command-level nick-or-mask channel-mask new-level
+Gives @var{nick} or @var{mask} level @var{new-level} on channel(s)
+@var{channel-mask}. Note that you can not change level for someone
+whose level is greater than yours, and that you can not give a
+level greater than yours.
+@end defun
+
+@c (1, 0, 0)
+@defun bot:cycle channel
+Makes the bot leave and join @var{channel}.
+@end defun
+
+@c (2, 0, 0)
+@defun bot:deban channel mask-or-nick
+Debans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
+user to deban with a @var{mask}.
+@end defun
+
+@c (1, 0, 0)
+@defun bot:delserver server-number
+Deletes server from server list whose number in the server list
+is @var{server-number}
+@end defun
+
+@c (2, 0, 0)
+@defun bot:deluser nick-or-mask channel-mask
+Removes @var{nick} or @var{mask} from the userlist.
+@end defun
+
+@c (2, 0, 0)
+@defun bot:delshit nick-or-mask channel-mask
+Removes @var{nick} or @var{mask} from the shitlist.
+@end defun
+
+@c (2, 0, 0)
+@defun bot:deop channel mask-or-nick
+Deops @var{mask} or @var{nick} on @var{channel}.
+@end defun
+
+@c (1, 0, 0)
+@defun bot:die reason
+Makes the bot stop immediately.
+@end defun
+
+@c (1, 0, 0)
+@defun bot:do ?
+@end defun
+
+@c (2, 0, 0)
+@defun bot:invite channel nick
+Invites @var{nick} on @var{channel}.
+@end defun
+
+@c (1, 1, 0)
+@defun bot:join channel
+Makes the bot join @var{channel}.
+@end defun
+
+@c (2, 0, 0)
+@defun bot:keep channel modes
+Sets the @var{modes} that the bot will keep for @var{channel}.
+See also STATS.
+@end defun
+
+@c (2, 1, 0)
+@defun bot:kick channel mask-or-nick [reason]
+Kicks @var{mask} or @var{nick} out of @var{channel}, because of @var{reason}.
+You need to be a trusted user to use a @var{mask}.
+@end defun
+
+@c (2, 1, 0)
+@defun bot:kickban channel mask-or-nick [reason]
+Bans then kicks @var{mask} or @var{nick} out of @var{channel},
+because of @var{reason}.
+You need to be a trusted user to use a @var{mask}.
+@end defun
+
+@c (1, 0, 0)
+@defun bot:lock channel
+Locks topic on @var{channel}.
+@end defun
+
+@c (0, 0, 0)
+@defun bot:logport
+[ Probably returns the log port? ]
+@end defun
+
+@c (2, 0, 0)
+@defun bot:mode channel mode-string
+Sends @var{mode-string} as mode for @var{channel}.
+@end defun
+
+@c (0, 0, 0)
+@defun bot:nextserver
+Makes the bot connect to the next server in its server list.
+@end defun
+
+@c (1, 0, 0)
+@defun bot:nick nick
+Makes the bot use nickname @var{nick}.
+@end defun
+
+@c (2, 0, 0)
+@defun bot:op channel nick
+Ops @var{nick} on @var{channel}.
+@end defun
+
+@c (1, 0, 0)
+@defun bot:part channel
+Makes the bot leave @var{channel}.
+@end defun
+
+@c (0, 0, 0)
+@defun bot:reconnect
+Makes the bot reconnect to its current server.
+@end defun
+
+@c (1, 0, 0)
+@defun bot:server server-number
+Select the server to connect to. @var{server-number} is the number of
+the server in the serverlist.
+@end defun
+
+@c (1, 0, 0)
+@defun bot:setfloodrate ?
+@end defun
+
+@c (1, 0, 0)
+@defun bot:setversion ?
+@end defun
+
+@c (3, 0, 0)
+@defun bot:tban channel nick-or-mask time
+Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds.
+@end defun
+
+@c (3, 1, 0)
+@defun bot:tkban channel nick-or-mask time [reason]
+Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds,
+then kicks him/them because of @var{reason}.
+@end defun
+
+@c (2, 0, 0)
+@defun bot:topic channel topic
+If no @var{topic} is given, prints @var{channel}'s topic. Otherwise,
+the bot will change @var{channel}'s topic to @var{topic}.
+@end defun
+
+@defun bot:unlock channel
+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? ]
+@end defun
+
+@c (0, 0, 0)
+@defun bot:getserver
+@end defun
+
+@c (0, 0, 0)
+@defun bot:getserverlist
+@end defun
+
+@c (0, 0, 0)
+@defun bot:flush
+[ Flushes the socket to the server? ]
+@end defun
+
+@c (0, 0, 0)
+@defun bot:flushport
+[ Flushes the log port? ]
+@end defun
+
+@c (1, 0, 0)
+@defun bot:random ?
+[ Returns a random number? What range? Why? ]
+@end defun
+
+@c (1, 0, 0)
+@defun bot:delcommand
+[ Probably deletes a command added with @code{bot:addcommand} ? ]
+@end defun
+
+@c (2, 0, 0)
+@defun bot:addtimer ? ?
+@end defun
+
+@c (1, 0, 0)
+@defun bot:deltimer ?
+@end defun
+
+@c (2, 0, 0)
+@defun bot:dcc-chat-send ? ?
+@end defun
+
+@quotation
+[ And what about the stuff defined in @file{bobot-utils.scm} ? I just
+added it here so it could be somewhere. There should also be a
+section dealing with modules. How to use them. What module scripts
+are in. What module bobot++ provided primites are in. And so on. ]
+@end quotation
+
+@defun bot:log . messages
+Write as many @var{messages} as you want to the log. If the arg is a
+thunk it will be executed and it's output will be written to the log.
+@end defun
+
+@defun bot:load file
+@end defun
+
+@defun bot:load-module module-spec
+@end defun
+
+@defun bot:use-module module-spec
+@end defun
+
+@defun bot:match-not-channel regex
+match-not-channel adds a prefix regex to your @var{regex} so it
+doesn't match the sender or channel in a PUBLIC message
+@end defun
+
+@defun bot:match-to-me regex
+match-to-me matches text that was addressed to the bot with a
+':', ',', or nothing after the bot name.
+@end defun
+
+@defun bot:sent-to-me? message
+@end defun
+
+@defun bot:ctcp-quote message
+Returns the CTCP quoted message
+Input @emph{MUST NOT} contain the trailing @code{\r\n}
+(it is added by the message sending code).
+@end defun
+
+
+@defvar %bot:loadpath
+@end defvar
+
+@defun %bot:load-extensions
+@end defun
+
+
+
@node Concept Index, Function Index, Scripting, Top
@unnumbered Concept Index
@printindex cp
@node Variable Index, , Function Index, Top
@unnumbered Variable Index
@printindex vr
+
+@bye
HCoop / clinton / bobotpp.git / blobdiff