README

= The RubOt Project 

This is an IRC Bot implemented in Ruby using Harry Vangberg's excellent isaac
library available at http://github.com/ichverstehe/isaac. Where isaac is a
library for creating an IRC BOT, this project implements the library to create
one.

The repository name is just a nod to a classic movie franchise. This bot
cannot destroy the Deathstar.

== Technical introduction

If you aren't a Ruby hacker, or just want to use this system, you probably
don't need to read this section. If you want to know generally how it's done,
then read on.

 *ConfigurationModule.rb* is a utility resource that defines some top-level
methods that users of the system probably don't need to know about and it sets
up the environment. Much of the stuff that makes RubOt its own project has
been placed in this file, to keep *RubOt.rb* as clean as possible, so that
users who have created other <tt>Isaac::Bot</tt>s can move some of their code
into it. Among these utilities are configuration file reading and writing, and
the +BotExtensions+ module that is used to _extend_ our Isaac::Bot instance.

The configuration file is stored on disk as a YAML file. The best way to
create a configuration file is to run *RubOt.rb* without one, and a new one
will be generated. Edit the file (jedbotconf.yaml) using a text editor, and
relaunch RubOt. We dislike global variables, so we stuff all the global system
configuration into the <tt>BOT_CONFIG</tt> Global Constant hash. As a plugin
author, the two that are most meaningful are <tt>BOT_CONFIG[:owner_nick]</tt>
and BOT_CONFIG[:bot_nick].

This project _extends_ Isaac::Bot, only minimally. <tt>Isaac::Bot</tt> stores
+Proc+ objects in an <tt>@event[]</tt> data structure using the +on+ method.
It has no mechanism for removing the routines, so I have extended it to add an
+off+ method. This manipulation of the events data structure is what makes it
possible to add plugin loading and unloading.

The remaining functionality is added to the bot either through adding <tt>on
<em>:event</em></tt> Isaac DSL blocks at the bottom of <b>RubOt.rb</b> (doing
things the Isaac way), or by creating subclasses of *PluginBase* to create
loadable plugins (the RubOt way). Note, that the Core plugin contains the
functionality to load and unload modules, and so it is instantiated
differently from any other modules. *PluginBase* is too complicated to explain
in a readme. We intend to provide documentation for it in the source, however,
in the "Creating a Plugin" section, we explain how to use it.

More at: http://rdoc.info/projects/jagipson/isaac-jedi-bot

== Creating a Bot

To personalize RubOt, or to start over, first locate your configuration file
(+jedbotcnf.yaml+ is the default one) and delete it or move it aside. Next run
<tt>$ ruby <em>path/to/</em>RubOt.rb</tt>. It will detect that you have no
configuration and build a file for you. Now, edit +jedbotcnf.yaml+ with your
IRC settings, an relaunch RubOt.

If it's working, then you should see +Connected.+ in the terminal. Your bot is
now logged in. The *Core* plugin is controlled using the *!do* token. In IRC,
send <tt>/msg <em><YourBotName></em> !do help</tt> for quick help.

One other hint: Sometimes, the help you get with the +help+ command will be
different depending on if you are asking for help in a channel, or a private
chat.

== Creating a Plugin
<Not written yet, coming soon>