uppercut 0.7.1

data/README.textile

@@ -0,0 +1,151 @@
+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.)
+
+There are also event callbacks for agents.  These events are based on XMPP presence messages.  So, as of this writing,
+the list of allowed callbacks is: signon, signoff, subscribe, unsubscribe, subscription_approval, subscription_denial,
+status_change, and status_message_change.
+
+You can use these callbacks as follows:
+
+<pre>
+  <code>
+    class CoolAgent < Uppercut::Agent
+      on :subscribe do |c|
+        c.send 'Hey dude, thanks for subscribing!'
+      end
+
+      on :signoff do |c|
+        puts "LOG: #{c.to} signed off."
+      end
+    end
+  </code>
+</pre>
+
+Some callbacks only work if the user allows the agent to subscribe to their presence notifications.  This happens
+automatically when a user subscribes to your agent.  (Depending on their client) they'll be presented with a choice
+to authorize or deny the subscription.  You can catch their answer with the 'subscription_approval' and 'subscription_denial'
+callbacks.  Without their approving the subscription, your 'signon', 'signoff', 'status_change', and 'status_message_change'
+callbacks will not be fired by them.  I suggest using the 'subscription_denial' callback to inform them of that.
+
+
+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 ...

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+patch: 1
+major: 0
+minor: 7

data/examples/basic_agent.rb

@@ -0,0 +1,28 @@
+class BasicNotifier < Uppercut::Notifier
+  notifier :basic do |n,data|
+    n.to 'tyler@codehallow.com'
+    n.send 'Hey kid.'
+  end
+end
+
+class BasicAgent < Uppercut::Agent
+  command 'date' do |m|
+    m.send `date`
+  end
+  
+  command /^cat (.*)/ do |m,rest|
+    m.send File.read(rest)
+  end
+  
+  command 'report' do |m|
+    m.send 'Hostname: ' + `hostname`
+    m.send 'Running as: ' + ENV['USER']
+  end
+  
+  command 'dangerous' do |c|
+    c.send "Are you sure?!"
+    c.wait_for do |reply|
+      c.send %w(yes y).include?(reply.downcase) ? "Okay!  Done boss!" : "Cancelled!"
+    end
+  end
+end

data/examples/personal.rb

@@ -0,0 +1,42 @@
+require 'rubygems'
+require 'uppercut'
+require 'yahoo-weather'
+require 'feed_tools'
+
+class PersonalAgent < Uppercut::Agent
+  def get_weather
+    @weather_client ||= YahooWeather::Client.new
+    @weather_client.lookup_location('94102') # lookup by zipcode
+  end
+
+  def get_news
+    FeedTools::Feed.open('feed://www.nytimes.com/services/xml/rss/nyt/HomePage.xml')
+  end
+
+  command 'weather' do |c,args|
+    weather = get_weather
+    c.send "#{weather.title}\n#{weather.condition.temp} degrees\n#{weather.condition.text}"
+  end
+
+  command 'forecast' do |c,args|
+    response = get_weather
+    msg = "#{response.forecasts[0].day} - #{response.forecasts[0].text}. "
+    msg << "High: #{response.forecasts[0].high} Low: #{response.forecasts[0].low}\n"
+    msg << "#{response.forecasts[1].day} - #{response.forecasts[1].text}. "
+    msg << "High: #{response.forecasts[1].high} Low: #{response.forecasts[1].low}\n"
+    c.send msg
+  end
+
+  command 'news' do |c,args|
+    msg = get_news.items[0,5].map { |item|
+      "#{item.title}\n#{item.link}"
+    }.join("\n\n")
+    c.send msg
+  end
+end
+
+if $0 == __FILE__
+  agent = PersonalAgent.new('reminder@drmcawesome.com/PersonalAgent','password')
+  agent.listen
+  sleep
+end

data/lib/uppercut.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'xmpp4r'
+require 'xmpp4r/roster'
+
+%w(base agent notifier message conversation).each do |mod|
+  require File.join(File.dirname(__FILE__), "uppercut/#{mod}")
+end
+

