h1. Marvin

Marvin is a ruby irc framework / library built on top of event machine.
It's been build from scratch to be evented - you build "handlers" which
are called whenever an event occurs.

A single client instance can handle multiple IRC connections (and will
automatically reconnect in the case that a connection is lost). Distributed
support (e.g. 1 client => multiple handler backends) is built in out of
the box on top of DRb.

h2. Getting Started

Starting out with Marvin is simple. You can either go the "edge" route -
cloning from the GitHub repository (in this case, [here](http://github.com/sutto/marvin))
and then running the following:

  $ rake gemspec
  $ gem build marvin.gemspec
  $ sudo gem install marvin.gem

Or, for a generally more stable release you can install it from the GitHub gem
server (requiring Rubygems >= 1.2.0 with the GitHub sources added), by running
the following:

  $ sudo gem install Sutto-marvin
  
Installing the gem will make available a new executable - "+marvin+" - which is
used as an easy way to do a variety of tasks. To get started, you can create
a project located at given path using the following command:

  $ marvin create path-to-my-bot
  
Once that's done, you'll have a blank slate loaded with the default marvin handlers -
+HelloWorld+ (which will respond to any addressed "hello"'s) and an empty debug handler
which you can use for generic debugging. To run the new app, you can use either of the
following:

  $ cd path-to-my-bot && script/client
  
or, alternatively,

  $ marvin client path-to-my-bot
  
There are a couple of options available for the client (as well as the marvin library),
Each of which can be found by appending the "--help" option to the command.

Once your client has been started (assuming the name wasn't taken / it could connect),
simply join the chat room your bot was instructed to join and say the following (substiting
BotNick for the nick name your bot connected with):

  BotNick: hello
  
Or even easier, by PM'ing the bot with:

  hello
  
Assuming all went well, your bot should reply back with something akin to (where YourNick)
if the nickname you connected with):

  YourNick: Hola from process with pid 12342

h2. Distributed Bots

One of the relatively unique features of Marvin is the ability to write bots
which use DRb and Rinda which can grow with relative ease.

It's important to keep in mind that keeping state is discouraged in this case
as it can not be ensured that clients are still active or that you will always
get messages from the same client.

For a start, take a look at the default +config/setup.rb+ file which contains
an example of registering handlers on a distributed client as well as setting
up the distributed handler which needs to be setup on the main client.

By default, the messages will be dispatched to the first discovered tuple
space (using Rinda::RingFinger) and will be of the format:

  [:marvin_format, :your_namespace, :message_name, {:message => "options"}, client_reference]
  
You can change the namespace (which defaults to +:default+) by setting +Marvin::Settings.distributed_namespace+

Running a distributed client requires three things:

* 1 Ring server instance (+script/ring_server+ or +marvin ring_server+ or +marvin rs+)
* 1+ Client instances (+script/client+ or +marvin client+ or +marvin cl+)
* 1+ Distributed Client instances (+script/distributed_client+ or +marvin distributed_client+ or +marvin dc+)

Each of which takes the default options of:
* -v - Be verbose and print to STDOUT if not daemonized
* -level=something - set level, defaults to info
* -d - daemonize the process
* -k - kill all daemonized instances of this specific kind

h2. Example Bots

Coming soon.

h2. Thanks

Thanks go to:

* Jeff Rafter - contributed code and doc changes, now one of the co-developers.
* epitron / halogrium - For the ragel state machine used in Marvin::Parsers::RagelParser
* The creator of Ruby-IRCD - the server component is heavily influenced by / part derivative of said work.