[project @ 2005-06-28 09:54:46 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,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
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,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
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++

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

@quotation
[ I kinda think this should go before the detailed description of the
config file.  I was didn't see it at first and was very frustrated
trying to find out @emph{where} to edit all this wonderful stuff. ]
@end quotation

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
* Starting the Bot::            
* User Levels::                 
* Protection::                  
* Automatic Op::                
* Built-In Commands::           
@end menu

@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 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.20 0.15 0.15 0.50
@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} @tab @tab @tab

@item @command{addserver} @tab @tab @tab Adds the server specified by
@var{host name} or @var{ip address} to the server list.

@item @command{addshit} @tab @tab @tab

@item @command{alias} @tab @tab @tab Makes an alias, and adds the
function @var{new name}, that will do exactly the same command as
@var{old name}.

@item @command{ban} @tab @tab @tab Bans @var{mask} or @var{nick} from
@var{channel}. You need to be a trusted user to ban with a
@var{mask}.

@item @command{banlist} @tab @tab @tab

@item @command{channels} @tab @tab @tab Prints the channel(s) where
the bot is currently.

@item @command{cycle} @tab Yes @tab @tab Makes the bot leave and join
@var{channel}.

@item @command{dcclist} @tab @tab @tab Gives the list of all DCC Chat
connections.

@item @command{deban} @tab Yes @tab @tab Debans @var{mask} or
@var{nick} from @var{channel}. You need to be a trusted user to deban
with a @var{mask}.

@item @command{delserver} @tab @tab @tab Deletes server from server
list whose number in the server list is @var{server number}.

@item @command{deluser} @tab @tab @tab Removes @var{nick} or
@var{mask} from the userlist.

@item @command{delshit} @tab @tab @tab Removes @var{nick} or
@var{mask} from the shitlist.

@item @command{deop} @tab Yes @tab @tab Deops @var{mask} or @var{nick}
on @var{channel}.

@item @command{die} @tab @tab @tab Makes the bot stop immediately.

@item @command{do} @tab @tab @tab

@item @command{execute} @tab @tab @tab @strong{Only available if
scripting support is enabled}

@item @command{help} @tab @tab @tab

@item @command{ident} @tab @tab @tab Identifies you on the bot. Note
that you should not use this command in public @dots{}

@item @command{invite} @tab Yes @tab @tab Invites @var{nick} on
@var{channel}.

@item @command{join} @tab @tab @tab Makes the bot join @var{channel}.

@item @command{keep} @tab Yes @tab @tab Sets the @var{modes} that the
bot will keep for @var{channel}.

@item @command{kick} @tab Yes @tab @tab Kicks @var{mask} or @var{nick}
out of @var{channel}, because of @var{reason}. You need to be a
trusted user to use a @var{mask}. 

@item @command{kickban} @tab Yes @tab @tab Bans then kicks @var{mask}
or @var{nick} out of @var{channel}, because of @var{reason}. You need
to be a trusted user to use a @var{mask}.

@item @command{load} @tab @tab @tab Reloads the userlist from disk.

@item @command{loadscript} @tab @tab @tab @strong{Only available if
scripting support is enabled}

@item @command{lock} @tab @tab @tab Locks topic on @var{channel}.

@item @command{mode} @tab Yes @tab @tab Sends @var{mode string} as
mode for @var{channel}.

@item @command{msg} @tab @tab @tab

@item @command{names} @tab Yes @tab @tab Shows the nicknames and
status of users on @var{channel}.

@item @command{nextserver} @tab @tab @tab Makes the bot connect to the
next server in its server list.

@item @command{nick} @tab @tab @tab Makes the bot use nickname @var{nick}.

@item @command{nslookup} @tab @tab @tab Does a nameserver query about
@var{nick} host, @var{host} or @var{ip address}.

@item @command{op} @tab Yes @tab @tab Ops @var{nick} on @var{channel}.

@item @command{part} @tab Yes @tab @tab Makes the bot leave @var{channel}.

@item @command{password} @tab @tab @tab Changes your password on the
bot. Use @code{NONE} as password if you want to clear it. Do not use this
command in public!

@item @command{reconnect} @tab @tab @tab Makes the bot reconnect to
its current server.

@item @command{rspymessage} @tab @tab @tab Removes you from the spy
list.

@item @command{save} @tab @tab @tab Saves the userlist.

@item @command{say} @tab Yes @tab @tab Makes the bot say @var{message}
on @var{channel}.

@item @command{server} @tab @tab @tab Select the server to connect
to. @var{server number} is the number of the server in the serverlist.

@item @command{serverlist} @tab @tab @tab Shows the bot's serverlist.

