| Authors: | Enrico Tröger
Dominic Hopf |
|---|---|
| Date: | 2008-06-24 |
| Version: | 0.1 |
Copyright © 2008
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.
Since there are just too many too good alternatives, this project died a silent death. It's pevious home, #geany on Freenode, is now inhabited by an instance of Supybot (http://sourceforge.net/projects/supybot/). Sources are still available from the GIT repository but no longer maintained or supported. (2010-02-22)
This code is not well tested and probably runs only on GNU/Linux systems. There has no work been made in being compatible with other systems nor being very secure. This whole code was just written to get an IRC bot working and only was published in case anyone might find it useful. The code quality is also not very good, comments are missing. It does not very much error checking, consider it running unstable. This document is the only documentation available besides the source code.
You have been warned.
Vomak is a very simple IRC bot with a few basic features. It connects to an IRC server and joins a channel. Then it waits for commands like ?? keyword. This is the built-in help system, see Help System. Additionally, the bot creates a socket (Unix Domain Socket) where it accepts directly IRC messages and a few special commands, see Socket Communication.
The source code is maintained in a GIT repository.
GIT clone URL: http://repo.or.cz/r/vomak.git
GIT web interface: http://repo.or.cz/w/vomak.git
For downloading a tarball, use the web interface. There is a link snapshot which you can use to download a generated tarball og any commit.
To compile the code, run the following two commands:
./waf configure ./waf build
If everything went fine, you should have an executable called vomak in the directory build/default.
Vomak expects two configuration files in the ~/.vomak. The first is config and defines basic settings for operation. The settings should be self-explanatory. The second file is database which contains all definitions for the built-in help system. The format is pretty simple, each line contains a key-value pair. The key should not contain whitespaces, quotes or any special characters. The values can contain any characters except line breaks. To add a line break, escape it with \n. Each defined key-value pair can later be queried with the command ?? key. Examples of both files are included in the source code.
The built-in help system is a handy way to access often used information and print them in the current channel for all users. It is triggered by two question marks followed by a space and the keyword to search. If the keyword is not known, nothing happens. If it is known, Vomak will print the corresponding help text found in its database. The database is a simple text file with some pre-defined help texts, see Configuration above. There is a special keyword named keywords which lists all known keywords.
A Unix Domain Socket is created once Vomak has start up and it is meant for inter-process communication with other applications running on this host. Please be careful with connecting clients: the opened socket connection should be closed as soon as all commands are sent and possible answers have been read. The socket is non-blocking, i.e. while a client connects to the socket, Vomaks main operation(reading and processing IRC messages) is blocked. All commands are line-based, i.e. answers are terminated with \r\n and you should your commands terminate with a \r\n. Vomak accepts direct IRC messages (e.g. PRIVMSG #channel :text to send) or the following special commands:
After sending this command to the socket, it will answer with a space separated list of currently connected users to current channel. Vomak caches this list for performance reasons and updates it every three minutes.
This command performs a reload of the database with the help texts. This is useful when you want to add, edit or remove some help texts and don't want to quit and start Vomak again.
Closes the logfile handle and open it again. This can be used to do some log rotating or to just clearing the logfile. This can also achieved by the SIGHUP signal.
Convenience shortcut to simple send a message to the channel. Any passed arguments are used as the text to send.
Does a graceful shutdown of the program. This can also achieved by the SIGTERM or SIGINT signals. The quit command accepts an arbitrary amount of additional arguments, these will be passed to Vomak and used as the IRC QUIT message.