data/lib/uppercut/agent.rb

@@ -0,0 +1,223 @@
+class Uppercut
+  class Agent < Base
+    VALID_CALLBACKS = [:signon, :signoff, :subscribe, :unsubscribe, :subscription_approval,
+                       :subscription_denial, :status_change, :status_message_change]
+
+    class << self
+      # Define a new command for the agent.
+      # 
+      # The pattern can be a String or a Regexp.  If a String is passed, it
+      # will dispatch this command only on an exact match.  A Regexp simply
+      # must match.
+      #
+      # There is always at least one argument sent to the block.  The first
+      # is a always an Uppercut::Message object, which can be used to reply
+      # to the sender.  The rest of the arguments to the block correspond to
+      # any captures in the pattern Regexp. (Does not apply to String 
+      # patterns).
+      def command(pattern,&block)
+        @@patterns ||= []
+        g = gensym
+        @@patterns << [pattern,g]
+        define_method(g, &block)
+      end
+
+      # Define a callback for specific presence events.
+      #
+      # At the moment this is only confirmed to work with :subscribe and :unsubscribe, but it may work with other types as well.
+      # Example:
+      #
+      # on :subscribe do |conversation|
+      #   conversation.send "Welcome! Send 'help' for instructions."
+      # end
+      #
+      def on(type, &block)
+        raise 'Not a valid callback' unless VALID_CALLBACKS.include?(type)
+        define_method("__on_#{type.to_s}") { |conversation| block[conversation] }
+      end
+
+      private
+
+      def gensym
+        ('__uc' + (self.instance_methods.grep(/^__uc/).size).to_s.rjust(8,'0')).intern
+      end
+    end
+
+    DEFAULT_OPTIONS = { :connect => true }
+    
+    # Create a new instance of an Agent, possibly connecting to the server.
+    #
+    # user should be a String in the form: "user@server/Resource".  pw is
+    # simply the password for this account.  The final, and optional, argument
+    # is a boolean which controls whether or not it will attempt to connect to
+    # the server immediately.  Defaults to true.
+    def initialize(user,pw,options={})
+      options = DEFAULT_OPTIONS.merge(options)
+      
+      @user = user
+      @pw = pw
+      connect if options[:connect]
+      listen if options[:listen]
+      
+      @allowed_roster = options[:roster]
+      @redirects = {}
+    end
+    
+    
+    def inspect #:nodoc:
+      "<Uppercut::Agent #{@user} " +
+      "#{listening? ? 'Listening' : 'Not Listening'}:" +
+      "#{connected? ? 'Connected' : 'Disconnected'}>"
+    end
+
+    # Makes an Agent instance begin listening for incoming messages and
+    # subscription requests.
+    #
+    # Current listen simply eats any errors that occur, in the interest of
+    # keeping the remote agent alive.  These should be logged at some point
+    # in the future. Pass debug as true to prevent this behaviour.
+    #
+    # Calling listen fires off a new Thread whose sole purpose is to listen
+    # for new incoming messages and then fire off a new Thread which dispatches
+    # the message to the proper handler.
+    def listen
+      connect unless connected?
+
+      @listen_thread = Thread.new {
+        @client.add_message_callback do |message|
+          log_and_continue do
+            next if message.body.nil?
+            next unless allowed_roster_includes?(message.from)
+            dispatch message
+          end
+        end
+
+        @roster ||= Jabber::Roster::Helper.new(@client)
+        @roster.add_presence_callback do |item, old_presence, new_presence|
+          # Callbacks:
+          # post-subscribe initial stuff (oldp == nil)
+          # status change: (oldp.show != newp.show)
+          # status message change: (oldp.status != newp.status)
+
+          log_and_continue do
+            if old_presence.nil? && new_presence.type == :unavailable
+              dispatch_presence :signoff, new_presence
+            elsif old_presence.nil?
+              # do nothing, we don't care
+            elsif old_presence.type == :unavailable && new_presence
+              dispatch_presence :signon, new_presence
+            elsif old_presence.show != new_presence.show
+              dispatch_presence :status_change, new_presence
+            elsif old_presence.status != new_presence.status
+              dispatch_presence :status_message_change, new_presence
+            end
+          end
+        end
+        @roster.add_subscription_request_callback do |item,presence|
+          # Callbacks:
+          # someone tries to subscribe (presence.type == 'subscribe')
+
+          log_and_continue do
+            case presence.type
+            when :subscribe
+              next unless allowed_roster_includes?(presence.from)
+              @roster.accept_subscription(presence.from)
+              @roster.add(presence.from, nil, true)
+              dispatch_presence :subscribe, presence
+            end
+          end
+        end
+        @roster.add_subscription_callback do |item, presence|
+          # Callbacks:
+          # user allows agent to subscribe to them (presence.type == 'subscribed')
+          # user denies agent subscribe request (presence.type == 'unsubscribed')
+          # user unsubscribes from agent (presence.type == 'unsubscribe')
+
+          log_and_continue do
+            case presence.type
+            when :subscribed
+              dispatch_presence :subscription_approval, presence
+            when :unsubscribed
+              # if item.subscription != :from, it's not a denial... it's just an unsub
+              dispatch_presence(:subscription_denial, presence) if item.subscription == :from
+            when :unsubscribe
+              dispatch_presence :unsubscribe, presence
+            end
+          end
+        end
+        sleep
+      }
+    end
+
+    # Stops the Agent from listening to incoming messages.
+    #
+    # Simply kills the thread if it is running.
+    def stop
+      @listen_thread.kill if listening?
+    end
+
+    # True if the Agent is currently listening for incoming messages.
+    def listening?
+      @listen_thread && @listen_thread.alive?
+    end
+    
+    def redirect_from(contact,&block)
+      @redirects[contact] ||= []
+      @redirects[contact].push block
+    end
+    
+    attr_accessor :allowed_roster, :roster
+
+    private
+
+    def log_and_continue
+      yield
+    rescue => e
+      log e
+      raise if @debug
+    end
+
+    def dispatch(msg)
+      bare_from = msg.from.bare
+      block = @redirects[bare_from].respond_to?(:shift) && @redirects[bare_from].shift
+      return block[msg.body] if block
+
+      captures = nil
+      pair = @@patterns.detect { |pattern,method| captures = matches?(pattern,msg.body) }
+      if pair
+        pattern, method = pair if pair
+        send method, Conversation.new(msg.from,self), captures
+      end
+    end
+
+    def dispatch_presence(type, presence)
+      handler = "__on_#{type}"
+      self.send(handler, Conversation.new(presence.from, self), presence) if respond_to?(handler)
+    end
+
+    def __ucDefault(msg)
+      Message.new(msg.from,self).send("I don't know what \"#{msg.body}\" means.")
+    end
+
+    def matches?(pattern,msg)
+      captures = nil
+      case pattern
+      when String
+        captures = [] if pattern == msg
+      when Regexp
+        match_data = pattern.match(msg)
+        captures = match_data.captures if match_data
+      end
+      captures
+    end
+
+    def allowed_roster_includes?(jid)
+      return true unless @allowed_roster
+      
+      jid = jid.to_s
+      return true if @allowed_roster.include?(jid)
+      return true if @allowed_roster.include?(jid.sub(/\/[^\/]+$/,''))
+    end
+
+  end
+end

