readme.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
   7 <title>Vomak</title>
   8 <meta name="authors" content="Enrico Tröger  Dominic Hopf" />
   9 <meta name="date" content="2008-06-24" />
  10 <style type="text/css">
  11
  12 /*
  13 :Author: Enrico Troeger
  14 :Contact: enrico(dot)troeger(at)uvena(dot)de
  15 :Copyright: This stylesheet has been placed in the public domain.
  16
  17 Stylesheet for Geany's documentation based on a version of John Gabriele.
  18 */
  19
  20 /*@import url(html4css1.css);*/
  21
  22 body {
  23     background-color: #f2f2f2;
  24     color: #404040;
  25         margin-left: 0.4em;
  26     width: 60em;
  27     font-size: 90%;
  28 }
  29
  30 a {
  31     color: #000099;
  32 }
  33
  34 a:visited {
  35     color: #000099;
  36 }
  37
  38 a:hover {
  39     text-decoration: none;
  40 }
  41
  42 h1 {
  43     border-top: 1px dotted;
  44     margin-top: 2em;
  45 }
  46
  47 h1, h2, h3 {
  48     font-family: sans-serif;
  49 }
  50
  51 h1.title {
  52   text-align: left }
  53
  54 h2 {
  55     margin-top: 30px;
  56 }
  57
  58 h2.subtitle {
  59   text-align: left }
  60
  61 h3 {
  62     padding-left: 3px;
  63 }
  64
  65 blockquote, pre {
  66     border: 1px solid;
  67     padding: 0.4em;
  68 }
  69
  70 blockquote {
  71     font-family: sans-serif;
  72     background-color: #DBEDD5;
  73     border: 1px dotted;
  74     border-left: 4px solid;
  75     border-color: #9FD98C;
  76 }
  77
  78 pre {
  79     background-color: #ECDFCE;
  80     border: 1px dotted;
  81     border-left: 4px solid;
  82     border-color: #D9BE9A;
  83 }
  84
  85 tt, pre, code {
  86     color: #6D1260;
  87 }
  88
  89 table {
  90     border: 1px solid #200067;
  91 }
  92
  93 th {
  94     border: 1px dotted #200067;
  95 }
  96
  97 td {
  98     border: 1px dotted #200067;
  99 }
 100
 101 .docinfo-name {
 102         color: #0000ff;
 103 }
 104
 105 p.admonition-title {
 106         color: #0000ff;
 107         font-weight: bold;
 108 }
 109
 110 div.note {
 111         margin: 1em 3em;
 112         padding: 0em;
 113 }
 114
 115 dt {
 116         font-style: italic;
 117 }
 118
 119 </style>
 120 </head>
 121 <body>
 122 <div class="document" id="vomak">
 123 <h1 class="title">Vomak</h1>
 124 <h2 class="subtitle" id="a-very-simple-irc-bot">A very simple IRC bot</h2>
 125 <table class="docinfo" frame="void" rules="none">
 126 <col class="docinfo-name" />
 127 <col class="docinfo-content" />
 128 <tbody valign="top">
 129 <tr><th class="docinfo-name">Authors:</th>
 130 <td>Enrico Tröger
 131 <br />Dominic Hopf</td></tr>
 132 <tr><th class="docinfo-name">Date:</th>
 133 <td>2008-06-24</td></tr>
 134 <tr><th class="docinfo-name">Version:</th>
 135 <td>0.1</td></tr>
 136 </tbody>
 137 </table>
 138 <p>Copyright © 2008</p>
 139 <p>Vomak is distributed under the terms of the GNU General Public
 140 License as published by the Free Software Foundation; version 2
 141 of the License. A copy of this license can be found in the file
 142 COPYING included with the source code of this program.</p>
 143 <div class="section">
 144 <h1><a id="big-fat-warning" name="big-fat-warning">BIG FAT WARNING</a></h1>
 145 <p>This code is not well tested and probably runs only on GNU/Linux systems.
 146 There has no work been made in being compatible with other systems nor
 147 being very secure.
 148 This whole code was just written to get an IRC bot working and only was
 149 published in case anyone might find it useful. The code quality is also
 150 not very good, comments are missing.
 151 It does not very much error checking, consider it running unstable.
 152 This document is the only documentation available besides the source code.</p>
 153 <p>You have been warned.</p>
 154 </div>
 155 <div class="section">
 156 <h1><a id="about" name="about">About</a></h1>
 157 <p>Vomak is a very simple IRC bot with a few basic features.
 158 It connects to an IRC server and joins a channel. Then it waits for
 159 commands like <tt class="docutils literal"><span class="pre">??</span> <span class="pre">keyword</span></tt>. This is the built-in help system, see
 160 <a class="reference" href="#help-system">Help System</a>.
 161 Additionally, the bot creates a socket (Unix Domain Socket) where it
 162 accepts directly IRC messages and a few special commands, see
 163 <a class="reference" href="#socket-communication">Socket Communication</a>.</p>
 164 </div>
 165 <div class="section">
 166 <h1><a id="get-the-code" name="get-the-code">Get the code</a></h1>
 167 <p>The source code is maintained in a GIT repository.</p>
 168 <p>GIT clone URL: <a class="reference" href="http://repo.or.cz/r/vomak.git">http://repo.or.cz/r/vomak.git</a></p>
 169 <p>GIT web interface: <a class="reference" href="http://repo.or.cz/w/vomak.git">http://repo.or.cz/w/vomak.git</a></p>
 170 <p>For downloading a tarball, use the web interface. There is a link
 171 <tt class="docutils literal"><span class="pre">snapshot</span></tt> which you can use to download a generated tarball og
 172 any commit.</p>
 173 </div>
 174 <div class="section">
 175 <h1><a id="installation" name="installation">Installation</a></h1>
 176 <p>To compile the code, run the following two commands:</p>
 177 <pre class="literal-block">
 178 ./waf configure
 179 ./waf build
 180 </pre>
 181 <p>If everything went fine, you should have an executable called <tt class="docutils literal"><span class="pre">vomak</span></tt>
 182 in the directory build/default.</p>
 183 </div>
 184 <div class="section">
 185 <h1><a id="configuration" name="configuration">Configuration</a></h1>
 186 <p>Vomak expects two configuration files in the ~/.vomak.
 187 The first is <tt class="docutils literal"><span class="pre">config</span></tt> and defines basic settings for operation.
 188 The settings should be self-explanatory.
 189 The second file is <cite>database</cite> which contains all definitions for the
 190 built-in help system. The format is pretty simple, each line contains
 191 a key-value pair. The key should not contain whitespaces, quotes or any
 192 special characters. The values can contain any characters except line
 193 breaks. To add a line break, escape it with <tt class="docutils literal"><span class="pre">\n</span></tt>.
 194 Each defined key-value pair can later be queried with the command
 195 <tt class="docutils literal"><span class="pre">??</span> <span class="pre">key</span></tt>.
 196 Examples of both files are included in the source code.</p>
 197 </div>
 198 <div class="section">
 199 <h1><a id="help-system" name="help-system">Help System</a></h1>
 200 <p>The built-in help system is a handy way to access often used information and
 201 print them in the current channel for all users. It is triggered by two question
 202 marks followed by a space and the keyword to search.
 203 If the keyword is not known, nothing happens.
 204 If it is known, Vomak will print the corresponding help text found in its database.
 205 The database is a simple text file with some pre-defined help texts, see
 206 <a class="reference" href="#configuration">Configuration</a> above.
 207 There is a special keyword named <tt class="docutils literal"><span class="pre">keywords</span></tt> which lists all known keywords.</p>
 208 </div>
 209 <div class="section">
 210 <h1><a id="socket-communication" name="socket-communication">Socket Communication</a></h1>
 211 <p>A Unix Domain Socket is created once Vomak has start up and it is meant for
 212 inter-process communication with other applications running on this host.
 213 Please be careful with connecting clients: the opened socket connection should
 214 be closed as soon as all commands are sent and possible answers have been read.
 215 The socket is non-blocking, i.e. while a client connects to the socket, Vomaks
 216 main operation(reading and processing IRC messages) is blocked.
 217 All commands are line-based, i.e. answers are terminated with <tt class="docutils literal"><span class="pre">\r\n</span></tt> and you
 218 should your commands terminate with a <tt class="docutils literal"><span class="pre">\r\n</span></tt>.
 219 Vomak accepts direct IRC messages (e.g. <tt class="docutils literal"><span class="pre">PRIVMSG</span> <span class="pre">#channel</span> <span class="pre">:text</span> <span class="pre">to</span> <span class="pre">send</span></tt>) or
 220 the following special commands:</p>
 221 <ul class="simple">
 222 <li>userlist</li>
 223 <li>reload</li>
 224 <li>openlog</li>
 225 <li>quit</li>
 226 </ul>
 227 <div class="section">
 228 <h2><a id="userlist" name="userlist">userlist</a></h2>
 229 <p>After sending this command to the socket, it will answer with a space separated
 230 list of currently connected users to current channel.
 231 Vomak caches this list for performance reasons and updates it every three minutes.</p>
 232 </div>
 233 <div class="section">
 234 <h2><a id="reload" name="reload">reload</a></h2>
 235 <p>This command performs a reload of the database with the help texts. This is useful
 236 when you want to add, edit or remove some help texts and don't want to quit and start
 237 Vomak again.</p>
 238 </div>
 239 <div class="section">
 240 <h2><a id="openlog" name="openlog">openlog</a></h2>
 241 <p>Closes the logfile handle and open it again. This can be used to do some log rotating
 242 or to just clearing the logfile. This can also achieved by the SIGHUP signal.</p>
 243 </div>
 244 <div class="section">
 245 <h2><a id="quit" name="quit">quit</a></h2>
 246 <p>Does a graceful shutdown of the program. This can also achieved by the SIGTERM or SIGINT
 247 signals.</p>
 248 </div>
 249 </div>
 250 </div>
 251 <div class="footer">
 252 <hr class="footer" />
 253 <a class="reference" href="README">View document source</a>.
 254 Generated on: 2008-06-24 17:06 UTC.
 255 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 256
 257 </div>
 258 </body>
 259 </html>