[project @ 2002-11-04 03:59:06 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 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
@c @vskip O plus 1filll
Copyright @copyright{} 2002 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.0 of the program named
Bobot++

Copyright 2002 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::              
@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. 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. 

@menu
* Configuration File Syntax::   
* Configure File Placement::    
@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
@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/}. 

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

FIXME: stuff here...

@menu
* User Levels::                 
@end menu

@node User Levels,  , Using 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}.

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

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

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

@c Since a bot calls hooks on things it says, you have to be careful
@c about hooks that output text that might match itself. E.g. if you have
@c a hook that matches @code{"foo"} and the hook displays @code{"foo to
@c the whatsit?"}, then the hook will call itself over and over until the
@c stack overflows! To protect against this I wrote the macro
@c @code{not-from-me}. You call it like this: @code{(not-from-me from
@c (stmts if not from bot) (stmts if from bot))}. E.g. 

@c @example
@c (bot:addhook hooks/public "foo"
@c              (lambda (f t p)
@c                (not-from-me f ((bot:say t "foo to the what!")))))
@c @end example

@c This say ``foo to the what!'' to the channel that ``foo'' was said in
@c and do nothing otherwise. You can optionally specify an action to be
@c executed if the message is from the bot:

@c @example
@c (bot:addhook hooks/public "foo"
@c              (lambda (f t p)
@c                (not-from-me f ((bot:say t "foo to the what!"))
@c                               ((bot:say t "moof")))))
@c @end example

@c That will do the same thing as the first example, but the bot will
@c say ``moof'' if it said ``foo'' before. That probably isn't a very
@c nice thing to do, but it works as an example. You can have as many
@c staments as you want in the clauses.

@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