data/lib/uppercut/base.rb

@@ -0,0 +1,90 @@
+class Uppercut
+  class Base
+    def stanza(msg) #:nodoc:
+      return false unless connected?
+      send! msg
+    end
+
+    # Attempt to connect to the server, if not already connected.
+    #
+    # Raises a simple RuntimeError if it fails to connect.  This should be
+    # changed eventually to be more useful.
+    def connect
+      return if connected?
+      connect!
+      raise 'Failed to connected' unless connected?
+      present!
+    end
+
+    # Disconnects from the server if it is connected.
+    def disconnect
+      disconnect! if connected?
+    end
+
+    # Disconnects and connects to the server.
+    def reconnect
+      disconnect
+      connect
+    end
+
+    attr_reader :client, :roster
+    
+    # True if the Agent is currently connected to the Jabber server.
+    def connected?
+      @client.respond_to?(:is_connected?) && @client.is_connected?
+    end
+    
+    private
+    
+    def connect!
+      @connect_lock ||= Mutex.new
+      return if @connect_lock.locked?
+      
+      client = Jabber::Client.new(@user)
+      
+      @connect_lock.lock
+
+      client.connect
+      client.auth(@pw)
+      @client = client
+      
+      @connect_lock.unlock
+    end
+
+    def disconnect!
+      @client.close if connected?
+      @client = nil
+    end
+    
+    def present!
+      send! Jabber::Presence.new(nil,"Available")
+    end
+    
+    # Taken directly from xmpp4r-simple (thanks Blaine!)
+    def send!(msg)
+      attempts = 0
+      begin
+        attempts += 1
+        @client.send(msg)
+      rescue Errno::EPIPE, IOError => e
+        sleep 1
+        disconnect!
+        connect!
+        retry unless attempts > 3
+        raise e
+      rescue Errno::ECONNRESET => e
+        sleep (attempts^2) * 60 + 60
+        disconnect!
+        connect!
+        retry unless attempts > 3
+        raise e
+      end
+    end
+
+    def log(error)
+      # todo
+      p error
+    end
+
+  end
+end

