safubot 0.0.1 → 0.0.2

data/.yardoc/checksums

@@ -0,0 +1,9 @@
+lib/safubot.rb da2c6f1fa7e7a17064469e0a5409f5dc2a6ec7ab
+lib/safubot/bot.rb a191fb9b972ebf19e4badc110658b64bb02f92ff
+lib/safubot/log.rb 132a7d9090c8c405b409fa12868244eb8de7b15a
+lib/safubot/xmpp.rb 50b683fbfcaef60d07102dd893df0a277c110f89
+lib/safubot/evented.rb 87b6fba0d6e65e5abf09e7606e1fd502713da2e7
+lib/safubot/version.rb 67c555f319499e0bcc596a73152df9f0797da190
+lib/safubot/twitter.rb 4574d47793303bc087f14b7c4bc7b5f0e7c938c7
+lib/safubot/known_user.rb 06960025ae9bf08570ab743f64a7b22ac1687542
+lib/safubot/test_helper.rb 870fe48e4efd009690b8cd8f29203491610ca8bb

data/README.md

@@ -1,16 +1,30 @@
 # safubot - an evented chatbot framework for Ruby
 
+## <a name="overview">Overview</a>
+Safubot is a chatbot framework for Twitter and XMPP which aims to abstract away the idiosyncracies of the underlying APIs, allowing you to focus on writing request-processing logic. Of course, if you want to use  service-specific features (such as responding to timeline tweets) it lets you do that too!
+
 ## <a name="installation">Installation</a>
+	gem install safubot
+
+## <a name="requirements">Requirements</a>
+Safubot uses [MongoDB](http://www.mongodb.org) for storage. It's [easy to install](http://www.mongodb.org/display/DOCS/Quickstart+Unix) and pretty awesome!
 
 ## <a name="documentation">Documentation</a>
+[http://rdoc.info/gems/safubot](http://rdoc.info/gems/safubot)
 
-## <a name="example">Example Usage</a>
+## <a name="example">Sample Usage</a>
 	require 'safubot'
 
 	class NiftyBot < Safubot::Bot
 	  def initialize
+		# Check the MongoMapper docs (http://www.mongomapper.com/documentation/) if you want
+		# to do something more sophisticated than an authless localhost connection.
 		super(:database => "niftybot")
 
+		# To access the underlying delegation targets:
+		# Safubot::Twitter::Bot bot.twitter
+		# ::Twitter::Client bot.twitter.client
+		# ::TweetStream::Client bot.twitter.stream
 		enable_twitter({
 			:username => "niftybot",
 			:consumer_key => CONSUMER_KEY,
@@ -19,11 +33,19 @@
 			:oauth_token_secret => OAUTH_TOKEN_SECRET
 		})
 
+		# Similarly, for XMPP:
+		# Safubot::XMPP::Bot bot.xmpp
+		# ::Blather::Client bot.xmpp.client
 		enable_xmpp({
 			:jid => "niftybot@jabber.org/niftyhost",
 			:password => JABBER_PASSWORD
 		})
 
+		# A Request can be sourced from a:
+		#   * Twitter mention
+		#   * Twitter DM
+		#   * XMPP chat message
+		# The "respond" method will reply using the appropriate medium.
 		on(:request) do |req|
 		  if req.text.match /nifty/i
 			respond req, "Yep, I'm a nifty bot! :3"
@@ -32,6 +54,8 @@
 		  end
 		end
 
+		# Any unhandled errors encountered during request processing
+		# will come through here.
 		on(:request_error) do |req, e|
 		  respond req, "#{e}"
 		end
@@ -41,3 +65,30 @@
 	# You can run this from inside another EventMachine loop if
 	# you don't want it to block indefinitely.
 	NiftyBot.new.run
+
+## <a name="example">Specific Examples</a>
+
+### Find the last processed request from a user
+
+	on(:request) do |req|
+	  req.user.requests.where(:processed => true).sort(:created_at.desc).first
+	end
+
+### Update our twitter account
+
+	@twitter.client.update("Hello there, wonderful, scary world of Twitter! I am so *not* a spambot.")
+
+### Reply to a non-request timeline tweet
+
+	@twitter.on(:timeline) do |tweet|
+	  if tweet.raw['user']['screen_name'] == "unnali"
+		@twitter.reply tweet, "Is HaeSeun OSS yet? :O"
+	  end
+	end
+
+### Start an unprompted conversation with an XMPP user.
+
+	@xmpp.on(:ready) do
+	  @xmpp.tell('^_^@jabber.org', "You'd best be maintaining safubot!")
+	end
+