@item @command{setfloodrate} @tab @tab @tab

@item @command{setversion} @tab @tab @tab

@item @command{shitlist} @tab @tab @tab Shows the bot's shitlist.

@item @command{spylist} @tab @tab @tab Shows the bot's spylist.

@item @command{spymessage} @tab @tab @tab Adds you to the spylist

@item @command{stats} @tab Yes @tab @tab Gives @var{channel}'s statistics.

@item @command{tban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
from @var{channel} for @var{time} seconds.

@item @command{tkban} @tab Yes @tab @tab Bans @var{nick} or @var{mask}
from @var{channel} for @var{time} seconds, then kicks him/them because
of @var{reason}.

@item @command{topic} @tab Yes @tab @tab If no @var{topic}is given,
prints @var{channel}'s topic. Otherwise, the bot will change
@var{channel}'s topic to @var{topic}.

@item @command{unlock} @tab Yes @tab @tab Makes the bot unlock topic
on @var{channel}

@item @command{userlist} @tab @tab @tab Shows the bot's userlist

@item @command{who} @tab Yes @tab @tab Show your level on @var{channel}

@item @command{whois} @tab Yes @tab @tab Shows information about
@var{nick} on @var{channel}

@end multitable

@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

Adding a new command is simple. To register a new command use
@code{bot:addcommand}.

@defun bot:addcommand name func needs-channel? num-of-args min-level

The @var{name} is a string representing the name of the command being
added.  @var{func} is a function accepting @var{num-of-args}
arguments. @var{needs-channel?} is a bool that is true if the function
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:

@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}}.
@end defun

@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. A hook is called when a regular expression is matched
against a message sent to or by the bot.

Bobot++ uses different hook types for each IRC message type, and also
includes a hook for accessing raw irc messages. Hooks are tagged with
a priority and a flag that specifies whether to call the next hook
that matches after calling the current one or to stop
processing. 

Hooks are processed from the highest to lowest priority, with
fallthrough hooks of equal priority to non-fallthrough hooks being
executed first.

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

