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