hayesdavis-grackle 0.0.6 → 0.1.0

data/History.txt

@@ -1,4 +1,5 @@
-== 1.0.0 / 2009-03-22
-
-* 1 major enhancement
-  * Birthday!
+== 0.1.0 (2009-04-12)
+* Added OAuth authentication
+* Deprecated :username and :password Grackle::Client constructor params
+* Changed multipart upload implementation and removed dependency on httpclient gem
+* Added dependency on mime-types gem

data/{README.txt → README.rdoc}

@@ -1,28 +1,44 @@
 =grackle
 by Hayes Davis
-	hayes@appozite.com
-	http://www.appozite.com
-	http://hayesdavis.net
+- hayes [at] appozite.com
+- http://cheaptweet.com
+- http://www.appozite.com
+- http://hayesdavis.net
 
 == DESCRIPTION
 Grackle is a lightweight Ruby wrapper around the Twitter REST and Search APIs. It's based on my experience using the 
 Twitter API to build http://cheaptweet.com. The main goal of Grackle is to never require a release when the Twitter 
-API changes (which it often does) or in the face of a particular Twitter API bug. As such it is somewhat different 
-from other Twitter API libraries. It does not try to hide the Twitter "methods" under an access layer nor does it 
+API changes (which it often does) or in the face of a particular Twitter API bug. As such it's somewhat different 
+from other Twitter API libraries. It doesn't try to hide the Twitter "methods" under an access layer nor does it 
 introduce concrete classes for the various objects returned by Twitter. Instead, calls to the Grackle client map 
 directly to Twitter API URLs. The objects returned by API calls are generated as OpenStructs on the fly and make no 
 assumptions about the presence or absence of any particular attributes. Taking this approach means that changes to 
 URLs used by Twitter, parameters required by those URLs or return values will not require a new release. It 
 will potentially require, however, some modifications to your code that uses Grackle. 
 
-==USING GRACKLE
+Grackle supports both OAuth and HTTP basic authentication.
 
-===Creating a Grackle::Client
+==USING GRACKLE
 
+Before you do anything else, you'll need to
   require 'grackle'
-  client = Grackle::Client.new(:username=>'your_user',:password=>'yourpass')
 
-See Grackle::Client for more information about valid arguments to the constructor including for custom headers and SSL.
+===Creating a Grackle::Client
+====Using Basic Auth
+  client = Grackle::Client.new(:auth=>{:type=:basic,:username=>'your_user',:password=>'yourpass'})
+
+====Using OAuth
+  client = Grackle::Client.new(:auth=>{
+    :type=>:oauth,
+    :consumer_key=>'SOMECONSUMERKEYFROMTWITTER', :consumer_token=>'SOMECONSUMERTOKENFROMTWITTER',
+    :token=>'ACCESSTOKENACQUIREDONUSERSBEHALF', :token_secret=>'SUPERSECRETACCESSTOKENSECRET'
+  }}
+  
+====Using No Auth
+  client = Grackle::Client.new
+
+See Grackle::Client for more information about valid arguments to the constructor. It's quite configurable. Among other things, 
+you can turn on ssl and specify custom headers. The calls below are pretty much as simple as it gets.
 
 ===Grackle Method Syntax
 Grackle uses a method syntax that corresponds to the Twitter API URLs with a few twists. Where you would have a slash in 
@@ -97,13 +113,14 @@ chain as described above, but use a "?" or "!" then the Grackle::Client.default_
 == REQUIREMENTS:
 
 You'll need the following gems to use all features of Grackle:
-- json_pure
-- httpclient 
+- json
+- oauth 
+- mime-types
 
 == INSTALL:
 
-sudo gem sources -a http://gems.github.com
-sudo gem install hayesdavis-grackle
+  sudo gem sources -a http://gems.github.com
+  sudo gem install hayesdavis-grackle
 
 == LICENSE:
 

data/grackle.gemspec

@@ -2,21 +2,22 @@
 
 Gem::Specification.new do |s|
   s.name = %q{grackle}
-  s.version = "0.0.6"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Hayes Davis"]
-  s.date = %q{2009-03-23}
+  s.date = %q{2009-04-12}
   s.description = %q{Grackle is a lightweight library for the Twitter REST and Search API.}
   s.email = %q{hayes@appozite.com}
