safubot 0.0.2 → 0.0.3

data/doc/top-level-namespace.html

@@ -94,7 +94,7 @@
 </div>
     
     <div id="footer">
-  Generated on Mon Nov 28 20:20:04 2011 by 
+  Generated on Tue Nov 29 11:44:04 2011 by 
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.7.3 (ruby-1.9.2).
 </div>

data/lib/safubot/bot.rb

@@ -1,10 +1,14 @@
 #!/usr/bin/env ruby
 
 module Safubot
+  ##
+  # Pretty-printing of Exceptions and their backtraces.
+  # @param e An Exception to print.
   def error_report(e)
 	"#{e.inspect}\n#{e.backtrace.join("\n\t")}"
   end
 
+  ##
   # Defines elements of the input queue, agnostic of the transfer medium.
   # May be extended by service-specific modules.
   class Request
@@ -18,11 +22,9 @@ module Safubot
 	belongs_to :user, :polymorphic => true
 	many :responses, :class_name => "Safubot::Response"
 	timestamps!
-
-	attr_accessor :callback # If a callback is set, responses will be sent to it instead of Response.
-
   end
 
+  ##
   # Defines elements of the output queue, agnostic of the transfer medium.
   # May be extended by service-specific modules.
   class Response
@@ -35,12 +37,19 @@ module Safubot
 	timestamps!
   end
 
+  ##
+  # The main event-processing class. You are encouraged to
+  # inherit from this class when building your own bot, but
+  # delegation is also entirely feasible.
   class Bot
 	include Evented
 
 	attr_reader :opts, :twitter, :xmpp
 
+	##
 	# Records an error and emits a corresponding :request_error event.
+	# @param req The Request for which the error was encountered.
+	# @param e The caught Exception.
 	def request_error(req, e)
 	  Log.error "Error processing #{req.source.class} '#{req.text}': #{e}\n#{e.backtrace.join("\n\t")}"
 	  req.errors[Time.now] = e
@@ -48,7 +57,9 @@ module Safubot
 	  emit(:request_error, req, e)
 	end
 
+	## 
 	# Processes an individual request (synchronously).
+	# @param req An unprocessed Request.
 	def process_request(req)
 	  begin
 		emit(:request, req)
@@ -60,7 +71,9 @@ module Safubot
 	  end
 	end
 
+	##
 	# Performs appropriate dispatch operation for response type.
+	# @param resp An undispatched Response.
 	def dispatch(resp)
 	  begin
 		source = resp.request.source
@@ -98,6 +111,7 @@ module Safubot
 	  end
 	end
 
+	##
 	# Adds a response to the queue.
 	# @param req Request to respond to.
 	# @param text Contents of the response.
@@ -117,11 +131,12 @@ module Safubot
 	  Response.where(:dispatched => false).each(&method(:dispatch))
 	end
 	
-	# Wraps EM::defer with error handling and response pushing for the given request.
+	##
+	# Wraps Thread.new with error handling and response pushing for the given request.
 	# @param req The Request being processed.
 	# @param blk The operation to be performed in a separate thread.
 	def concurrently(req, &blk)
-	  EM::defer do
+	  Thread.new do
 		begin
 		  blk.call
 		rescue Exception => e
@@ -132,20 +147,24 @@ module Safubot
 	  end
 	end
 
+	# Runs an initial request-processing loop and then forks the streaming processes.
+	def run_nowait
+	  pull; process; push
+	  @twitter.run if @twitter
+	  @xmpp.run if @xmpp
+	end
+
+	# Calls run_nowait and then waits for all child processes.
 	def run
-	  #EventMachine::run do
-		pull; process; push
-		@twitter.run if @twitter
-		@xmpp.run if @xmpp
-		begin
-		  Process.waitall
-		rescue Interrupt
-		  stop
-		end
-	  #end
+	  run_nowait
+	  begin
+		Process.waitall
+	  rescue Interrupt
+		stop
+	  end
 	end
 
-	# Shuts down the event loop.
+	# Shuts down the streaming processes.
 	def stop
 	  @twitter.stop if @twitter
 	  @xmpp.stop if @xmpp

data/lib/safubot/evented.rb

@@ -7,7 +7,7 @@ module Safubot
 	#
 	# 	{ :evid => Symbol, :id => Symbol, :repeat => Boolean, :proc => Proc }
 	#
-	# See {on}[rdoc-ref:Safubot::Evented#on] and {once}[rdoc-ref:Safubot::Evented#once] for sugar.
+	# See Evented#on and Evented#once for sugar.
 	def bind(evid, handler)
 	  @handlers ||= {}
 	  @handlers[evid] ||= {}

data/lib/safubot/log.rb

@@ -1,6 +1,7 @@
 require 'logger'
 
 module Safubot
+  # Log is a simple wrapper for stdout and file-writing Logger instances.
   module Log
     class << self
       attr_reader :path
@@ -11,6 +12,7 @@ module Safubot
         @filelog = Logger.new(str)
       end
 
