Creating a Twitter Client for OSX in MacRuby

UPDATE: Part Two of this series is now available

Howdy. This is a new series I intend to write on how to create a Twitter client in MacRuby using the Cocoa framework on OSX. There doesn't seem to be a lot of articles around on this subject, so I thought it would be beneficial to the world at large if I chronicled my own journey.

Warning: this is not a "Learning Ruby" guide, if you don't know how to program in Ruby, or have a good Ruby book at hand, then you ain't gonna get too far with this.

I first started by following the original Getting Started with MacRuby tutorial provided by Apple, which, as well as giving you a good introduction to MacRuby, gets you to the starting point for this series - we'll adapt the application you build following that tutorial into our Twitter client, so off you go and follow that. We'll see you back here in half an hour.

---

Welcome back. Now that you've followed the Apple tutorial, you should have an application that contains a table and a button - the next step, and the purpose of this first article, is to add the ability to download data from a url.

There are easy ways to do synchronous url requests, such as NSString.initWithContentsOfURL, but synchronous calls would freeze our UI while we wait for the call to complete, which is bad for the user, so we need to asynchronously request our urls.

A bit of googling found me an article in Objective-C that taught me everything we need to do to achieve our goal, unfortunately it was in Objective-C:
http://cocoawithlove.com/2008/09/cocoa-application-driven-by-http-data.html

Luckily, after searching on the methods used in the Objective-C article, I managed to find some MacRuby code that implemented async url requests, so saved myself a big Cocoa->Ruby headache:
http://github.com/psychs/limechat/blob/4c8a75aff8f3f7af10bf1e6049baeee29af7d82b/ruby/lib/pasternakclient.rb

The NSURLConnection.initWithRequest method requires a delegate be provided that meets certain criteria. The request method will immediately return and the actual request will be performed in the background - once the request completes, it will hand the result to the code in this delegate object.

Both the Obj-C and MacRuby examples passed 'self' in as that delegate, but that would limit our object to only being able to run one request at a time. Therefore I knocked up the following class to be the delegate we pass, which allows us to set a delegate for each request:

class HttpRequestCallback
	attr_accessor :delegate, :buf, :response, :conn
	
	def cancel
		if @conn
			@conn.cancel
			@conn = nil
		end
	end
  
	def connection(conn, didReceiveResponse:res)
		return if @conn != conn
		@response = res
	end
 
	def connectionDidFinishLoading(conn)
		if @response
			code = @response.statusCode
			if code.to_s =~ /^20[01]$/
				@delegate.call(@buf)
			else
				@delegate.call(false)
			end
		end
		@conn = nil
	end
  
	def connection(conn, didReceiveData:data)
		return if @conn != conn
		@buf.appendData(data)
	end
  
	def connection(conn, didFailWithError:err)
		if @conn == conn
			@delegate.call(false)
		end
		@conn = nil
	end
  
	def connection(conn, willSendRequest:req, redirectResponse:res)
		return nil if @conn != conn
		if res && res.statusCode == 302
			@delegate.call(req.URL.to_s)
			@conn = nil
			nil
		else
			req
		end
	end	
end

The idea being that we create one of these each time we request a url, the request then communicates with this class which in turn calls a method of our choosing when the request is complete. Think of it like a middle man: We want the request to call one of our methods when it completes, however, the NSUrlConnection class requires a bit of infrastructure in place to deal with things, so this class is the middleman who has the complicated conversation with NSUrlConnection and then simply hands us an envelope with the answer.

With the HttpRequestCallback class in place, we can now implement the following getUrl method in a TwitterApi class:

class TwitterApi
	TIMEOUT = 10
	POLICY = NSURLRequestReloadIgnoringLocalCacheData

	def getUrl(urlString, delegate)

		callback = HttpRequestCallback.new
		callback.delegate = delegate
		callback.buf = NSMutableData.new
		callback.response = nil

		url = NSURL.URLWithString(urlString)
		request = NSMutableURLRequest.requestWithURL(url, cachePolicy:POLICY, timeoutInterval:TIMEOUT)
		callback.conn = NSURLConnection.alloc.initWithRequest(request, delegate:callback)

	end
end

We call this method passing it a url string and a lambda method that will be called when the request returns. The lambda will be called with one parameter of type NSMutableData, which we can convert into a string using NSString.initWithData. We can therefore consume and test our getUrl method by replacing the code in the addFriend method with:

def addFriend(sender)
	twitter = TwitterApi.new
	twitter.getUrl('www.google.com', lambda do |data|

		result = NSString.alloc.initWithData data, encoding:NSUTF8StringEncoding

		# display the result in an alert box
		alert = NSAlert.new
		alert.setMessageText(result)
		alert.runModal()	

	end)
end

Now when you run your application and click on the Add button, you should get a message alert containing the HTML source for the Google homepage.

Next Article: We need to be able to authenticate ourselves with the Twitter API in order to get access to our own Twitter stream - so we'll cover Basic Authentication and Base64 encoding. Part Two Available Here.

Further Reading:

Additional MacRuby Tutorial - makes understanding Objective-C syntax easier:
http://www.macruby.org/trac/wiki/MacRubyTutorial

Apple Objective-C Messaging:
https://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Articles/chapter_2_section_4.html

Apple reference for NSUrlReq:
http://developer.apple.com/documentation/Cocoa/Reference/Foundation/Classes/NSMutableURLRequest_Class/Reference/Reference.html

Article on using NSUrlReq in Objective-C:
http://cocoawithlove.com/2008/09/cocoa-application-driven-by-http-data.html

The Twitter API Documentation:
http://apiwiki.twitter.com

Comments

Name
For Spam Fighting Reasons, are you Human or Robot?
Address (web or email)
Comment