Writing Modules
===============

PogoBOT currently has one core, listening on port 3009 on molotov. It is
behind a firewall, so you'll either need to run modules on 'tov, or use ssh
port forwarding.

Modules are independent processes, and communicate over tcp sockets (for
now). They send lines to each other, terminated with a UNIX newline
character (\n). The first `word' of the line is the command that the line
is calling.

Registering Commands
--------------------

Modules can register commands. They will then receive all lines beginning
with that command name. To register a command, use the `REG' command. e.g.:

REG foo\n

This module will then receive any lines going through the core that begin
with `foo'.

PBScript
--------

PBScript (PogoBOT script) is being built into the syntax of the IRC
connector module. This affects module design. PBScript uses tab separation
- each field of a line is one command, along with arguments. e.g.:

calc 5*10/2        say The answer is:        PogoBOT@irc.uwcs.co.uk #compsoc Tim\n

This line will first get sent to the module which has registered the `calc'
command. The output from this module will then be appended to the arguments
of the second command (leaving a single space), and then the whole line is
returned to the core.

To continue the example, the line will now look like:

say The answer is: 25        PogoBOT@irc.uwcs.co.uk #compsoc Tim\n

The `say' module (if there were one; it's a bit pointless in this bot)
would just return:

PogoBOT@irc.uwcs.co.uk #compsoc Tim The answer is: 25\n

The IRC connection module is the one that has registered
`PogoBOT@irc.uwcs.co.uk', so the line will now get sent there, and spoken
on IRC.

Rules
-----

Modules should understand the following:
* Responses must not contain tabs - these must be converted to `\t'.
* Backslashes in responses must be sent as `\\'.
* The first word (up to the first space) of a line is the command name.
* From there up until the first tab is the set of arguments to the command.
* To reply directly to a line, the original command, arguments and first
tab should be removed, and the reply appended just before what was the
second tab.

These rules are not /enforced/ in the core, but it is suggested that module
writers follow them if they want modules to work together effectively.

Command Interpreter
-------------------

Currently, there is a module plugged into the core which interprets lines
from IRC, and calls required commands. It does not yet do arbitrary
regexes, just looks for an initial `-' (hyphen). Any lines from IRC which
begin with that character will get called as commands, possibly after some
rewriting.