+	  # Dispatch method calls to Logger objects.
       def method_missing(method, *args)
         @stdlog ||= Logger.new(STDOUT)
         @stdlog.send(method, *args)

data/lib/safubot/test_helper.rb

@@ -15,8 +15,10 @@ module Safubot
 	end
   end
 
+  # Helpful methods for testing either via RSpec or IRB.
   module Test
     class << self
+	  # Switches to the "safubot_testing" database and clears all data.
       def clean_environment
 		MongoMapper.database = "safubot_testing"
         Request.destroy_all
@@ -27,14 +29,16 @@ module Safubot
         $bot = Safubot::Bot.new(:database => "safubot_testing")
       end
 
+	  # Creates a Query-sourced testing Request.
+	  # @param text The body of the Request.
 	  def request(text)
 		Query.create(:user => KnownUser.by_name('testing'), :text => text).make_request
 	  end
     end
   end
 
+  # Generic mediumless Request source.
   class Query
-    # Generic mediumless Request source.
     include MongoMapper::Document
     safe
 
@@ -44,6 +48,7 @@ module Safubot
 
 	one :request, :class_name => "Safubot::Request"
 
+	# Find or create a Request sourced from this Query.
     def make_request
 	  self.request || Request.create(:user => self.user, :text => self.text, :source => self)
     end
@@ -51,6 +56,8 @@ module Safubot
 
   class Bot
 	# A generic "respond immediately" interface.
+	# @param text The body of a Request to process.
+	# @param user The user sending the request. Defaults to KnownUser.by_name('testing')
 	def answer(text, user=nil)
 	  user ||= KnownUser.by_name('testing')
 	  query = Query.create(:user => user, :text => text)

data/lib/safubot/twitter.rb

@@ -34,12 +34,13 @@ module Safubot
 	end
   end
 
-  # Extend the Request class with Twitter-related source_type scoping.
   class Request
+	# Extend the Request class with Twitter-related source_type scoping.
 	scope :tweet, :source_type => "Safubot::Twitter::Tweet"
 	scope :dm, :source_type => "Safubot::Twitter::DirectMessage"
   end
 
+  # XMPP-specific functionality.
   module Twitter
 	# Tweet is both a Request source and general-purpose tweet storage.
 	# Mentions are automatically made into Requests, but not timeline tweets.
@@ -54,12 +55,14 @@ module Safubot
 	  one :request, :as => :source, :class_name => "Safubot::Request"
 
 	  class << self
+		##
 		# Quickly look up a Tweet.
 		# @param id The Twitter id.
 		def [](id)
 		  Tweet.where('raw.id' => id).first
 		end
 
+		##
 		# Find or create a Tweet.
 		# @param status An appropriate ::Twitter or ::TweetStream object.
 		def from(status)
@@ -123,6 +126,7 @@ module Safubot
 	  one :request, :as => :source, :class_name => "Safubot::Request"
 
 	  class << self
+		##
 		# Find or create a DirectMessage.
 		# @param message An appropriate ::Twitter or ::TweetStream object.
 		def from(message)
@@ -158,7 +162,9 @@ module Safubot
 
 	  attr_reader :username, :client, :opts, :stream, :pid
 
+	  ##
 	  # Sends a Twitter-sourced Response to the appropriate target.
+	  # @param resp Response to send.
 	  def send(resp)
 		source = resp.request.source
 		if source.is_a?(DirectMessage)
@@ -170,19 +176,25 @@ module Safubot
 		end
 	  end
 
+	  ##
 	  # Emit a request event unless the request is already processed.
+	  # @param req Request to handle.
 	  def handle_request(req)
 		emit(:request, req) unless req.nil? || req.processed
 	  end
 
+	  ##
 	  # Stores a DM and creates a matching Request as needed.
+	  # @param message A raw JSON-derived direct message.
 	  def handle_message(message)
 		return if message.sender.screen_name == @username
 		DirectMessage.from(message).make_request
 	  end
 
+	  ##
 	  # Stores a tweet. If this tweet is directed at us, create a matching Request.
 	  # Otherwise, emit a :timeline event.
