SphereBot readme documentation.

Contents:

1. Requirements
2. Configuration
3. Generic Use
4. Module Use
5. Module Development
6. Important files & directories
7. Developer Information


=====================
++ 1. Requirements ++
=====================

The bot was designed and developed under Perl v.5.8.7 so it's safe to assume 
that versions from there on up will be usable. Versions lower than that have
not been tested. If you try it, and it works, let us know so we can update 
this paragraph with the informaion.

In addition to Perl, there are several Perl module required for different 
tasks. The following modules are *required* for the bot itself to launch 
and work:

- Getopt::Long
- Config::Natural
- IO::Socket::INET
- IO::Socket::SSL
- Switch

In addition to those, several SphereBot modules may require other things. The 
following items are required by the *default included set* of SphereBot 
modules:

Modules 'bar' and 'calc' require:
	- Perl Module: URI::Escape
	- Perl Module: LWP::UserAgent
Modules 'bash' and '00qdb' requires:
	- Perl Module: LWP::Simple
Module 'fortune' requires:
	- Application: 'fortune'

Unloading or not loading these modules in the first place removes the need for 
their dependencies.


======================
++ 2. Configuration ++
======================

There are 3 configuration files contained in the config/ directory, each 
containing a sample configuration:

config/sphere.conf - Bot's main configuration file.
config/users.conf - Bot's user priviliege configuration file.
config/modules.conf - Bot's module configuration file.

For information on the actual settings that need to be set, please read 
the included sample configurations and change them to fit your needs.

* sphere.conf & modules.conf *
Entries in these files are as follows:

setting = value
Sets the speicified setting to the value. For on/off settings, you can use 
'on', 'true', or 'yes', as well as 'no', 'false', or 'off'.

setting += value2
Appends the setting. For example, if settings was 'value', it would now be 
'valuevalue2'.

// comment
To make comments throughout the configuration file, begin them with //. 
Everything on the line after that symbol will be read as a comment and 
ignored. Comments do not need to start at the beginning of the line.

include "another.conf"
Causes it to continue reading from the file 'another.conf' for further 
settings. Useful for breaking the configuration down into multiple parts.

* users.conf *
Syntax for this file is the same, with the following extra usage:

block {
	setting = value
	setting2 = value2
}

This allows for the same settings to be set for different users.


====================
++ 3. Generic Use ++
====================

The bot is launched by simply typing './bot.pl' or 'perl bot.pl' from the 
bot's working directory.

Usage: bot.pl [--help]
Usage: bot.pl [-c file] [-u file] [-m file] [-d]

Flags & arguments:
		-c      --config-file=file      Path to SphereBot config file.
										Default: ./sphere.conf
		-u      --user-file=file        Path to user config file.
										Default: ./users.conf
		-m      --module-file=file      Path to module config file.
										Default: ./modules.conf
		-d      --debug                 Show debug information.
						(Mostly for developers. And there's a lot of it.)
				--help                  Show help

We reccomend launching it using "./bot.pl &>./bot.log &". This causes the bot 
to output all it's information to 'bot.log' in it's working directory, and 
then background so you can resume using your terminal. Launching it with no 
options will cause it to use the default paths and settings listed above.

Once connected, the bot's command can be called by typing the prefix specified 
in sphere.conf (default: -) followed by the command name, eg: -die Going down 
for maintenance.

If the bot is disconnected from the server, it will automatically reconnect, 
and if it is kicked from a channel, it will automatically rejoin. System 
commands (such as module control) the bot responds to using notice, and will 
recognise these commands in either a public channel or a private message 
environment.

* System Commands *

There are some commands built into the bot which do not use modules. These 
commands include the following, and all of them require appropriate permissions
set in users.conf to be executed. These permissions are in brackets after the
descriptions.

'die reason' will cause the bot to quit. Optionally, specify a reason to use 
	instead of the bot's default quit reason. [die]
'load module-name' will cause the bot to load the module 'module-name' from the
	modules/ directory. [modules]
'unload module-name' will cause the bot to clear from memory the module
	'module-name'. [modules]
'rehash' will cause the bot to re-read it's configuration files. Changes to the
	startup configuration, such as channels, ports, servers, and SSL, will
	be learned and used if the bot gets disconnected, but changes to these
	will not take place on a rehash. All other options will. [rehash]

The bot also has CTCP responses built-in to the following CTCP queries:
- VERSION
- TIME
- PING


===================
++ 4. Module Use ++
===================

Moduling on SphereBot is a two-part system. The benefit to this is modules can 
be written in any language. Several sample modules are included with the bot by
default, and we plan to add a modules area to the site where more modules can 
be submitted and downloaded. 

The first part of the module is the module template file. This specified what
the bot should react to, when it should react to it, and what it does when it 
reacts. These files belong in the modules/ directory, and should be named 
module_name.sphr.

The second part of the module is the executable. Modules can either use system 
commands, such as 'echo' or 'cat', or they can include their own executable 
file or script for it's own specific purpose (as several of the ones included 
in the default package do). For the sake of organisation, we reccomend that 
these custom exectuables and scripts be in the modules/exec/ directory, so that
the template file can use a relative path to find the module, although they 
do not have to be.


