ashrewdmint-chirpy

= Chirpy

== Description

Chirpy is a simple Twitter client for Ruby, written using Hpricot and RestClient.

• Github: http://github.com/ashrewdmint/chirpy
• Documentation: http://ashrewdmint.com/code/chirpy

== Caveats

Currently, Chirpy doesn't support OAuth yet. It also can't upload images to Twitter (+profile_image_update+ and +profile_background_image_update+). However, I hope to support both of these things in the future.

== Installation

sudo gem install ashrewdmint-chirpy

Or, if that doesn't work, try:

sudo gem install ashrewdmint-chirpy --source=http://gems.github.com

If that failed too, you can do this:

$ git clone git://github.com/ashrewdmint/chirpy.git $ cd chirpy $ gem build chirpy.gemspec $ sudo gem install chirpy-x.x.x.gem

== Usage

Once you have the gem installed, you have to require it at the top of your Ruby document.

require 'rubygems' require 'chirpy'

Everything Chirpy returns is a Hpricot object, which lets you easily search through XML soup and find what you need. You should familiarize yourself with Hpricot first: http://wiki.github.com/why/hpricot

=== Examples

Let's say you want to see the public timeline:

Chirpy.public_timeline.search('text').each do |text| puts text.inner_html end

That was easy! Note that everything after .public_timeline was just Hpricot magic.

But what if I want to search Twitter? That's simple, too:

Chirpy.search('Murray Rothbard').search('content').each do |text| puts text.inner_html end

Well, that was certainly painless. Unfortunately, since the search method parses an RSS feed, there's a lot of entities and links making a mess of the text. Chirpy has a method to handle annoyances like that:

puts Chirpy.remove_crap(text.inner_html)

But I'm getting ahead of myself. What if you want to post a new tweet?

chirpy = Chirpy.new('username', 'password') chirpy.update_status("I'm posting this with Chirpy!")

...or view a list of your friends?

chirpy.friends.search('name').each do |name| puts name.inner_html + ' is a horrible person' end

...or look at peoples' favorite tweets?

chirpy.favorites # Your own favorites chirpy.favorites('ashrewdmint') # My favorites!

But what if something goes wrong? Well, it's easy to check for an error:

response = Chirpy.public_timeline

if response.ok? # Do something awesome else puts response.status.inspect end

If anything goes wrong, you can find error details in the status attribute. Just so you know, Chirpy adds two new attributes to the Hpricot response object: status and url.

One last thing: some Twitter methods let you pass some extra GET parameters, like page or since_id. It's easy to do this with Chirpy, just pass those arguments in a hash:

chirpy.friends_timeline :page => 3

Nifty, eh? Good luck, and enjoy!

== Special thanks & credits

• Thanks to Why The Lucky Stiff for making Hpricot
• Thanks to Adam Wiggins for making RestClient
• Written by Andrew Smith [[e-mail]] [@ashrewdmint]

== License

Released under the MIT license. Mayest thou go forth and redistributeth to thine heart's content.