-  s.files = ["History.txt", "README.txt", "Rakefile", "grackle.gemspec", "lib/grackle.rb", "lib/grackle/client.rb", "lib/grackle/handlers.rb", "lib/grackle/transport.rb", "lib/grackle/utils.rb", "spec/grackle_spec.rb", "spec/spec_helper.rb", "test/test_grackle.rb"]
+  s.files = ["History.txt", "README.rdoc", "grackle.gemspec", "lib/grackle.rb", "lib/grackle/client.rb", "lib/grackle/handlers.rb", "lib/grackle/transport.rb", "lib/grackle/utils.rb", "test/test_grackle.rb", "test/test_helper.rb", "test/test_client.rb", "test/test_handlers.rb"]
   s.has_rdoc = true
   s.homepage = %q{http://github.com/hayesdavis/grackle}
-  s.rdoc_options = ["--inline-source", "--charset=UTF-8"]
+  s.rdoc_options = ["--inline-source", "--charset=UTF-8","--main=README.rdoc"]
+  s.extra_rdoc_files = ['README.rdoc']
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{grackle}
   s.rubygems_version = %q{1.3.1}
-  s.summary = %q{Grackle is a library for the Twitter REST and Search API designed to not require a new release in the face Twitter API changes or errors.}
+  s.summary = %q{Grackle is a library for the Twitter REST and Search API designed to not require a new release in the face Twitter API changes or errors. It supports both basic and OAuth authentication mechanisms.}
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
@@ -24,13 +25,16 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<json>, [">= 0"])
-      s.add_runtime_dependency(%q<httpclient>, [">= 0"])
+      s.add_dependency(%q<mime-types>, [">= 0"])
+      s.add_dependency(%q<oauth>, [">= 0"])
     else
       s.add_dependency(%q<json>, [">= 0"])
-      s.add_dependency(%q<httpclient>, [">= 0"])
+      s.add_dependency(%q<mime-types>, [">= 0"])
+      s.add_dependency(%q<oauth>, [">= 0"])
     end
   else
     s.add_dependency(%q<json>, [">= 0"])
-    s.add_dependency(%q<httpclient>, [">= 0"])
+    s.add_dependency(%q<mime-types>, [">= 0"])
+    s.add_dependency(%q<oauth>, [">= 0"])
   end
 end

data/lib/grackle/client.rb

@@ -1,9 +1,11 @@
 module Grackle
   
+  #Returned by methods which retrieve data from the API
   class TwitterStruct < OpenStruct
     attr_accessor :id
   end
 
+  #Raised by methods which call the API if a non-200 response status is received 
   class TwitterError < StandardError
     attr_accessor :method, :request_uri, :status, :response_body, :response_object
   
@@ -18,12 +20,35 @@ module Grackle
   
   # The Client is the public interface to Grackle. You build Twitter API calls using method chains. See the README for details 
   # and new for information on valid options.
+  #
+  # ==Authentication
+  # Twitter is migrating to OAuth as the preferred mechanism for authentication (over HTTP basic auth). Grackle supports both methods.
+  # Typically you will supply Grackle with authentication information at the time you create your Grackle::Client via the :auth parameter.
+  # ===Basic Auth
+  #   client = Grackle.Client.new(:auth=>{:type=>:basic,:username=>'twitteruser',:password=>'secret'})
+  # Please note that the original way of specifying basic authentication still works but is deprecated
+  #   client = Grackle.Client.new(:username=>'twitteruser',:password=>'secret') #deprecated
+  #
+  # ===OAuth
+  # OAuth is a relatively complex topic. For more information on OAuth applications see the official OAuth site at http://oauth.net and the 
+  # OAuth specification at http://oauth.net/core/1.0. For authentication using OAuth, you will need do the following:
+  # - Acquire a key and token for your application ("Consumer" in OAuth terms) from Twitter. Learn more here:  http://apiwiki.twitter.com/OAuth-FAQ
+  # - Acquire an access token and token secret for the user that will be using OAuth to authenticate into Twitter
+  # The process of acquiring the access token and token secret are outside the scope of Grackle and will need to be coded on a per-application 
+  # basis. Grackle comes into play once you've acquired all of the above pieces of information. To create a Grackle::Client that uses OAuth once 
+  # you've got all the necessary tokens and keys:
+  #   client = Grackle::Client.new(:auth=>{
+  #     :type=>:oauth,
+  #     :consumer_key=>'SOMECONSUMERKEYFROMTWITTER, :consumer_token=>'SOMECONSUMERTOKENFROMTWITTER',
+  #     :token=>'ACCESSTOKENACQUIREDONUSERSBEHALF', :token_secret=>'SUPERSECRETACCESSTOKENSECRET'
+  #   }} 
   class Client
