h1. Uppercut


h2. Overview

Uppercut is a little DSL for writing agents and notifiers which you interact with via your Jabber client.


h2. Making an Agent

You could put together a very simple agent as follows:

<pre>
  <code>
    class BasicAgent < Uppercut::Agent
      command 'date' do |c|
        m.send `date`
      end
  
      command /^cat (.*)/ do |c,rest|
        m.send File.read(rest)
      end
  
      command 'report' do |c|
        m.send 'Hostname: ' + `hostname`
        m.send 'Running as: ' + ENV['USER']
      end
    end
  </code>
</pre>

With the above code, we've created an Agent template of sorts.  It responds to three commands: {date cat report}.
The block which is passed to "command" should always have at least one paramater.  The first parameter will 
always be an Uppercut::Conversation object, which can be used to respond to the user who sent the input.  When passing
a regular expression as the first parameter to "command", all of the _captures_ which the pattern match generates
will also be passed to the block.  This can be seen in the "cat" example above.  There is one capture and it is
passed in as _rest_.

Then to actually put the Agent to work...

<pre>
  <code>
    BasicAgent.new('user@server/resource','password').listen
  </code>
</pre>

This creates a new BasicAgent instance and sends it _listen_ to make it start accepting messages.
Note that by default when an agent is listening, it ignores all errors.  (In the future, I'll have it log them.)


h2. Making a Notifier

<pre>
  <code>
    class BasicNotifier < Uppercut::Notifier
      notifier :error do |m,data|
        m.to 'tbmcmullen@gmail.com'
        m.send "Something in your app blew up: #{data}"
      end
    end
  </code>
</pre>

So, we make a new Notifier class and call a _notifier_ block within it.  This makes a notifier with the name :error, which sends a message to tbmcmullen@gmail.com when it fires.

<pre>
  <code>
    notifier = BasicNotifier.new('user@server/resource','password').connect
    
    notifier.notify :error, 'Sprocket Error!'
  </code>
</pre>

The purpose of a Notifier is just to make a multi-purpose event-driven notification system.  You could use it notify yourself of errors in your Rails app, or ping you when a new comment arrives on your blog, or ... I dunno, something else.

The way I intend a Notifier to be used though is with Starling.  Take the following example...

<pre>
  <code>
    notifier = BasicNotifier.new('user@server','password', :starling => 'localhost:22122', :queue => 'basic')
    notifier.listen
    sleep
  </code>
</pre>

<pre>
  <code>
    require 'starling'
    starling = Starling.new('localhost:22122')
    starling.set 'basic', :error
  </code>
</pre>

In that example, we have the same BasicNotifier.  Except this time, we provide it with information on which Starling queue on which Starling server to monitor.  Meanwhile, in the separate program, we attach to that same Starling server and push a symbol onto that same queue.

In this case, what happens is BasicNotifier sees that symbol and begins processing it, just as if it had been passed in via the #notify method.



h2. Todo


h3. Security

If you intend to use this on an open Jabber network (read: Google Talk) take some precautions.  Agent#new takes an optional list of JIDs that the agent will respond to.

<pre>
  <code>
    BasicAgent.new('user@server/res', 'pw', :roster => ['you@server'])
  </code>
</pre>

The agent created with the above statement will not respond to messages or subscription requests from anyone other than 'you@server'.

h3. Features

Uppercut is currently very thin on features, as it's in its infancy.  Here's a brief list of where I'm
currently intending to take the project:

* send files to and receive files from agents
* improving the way one writes executables (using the Daemons library is best for the moment)
* auto-updating of agents
* I swear I'm going to find a use for MUC
* allow agents to establish communications on their own, rather than being reactionary (think RSS updates)
* ... other stuff that sounds fun to code up ...