+	  # @param status A raw JSON-derived tweet.
 	  def handle_tweet(status)
 		return if status.user.screen_name == @username
 		if status.text.match(/@#{@username}/i)
@@ -222,8 +234,8 @@ module Safubot
 		end
 	  end
 
-	  # Starts our TweetStream client running.
-	  def run
+	  # Initializes the TweetStream client.
+	  def init_stream
 		@stream = TweetStream::Client.new(@opts)
 
 		@stream.on_direct_message do |message|
@@ -239,33 +251,52 @@ module Safubot
 		  end
 		end
 
-		@pid = Process.fork do
-		  begin
-			@stream.userstream do |status|
-			  req = handle_tweet(status)
-			  handle_request(req) if req.is_a? Request
-			end
-		  rescue Exception => e
-			unless e.is_a? Interrupt
-			  Log.error "TweetStream client exited unexpectedly: #{error_report(e)}"
-			  Log.error "Restarting TweetStream client in 5 seconds."
-			  sleep 5; run
-			end
-		  end
+		@stream.on_inited do
+		  Log.info("TweetStream client is online at @#{@username} :3")
+		end
+	  end
 
-		  Log.info("TweetStream client shutdown complete.")
+	  # Runs the TweetStream client.
+	  def run_stream
+		begin
+		  @stream.userstream do |status|
+			req = handle_tweet(status)
+			handle_request(req) if req.is_a? Request
+		  end
+		rescue Exception => e
+		  if e.is_a?(Interrupt) || e.is_a?(SignalException)
+			stop
+		  else
+			Log.error "TweetStream client exited unexpectedly: #{error_report(e)}"
+			Log.error "Restarting TweetStream client in 5 seconds."
+			sleep 5; init_stream; run_stream
+		  end
 		end
+	  end
 
-		Log.info("TweetStream client is online at @#{@username} :3")
+	  # Starts our TweetStream client running in a new process.
+	  def run
+		@pid = Process.fork do
+		  Signal.trap("TERM") { stop }
+		  init_stream
+		  run_stream
+		end
 	  end
 
 	  # Shut down the TweetStream client.
 	  def stop
-		@stream.stop
+		if @stream
+		  @stream.stop
+		  @stream = nil
+		  Log.info("TweetStream client shutdown complete.")
+		else
+		  Process.kill("TERM", @pid) if @pid
+		end
 	  end
 
-	  # Options are passed straight through to ::TweetStream and ::Twitter,
-	  # but the :username is ours and important.
+	  ##
+	  # @param options These are passed straight through to ::TweetStream and 
+	  # ::Twitter, but the :username is ours and important.
 	  def initialize(options={})
 		defaults = { :username => nil,
 					 :consumer_key => nil, :consumer_secret => nil, 

data/lib/safubot/version.rb

@@ -1,3 +1,3 @@
 module Safubot
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/safubot/xmpp.rb

@@ -16,8 +16,8 @@ module Safubot
 	end
   end
 
-  # XMPP-specific extensions to Request.
   class Request
+	# XMPP-specific extensions to Request.
 	scope :xmpp, :source_type => "Safubot::XMPP::Message"
   end
 
@@ -75,7 +75,7 @@ module Safubot
 	  attr_reader :jid, :client, :state, :pid
 
 	  # Sets our Blather::Client event processor running.
-	  def run
+	  def init_blather
 		@client = Blather::Client.setup(@jid, @password)
 
 		@client.register_handler(:ready) do
@@ -95,6 +95,7 @@ module Safubot
 		end
 
 		@client.register_handler(:disconnected) do 
+		  sleep 1 # HACK (Mispy): Give the state a chance to change when we're stopped.
 		  if @state == :running
 			Log.warn("XMPP disconnected; attempting reconnection in 5 seconds.") 
 			sleep 5; @client.connect
@@ -105,26 +106,44 @@ module Safubot
 		  Log.error "Unhandled Blather error: #{error_report(e)}"
 		end
 
-		@pid = Process.fork do
-		  begin
-			EM::run { @client.run }
-		  rescue Exception => e
-			unless e.is_a? Interrupt
-			  Log.error "XMPP client exited unexpectedly: #{error_report(e)}"
-			  Log.error "Restarting XMPP client in 5 seconds."
-			  sleep 5; run
-			end
+
+		@state = :running
+	  end
+
+	  # Runs the Blather client.
+	  def run_blather
+		begin
+		  EM::run { @client.run }
+		rescue Exception => e
+		  if e.is_a?(Interrupt) || e.is_a?(SignalException)
+			stop
+		  else
+			Log.error "XMPP client exited unexpectedly: #{error_report(e)}"
+			Log.error "Restarting XMPP client in 5 seconds."
+			sleep 5; init_blather; run_blather
 		  end
-		  Log.info "XMPP client shutdown complete."
 		end
+	  end
 
-		@state = :running
+	  # Starts our Blather client running in a new process.
+	  def run
+		@pid = Process.fork do
+		  Signal.trap("TERM") { stop }
+		  init_blather
+		  run_blather
+		end
 	  end
 
 	  # Shuts down the Blather client.
 	  def stop
-		@state = :stopped
-		@client.close
+		if @client
+		  @state = :stopped
+		  @client.close
+		  @client = nil
+		  Log.info "XMPP client shutdown complete."
+		elsif @pid
+		  Process.kill("TERM", @pid)
+		end
 	  end
 
 	  def tell(jid, text)

data/safubot.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |s|
   s.platform	= Gem::Platform::RUBY
   s.authors     = ["Jaiden Mispy"]
   s.email       = ["^_^@mispy.me"]
-  s.homepage    = "http://safubot.mispy.me"
-  s.summary     = "A modular, evented chatbot framework. Supports Twitter and XMPP."
-  s.description = "A modular, evented chatbot framework. Supports Twitter and XMPP."
+  s.homepage    = ""
+  s.summary     = "A friendly event-driven chatbot framework. Supports Twitter and XMPP."
+  s.description = "A friendly event-driven chatbot framework. Supports Twitter and XMPP."
 
   s.rubyforge_project = "safubot"