[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
@vskip Opt 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::               
* 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, Scripting, 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 Scripting, Concept Index, Configuration, 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::                       
@end menu

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

Not here yet.

@node Hooks,  , Adding New Commands, Scripting
@section 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. 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

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

@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
# of args
@itemize @minus
@item
@code{arg1}: desc
@item
@code{arg2}: desc
@item
...
@item
@code{argN}: desc
@end itemize
@end itemize
@end itemize

That said, here is the list of available hooks:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@end itemize


@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