-        
-    class Request
-      attr_accessor :path, :method, :api, :ssl
+    
+    class Request #:nodoc:
+      attr_accessor :client, :path, :method, :api, :ssl
       
-      def initialize(api=:rest,ssl=true)
+      def initialize(client,api=:rest,ssl=true)
+        self.client = client
         self.api = api
         self.ssl = ssl
         self.method = :get
@@ -43,7 +68,7 @@ module Grackle
       end
          
       def host
-        APIS[api]
+        client.api_hosts[api]
       end
     
       def scheme
@@ -54,28 +79,50 @@ module Grackle
     VALID_METHODS = [:get,:post,:put,:delete]
     VALID_FORMATS = [:json,:xml,:atom,:rss]
 
-    APIS = {:rest=>'twitter.com',:search=>'search.twitter.com'}
+    TWITTER_API_HOSTS = {:rest=>'twitter.com',:search=>'search.twitter.com'}
+    
+    #Basic OAuth information needed to communicate with Twitter
+    TWITTER_OAUTH_SPEC = {
+      :site=>'http://twitter.com',
+      :request_token_path=>'/oauth/request_token',
+      :access_token_path=>'/oauth/access_token',
+      :authorize_path=>'/oauth/authorize'
+    }
     
-    attr_accessor :username, :password, :handlers, :default_format, :headers, :ssl, :api, :transport, :request 
+    attr_accessor :auth, :handlers, :default_format, :headers, :ssl, :api, :transport, :request, :api_hosts
     
     # Arguments (all are optional):
-    # - :username       - twitter username to authenticate with
-    # - :password       - twitter password to authenticate with
+    # - :username       - twitter username to authenticate with (deprecated in favor of :auth arg)
+    # - :password       - twitter password to authenticate with (deprecated in favor of :auth arg)
     # - :handlers       - Hash of formats to Handler instances (e.g. {:json=>CustomJSONHandler.new})
     # - :default_format - Symbol of format to use when no format is specified in an API call (e.g. :json, :xml)
     # - :headers        - Hash of string keys and values for headers to pass in the HTTP request to twitter
     # - :ssl            - true or false to turn SSL on or off. Default is off (i.e. http://)
-    # - :api            - one of :rest or :search
+    # - :api            - one of :rest or :search. :rest is the default
+    # - :auth           - Hash of authentication type and credentials. Must have :type key with value one of :basic or :oauth
+    #   - :type=>:basic  - Include :username and :password keys
+    #   - :type=>:oauth  - Include :consumer_key, :consumer_secret, :token and :token_secret keys
     def initialize(options={})
       self.transport = Transport.new
-      self.username = options.delete(:username)
-      self.password = options.delete(:password)
       self.handlers = {:json=>Handlers::JSONHandler.new,:xml=>Handlers::XMLHandler.new,:unknown=>Handlers::StringHandler.new}
       self.handlers.merge!(options[:handlers]||{})
       self.default_format = options[:default_format] || :json 
-      self.headers = {'User-Agent'=>'Grackle/1.0'}.merge!(options[:headers]||{})
+      self.headers = {"User-Agent"=>"Grackle/#{Grackle::VERSION}"}.merge!(options[:headers]||{})
       self.ssl = options[:ssl] == true
       self.api = options[:api] || :rest
+      self.api_hosts = TWITTER_API_HOSTS.clone
+      self.auth = {}
+      if options.has_key?(:username) || options.has_key?(:password)
+        #Use basic auth if :username and :password args are passed in
+        self.auth.merge!({:type=>:basic,:username=>options[:username],:password=>options[:password]})
+      end
+      #Handle auth mechanism that permits basic or oauth
+      if options.has_key?(:auth)
+        self.auth = options[:auth]
+        if auth[:type] == :oauth
+          self.auth = TWITTER_OAUTH_SPEC.merge(auth)
+        end
+      end
     end
                
     def method_missing(name,*args)
@@ -112,6 +159,36 @@ module Grackle
       self.request = nil
     end
     