@defun bot:addhook type regex function [pri fall name]
@var{type} specifies the type of hook (the types of hooks are listed
in @ref{Hook Types}). @var{regex} is a standard regular expression. If
@var{regex} is matched, @var{function} will be called. @var{function}
will take a different number of args depending on the hook
type. @var{pri} specifies the priority of the hook---higher priority
hooks are executed first. This argument is optional and defaults to
@code{0}. @var{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}.  @var{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.
@end defun

@node Hook Types,  , Creating a Hook, Hooks
@subsection Hook Types

Here is a list of the various hooks funtions and notes on each
one. The general format of each hook description is as if it was was
function to be defined, but these describe the function to be passwd
to @code{bot:add-hook}.  Do @emph{not} name your functions these
names.

@quotation
[ Boy, that's clumsy.  I want to say that the hook/xx functions that
are documented below are not funtions that you call.  They are the
functions that needs to be passed to bot:addhook for that kind of
hook.

Still clumsy.  Oh well. ]
@end quotation


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

@defun hooks/action from to action
This hook is triggered when someone performs an action.  @var{from} is
the address of the person that performed the action in the form
@samp{@var{nick} ! @var{user} @@ @var{host}} (without the spaces).
@var{to} is the target of the action, which is either a channel or the
Bot's nick.  @var{action} 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 defun


@defun hooks/nickname old-nick new-nick
This hook gets called when someone changes thir nickname from
@var{old-nick} to @var{new-nick}.
@end defun

@defun hooks/signoff nick rest
@end defun

@defun hooks/ctcp nick to command rest
@end defun

@defun hooks/ctcp-reply nick command rest
@end defun

@defun hooks/disconnect server
This is called when the bot is disconnected from a server
unintentionally. @code{hooks/signoff} is called when the bot purposefully
disconnected. The hook function is passed the hostname of the
server it was disconnected from.
@end defun

@defun hooks/flood nick
@end defun

@defun hooks/invite nick channel
@end defun

@defun hooks/join nick channel
@end defun

@defun hooks/kick target from channel reason
@end defun

@defun hooks/leave nick channel
@defunx hooks/part nick channel
@end defun

@defun hooks/mode nick channel modes
@end defun

@defun hooks/message from message
@end defun

@defun hooks/notice nick message
@end defun

@defun hooks/public from to message
@end defun

@defun hooks/public-notice nick to message
@end defun

@defun hooks/raw raw-message
@end defun

@defun hooks/timer time
This hook seems to be called once a minute.  @var{time} is in
@code{hh:mm} format.
@end defun

@defun hooks/topic nick channel new-topic
@end defun

@defun hooks/send/public mynick dest message
@end defun

@defun hooks/send/message botnick message
@end defun

@defun hooks/send/action mynick to message
@end defun

@defun hooks/send/ctcp mynick to command message
@end defun

@defun hooks/dcc/chat-begin from
This hook is triggered when a user begins a DCC CHAT with the bot.
@var{from} is the user's address in the form @samp{nick!user@@host}.
@end defun

@defun hooks/dcc/chat-message from message
This hook is triggered when a user sends a message to the bot through
a DCC CHAT @var{from} is the user's address in the form
@samp{nick!user@@host}.  @var{message} is the message the user sent to
the bot.
@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
@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

@defun bot:say channel message
Send a public or private @var{message} to @var{channel}.

Sends a normal text message, as if a user had typed it in.  The
@var{dest} can be a nickname or a channel.
@end defun

@defun bot:action channel message
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.
@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.
@end defun

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

@c Add a url for rfc2812
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.

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

@defun bot:send-ctcp-reply to command message
@code{to} is the target of your CTCP reply, @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!

This is used to reply to a ctcp that the bot has received.
@end defun

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

@quotation
[ I didn't know where to put any of these, so I jsut stuck them in
here.

There probably needs to be several sections added, like dealing with
users (kicking, added, etc), dealing with the bot (channels, nickname
of the bot, etc), server issues (serverlist), useful tools (nslookup,
whois), and do on. ]
@end quotation


@defun bot:adduser nick-or-mask cbannel-mask level prot auto-op
Adds an user to the userlist, for a @code{nick!user@@host} matching the
one given, on a channel matching the @var{channelMask} given.

@multitable @columnfractions 0.33 0.33 0.33
@item The @var{level} can be: @tab The @var{prot} can be:  @tab The @var{auto-op} can be: 
@item  0 - No level      @tab   0 - No protection @tab  0 - No auto-op
@item  1 - User          @tab   1 - No ban        @tab  1 - Op on join
@item  2 - Trusted User  @tab   2 - No kick       @tab
@item  3 - Friend        @tab   3 - No deop       @tab
@item  4 - Master        @tab                     @tab
@end multitable

@end defun

@c (3, 4, 0)
@defun bot:addserver hostname ip-address [portnumber]
Adds the server specified by @var{hostname} or @var{ip-address} to
the server list.
@end defun

@c (3, 2, 0)
@defun bot:addshit nick-or-mask channel-mask level [time reason]
Adds an user to the shitlist, for a nick!user@@host matching the
one given, on a channel matching the @var{channelMask} given.

@display
The @var{level} can be:
  0 - No shit
  1 - No op
  2 - Kick and Ban on join
  3 - Kick and Ban on join, no deban
@end display

@end defun

@c (2, 0, 0)
@defun bot:ban channel mask-or-nick
Bans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
user to ban with a @var{mask}.
@end defun

@c (2, 0, 0)
@defun bot:change-command-level nick-or-mask channel-mask new-level
Gives @var{nick} or @var{mask} level @var{new-level} on channel(s)
@var{channel-mask}. Note that you can not change level for someone
whose level is greater than yours, and that you can not give a
level greater than yours.
@end defun

@c (1, 0, 0)
@defun bot:cycle channel
Makes the bot leave and join @var{channel}.
@end defun

@c (2, 0, 0)
@defun bot:deban channel mask-or-nick
Debans @var{mask} or @var{nick} from @var{channel}. You need to be a trusted
user to deban with a @var{mask}.
@end defun

@c (1, 0, 0)
@defun bot:delserver server-number
Deletes server from server list whose number in the server list
is @var{server-number}
@end defun

@c (2, 0, 0)
@defun bot:deluser nick-or-mask channel-mask
Removes @var{nick} or @var{mask} from the userlist.
@end defun

@c (2, 0, 0)
@defun bot:delshit nick-or-mask channel-mask
Removes @var{nick} or @var{mask} from the shitlist.
@end defun

@c (2, 0, 0)
@defun bot:deop channel mask-or-nick
Deops @var{mask} or @var{nick} on @var{channel}.
@end defun

@c (1, 0, 0)
@defun bot:die reason
Makes the bot stop immediately.
@end defun

@c (1, 0, 0)
@defun bot:do ?
@end defun

@c (2, 0, 0)
@defun bot:invite channel nick
Invites @var{nick} on @var{channel}.
@end defun

@c (1, 1, 0)
@defun bot:join channel
Makes the bot join @var{channel}.
@end defun

@c (2, 0, 0)
@defun bot:keep channel modes
Sets the @var{modes} that the bot will keep for @var{channel}.
See also STATS.
@end defun

@c (2, 1, 0)
@defun bot:kick channel mask-or-nick [reason]
Kicks @var{mask} or @var{nick} out of @var{channel}, because of @var{reason}.
You need to be a trusted user to use a @var{mask}.
@end defun

@c (2, 1, 0)
@defun bot:kickban channel mask-or-nick [reason]
Bans then kicks @var{mask} or @var{nick} out of @var{channel},
because of @var{reason}.
You need to be a trusted user to use a @var{mask}.
@end defun

@c (1, 0, 0)
@defun bot:lock channel
Locks topic on @var{channel}.
@end defun

@c (0, 0, 0)
@defun bot:logport
[ Probably returns the log port? ]
@end defun

@c (2, 0, 0)
@defun bot:mode channel mode-string
Sends @var{mode-string} as mode for @var{channel}.
@end defun

@c (0, 0, 0)
@defun bot:nextserver
Makes the bot connect to the next server in its server list.
@end defun

@c (1, 0, 0)
@defun bot:nick nick
Makes the bot use nickname @var{nick}.
@end defun

@c (2, 0, 0)
@defun bot:op channel nick
Ops @var{nick} on @var{channel}.
@end defun

@c (1, 0, 0)
@defun bot:part channel
Makes the bot leave @var{channel}.
@end defun

@c (0, 0, 0)
@defun bot:reconnect
Makes the bot reconnect to its current server.
@end defun

@c (1, 0, 0)
@defun bot:server server-number
Select the server to connect to. @var{server-number} is the number of
the server in the serverlist.
@end defun

@c (1, 0, 0)
@defun bot:setfloodrate ?
@end defun

@c (1, 0, 0)
@defun bot:setversion ?
@end defun

@c (3, 0, 0)
@defun bot:tban channel nick-or-mask time
Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds.
@end defun

@c (3, 1, 0)
@defun bot:tkban channel nick-or-mask time [reason]
Bans @var{nick} or @var{mask} from @var{channel} for @var{time} seconds,
then kicks him/them because of @var{reason}.
@end defun

@c (2, 0, 0)
@defun bot:topic channel topic
If no @var{topic} is given, prints @var{channel}'s topic. Otherwise,
the bot will change @var{channel}'s topic to @var{topic}.
@end defun

@defun bot:unlock channel
Makes the bot unlock topic on @var{channel}.
@end defun

@c (0, 0, 0)
@defun bot:getnickname
[ Gets the bot's nickname? ]
@end defun

@c (0, 0, 0)
@defun bot:getserver
@end defun

@c (0, 0, 0)
@defun bot:getserverlist
@end defun

@c (0, 0, 0)
@defun bot:flush
[ Flushes the socket to the server? ]
@end defun

@c (0, 0, 0)
@defun bot:flushport
[ Flushes the log port? ]
@end defun

@c (1, 0, 0)
@defun bot:random ?
[ Returns a random number?  What range?  Why? ]
@end defun

@c (1, 0, 0)
@defun bot:delcommand
[ Probably deletes a command added with @code{bot:addcommand} ? ]
@end defun

@c (2, 0, 0)
@defun bot:addtimer ?  ?
@end defun

@c (1, 0, 0)
@defun bot:deltimer ?
@end defun

@c (2, 0, 0)
@defun bot:dcc-chat-send ? ?
@end defun

@quotation
[ And what about the stuff defined in @file{bobot-utils.scm} ? I just
added it here so it could be somewhere.  There should also be a
section dealing with modules.  How to use them.  What module scripts
are in.  What module bobot++ provided primites are in.  And so on. ]
@end quotation

@defun bot:log . messages
Write as many @var{messages} as you want to the log.  If the arg is a
thunk it will be executed and it's output will be written to the log.
@end defun

@defun bot:load file
@end defun

@defun bot:load-module module-spec
@end defun

@defun bot:use-module module-spec
@end defun

@defun bot:match-not-channel regex
match-not-channel adds a prefix regex to your @var{regex} so it
doesn't match the sender or channel in a PUBLIC message
@end defun

@defun bot:match-to-me regex
match-to-me matches text that was addressed to the bot with a
':',  ',',  or nothing after the bot name.
@end defun

@defun bot:sent-to-me? message
@end defun

@defun bot:ctcp-quote message
Returns the CTCP quoted message
Input @emph{MUST NOT} contain the trailing @code{\r\n}
(it is added by the message sending code).
@end defun


@defvar %bot:loadpath
@end defvar

@defun %bot:load-extensions
@end defun



@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