-\input texinfo @c -*- texinfo -*-
+input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename bobot++.info
@settitle Bobot++: A Schemeable IRC Bot
This file documents Bobot++ by Clinton Ebadi and Etienne Bernard
(original author, no longer works on 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
-@c @vskip O plus 1filll
-Copyright @copyright{} 2002 Clinton Ebadi
+@vskip O 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
This document describes Bobot++ by Clinton Ebadi and Etienne Bernard
(original author, no longer works on program).
-This document applies to version 2.1.0 of the program named
+This document applies to version 2.1.5 of the program named
Bobot++
-Copyright 2002 Clinton Ebadi
+Copyright 2002,2004 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
* Concept Index::
* Function Index::
* Variable Index::
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Configuration
+
+* Configuration Files::
+* Configuration File Placement::
+
+Configuration Files
+
+* bot.conf::
+* bot.users::
+
+bot.conf
+
+* server syntax::
+* channel syntax::
+
+Using Bobot++
+
+* Starting the Bot::
+* User Levels::
+* Protection::
+* Automatic Op::
+* Built-In Commands::
+
+Scripting
+
+* Adding New Commands::
+* Hooks::
+* Scheme User Levels::
+* Sending Messages::
+* Misc Scripting Stuff::
+
+Hooks
+
+* Creating a Hook::
+* Hook Types::
+
+Sending Messages
+
+* High Level Message Functions::
+* Low Level Message Functions::
+
+@end detailmenu
@end menu
@node Introduction, Configuration, Top, Top
@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.
+
+@menu
+* Configuration Files::
+* Configuration File Placement::
+@end menu
+
+@node Configuration Files, Configuration File Placement, Configuration, Configuration
+@section Configuration Files
@menu
-* Configuration File Syntax::
-* Configure File Placement::
+* bot.conf::
+* bot.users::
@end menu
-@node Configuration File Syntax, Configure File Placement, Configuration, Configuration
-@section Configuration File Syntax
+@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>}
+
+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''
+
+@itemize @bullet
+
+@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 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.
+
+@end itemize
+
+@node server syntax, channel syntax, bot.conf, bot.conf
+@subsubsection server syntax
+
+@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).
+
+@node channel syntax, , server syntax, bot.conf
+@subsubsection channel syntax
+
+@var{channel} =
+@var{name}:@var{initial_modes}:@var{modes_to_keep}:@var{channel_key}
-Not here yet.
+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.
-@node Configure File Placement, , Configuration File Syntax, Configuration
+A few example lines:
+
+@code{@var{channel} = #foo:nt:nt:bar}
+
+The bot will join @code{#foo} with the channel key @code{bar} and will
+then maintain the modes @code{nt}.
+
+@code{@var{channel} = #bar:::}
+
+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
+
+@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:
+
+@samp{@var{mask}:@var{channel}:@var{level}:@var{protection}:@var{auto-op}}
+
+@itemize
+
+@item @var{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
+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}).
+
+@end itemize
+
+@node Configuration File Placement, , Configuration Files, 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 Using the Bot, Scripting, Configuration, Top
@chapter Using Bobot++
FIXME: stuff here...
@menu
+* Starting the Bot::
* User Levels::
+* Protection::
+* Automatic Op::
+* Built-In Commands::
@end menu
-@node User Levels, , Using the Bot, Using the Bot
+@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
+
+@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 five levels that a user may be when interfacing with a bot:
-@var{none}, @var{user}, @var{trusted_user}, @var{friend},
-@var{master}. All users default to @var{none} unless they are changed
-by a script, the @code{!adduser} command or the @file{bot.users}
-file. @var{none} is for everyone---very few commands (e.g. help) are
-available to the users and almost everyone should be this
-level. A @var{user} can execute many of the bot commands, but can't
-use masks on kicks and bans. A @var{trusted} user can everything a
-@var{user} can do, but can also use masks on kicks and bans. A
-@var{friend} can do everything except for stopping the bot (be
-careful who you give this to!). The @var{master} level is for the
-bot's owner (probably you) and can do @emph{everything} to the bot. Be
-@emph{very} careful if you give @var{master} level access to anyone
-else. You cannot use this symbolic levels with the @code{!adduser}
-command. See (FIXME: ref) for the numbers you must use with
-@code{!adduser}.
+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}.
+
+@enumerate 0
+
+@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. There are currently no symbolic levels in Scheme; just use the
+numeric code.
+
+@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
+the user who kicked the protected user.
+
+@item 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
+@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.
+
+@node Built-In Commands, , Automatic Op, 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.25 0.25 0.25 0.25
+@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}
+
+@item @command{addserver}
+
+@item @command{addshit}
+
+@item @command{alias}
+
+@item @command{ban}
+
+@item @command{banlist}
+
+@item @command{channels}
+
+@item @command{cycle}
+
+@item @command{dcclist}
+
+@item @command{deban}
+
+@item @command{delserver}
+
+@item @command{deluser}
+
+@item @command{delshit}
+
+@item @command{deop}
+
+@item @command{die}
+
+@item @command{do}
+
+@item @command{execute} @tab @tab @tab @strong{Only available if scripting
+support is enabled}
+
+@item @command{help}
+
+@item @command{ident}
+
+@item @command{invite}
+
+@item @command{join}
+
+@item @command{keep}
+
+@item @command{kick}
+
+@item @command{kickban}
+
+@item @command{load}
+
+@item @command{loadscript} @tab @tab @tab @strong{Only available if scripting
+support is enabled}
+
+@item @command{lock}
+
+@item @command{mode}
+
+@item @command{msg}
+
+@item @command{names}
+
+@item @command{nextserver}
+
+@item @command{nick}
+
+@item @command{nslookup}
+
+@item @command{op}
+
+@item @command{part}
+
+@item @command{password}
+
+@item @command{reconnect}
+
+@item @command{rspymessage}
+
+@item @command{save}
+
+@item @command{say}
+
+@item @command{server}
+
+@item @command{serverlist}
+
+@item @command{setfloodrate}
+
+@item @command{setversion}
+
+@item @command{shitlist}
+
+@item @command{spylist}
+
+@item @command{spymessage}
+
+@item @command{stats}
+
+@item @command{tban}
+
+@item @command{tkban}
+
+@item @command{topic}
+
+@item @command{unlock}
+
+@item @command{userlist}
+
+@item @command{who}
+
+@item @command{whois}
+
+@end multitable
@node Scripting, Concept Index, Using the Bot, Top
@chapter Scripting
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++ 2.4. 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.
+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.
@menu
* Adding New Commands::
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:
-@verb{|
+
+@example
(define (hello channel name)
- (if (string=? 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 @code{USER}'' if called as @kbd{!hello @var{USER}}.
@cindex Background on Hooks
Hooks are a powerful feature of Bobot++. Hooks are a hybrid of ircII
-hooks and tiny fugue (a MUD bot) hooks. 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.
+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.
@menu
* Creating a Hook::
@findex addhook
To add a new hook you use the function
@code{bot:addhook}. @code{bot:addhook} is prototyped as
-@code{(bot:addhook type regex function pri fall)}. @code{type}
+@code{(bot:addhook type regex function pri fall name)}. @code{type}
specifies the type of hook (the types of hooks are listed in @ref{Hook
Types}). @code{regex} is a standard regular expression. If
@code{regex} is matched, @code{function} will be
hook---higher priority hooks are executed first. This argument is
optional and defaults to @code{0}. @code{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}.
+fallthrough hook. This arg is also optional and default to
+@code{#t}. @code{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.
@node Hook Types, , Creating a Hook, Hooks
@subsection Hook Types
@item
Description of the hook
@item
-# of args
+@var{arg1} @var{arg2} ... @var{argn}
@itemize @minus
@item
-@code{arg1}: desc
+@var{arg1}: desc
@item
-@code{arg2}: desc
+@var{arg2}: desc
@item
...
@item
-@code{argN}: desc
+@var{argN}: desc
@end itemize
@end itemize
@end itemize
@code{hooks/action}
@itemize @minus
@item
-Description of the hook
+This hook is triggered when someone performs an action.
@item
-# of args
+@var{from}, @var{to}, @var{action}
@itemize @minus
@item
-@code{arg1}: desc
+@var{from}: this is the address of the person that performed the
+action in the form @samp{@var{nick} ! @var{user} @@ @var{host}}
+(without the spaces).
+@item
+@var{to}: This is the target of the action, which is either a channel
+or the Bot's nick.
+@item
+@var{action}: This 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 itemize
@end itemize
@end itemize
@end itemize
+@item
+@vindex hooks/dcc/begin
+@code{hooks/dcc/begin}
+@itemize @minus
+@item
+This hook is triggered when a user begins a DCC CHAT with the bot.
+@item
+@var{FROM}
+@itemize @minus
+@item
+@var{FROM}: This is the user's address in the form
+@samp{nick!user@@host}.
+@end itemize
+@end itemize
+
+@item
+@vindex hooks/dcc/message
+@code{hooks/dcc/message}
+@itemize @minus
+@item
+This hook is triggered when a user sends a message to the bot through
+a DCC CHAT
+@item
+@var{FROM} @var{MESSAGE}
+@itemize @minus
+@item
+@var{FROM}: This is the user's address in the form
+@samp{nick!user@@host}.
+@item
+@var{MESSAGE}: This is the message the user sent to the bot.
+@end itemize
+@end itemize
@end itemize
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.
+level functions (in progress).
@menu
* High Level Message Functions::
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
HCoop / clinton / bobotpp.git / blobdiff