+    #Deprecated in favor of using the auth attribute.
+    def username
+      if auth[:type] == :basic
+        auth[:username]
+      end
+    end
+    
+    #Deprecated in favor of using the auth attribute.    
+    def username=(value)
+      unless auth[:type] == :basic
+        auth[:type] = :basic        
+      end
+      auth[:username] = value
+    end
+    
+    #Deprecated in favor of using the auth attribute.    
+    def password
+      if auth[:type] == :basic
+        auth[:password]
+      end
+    end
+    
+    #Deprecated in favor of using the auth attribute.    
+    def password=(value)
+      unless auth[:type] == :basic
+        auth[:type] = :basic
+      end
+      auth[:password] = value
+    end
+    
     protected
       def call_with_format(format,params={})
         id = params.delete(:id)
@@ -126,7 +203,7 @@ module Grackle
       def send_request(params)
         begin
           transport.request(
-            request.method,request.url,:username=>self.username,:password=>self.password,:headers=>headers,:params=>params
+            request.method,request.url,:auth=>auth,:headers=>headers,:params=>params
           )
         rescue => e
           puts e
@@ -150,7 +227,7 @@ module Grackle
       end
       
       def request
-        @request ||= Request.new(api,ssl)
+        @request ||= Request.new(self,api,ssl)
       end
       
       def handler(format)

data/lib/grackle/transport.rb

@@ -1,6 +1,6 @@
 module Grackle
   
-  class Response
+  class Response #:nodoc:
     attr_accessor :method, :request_uri, :status, :body
     
     def initialize(method,request_uri,status,body)
@@ -12,22 +12,10 @@ module Grackle
   end
   
   class Transport
-  
-    def get(string_url,options={})
-      request(:get,url,options)
-    end
     
-    def post(string_url,options={})
-      request(:post,url,options)
-    end
-    
-    def put(url,options={})
-      request(:put,url,options)
-    end
-    
-    def delete(url,options={})
-      request(:delete,url,options)
-    end
+    attr_accessor :debug
+  
+    CRLF = "\r\n"
     
     def req_class(method)
       case method
@@ -38,6 +26,11 @@ module Grackle
       end
     end
     
+    # Options are one of
+    # - :params - a hash of parameters to be sent with the request. If a File is a parameter value, \
+    #             a multipart request will be sent. If a Time is included, .httpdate will be called on it.
+    # - :headers - a hash of headers to send with the request
+    # - :auth - a hash of authentication parameters for either basic or oauth
     def request(method, string_url, options={})
       params = stringify_params(options[:params])
       if method == :get && params
@@ -45,35 +38,33 @@ module Grackle
       end
       url = URI.parse(string_url)
       begin
-        if file_param?(options[:params])
-          request_multipart(method,url,options)
-        else
-          request_standard(method,url,options)
-        end
+        execute_request(method,url,options)
       rescue Timeout::Error
         raise "Timeout while #{method}ing #{url.to_s}"
       end
     end
     
-    def request_multipart(method, url, options={})
-      require 'httpclient' unless defined? HTTPClient
-      client = HTTPClient.new
-      if options[:username] && options[:password]
-        client.set_auth(url.to_s,options.delete(:username),options.delete(:password))
-      end
-      res = client.request(method,url.to_s,nil,options[:params],options[:headers])
-      Response.new(method,url.to_s,res.status,res.content)
-    end
-    
-    def request_standard(method,url,options={})
+    def execute_request(method,url,options={})
       Net::HTTP.new(url.host, url.port).start do |http| 
         req = req_class(method).new(url.request_uri)
         add_headers(req,options[:headers])
-        add_form_data(req,options[:params])
-        add_basic_auth(req,options[:username],options[:password])
+        if file_param?(options[:params])
+          add_multipart_data(req,options[:params])
+        else
+          add_form_data(req,options[:params])
+        end
+        if options.has_key? :auth
+          if options[:auth][:type] == :basic
+            add_basic_auth(req,options[:auth])
+          elsif options[:auth][:type] == :oauth
+            add_oauth(req,options[:auth])
+          end
+        end
+        dump_request(req) if debug
         res = http.request(req)
+        dump_response(res) if debug
         Response.new(method,url.to_s,res.code.to_i,res.body)
-      end        
+      end
     end
 
     def query_string(params)
@@ -128,10 +119,62 @@ module Grackle
         end
       end
     