===========================
++ 5. Module Development ++
===========================

If you do not know IRC numerics and commands (such as PRIVMSG, 353, NOTICE, 
etc) or the IRC protocol, please review that before reading this section. It 
assumes a certain level of familiarity with this topic.

* Template file, modules/name.sphr *

In the template module, a module is assigned a handle. This handle *must* be 
unique for every module--we reccomend naming in the fashion of 
'yourname-handle' to ensure it's uniqueness, however, this is not required. Any
 unique name will do. These handles used to specify options in the following 
format

	handle.hook = numeric
	handle.match = eval
	handle.exec = command

Numeric is the single case-insensitive IRC numeric that handle should be hooked
to, for example, 'privmsg' for a private or channel message.

Eval is a Perl statement that gets evaluated when the module is executed. If 
the statement returns '1', than the module gets executed. If it returns '0', 
the module is not. For example, to have a module *always* run, you could simply
specify:
	handle.match = return 1;
Or if your module was to execute on the command 'command', you could specify:
	handle.match = if($msg = $prefix."command"){ return 1; }else{ return 0; }
(Note we use $prefix to specify the comand prefix specified in the sphere.conf,
you are not required to use, but we reccomend it for synergy's sake.) We also 
reccomend that if your command requires options after it (for example 'command 
#channel' does something to the channel), using a regular expression instead 
of a flat if statement, such as:
	handle.match = if($msg =~ /^\Q$prefix\Ecommand/){ return 1;}else{ return 0; }
See the section on variables further down for a list of variables you can use 
to check against.

Exec is the command to be executed when the evaluated statement is returned 
true. Information can be passed to the command using either one or both of the 
following methods: Command-line arguments, or environment variables. Everytime 
a module is executed, it is done so within an environment with explicit 
variables set. See the section on environment variables further down for a 
list of these variables. You can also specify variables to be passed via the 
command line. This is done by specifying [%var] to pass the value of variable 
$var, or [@arr:key] to pass the value of $key in the @arr array 
(e.g. $arr{$key}). 
Commands are expected to output raw IRC data, as a client would to a server. 
A module can output as many commands on seperate lines as it wishes, separated 
by a \n.
For example:
	handle.exec = echo PRIVMSG [%replyto] :[@origin:nick] with ident [@origin:ident] said [%message]
This will send a private message to the channel or user that the command was 
sent to/from saying 'NICKNAME with IDENT said MESSAGE' when NICKNAME who has 
an ident of IDENT says MESSAGE.

You can have any number of handles & hooks per module template file.

* Environment Variables *

Each time a module is executed, it is done so in an environment with certain 
environment variables set. These variables include:

ORIGIN_NICK - The nickname, if any, of the user who caused the module to 
	launched.
ORIGIN_IDENT - The ident, if any, of the user who caused the module to be 
	launched.
ORIGIN_HOST - The hostname/hostmask/IP/vhost of the user who caused the module 
	to be launched.
NUMERIC - The numeric or command on which the module was hooked to.
DESTINATION - The channel (if public message), server (if global message), or 
	nickname (if private message) that the event was destined for. If 
	private, it will usually be the bot's nickname.
ARGS - Any extra arguments sent by the event, not as part of the message.
MESSAGE - The part of the event after the ':' when data is sent.
BOT_NICK - The bot's own nick.
BOT_PREFIX - The command prefix as specified in the config.
REPLYTO - If the message was sent as a public message to a channel, this will 
	be that channel. If the message was sent as a private message to the 
	bot, this will be the user that sent the message.
USERFILE_IDENT - If the user exists in users.conf, this is what the ident 
	listed in there for that user is.
USERFILE_FLAGS - If the user exists in users.conf, this is what the permission 
	flags for that user listed there is.

* Other Variables *

Any variables accessible to the Perl script when the evaluation and execution 
statements are called can be passed to the module as commandline arguments.
See above about the handle.exec section of the template file for how to do 
this. Some of the more commonly used variables are:

$origin{'nick'} - The nickname, if any, of the user who caused the module to 
	launched.
$origin{'ident'} - The ident, if any, of the user who caused the module to be 
	launched.
$origin{'host'} - The hostname/hostmask/IP/vhost of the user who caused the 
	module to be launched.
$numeric - The numeric or command on which the module was hooked to.
$destination - The channel (if public message), server (if global message), or 
	nickname (if private message) that the event was destined for. If 
	private, it will usually be the bot's nickname.
$args - Any extra arguments sent by the event, not as part of the message.
$message or $msg - The part of the event after the ':' when data is sent.
$botnick - The bot's own nick.
$prefix - The command prefix as specified in the config.
$replyto - If the message was sent as a public message to a channel, this will 
	be that channel. If the message was sent as a private message to the 
	bot, this will be the user that sent the message.
$nspass - The bot's nickserv password as set in sphere.conf.


* Extra Commands *

In addition to outputting raw IRC command, modules can also output the 
following extra commands to be parsed before sending to the IRC server:

CTCP #channel|nickname :command arguments
	This will send a CTCP-encoded 'command' with the arguments of 
	'arguments' to the specified channel or nickname. This can be used to 
	send actions (CTCP #channel :ACTION waves.) or request information 
	from a user (CTCP nickname :VERSION). The data part of the message 
	after the ':' is encoded in \001 characters and then sent to the 
	client.
	
ECHO :output string
	This will simply echo the 'output string' to the bot's STDOUT (be it 
	console or log file) followed by a \n. Useful for debugging modules,
	 or outputting errors & alerts.
	
STRING :variable=value
	This will set '$variable' equal to 'value' in the bot itself. This 
	string can then be passed to other modules in the same manner as the 
	variables above.
	

======================================
++ 6. Important Files & Directories ++
======================================

In addition to the modules/ directory, and the *.sphr files contained within, 
and the config/ directory, with it's *.conf files, there are 2 other important 
directories used required for the bot to function.

functions/
	irc_functions.pl
	client_functions.pl
These files provide the critical protocol & client functions that the bot runs
on. These folder & it's files must be in the bot's working directory (.) at the
time of launch, or in your Perl environment's @INC path. Without them, the bot 
will not start.

data/
This directory can be used as a data storage directory than any module that 
needs to save data across sessions (such as the 'seen' module) can store it's 
information. We ask that modules create their own subdirectory of this 
directory to keep it organised, although it's not required. This directory, 
and all it's contents, should be readble & writable by the bot's process.
	seen/
		*
This directory & it's contents are only important if you are using the 'seen' 
module (included & loaded by default) to keep track of who says what when, and 
find out when the last time a user said anything was.
	
================================
SphereBot by cmantito (Kevin Leacock, http://cmantito.com)
with modules by celti (Patrick Burroughs, http://www.celti.be)

This is an ItchyCode Production >.<
http://itchycode.double0.net