data/lib/uppercut/conversation.rb

@@ -0,0 +1,28 @@
+class Uppercut
+  class Conversation < Message
+    attr_reader :to
+
+    def initialize(to,base) #:nodoc:
+      @to = to
+      super base
+    end
+    
+    # Wait for another message from this contact.
+    #
+    # Expects a block which should receive one parameter, which will be a
+    # String.
+    #
+    # One common use of _wait_for_ is for confirmation of a sensitive action.
+    #
+    #     command('foo') do |c|
+    #       c.send 'Are you sure?'
+    #       c.wait_for do |reply|
+    #         do_it if reply.downcase == 'yes'
+    #       end
+    #     end
+    def wait_for(&block)
+      @base.redirect_from(@to.bare,&block)
+    end
+
+  end
+end

data/lib/uppercut/message.rb

@@ -0,0 +1,18 @@
+class Uppercut
+  class Message
+    attr_accessor :to, :message
+
+    def initialize(base) #:nodoc:
+      @base = base
+    end
+
+    # Send a blob of text.
+    def send(body=nil)
+      msg = Jabber::Message.new(@to)
+      msg.type = :chat
+      msg.body = body || @message
+      @base.stanza(msg)
+    end
+  end
+end
+

data/lib/uppercut/notifier.rb

@@ -0,0 +1,64 @@
+class Uppercut
+  class Notifier < Base
+    class << self
+      @@notifiers = []
+      
+      def notifier(name,&block)
+        @@notifiers << name
+        define_method(name, &block)
+      end
+    end
+
+    def notify(name,data=nil)
+      return false unless connected?
+      return nil unless @@notifiers.include?(name)
+
+      send(name,Message.new(self),data)
+    end
+
+    def initialize(user,pw,options={})
+      options = DEFAULT_OPTIONS.merge(options)
+
+      initialize_queue options[:starling], options[:queue]
+      
+      @user = user
+      @pw = pw
+      connect if options[:connect]
+      listen if options[:listen]
+    end
+
+    DEFAULT_OPTIONS = { :connect => true }
+    
+    def listen
+      connect unless connected?
+
+      @listen_thread = Thread.new {
+        loop { notify @starling.get(@queue) }
+      }
+    end
+
+    def stop
+      @listen_thread.kill if listening?
+    end
+    
+    def listening?
+      @listen_thread && @listen_thread.alive?
+    end
+
+    def inspect #:nodoc:
+      "<Uppercut::Notifier #{@user} " +
+      "#{listening? ? 'Listening' : 'Not Listening'} " + 
+      "#{connected? ? 'Connected' : 'Disconnected'}>"
+    end
+
+    private
+
+    def initialize_queue(server,queue)
+      return unless queue && server      
+      require 'starling'
+      @queue = queue
+      @starling = Starling.new(server)
+    end
+
+  end
+end