-      def add_basic_auth(req,username,password)
+      def add_multipart_data(req,params)
+        boundary = Time.now.to_i.to_s(16)
+        req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+        body = ""
+        params.each do |key,value|
+          esc_key = url_encode(key)
+          body << "--#{boundary}#{CRLF}"
+          if value.respond_to?(:read)
+            mime_type = MIME::Types.type_for(value.path)[0] || MIME::Types["application/octet-stream"][0]
+            body << "Content-Disposition: form-data; name=\"#{esc_key}\"; filename=\"#{File.basename(value.path)}\"#{CRLF}"
+            body << "Content-Type: #{mime_type.simplified}#{CRLF*2}"
+            body << value.read
+          else
+            body << "Content-Disposition: form-data; name=\"#{esc_key}\"#{CRLF*2}#{value}"
+          end
+          body << CRLF
+        end
+        body << "--#{boundary}--#{CRLF*2}"
+        req.body = body
+        req["Content-Length"] = req.body.size
+      end
+    
+      def add_basic_auth(req,auth)
+        username = auth[:username]
+        password = auth[:password]
         if username && password
           req.basic_auth(username,password)
         end
       end
+      
+      def add_oauth(req,auth)
+        options = auth.reject do |key,value|
+          [:type,:consumer_key,:consumer_secret,:token,:token_secret].include?(key)
+        end
+        consumer = OAuth::Consumer.new(auth[:consumer_key],auth[:consumer_secret],options)
+        access_token = OAuth::AccessToken.new(consumer,auth[:token],auth[:token_secret])
+        consumer.sign!(req,access_token)
+      end
+
+      private
+        def dump_request(req)
+          puts "Sending Request"
+          puts"#{req.method} #{req.path}"
+          dump_headers(req)
+        end
+      
+        def dump_response(res)
+          puts "Received Response"
+          dump_headers(res)
+          puts res.body
+        end
+      
+        def dump_headers(msg)
+          msg.each_header do |key, value|
+            puts "\t#{key}=#{value}"
+          end
+        end
   end
 end

data/lib/grackle.rb

@@ -1,7 +1,7 @@
 module Grackle
 
   # :stopdoc:
-  VERSION = '0.0.5'
+  VERSION = '0.1.0'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   # :startdoc:
@@ -18,8 +18,12 @@ $:.unshift File.dirname(__FILE__)
 require 'ostruct'
 require 'open-uri'
 require 'net/http'
+require 'time'
 require 'rexml/document'
 require 'json'
+require 'oauth'
+require 'oauth/client'
+require 'mime/types'
 
 require 'grackle/utils'
 require 'grackle/transport'

data/test/test_client.rb

