10 :Author: Enrico Tröger
16 Vomak is distributed under the terms of the GNU General Public
17 License as published by the Free Software Foundation; version 2
18 of the License. A copy of this license can be found in the file
19 COPYING included with the source code of this program.
24 This code is not well tested and probably runs only on GNU/Linux systems.
25 There has no work been made in being compatible with other systems nor
27 This whole code was just written to get an IRC bot working and only was
28 published in case anyone might find it useful. The code quality is also
29 not very good, comments are missing.
30 It does not very much error checking, consider it running unstable.
31 This document is the only documentation available besides the source code.
38 Vomak is a very simple IRC bot with a few basic features.
39 It connects to an IRC server and joins a channel. Then it waits for
40 commands like ``?? keyword``. This is the built-in help system, see
42 Additionally, the bot creates a socket (Unix Domain Socket) where it
43 accepts directly IRC messages and a few special commands, see
44 `Socket Communication`_.
49 The source code is maintained in a GIT repository.
51 GIT clone URL: http://repo.or.cz/r/vomak.git
53 GIT web interface: http://repo.or.cz/w/vomak.git
55 For downloading a tarball, use the web interface. There is a link
56 ``snapshot`` which you can use to download a generated tarball og
62 To compile the code, run the following two commands::
67 If everything went fine, you should have an executable called ``vomak``
68 in the directory build/default.
69 (Alternatively you can also simply type ``make`` but this is not supported
75 Vomak expects two configuration files in the ~/.vomak.
76 The first is ``config`` and defines basic settings for operation.
77 The settings should be self-explanatory.
78 The second file is `database` which contains all definitions for the
79 built-in help system. The format is pretty simple, each line contains
80 a key-value pair. The key should not contain whitespaces, quotes or any
81 special characters. The values can contain any characters except line
82 breaks. To add a line break, escape it with ``\n``.
83 Each defined key-value pair can later be queried with the command
85 Examples of both files are included in the source code.
90 The built-in help system is a handy way to access often used information and
91 print them in the current channel for all users. It is triggered by two question
92 marks followed by a space and the keyword to search.
93 If the keyword is not known, nothing happens.
94 If it is known, Vomak will print the corresponding help text found in its database.
95 The database is a simple text file with some pre-defined help texts, see
96 `Configuration`_ above.
97 There is a special keyword named ``keywords`` which lists all known keywords.
102 A Unix Domain Socket is created once Vomak has start up and it is meant for
103 inter-process communication with other applications running on this host.
104 Please be careful with connecting clients: the opened socket connection should
105 be closed as soon as all commands are sent and possible answers have been read.
106 The socket is non-blocking, i.e. while a client connects to the socket, Vomaks
107 main operation(reading and processing IRC messages) is blocked.
108 All commands are line-based, i.e. answers are terminated with ``\r\n`` and you
109 should your commands terminate with a ``\r\n``.
110 Vomak accepts direct IRC messages (e.g. ``PRIVMSG #channel :text to send``) or
111 the following special commands:
119 After sending this command to the socket, it will answer with a space separated
120 list of currently connected users to current channel.
121 Vomak caches this list for performance reasons and updates it every three minutes.
125 This command performs a reload of the database with the help texts. This is useful
126 when you want to add, edit or remove some help texts and don't want to quit and start
131 Does a graceful shutdown of the program. This can also achieved by the SIGTERM or SIGINT