data/spec/agent_spec.rb

@@ -0,0 +1,278 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe Uppercut::Agent do
+  before :each do
+    @agent = TestAgent.new('test@foo.com', 'pw', :connect => false)
+  end
+  
+  describe :new do
+    it "connects by default" do
+      agent = Uppercut::Agent.new('test@foo','pw')
+      agent.should be_connected
+    end
+
+    it "does not connect by default with :connect = false" do
+      agent = Uppercut::Agent.new('test@foo','pw', :connect => false)
+      agent.should_not be_connected
+    end
+    
+    it "starts to listen with :listen = true" do
+      agent = Uppercut::Agent.new('test@foo','pw', :listen => true)
+      agent.should be_listening
+    end
+
+    it "initializes @redirects with a blank hash" do
+      agent = Uppercut::Agent.new('test@foo','pw', :connect => false)
+      agent.instance_eval { @redirects }.should == {}
+    end
+
+    it "populates @pw and @user" do
+      agent = Uppercut::Agent.new('test@foo','pw')
+      agent.instance_eval { @pw }.should == 'pw'
+      agent.instance_eval { @user }.should == 'test@foo'
+    end
+    
+    it "populates @allowed_roster with :roster option" do
+      jids = %w(bob@foo fred@foo)
+      agent = Uppercut::Agent.new('test@foo','pw', :roster => jids)
+      agent.instance_eval { @allowed_roster }.should == jids
+    end
+  end
+  
+  describe :connect do
+    it "does not try to connect if already connected" do
+      @agent.connect
+      old_client = @agent.client
+
+      @agent.connect
+      (@agent.client == old_client).should == true
+    end
+    
+    it "connects if disconnected" do
+      @agent.should_not be_connected
+
+      old_client = @agent.client
+      
+      @agent.connect
+      (@agent.client == old_client).should_not == true
+    end
+    
+    it "sends a Presence notification" do
+      @agent.connect
+      @agent.client.sent.first.class.should == Jabber::Presence
+    end
+  end
+  
+  describe :disconnect do
+    it "does not try to disconnect if not connected" do
+      @agent.client.should be_nil
+      @agent.instance_eval { @client = :foo }
+      
+      @agent.disconnect
+      @agent.client.should == :foo
+    end
+    
+    it "sets @client to nil" do
+      @agent.connect
+      @agent.client.should_not be_nil
+      
+      @agent.disconnect
+      @agent.client.should be_nil
+    end
+  end
+  
+  describe :reconnect do
+    it "calls disconnect then connect" do
+      @agent.should_receive(:disconnect).once.ordered
+      @agent.should_receive(:connect).once.ordered
+
+      @agent.reconnect
+    end
+  end
+  
+  describe :connected? do
+    it "returns true if client#is_connected? is true" do
+      @agent.connect
+      @agent.client.instance_eval { @connected = true }
+      @agent.should be_connected
+    end
+  end
+  
+  describe :listen do
+    it "connects if not connected" do
+      @agent.listen
+      @agent.should be_connected
+    end
+
+    it "spins off a new thread in @listen_thread" do
+      @agent.listen
+      @agent.instance_eval { @listen_thread.class }.should == Thread
+    end
+    
+    it "creates a receive message callback" do
+      @agent.listen
+      @agent.client.on_message.class.should == Proc
+    end
+    
+    it "creates a subscription request callback" do
+      @agent.listen
+      @agent.roster.on_subscription_request.class.should == Proc
+    end
+    
+    it "calls dispatch when receving a message" do
+      @agent.listen
+      @agent.should_receive(:dispatch)
+      @agent.client.receive_message("foo@bar.com","test")
+    end
+
+    describe 'presence callbacks' do
+      it 'processes :signon presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_signon
+        new_presence = Jabber::Presence.new(nil,nil)
+        old_presence = Jabber::Presence.new(nil,nil)
+        old_presence.type = :unavailable
+
+        @agent.roster.receive_presence(Jabber::Roster::Helper::RosterItem.new, old_presence, new_presence)
+      end
+
+      it 'processes :signoff presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_signoff
+        presence = Jabber::Presence.new(nil,nil)
+        presence.type = :unavailable
+
+        @agent.roster.receive_presence(Jabber::Roster::Helper::RosterItem.new, nil, presence)
+      end
+
+      it 'processes :status_change presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_status_change
+
+        old_presence = Jabber::Presence.new(nil,nil)
+        new_presence = Jabber::Presence.new(nil,nil)
+        new_presence.show = :away
+
+        @agent.roster.receive_presence(Jabber::Roster::Helper::RosterItem.new, old_presence, new_presence)
+      end
+
+      it 'processes :status_message_change presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_status_message_change
+
+        old_presence = Jabber::Presence.new(nil,nil)
+        old_presence.status = 'chicka chicka yeaaaaah'
+
+        new_presence = Jabber::Presence.new(nil,nil)
+        new_presence.status = 'thom yorke is the man'
+
+        @agent.roster.receive_presence(Jabber::Roster::Helper::RosterItem.new, old_presence, new_presence)
+      end
+
+      it 'processes :subscribe presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_subscribe
+        @agent.roster.should_receive :add
+        @agent.roster.should_receive :accept_subscription
+
+        presence = Jabber::Presence.new(nil,nil)
+        presence.type = :subscribe
+
+        @agent.roster.receive_subscription_request(Jabber::Roster::Helper::RosterItem.new, presence)
+      end
+
+      it 'processes :subscription_approval presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_subscription_approval
+
+        presence = Jabber::Presence.new(nil,nil)
+        presence.type = :subscribed
+
+        @agent.roster.receive_subscription(Jabber::Roster::Helper::RosterItem.new, presence)
+      end
+
+      it 'processes :subscription_denial presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_subscription_denial
+
+        presence = Jabber::Presence.new(nil,nil)
+        presence.type = :unsubscribed
+
+        item = Jabber::Roster::Helper::RosterItem.new
+        item.subscription = :from
+
+        @agent.roster.receive_subscription(item, presence)
+      end
+
+      it 'processes :unsubscribe presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_unsubscribe
+
+        presence = Jabber::Presence.new(nil,nil)
+        presence.type = :unsubscribe
+
+        @agent.roster.receive_subscription(Jabber::Roster::Helper::RosterItem.new, presence)
+      end
+    end
+  end
+  
+  describe :stop do
+    it "kills the @listen_thread" do
+      @agent.listen
+      @agent.instance_eval { @listen_thread.alive? }.should == true
+      
+      @agent.stop
+      @agent.instance_eval { @listen_thread.alive? }.should_not == true
+    end
+  end
+  
+  describe :listening? do
+    it "returns true if @listen_thread is alive" do
+      @agent.listen
+      @agent.instance_eval { @listen_thread.alive? }.should == true
+      @agent.should be_listening
+    end
+    
+    it "returns false if @listen_thread is not alive" do
+      @agent.listen
+      @agent.stop
+      @agent.should_not be_listening
+    end
+    
+    it "returns false if @listen_thread has not been set" do
+      @agent.should_not be_listening
+    end
+  end
+
+  describe :dispatch_presence do
+    it 'calls the correct callback' do
+      @agent.listen
+      @agent.should_receive(:__on_subscribe)
+
+      presence = Jabber::Presence.new(nil,nil)
+      @agent.send(:dispatch_presence, :subscribe, presence)
+    end
+  end
+  
+  describe :dispatch do
+    it "calls the first matching command" do
+      msg = Jabber::Message.new(nil)
+      msg.body = 'hi'
+      msg.from = Jabber::JID.fake_jid
+            
+      @agent.send(:dispatch, msg)
+      @agent.instance_eval { @called_hi_regex }.should_not == true
+      @agent.instance_eval { @called_hi }.should == true
+    end
+    
+    it "matches by regular expression" do
+      msg = Jabber::Message.new(nil)
+      msg.body = 'high'
+      msg.from = Jabber::JID.fake_jid
+      
+      @agent.send(:dispatch, msg)
+      @agent.instance_eval { @called_hi }.should_not == true
+      @agent.instance_eval { @called_hi_regex }.should == true
+    end
+  end
+end

