README

   1
   2 ======
   3  Vomak
   4 ======
   5
   6 ----------------------
   7  A very simple IRC bot
   8 ----------------------
   9
  10 :Authors: Enrico Tröger,
  11           Dominic Hopf
  12 :Date: 2008-06-24
  13 :Version: 0.1
  14
  15 Copyright © 2008
  16
  17 Vomak is distributed under the terms of the GNU General Public
  18 License as published by the Free Software Foundation; version 2
  19 of the License. A copy of this license can be found in the file
  20 COPYING included with the source code of this program.
  21
  22
  23 BIG FAT WARNING
  24 ===============
  25 This code is not well tested and probably runs only on GNU/Linux systems.
  26 There has no work been made in being compatible with other systems nor
  27 being very secure.
  28 This whole code was just written to get an IRC bot working and only was
  29 published in case anyone might find it useful. The code quality is also
  30 not very good, comments are missing.
  31 It does not very much error checking, consider it running unstable.
  32 This document is the only documentation available besides the source code.
  33
  34 You have been warned.
  35
  36
  37 About
  38 =====
  39 Vomak is a very simple IRC bot with a few basic features.
  40 It connects to an IRC server and joins a channel. Then it waits for
  41 commands like ``?? keyword``. This is the built-in help system, see
  42 `Help System`_.
  43 Additionally, the bot creates a socket (Unix Domain Socket) where it
  44 accepts directly IRC messages and a few special commands, see
  45 `Socket Communication`_.
  46
  47
  48 Get the code
  49 ============
  50 The source code is maintained in a GIT repository.
  51
  52 GIT clone URL: http://repo.or.cz/r/vomak.git
  53
  54 GIT web interface: http://repo.or.cz/w/vomak.git
  55
  56 For downloading a tarball, use the web interface. There is a link
  57 ``snapshot`` which you can use to download a generated tarball og
  58 any commit.
  59
  60
  61 Installation
  62 ============
  63 To compile the code, run the following two commands::
  64
  65         ./waf configure
  66         ./waf build
  67
  68 If everything went fine, you should have an executable called ``vomak``
  69 in the directory build/default.
  70
  71
  72 Configuration
  73 =============
  74 Vomak expects two configuration files in the ~/.vomak.
  75 The first is ``config`` and defines basic settings for operation.
  76 The settings should be self-explanatory.
  77 The second file is `database` which contains all definitions for the
  78 built-in help system. The format is pretty simple, each line contains
  79 a key-value pair. The key should not contain whitespaces, quotes or any
  80 special characters. The values can contain any characters except line
  81 breaks. To add a line break, escape it with ``\n``.
  82 Each defined key-value pair can later be queried with the command
  83 ``?? key``.
  84 Examples of both files are included in the source code.
  85
  86
  87 Help System
  88 ===========
  89 The built-in help system is a handy way to access often used information and
  90 print them in the current channel for all users. It is triggered by two question
  91 marks followed by a space and the keyword to search.
  92 If the keyword is not known, nothing happens.
  93 If it is known, Vomak will print the corresponding help text found in its database.
  94 The database is a simple text file with some pre-defined help texts, see
  95 `Configuration`_ above.
  96 There is a special keyword named ``keywords`` which lists all known keywords.
  97
  98
  99 Socket Communication
 100 ====================
 101 A Unix Domain Socket is created once Vomak has start up and it is meant for
 102 inter-process communication with other applications running on this host.
 103 Please be careful with connecting clients: the opened socket connection should
 104 be closed as soon as all commands are sent and possible answers have been read.
 105 The socket is non-blocking, i.e. while a client connects to the socket, Vomaks
 106 main operation(reading and processing IRC messages) is blocked.
 107 All commands are line-based, i.e. answers are terminated with ``\r\n`` and you
 108 should your commands terminate with a ``\r\n``.
 109 Vomak accepts direct IRC messages (e.g. ``PRIVMSG #channel :text to send``) or
 110 the following special commands:
 111
 112 * userlist
 113 * reload
 114 * openlog
 115 * say
 116 * quit
 117
 118 userlist
 119 --------
 120 After sending this command to the socket, it will answer with a space separated
 121 list of currently connected users to current channel.
 122 Vomak caches this list for performance reasons and updates it every three minutes.
 123
 124 reload
 125 ------
 126 This command performs a reload of the database with the help texts. This is useful
 127 when you want to add, edit or remove some help texts and don't want to quit and start
 128 Vomak again.
 129
 130 openlog
 131 -------
 132 Closes the logfile handle and open it again. This can be used to do some log rotating
 133 or to just clearing the logfile. This can also achieved by the SIGHUP signal.
 134
 135 say
 136 ---
 137 Convenience shortcut to simple send a message to the channel. Any passed arguments are
 138 used as the text to send.
 139
 140 quit
 141 ----
 142 Does a graceful shutdown of the program. This can also achieved by the SIGTERM or SIGINT
 143 signals. The ``quit`` command accepts an arbitrary amount of additional arguments, these
 144 will be passed to Vomak and used as the IRC QUIT message.
 145
 146