NAME

       manderlbot.conf - Configuring the manderlbot IRC robot.

DESCRIPTION

       manderlbot  is  an  irc  bot aimed at saying idioties or doing some little searches on the
       internet. It is not an eggdrop bot.

CONFIGURATION

       The configuration file is an XML file containing the following elements:

       manderlbot
              the opening XML element of the configuration, it contains the properties  name  and
              controler.  The name will be shown as the bot fullname, the controller property may
              contain one or more nicknames separated by spaces, only those people will  then  be
              allowed to operate on the running bot from irc channel.

              All the following sections, otherwise stated, are to be found under this one.

       dict   is  the  section  where  to  define the dictionnary server you may want to use. See
              dict.org for details about the protocol and servers. Be aware that you  can  run  a
              dict server locally, and download some useful dictionnaries.

              The  properties  to define here are the dict server host, the port, and the default
              dictionnary to use.

       server allows you to define which servers manderlbot should connect to. The properties are
              host  and  port.  You have to define a server section for each and every irc server
              you want manderlbot to connect to.

       channel
              section is where to configure the manderlbot behaviour and name. This  section  has
              to  be embedded in the server one. You have to define a channel section per channel
              you want manderlbot to join on a server.

              The properties of  channel  section  are  name,  the  channel  name,  botname,  the
              manderlbot  nickname on that channel, and behaviours, a list of behaviours name you
              want to activate for that channel.

       behaviours
              will just contain your behaviour list

       behaviour
              have to be found under the behaviours section.  You  define  here  your  behaviour,
              which  properties  are name, the name to use in the channel definition, the action,
              defining what will be done, and one or more of  the  followings  pattern  elements:
              pattern, op, to, option and from. You can even prefix those properties with exl_ to
              get an exclude pattern match (see [XRef to MATCH]>).

              This element contains data wich will be used as the action parameter, as explain in
              section [sub:Implemented-actions].

BEHAVIOUR MATCHING

       So  when you define a behaviour, you want manderlbot to react on some event on irc channel
       it is connected to, and take some action. Here we see how to define the event you want  it
       to  react  to.  As on irc all you do is sending lines of text, an event as to be text line
       oriented.

       So  manderlbot   configuration   allows   you   to   define   some   Regular   Expressions
       <URL:http://www.regular-expressions.info>  to  match  the  lines  received. If the line is
       matched, the associated action is done. Please note the regexp  are  all  considered  case
       insensitive ones.

       You  can  define  some regexp on the following parts of the received line (containing some
       server informations relative to IRC protocol <URL:http://www.faqs.org/rfcs/rfc1459.html>):

       pattern
              will try to match the user input, that is what your ordinary irc client  will  show
              you

       op     will  try to match the irc operation, see the RFC for complete list (op can be kick
              or join for example)

       to     irc protocol field, will probably contain the  channel  name,  so  you  won't  need
              that...

       option irc protocol option field

       from   the   nickname   of   the   one   who   typed   the   current  line,  on  the  form
              nick!~user@host.domain.tld

       And in order to make it even more powerful and readable, you can define the same  patterns
       with  an  'exl_' prefix, this will prevent the action to being taken if it matches. So you
       can define the parameters exl_pattern, exl_op, exl_to, exl_option and exl_from.

       Of course, you can use any combination of the listed parameters, thus being quite  precise
       on what you want to react to.

IMPLEMENTED ACTIONS

       The  action  parameter  of  the  behaviour  configuration  element  defines the manderlbot
       behaviour on matching a line. Here is a list of provided actions you can use.  If you want
       manderlbot  to  take an action not described here, you will have to write some erlang code
       to teach him what you want!

       The argument of the action is the xml data given enclosed in the behaviour element.

       action send the given argument as if manderlbot had typed it after the /me irc command.

       answer send the line prefixed with the sender name and a colon.

       bloto  this will count the matched lines per user, and first obtaining 5  points  has  won
              the business loto game. Just define your buzzwords set and make it a regexp!

       debian_file
              will  search  the irc given file using the debian web site cgi. The argument is not
              used.

       debian_pkg
              will search the irc given package using the debian web site cgi.  The  argument  is
              not used.

       dict   will  ask  your  defined  dict  server  for the given word. The argument may be the
              dictionnary name to use in the query, but defaults to the 'default'  entry  of  the
              dict config element.

       google will ask google for the rest of the irc line. The argument is not used.

       mute   mute will mute the bot, you have to be a controler to use that. The argument is not
              used.

       pyramid
              pyramid is a game named after a french TV game. You have to make guess a  world  to
              an  irc  fellow  on  that  channel, in a given number or tries. The argument is not
              used.

       random will say one of the sentences listed in the arguments randomly. The sentences  have
              to be separated by '%' signs.

       fortune
              same  behaviour as random, but this time the argument is the name of a traditionnal
              separate fortune file.

       reconf will ask the bot to re-read its configuration. It allows you to handle  dynamically
              your  configuration, no need to restart the bot, and irc control! You have to be in
              the controler list to use this action.

       rejoin allows you te rejoin a channel (useful on kick, just add a op="kick"  parameter  to
              the behaviour element definition).

       say    say will say the arguments.

       timer  will  say  the  first  argument,  then  wait  for  a random time, and say the other
              arguments. The args have to be separated bu a '%' char.

INTERACTING WITH THE RUNNING BOT, FROM IRC

       You can use the reconf and mute actions to control the bot from irc, and  you  define  who
       can do that in the first configuration element, with the controler property.

EXAMPLE

       Please see the given configuration file, in /etc/manderlbot/config.xml.

HISTORY

       But why did we wrote this software ?

       Well,  I  wanted  an  irc  bot  to  play  with,  in order to have it say some silly things
       automatically on answer to our own idioties.  I  did  not  want  an  eggdrop  or  whatever
       controlling channel bot. I saw that manderlbot project existing, was already familiar with
       erlang developpment, so I began using it.

       The existing project was on early stage of development, and I wanted the bot  to  do  more
       and  more  things.  So  I wrote some code to make it fit my needs. As the original authors
       would not consider my patches, I forked the project, keeping the name (they seemed not  to
       work on their version at all), and hosting it on the TuxFamily services.

AUTHORS

       manderlbot  was  written  by  Dimitri  Fontaine  <dim@tuxfamily.org> and Nicolas Niclausse
       <nico@niclux.org>.

                                            Avril 2004                         MANDERLBOT.CONF(5)