data/spec/conversation_spec.rb

@@ -0,0 +1,14 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+
+describe Uppercut::Conversation do
+  before(:each) do
+    @conv = Uppercut::Conversation.new('test@foo.com', nil)
+  end
+  
+  describe :contact do
+    it "should have a contact method" do
+      @conv.should.respond_to?(:contact)
+    end
+  end
+end

data/spec/jabber_stub.rb

@@ -0,0 +1,121 @@
+Object.send(:remove_const, :Jabber)
+class Jabber
+  class Client
+    def initialize(user)
+      @user = user
+    end
+    
+    def connect
+      @connected = true
+    end
+    
+    def auth(pw)
+      @pw = pw
+    end
+    
+    def is_connected?
+      @connected
+    end
+    
+    def close
+      @connected = nil
+    end
+    
+    attr_reader :sent
+    def send(msg)
+      @sent ||= []
+      @sent << msg
+    end
+    
+    attr_reader :on_message
+    def add_message_callback(&block)
+      @on_message = block
+    end
+
+
+    
+    # TESTING HELPER METHODS
+    
+    def receive_message(from,body,type=:chat)
+      msg = Message.new(nil)
+      msg.type = type
+      msg.body = body
+      msg.from = from
+      @on_message[msg]
+    end
+  end
+  
+  class Presence
+    attr_accessor :from, :type, :show, :status
+
+    def initialize(a,b)
+    end
+  end
+  
+  class Message
+    attr_accessor :type, :body, :from
+    def initialize(to)
+      @to = to
+    end
+  end
+  
+  class Roster
+    class Helper
+      class RosterItem
+        attr_accessor :subscription
+      end
+
+      def initialize(client)
+        @client = client
+      end
+      
+      def accept_subscription(a)
+      end
+
+      def add(a)
+      end
+   
+      attr_reader :on_subscription_request
+      def add_subscription_request_callback(&block)
+        @on_subscription_request = block
+      end
+
+      def add_presence_callback(&block)
+        @on_presence = block
+      end
+
+      def add_subscription_callback(&block)
+        @on_subscription = block
+      end
+
+      # TESTING HELPER METHODS
+
+      def receive_presence(item, old_presence, new_presence)
+        @on_presence[item, old_presence, new_presence]
+      end
+
+      def receive_subscription(item, presence)
+        @on_subscription[item, presence]
+      end
+
+      def receive_subscription_request(item, presence)
+        @on_subscription_request[item, presence]
+      end
+    end
+  end
+
+  class JID
+    def self.fake_jid
+      new 'foo', 'bar.com', 'baz'
+    end
+
+    def initialize(node,domain,res)
+      @node, @domain, @res = node, domain, res
+    end
+
+    def bare
+      self.class.new @node, @domain, nil
+    end
+  end
+end
+

