[project @ 2004-06-14 04:26:29 by unknown_lamer]

[clinton/bobotpp.git] / bobot++.texinfo

input texinfo  @c -*- texinfo -*-
@c %**start of header
@setfilename bobot++.info
@settitle Bobot++: A Schemeable IRC Bot
@setchapternewpage on
@c %**end of header

@ifinfo
This file documents Bobot++ by Clinton Ebadi and Etienne Bernard
(original author, no longer works on program).

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
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

@titlepage
@title Bobot++: A Schemeable IRC Bot
@author Clinton Ebadi

@page
@vskip O plus 1filll
Copyright @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
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 titlepage

@node Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up

@ifinfo
This document describes Bobot++ by Clinton Ebadi and Etienne Bernard
(original author, no longer works on program).

This document applies to version 2.1.5 of the program named
Bobot++

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
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 Files::         
* Configuration File Placement::  

Configuration Files

* bot.conf::                    
* bot.users::                   

bot.conf

* server syntax::               
* channel syntax::              

Using Bobot++

* User Levels::                 
* Protection::                  
* Automatic Op::                

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
@chapter Introduction

This manual feels abused and neglected because it has almost no
content.

@node Configuration, Using the Bot, Introduction, Top
@chapter 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
* bot.conf::                    
* bot.users::                   
@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>}

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}

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. 

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 configuration, put it
in @file{~/.bobotpp/config/default/}.

@node Using the Bot, Scripting, Configuration, Top
@chapter Using Bobot++

FIXME: stuff here...

@menu
* User Levels::                 
* Protection::                  
* Automatic Op::                
@end menu

@node User Levels, Protection, Using 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 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,  , 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 Scripting, Concept Index, Using the Bot, Top
@chapter Scripting

Bobot++'s most powerful feature is its scripting system. You write
scripts using Guile Scheme. This manual does not cover how to use
Guile or how to learn Scheme. @xref{Top, , Guile Reference Manual,
guile, The Guile Reference Manual}, for the Guile reference manual and
@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.

@menu
* Adding New Commands::         
* Hooks::                       
* Scheme User Levels::          
* Sending Messages::            
* Misc Scripting Stuff::        
@end menu

@node Adding New Commands, Hooks, Scripting, Scripting
@section Adding New Commands

@findex addcommand
Adding a new command is simple. To register a new command use
@code{bot:addcommand}. The prototype for @code{bot:addcommand} is
@code{(bot:addcommand name func needs-channel? num-of-args
min-level)}. The @code{name} is a string representing the name of the
command being added. @code{func} is a function accepting
@code{num-of-args} arguments. @code{needs-channel?} is a bool that is
true if the function needs the channel name as its first arg, and
false otherwise. @code{num-of-args} is the number of args @code{func}
will take and must be within zero (0) and twenty
(20). @code{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:

@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 @code{USER}'' if called as @kbd{!hello @var{USER}}. 

@node Hooks, Scheme User Levels, 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. 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::             
* Hook Types::                  
@end menu

@node Creating a Hook, Hook Types, Hooks, Hooks
@subsection 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 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
called. @code{function} will take a different number of args depending
on the hook type. @code{pri} specifies the priority of the
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}. @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

Here is a list of the various hooks are notes on each one. The general
format of a hook is:

@itemize @bullet
@item
@code{hooks/name} (this is the Scheme variable name of the hook)
@itemize @minus
@item
Description of the hook
@item
@var{arg1} @var{arg2} ... @var{argn}
@itemize @minus
@item
@var{arg1}: desc
@item
@var{arg2}: desc
@item
...
@item
@var{argN}: desc
@end itemize
@end itemize
@end itemize

That said, here is the list of available hooks:
FIXME: write docs

@itemize @bullet

@item
@vindex hooks/action
@code{hooks/action}
@itemize @minus
@item
This hook is triggered when someone performs an action.
@item
@var{from}, @var{to}, @var{action}
@itemize @minus
@item
@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

@item
@vindex hooks/nickname
@code{hooks/nickname}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/signoff
@code{hooks/signoff}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/ctcp
@code{hooks/ctcp}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/ctcp-reply
@code{hooks/ctcp-reply}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/disconnect
@code{hooks/disconnect}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/flood
@code{hooks/flood}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/invite
@code{hooks/invite}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/join
@code{hooks/join}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/kick
@code{hooks/kick}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/part
@code{hooks/part}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/mode
@code{hooks/mode}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/message
@code{hooks/message}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/notice
@code{hooks/notice}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/public
@code{hooks/public}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/public-notice
@code{hooks/public-notice}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/raw
@code{hooks/raw}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/timer
@code{hooks/timer}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@end itemize
@end itemize

@item
@vindex hooks/topic
@code{hooks/topic}
@itemize @minus
@item
Description of the hook
@item
# of args
@itemize @minus
@item
@code{arg1}: desc
@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


@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
@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).

@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

...

@node Low Level Message Functions,  , High Level Message Functions, Sending Messages
@subsection ``Low Level'' Message Functions

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.

@itemize @bullet

@item @code{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
command. Make sure to @code{bot:ctcp-quote} the message!

@end itemize

@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.

@node Concept Index, Function Index, Scripting, Top
@unnumbered Concept Index
@printindex cp

@node Function Index, Variable Index, Concept Index, Top
@unnumbered Function Index
@printindex fn

@node Variable Index,  , Function Index, Top
@unnumbered Variable Index
@printindex vr

@bye