@@ -0,0 +1,168 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class TestClient < Test::Unit::TestCase
+  
+  #Used for mocking HTTP requests
+  class Net::HTTP
+    class << self
+      attr_accessor :response, :request
+    end
+   
+    def request(req)
+      self.class.request = req
+      self.class.response
+    end
+  end  
+  
+  #Mock responses that conform mostly to HTTPResponse's interface
+  class MockResponse
+    include Net::HTTPHeader
+    attr_accessor :code, :body
+    def initialize(code,body,headers={})
+      self.code = code
+      self.body = body
+      headers.each do |name, value|
+        self[name] = value
+      end
+    end
+  end
+  
+  #Transport that collects info on requests and responses for testing purposes
+  class MockTransport < Grackle::Transport
+    attr_accessor :status, :body, :method, :url, :options
+    
+    def initialize(status,body,headers={})
+      Net::HTTP.response = MockResponse.new(status,body,headers)
+    end
+    
+    def request(method, string_url, options)
+      self.method = method
+      self.url = URI.parse(string_url)
+      self.options = options
+      super(method,string_url,options)
+    end
+  end
+  
+  class TestHandler
+    attr_accessor :decode_value
+    
+    def initialize(value)
+      self.decode_value = value
+    end
+    
+    def decode_response(body)
+      decode_value  
+    end
+  end
+  
+  def test_simple_get_request
+    client = new_client(200,'{"id":12345,"screen_name":"test_user"}')
+    value = client.users.show.json? :screen_name=>'test_user'
+    assert_equal(:get,client.transport.method)
+    assert_equal('http',client.transport.url.scheme)
+    assert_equal('twitter.com',client.transport.url.host)
+    assert_equal('/users/show.json',client.transport.url.path)
+    assert_equal('test_user',client.transport.options[:params][:screen_name])
+    assert_equal('screen_name=test_user',Net::HTTP.request.path.split(/\?/)[1])
+    assert_equal(12345,value.id)
+  end
+  
+  def test_simple_post_request_with_basic_auth
+    client = Grackle::Client.new(:auth=>{:type=>:basic,:username=>'fake_user',:password=>'fake_pass'})
+    test_simple_post(client) do
+      assert_match(/Basic/i,Net::HTTP.request['Authorization'],"Request should include Authorization header for basic auth")
+    end
+  end
+  
+  def test_simple_post_request_with_oauth
+    client = Grackle::Client.new(:auth=>{:type=>:oauth,:consumer_key=>'12345',:consumer_secret=>'abc',:token=>'wxyz',:token_secret=>'98765'})
+    test_simple_post(client) do
+      auth = Net::HTTP.request['Authorization']
+      assert_match(/OAuth/i,auth,"Request should include Authorization header for OAuth")
+      assert_match(/oauth_consumer_key="12345"/,auth,"Auth header should include consumer key")
+      assert_match(/oauth_token="wxyz"/,auth,"Auth header should include token")
+      assert_match(/oauth_signature_method="HMAC-SHA1"/,auth,"Auth header should include HMAC-SHA1 signature method as that's what Twitter supports")
+    end
+  end
+  
+  def test_ssl
+    client = new_client(200,'[{"id":1,"text":"test 1"}]',:ssl=>true)
+    client.statuses.public_timeline?
+    assert_equal("https",client.transport.url.scheme)
+  end
+  
+  def test_default_format
+    client = new_client(200,'[{"id":1,"text":"test 1"}]',:default_format=>:json)
+    client.statuses.public_timeline?
+    assert_match(/\.json$/,client.transport.url.path)
+    
+    client = new_client(200,'<statuses type="array"><status><id>1</id><text>test 1</text></status></statuses>',:default_format=>:xml)
+    client.statuses.public_timeline?
+    assert_match(/\.xml$/,client.transport.url.path)
+  end
+  
+  def test_api
+    client = new_client(200,'[{"id":1,"text":"test 1"}]',:api=>:search)
+    client.search? :q=>'test'
+    assert_equal('search.twitter.com',client.transport.url.host)
+    client[:rest].users.show.some_user?
+    assert_equal('twitter.com',client.transport.url.host)
+    client.api = :search
+    client.trends?
+    assert_equal('search.twitter.com',client.transport.url.host)
+  end
+  
+  def test_headers
+    client = new_client(200,'[{"id":1,"text":"test 1"}]',:headers=>{'User-Agent'=>'TestAgent/1.0','X-Test-Header'=>'Header Value'})
+    client.statuses.public_timeline?
+    assert_equal('TestAgent/1.0',Net::HTTP.request['User-Agent'],"Custom User-Agent header should have been set")
+    assert_equal('Header Value',Net::HTTP.request['X-Test-Header'],"Custom X-Test-Header header should have been set")
+  end
+  
+  def test_custom_handlers
+    client = new_client(200,'[{"id":1,"text":"test 1"}]',:handlers=>{:json=>TestHandler.new(42)})
+    value = client.statuses.public_timeline.json?
+    assert_equal(42,value)
+  end
+  
+  def test_clear
+    client = new_client(200,'[{"id":1,"text":"test 1"}]')
+    client.some.url.that.does.not.exist
+    assert_equal('/some/url/that/does/not/exist',client.send(:request).path,"An unexecuted path should be build up")
+    client.clear
+    assert_equal('',client.send(:request).path,"The path shoudl be cleared")
+  end
+  
+  def test_file_param_triggers_multipart_encoding
+    client = new_client(200,'[{"id":1,"text":"test 1"}]')
+    client.account.update_profile_image! :image=>File.new(__FILE__)    
+    assert_match(/multipart\/form-data/,Net::HTTP.request['Content-Type'])
+  end
+  
+  def test_time_param_is_http_encoded_and_escaped
+    client = new_client(200,'[{"id":1,"text":"test 1"}]')
+    time = Time.now-60*60
+    client.statuses.public_timeline? :since=>time  
+    assert_equal("/statuses/public_timeline.json?since=#{CGI::escape(time.httpdate)}",Net::HTTP.request.path)
+  end
+  
+  private
+    def new_client(response_status, response_body, client_opts={})
+      client = Grackle::Client.new(client_opts)
+      client.transport = MockTransport.new(response_status,response_body)
+      client
+    end
+    
+    def test_simple_post(client)
+      client.transport = MockTransport.new(200,'{"id":12345,"text":"test status"}')
+      value = client.statuses.update! :status=>'test status'
+      assert_equal(:post,client.transport.method,"Expected post request")
+      assert_equal('http',client.transport.url.scheme,"Expected scheme to be http")
+      assert_equal('twitter.com',client.transport.url.host,"Expected request to be against twitter.com")
+      assert_equal('/statuses/update.json',client.transport.url.path)
+      assert_match(/status=test%20status/,Net::HTTP.request.body,"Parameters should be form encoded")
+      assert_equal(12345,value.id)
+      yield(client) if block_given?
+    end
+  
+end