data/spec/notifier_spec.rb

@@ -0,0 +1,85 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe Uppercut::Notifier do
+  before :each do
+    @notifier = TestNotifier.new('test@foo.com', 'pw', :connect => false)
+  end
+  
+  describe :new do
+    it "connects by default" do
+      notifier = Uppercut::Notifier.new('test@foo','pw')
+      notifier.should be_connected
+    end
+
+    it "does not connect by default with :connect = false" do
+      notifier = Uppercut::Notifier.new('test@foo','pw', :connect => false)
+      notifier.should_not be_connected
+    end
+    
+    it "populates @pw and @user" do
+      notifier = Uppercut::Notifier.new('test@foo','pw')
+      notifier.instance_eval { @pw }.should == 'pw'
+      notifier.instance_eval { @user }.should == 'test@foo'
+    end
+  end
+  
+  describe :connect do
+    it "does not try to connect if already connected" do
+      @notifier.connect
+      old_client = @notifier.client
+
+      @notifier.connect
+      (@notifier.client == old_client).should == true
+    end
+    
+    it "connects if disconnected" do
+      @notifier.should_not be_connected
+
+      old_client = @notifier.client
+      
+      @notifier.connect
+      (@notifier.client == old_client).should_not == true
+    end
+    
+    it "sends a Presence notification" do
+      @notifier.connect
+      @notifier.client.sent.first.class.should == Jabber::Presence
+    end
+  end
+  
+  describe :disconnect do
+    it "does not try to disconnect if not connected" do
+      @notifier.client.should be_nil
+      @notifier.instance_eval { @client = :foo }
+      
+      @notifier.disconnect
+      @notifier.client.should == :foo
+    end
+    
+    it "sets @client to nil" do
+      @notifier.connect
+      @notifier.client.should_not be_nil
+      
+      @notifier.disconnect
+      @notifier.client.should be_nil
+    end
+  end
+  
+  describe :reconnect do
+    it "calls disconnect then connect" do
+      @notifier.should_receive(:disconnect).once.ordered
+      @notifier.should_receive(:connect).once.ordered
+
+      @notifier.reconnect
+    end
+  end
+  
+  describe :connected? do
+    it "returns true if client#is_connected? is true" do
+      @notifier.connect
+      @notifier.client.instance_eval { @connected = true }
+      @notifier.should be_connected
+    end
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'spec'
+require 'set'
+
+$: << File.dirname(__FILE__)
+$: << File.join(File.dirname(__FILE__),'../lib')
+
+# Loads uppercut and jabber
+require 'uppercut'
+
+# Unloads jabber, replacing it with a stub
+require 'jabber_stub'
+
+class TestAgent < Uppercut::Agent
+  command 'hi' do |c,args|
+    c.instance_eval { @base.instance_eval { @called_hi = true } }
+    c.send 'called hi'
+  end
+  
+  command /^hi/ do |c,args|
+    c.instance_eval { @base.instance_eval { @called_hi_regex = true } }
+    c.send 'called high regex'
+  end
+  
+  command /(good)?bye/ do |c,args|
+    @called_goodbye = true
+    c.send args.first ? "Good bye to you as well!" : "Rot!"
+  end
+  
+  command 'wait' do |c,args|
+    @called_wait = true
+    c.send 'Waiting...'
+    c.wait_for do |reply|
+      @called_wait_block = true
+      c.send 'Hooray!'
+    end
+  end
+
+  Uppercut::Agent::VALID_CALLBACKS.each do |cb|
+    on(cb) { }
+  end
+end
+
+class TestNotifier < Uppercut::Notifier
+  notifier :foo do |m,data|
+    m.to = 'foo@bar.com'
+    m.send 'Foo happened!'
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: uppercut
+version: !ruby/object:Gem::Version 
+  version: 0.7.1
+platform: ruby
+authors: 
+- Tyler McMullen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-12-27 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: xmpp4r
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A DSL for writing agents and notifiers for Jabber.
+email: tbmcmullen@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.textile
+- VERSION.yml
+- lib/uppercut/agent.rb
+- lib/uppercut/base.rb
+- lib/uppercut/conversation.rb
+- lib/uppercut/message.rb
+- lib/uppercut/notifier.rb
+- lib/uppercut.rb
+- spec/agent_spec.rb
+- spec/conversation_spec.rb
+- spec/jabber_stub.rb
+- spec/notifier_spec.rb
+- spec/spec_helper.rb
+- examples/basic_agent.rb
+- examples/personal.rb
+has_rdoc: true
+homepage: http://github.com/tyler/uppercut
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: A DSL for writing agents and notifiers for Jabber.
+test_files: []
+