* 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::
@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
@menu
* bot.conf::
* bot.users::
+* bot.shit::
@end menu
@node bot.conf, bot.users, Configuration Files, Configuration Files
@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 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.
+
+The file contains lines with the format:
-@samp{@var{mask}:@var{channel}:@var{level}:@var{protection}:@var{auto-op}}
+@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 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
* User Levels::
* Protection::
* Automatic Op::
+* Shit Levels::
* Built-In Commands::
@end menu
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
+@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
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
@item @code{bot:aop/yes} Do automatically op the user
@end enumerate
-@node Built-In Commands, , Automatic Op, Using the Bot
+@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
@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)
``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
@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
@var{time} is the in zero-padded @code{hh:mm} format.
@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
+
+@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
HCoop / clinton / bobotpp.git / blobdiff