data/test/test_grackle.rb

@@ -0,0 +1,4 @@
+Dir.glob("#{File.dirname(__FILE__)}/*.rb").each do |file|
+  require file
+end
+ 

data/test/test_handlers.rb

@@ -0,0 +1,89 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class TestHandlers < Test::Unit::TestCase
+  
+  def test_string_handler_echoes
+    sh = Grackle::Handlers::StringHandler.new
+    body = "This is some text"
+    assert_equal(body,sh.decode_response(body),"String handler should just echo response body")
+  end
+  
+  def test_xml_handler_parses_text_only_nodes_as_attributes
+    h = Grackle::Handlers::XMLHandler.new
+    body = "<user><id>12345</id><screen_name>User1</screen_name></user>"
+    value = h.decode_response(body)
+    assert_equal(12345,value.id,"Id element should be treated as an attribute and be returned as a Fixnum")
+    assert_equal("User1",value.screen_name,"screen_name element should be treated as an attribute")
+  end
+  
+  def test_xml_handler_parses_nested_elements_with_children_as_nested_objects
+    h = Grackle::Handlers::XMLHandler.new
+    body = "<user><id>12345</id><screen_name>User1</screen_name><status><id>9876</id><text>this is a status</text></status></user>"
+    value = h.decode_response(body)
+    assert_not_nil(value.status,"status element should be turned into an object")
+    assert_equal(9876,value.status.id,"status element should have id")
+    assert_equal("this is a status",value.status.text,"status element should have text")
+  end
+  
+  def test_xml_handler_parses_elements_with_type_array_as_arrays
+    h  = Grackle::Handlers::XMLHandler.new
+    body = "<some_ids type=\"array\">"
+    1.upto(10) do |i|
+      body << "<id>#{i}</id>"
+    end
+    body << "</some_ids>"
+    value = h.decode_response(body)    
+    assert_equal(Array,value.class,"Root parsed object should be an array")
+    assert_equal(10,value.length,"Parsed array should have correct length")
+    0.upto(9) do |i|
+      assert_equal(i+1,value[i],"Parsed array should contain #{i+1} at index #{i}")
+    end
+  end
+  
+  def test_xml_handler_parses_certain_elements_as_arrays
+    h  = Grackle::Handlers::XMLHandler.new
+    special_twitter_elements = ['ids','statuses','users']
+    special_twitter_elements.each do |name|
+      body = "<#{name}>"
+      1.upto(10) do |i|
+        body << "<complex_value><id>#{i}</id><profile>This is profile #{i}</profile></complex_value>"
+      end
+      body << "</#{name}>"
+      value = h.decode_response(body)    
+      assert_equal(Array,value.class,"Root parsed object should be an array")
+      assert_equal(10,value.length,"Parsed array should have correct length")
+      0.upto(9) do |i|
+        assert_equal(i+1,value[i].id,"Parsed array should contain id #{i+1} at index #{i}")
+        assert_equal("This is profile #{i+1}",value[i].profile,"Parsed array should contain profile 'This is profile #{i+1}' at index #{i}")
+      end
+    end
+  end
+  
+  def test_json_handler_parses_basic_attributes
+    h = Grackle::Handlers::JSONHandler.new
+    body = '{"id":12345,"screen_name":"User1"}'
+    value = h.decode_response(body)
+    assert_equal(12345,value.id,"Id element should be treated as an attribute and be returned as a Fixnum")
+    assert_equal("User1",value.screen_name,"screen_name element should be treated as an attribute")    
+  end
+  
+  def test_json_handler_parses_complex_attributes
+    h = Grackle::Handlers::JSONHandler.new
+    body = '{"id":12345,"screen_name":"User1","statuses":['
+    1.upto(10) do |i|
+      user_id = i+5000
+      body << ',' unless i == 1
+      body << %Q{{"id":#{i},"text":"Status from user #{user_id}", "user":{"id":#{user_id},"screen_name":"User #{user_id}"}}}
+    end
+    body << ']}'
+    value = h.decode_response(body)
+    assert_equal(12345,value.id,"Id element should be treated as an attribute and be returned as a Fixnum")
+    assert_equal("User1",value.screen_name,"screen_name element should be treated as an attribute")
+    assert_equal(Array,value.statuses.class,"statuses attribute should be an array")
+    1.upto(10) do |i|
+      assert_equal(i,value.statuses[i-1].id,"array should contain status with id #{i} at index #{i-1}")
+      assert_equal(i+5000,value.statuses[i-1].user.id,"status at index #{i-1} should contain user with id #{i+5000}")
+    end
+  end
+  
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require 'test/unit'
+require 'rubygems'
+require File.dirname(__FILE__) + '/../lib/grackle'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: hayesdavis-grackle
 version: !ruby/object:Gem::Version 
-  version: 0.0.6
+  version: 0.1.0
 platform: ruby
 authors: 
 - Hayes Davis
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-23 00:00:00 -07:00
+date: 2009-04-12 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -23,7 +23,17 @@ dependencies:
         version: "0"
     version: 
 - !ruby/object:Gem::Dependency 
-  name: httpclient
+  name: mime-types
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: oauth
   type: :runtime
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
@@ -38,27 +48,28 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- README.rdoc
 files: 
 - History.txt
-- README.txt
-- Rakefile
+- README.rdoc
 - grackle.gemspec
 - lib/grackle.rb
 - lib/grackle/client.rb
 - lib/grackle/handlers.rb
 - lib/grackle/transport.rb
 - lib/grackle/utils.rb
-- spec/grackle_spec.rb
-- spec/spec_helper.rb
 - test/test_grackle.rb
+- test/test_helper.rb
+- test/test_client.rb
+- test/test_handlers.rb
 has_rdoc: true
 homepage: http://github.com/hayesdavis/grackle
 post_install_message: 
 rdoc_options: 
 - --inline-source
 - --charset=UTF-8
+- --main=README.rdoc
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -79,6 +90,6 @@ rubyforge_project: grackle
 rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
-summary: Grackle is a library for the Twitter REST and Search API designed to not require a new release in the face Twitter API changes or errors.
+summary: Grackle is a library for the Twitter REST and Search API designed to not require a new release in the face Twitter API changes or errors. It supports both basic and OAuth authentication mechanisms.
 test_files: []
 

data/Rakefile

@@ -1,35 +0,0 @@
-# Look in the tasks/setup.rb file for the various options that can be
-# configured in this Rakefile. The .rake files in the tasks directory
-# are where the options are used.
-
-begin
-  require 'bones'
-  Bones.setup
-rescue LoadError
-  begin
-    load 'tasks/setup.rb'
-  rescue LoadError
-    raise RuntimeError, '### please install the "bones" gem ###'
-  end
-end
-
-ensure_in_path 'lib'
-require 'grackle'
-
-task :default => 'spec:run'
-
-PROJ.name = 'grackle'
-PROJ.authors = 'Hayes Davis'
-PROJ.email = 'hayes@appozite.com'
-PROJ.url = 'http://github.com/hayesdavis/grackle'
-PROJ.version = Grackle::VERSION
-PROJ.rubyforge.name = 'grackle'
-PROJ.summary = 'Grackle is a library for the Twitter REST and Search API'
-PROJ.description = 'Grackle is a library for the Twitter REST and Search API that aims to go with the flow.'
-PROJ.spec.opts << '--color'
-PROJ.exclude = %w(.git pkg)
-
-depend_on 'json'
-depend_on 'httpclient'
-
-# EOF

data/spec/grackle_spec.rb

@@ -1,7 +0,0 @@
-
-require File.join(File.dirname(__FILE__), %w[spec_helper])
-
-describe Grackle do
-end
-
-# EOF

data/spec/spec_helper.rb

@@ -1,16 +0,0 @@
-
-require File.expand_path(
-    File.join(File.dirname(__FILE__), %w[.. lib grackle]))
-
-Spec::Runner.configure do |config|
-  # == Mock Framework
-  #
-  # RSpec uses it's own mocking framework by default. If you prefer to
-  # use mocha, flexmock or RR, uncomment the appropriate line:
-  #
-  # config.mock_with :mocha
-  # config.mock_with :flexmock
-  # config.mock_with :rr
-end
-
-# EOF