grackle 0.1.5

data/CHANGELOG.rdoc

@@ -0,0 +1,25 @@
+== 0.1.5 (2009-10-28)
+Added support for the Twitter version 1 API as a API symbol :v1
+
+== 0.1.4 (2009-08-09)
+Added additional check for 3xx responses that don't have location headers. 
+
+== 0.1.3 (2009-08-09)
+Merged in changes from gotwalt for timeouts and redirects. Revised 30x 
+redirect handling to support a limit that prevents infinite redirects. 
+
+== 0.1.2 (2009-05-11)
+Changed :site param used by OAuth to be determined dynamically unless 
+explicitly specified as part of the :auth param to the Client constructor. 
+This param needs to match the scheme and authority of the request using 
+OAuth or the signing will not validate.
+
+== 0.1.1 (2009-05-10)
+Fixed issue where SSL setting wasn't being applied correctly to Net:HTTP 
+which was preventing SSL-enabled requests from working correctly.
+
+== 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.rdoc

@@ -0,0 +1,171 @@
+=grackle
+by Hayes Davis
+- http://twitter.com/hayesdavis
+- 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'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. 
+
+Grackle supports both OAuth and HTTP basic authentication.
+
+==USING GRACKLE
+
+Before you do anything else, you'll need to
+  require 'grackle'
+
+===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_secret=>'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 
+a Twitter URL, that becomes a "." in a chained set of Grackle method calls. Each call in the method chain is used to build 
+Twitter URL path until a particular call is encountered which causes the request to be sent. Methods which will cause a 
+request to be execute include:
+- A method call ending in "?" will cause an HTTP GET to be executed
+- A method call ending in "!" will cause an HTTP POST to be executed
+- If a valid format such as .json, .xml, .rss or .atom is encounted, a get will be executed with that format
+- A format method can also include a ? or ! to determine GET or POST in that format respectively
+
+===GETting Data
+The preferred and simplest way of executing a GET is to use the "?" method notation. This will use the default client 
+format (usually JSON, but see Formats section below):
+  client.users.show? :screen_name=>'some_user' #http://twitter.com/users/show.json?screen_name=some_user
+
+You can force XML format by doing:
+  client.users.show.xml? :screen_name=>'some_user' #http://twitter.com/users/show.xml?scren_name=some_user
+  
+You can force JSON:
+  client.users.show.json? :screen_name=>'some_user' #http://twitter.com/users/show.json?screen_name=some_user
+
+Or, since Twitter also allows certain ids/screen_names to be part of their URLs, this works:
+  client.users.show.some_user? #http://twitter.com/users/show/some_user.json
+
+If you use an explicit format, you can leave off the "?" like so:
+  client.users.show.xml :screen_name=>'some_user' #http://twitter.com/users/show.xml?scren_name=some_user
+
+===POSTing data
+To use Twitter API methods that require an HTTP POST, you need to end your method chain with a bang (!)
+
+The preferred way is to use the Client's default format (usually JSON, but see Formats section below):
+  client.statuses.update! :status=>'this status is from grackle' #POST to http://twitter.com/statuses/update.json
+
+You can force a format. To update the authenticated user's status using the XML format:
+  client.statuses.update.xml! :status=>'this status is from grackle' #POST to http://twitter.com/statuses/update.xml
+
+Or, with JSON
+  client.statuses.update.json! :status=>'this status is from grackle' #POST to http://twitter.com/statuses/update.json
+
+===Toggling APIs
+By default, the Grackle::Client sends all requests to the unversioned Twitter REST API. If you want to send requests to 
+the Twitter Search API, just set Grackle::Client.api to :search. To toggle back, set it to be :rest. All requests made 
+after setting this attribute will go to that API.
+
+If you want to make a specific request to one API and not change the Client's overall api setting beyond that request, you can use the 
+bracket syntax like so:
+  client[:search].trends.daily? :exclude=>'hashtags'
+  client[:rest].users.show? :id=>'hayesdavis'
+ 
+Search and REST requests are all built using the same method chaining and termination conventions.
+
+Twitter is introducing API versioning. Grackle now supports the version 1 API using the :v1 API name. When using the :v1 
+API, resources that were previously separated between the search and REST APIs are available under one unified API. To 
+use the :v1 API, do the following:
+  client[:v1].search? :q=>'grackle'
+  client[:v1].users.show? :id=>'hayesdavis'
+  
+If you want to use the :v1 API for all requests, you may set Grackle::Client.api to :v1 or specify the :api option in the 
+Grackle::Client constructor like:
+  client = Grackle::Client.new(:api=>:v1)
+
+===Parameter handling
+- All parameters are URL encoded as necessary.
+- If you use a File object as a parameter it will be POSTed to Twitter in a multipart request.
+- If you use a Time object as a parameter, .httpdate will be called on it and that value will be used
+
+===Return Values
+Regardless of the format used, Grackle returns an OpenStruct (actually a Grackle::TwitterStruct) of data. The attributes 
+available on these structs correspond to the data returned by Twitter.
+
+===Dealing with Errors
+If the request to Twitter does not return a status code of 200, then a TwitterError is thrown. This contains the HTTP method used, 
+the full request URI, the response status, the response body in text and a response object build by parsing the formatted error 
+returned by Twitter. It's a good idea to wrap your API calls with rescue clauses for Grackle::TwitterError.
+
+If there is an unexpected connection error or Twitter returns data in the wrong format (which it can do), you'll still get a TwitterError.
+
+===Formats
+Twitter allows you to request data in particular formats. Grackle automatically parses JSON and XML formatted responses 
+and returns an OpenStruct. If you specify a format that Grackle doesn't parse for you, you'll receive a string containing 
+the raw response body. The Grackle::Client has a default_format you can specify. By default, the default_format is :json. 
+If you don't include a named format in your method chain as described above, but use a "?" or "!" then the 
+Grackle::Client.default_format is used.
+
+== REQUIREMENTS:
+
+You'll need the following gems to use all features of Grackle:
+- json
+- oauth 
+- mime-types
+
+== INSTALL:
+The grackle gem is now hosted at http://gemcutter.org. If you've already setup gemcutter 
+in your sources, you can do the following:
+  sudo gem install grackle
+
+If you haven't yet setup gemcutter in your sources, go to http://gemcutter.org and follow the instructions there.
+They will likely tell you to do the following:
+  sudo gem install gemcutter
+  sudo gem tumble
+
+Once you've done that you can do: 
+  sudo gem install grackle
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/grackle.gemspec

@@ -0,0 +1,40 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{grackle}
+  s.version = "0.1.5"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Hayes Davis"]
+  s.date = %q{2009-05-23}
+  s.description = %q{Grackle is a lightweight library for the Twitter REST and Search API.}
+  s.email = %q{hayes@appozite.com}
+  s.files = ["CHANGELOG.rdoc", "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","--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. It supports both basic and OAuth authentication mechanisms.}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<json>, [">= 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<mime-types>, [">= 0"])
+      s.add_dependency(%q<oauth>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<json>, [">= 0"])
+    s.add_dependency(%q<mime-types>, [">= 0"])
+    s.add_dependency(%q<oauth>, [">= 0"])
+  end
+end

data/lib/grackle/client.rb

@@ -0,0 +1,255 @@
+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
+  
+    def initialize(method, request_uri, status, response_body, msg=nil)
+      self.method = method
+      self.request_uri = request_uri
+      self.status = status
+      self.response_body = response_body
+      super(msg||"#{self.method} #{self.request_uri} => #{self.status}: #{self.response_body}")
+    end
+  end  
+  
+  # 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_secret=>'SOMECONSUMERTOKENFROMTWITTER',
+  #     :token=>'ACCESSTOKENACQUIREDONUSERSBEHALF', :token_secret=>'SUPERSECRETACCESSTOKENSECRET'
+  #   }) 
+  class Client
+    
+    class Request #:nodoc:
+      attr_accessor :client, :path, :method, :api, :ssl
+      
+      def initialize(client,api=:rest,ssl=true)
+        self.client = client
+        self.api = api
+        self.ssl = ssl
+        self.method = :get
+        self.path = ''
+      end
+      
+      def <<(path)
+        self.path << path
+      end
+      
+      def path?
+        path.length > 0
+      end
+    
+      def url
+        "#{scheme}://#{host}#{path}"
+      end
+         
+      def host
+        client.api_hosts[api]
+      end
+    
+      def scheme
+        ssl ? 'https' :'http'
+      end
+    end
+    
+    VALID_METHODS = [:get,:post,:put,:delete]
+    VALID_FORMATS = [:json,:xml,:atom,:rss]
+
+    # Contains the mapping of API name symbols to actual host (and path) 
+    # prefixes to use with requests. You can add your own to this hash and 
+    # refer to it wherever Grackle::Client uses an API symbol. You may wish 
+    # to do this when Twitter introduces API versions greater than 1.
+    TWITTER_API_HOSTS = {
+      :rest=>'twitter.com',
+      :search=>'search.twitter.com',
+      :v1=>'api.twitter.com/1'
+    }
+    
+    #Basic OAuth information needed to communicate with Twitter
+    TWITTER_OAUTH_SPEC = {
+      :request_token_path=>'/oauth/request_token',
+      :access_token_path=>'/oauth/access_token',
+      :authorize_path=>'/oauth/authorize'
+    }
+    
+    attr_accessor :auth, :handlers, :default_format, :headers, :ssl, :api, :transport, :request, :api_hosts, :timeout
+    
+    # Arguments (all are optional):
+    # - :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, :search or :v1. :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.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/#{Grackle::VERSION}"}.merge!(options[:headers]||{})
+      self.ssl = options[:ssl] == true
+      self.api = options[:api] || :rest
+      self.api_hosts = TWITTER_API_HOSTS.clone
+      self.timeout = options[:timeout] || 60
+      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)
+      #If method is a format name, execute using that format
+      if format_invocation?(name)
+        return call_with_format(name,*args)
+      end
+      #If method ends in ! or ? use that to determine post or get
+      if name.to_s =~ /^(.*)(!|\?)$/
+        name = $1.to_sym
+        #! is a post, ? is a get
+        self.request.method = ($2 == '!' ? :post : :get)          
+        if format_invocation?(name)
+          return call_with_format(name,*args)
+        else
+          self.request << "/#{$1}"
+          return call_with_format(self.default_format,*args)
+        end
+      end
+      #Else add to the request path
+      self.request << "/#{name}"
+      self
+    end
+    
+    # Used to toggle APIs for a particular request without setting the Client's default API
+    #   client[:rest].users.show.hayesdavis?
+    def [](api_name)
+      request.api = api_name
+      self
+    end
+    
+    #Clears any pending request built up by chained methods but not executed
+    def clear
+      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)
+        request << "/#{id}" if id
+        request << ".#{format}"
+        res = send_request(params)
+        process_response(format,res)
+      ensure
+        clear
+      end
+      
+      def send_request(params)
+        begin
+          transport.request(
+            request.method,request.url,:auth=>auth,:headers=>headers,:params=>params, :timeout => timeout
+          )
+        rescue => e
+          puts e
+          raise TwitterError.new(request.method,request.url,nil,nil,"Unexpected failure making request: #{e}")
+        end        
+      end
+      
+      def process_response(format,res)
+        fmt_handler = handler(format)        
+        begin
+          unless res.status == 200
+            handle_error_response(res,fmt_handler)
+          else
+            fmt_handler.decode_response(res.body)
+          end
+        rescue TwitterError => e
+          raise e
+        rescue => e
+          raise TwitterError.new(res.method,res.request_uri,res.status,res.body,"Unable to decode response: #{e}")
+        end
+      end
+      
+      def request
+        @request ||= Request.new(self,api,ssl)
+      end
+      
+      def handler(format)
+        handlers[format] || handlers[:unknown]
+      end
+      
+      def handle_error_response(res,handler)
+        err = TwitterError.new(res.method,res.request_uri,res.status,res.body)
+        err.response_object = handler.decode_response(err.response_body)
+        raise err        
+      end
+      
+      def format_invocation?(name)
+        self.request.path? && VALID_FORMATS.include?(name)
+      end
+  end
+end

data/lib/grackle/handlers.rb

@@ -0,0 +1,90 @@
+module Grackle
+  
+  # This module contain handlers that know how to take a response body 
+  # from Twitter and turn it into a TwitterStruct return value. Handlers are 
+  # used by the Client to give back return values from API calls. A handler
+  # is intended to provide a +decode_response+ method which accepts the response body 
+  # as a string.
+  module Handlers
+    
+    # Decodes JSON Twitter API responses
+    class JSONHandler
+    
+      def decode_response(res)
+        json_result = JSON.parse(res)
+        load_recursive(json_result)
+      end
+      
+      private
+        def load_recursive(value)
+          if value.kind_of? Hash
+            build_struct(value)
+          elsif value.kind_of? Array
+            value.map{|v| load_recursive(v)}
+          else
+            value
+          end
+        end
+      
+        def build_struct(hash)
+          struct = TwitterStruct.new
+          hash.each do |key,v|
+            struct.send("#{key}=",load_recursive(v))
+          end
+          struct
+        end
+      
+    end
+    
+    # Decodes XML Twitter API responses
+    class XMLHandler
+      
+      #Known nodes returned by twitter that contain arrays
+      ARRAY_NODES = ['ids','statuses','users']
+      
+      def decode_response(res)
+        xml = REXML::Document.new(res)
+        load_recursive(xml.root)
+      end
+      
+      private
+        def load_recursive(node)
+          if array_node?(node)
+            node.elements.map {|e| load_recursive(e)}
+          elsif node.elements.size > 0
+            build_struct(node)
+          elsif node.elements.size == 0
+            value = node.text
+            fixnum?(value) ? value.to_i : value
+          end
+        end
+      
+        def build_struct(node)
+          ts = TwitterStruct.new
+          node.elements.each do |e|
+            ts.send("#{e.name}=",load_recursive(e))  
+          end
+          ts
+        end
+        
+        # Most of the time Twitter specifies nodes that contain an array of 
+        # sub-nodes with a type="array" attribute. There are some nodes that 
+        # they dont' do that for, though, including the <ids> node returned 
+        # by the social graph methods. This method tries to work in both situations.
+        def array_node?(node)
+          node.attributes['type'] == 'array' || ARRAY_NODES.include?(node.name)
+        end
+      
+        def fixnum?(value)
+          value =~ /^\d+$/
+        end
+    end
+    
+    # Just echoes back the response body. This is primarily used for unknown formats
+    class StringHandler
+      def decode_response(res)
+        res
+      end
+    end
+  end
+end

data/lib/grackle/transport.rb

@@ -0,0 +1,201 @@
+module Grackle
+  
+  class Response #:nodoc:
+    attr_accessor :method, :request_uri, :status, :body
+    
+    def initialize(method,request_uri,status,body)
+      self.method = method
+      self.request_uri = request_uri
+      self.status = status
+      self.body = body
+    end
+  end
+  
+  class Transport
+    
+    attr_accessor :debug
+  
+    CRLF = "\r\n"
+    DEFAULT_REDIRECT_LIMIT = 5
+    
+    def req_class(method)
+      case method
+        when :get then Net::HTTP::Get
+        when :post then Net::HTTP::Post
+        when :put then Net::HTTP::Put
+        when :delete then Net::HTTP::Delete
+      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
+    # - :timeout - timeout for the http request in seconds
+    def request(method, string_url, options={})
+      params = stringify_params(options[:params])
+      if method == :get && params
+        string_url << query_string(params)
+      end
+      url = URI.parse(string_url)
+      begin
+        execute_request(method,url,options)
+      rescue Timeout::Error
+        raise "Timeout while #{method}ing #{url.to_s}"
+      end
+    end
+    
+    def execute_request(method,url,options={})
+      conn = Net::HTTP.new(url.host, url.port)
+      conn.use_ssl = (url.scheme == 'https')
+      conn.start do |http| 
+        req = req_class(method).new(url.request_uri)
+        http.read_timeout = options[:timeout]
+        add_headers(req,options[:headers])
+        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(http,req,options[:auth])
+          end
+        end
+        dump_request(req) if debug
+        res = http.request(req)
+        dump_response(res) if debug
+        redirect_limit = options[:redirect_limit] || DEFAULT_REDIRECT_LIMIT
+        if res.code.to_s =~ /^3\d\d$/ && redirect_limit > 0 && res['location']
+          execute_request(method,URI.parse(res['location']),options.merge(:redirect_limit=>redirect_limit-1))
+        else 
+          Response.new(method,url.to_s,res.code.to_i,res.body)
+        end
+      end
+    end
+
+    def query_string(params)
+      query = case params
+        when Hash then params.map{|key,value| url_encode_param(key,value) }.join("&")
+        else url_encode(params.to_s)
+      end
+      if !(query == nil || query.length == 0) && query[0,1] != '?'
+        query = "?#{query}"
+      end
+      query
+    end      
+  
+    private
+      def stringify_params(params)
+        return nil unless params
+        params.inject({}) do |h, pair|
+          key, value = pair
+          if value.respond_to? :httpdate
+            value = value.httpdate
+          end
+          h[key] = value
+          h
+        end
+      end
+      
+      def file_param?(params)
+        return false unless params
+        params.any? {|key,value| value.respond_to? :read }
+      end
+      
+      def url_encode(value)
+        require 'cgi' unless defined?(CGI) && defined?(CGI::escape)
+        CGI.escape(value.to_s)
+      end
+      
+      def url_encode_param(key,value)
+        "#{url_encode(key)}=#{url_encode(value)}"
+      end
+      
+      def add_headers(req,headers)
+        if headers
+          headers.each do |header, value|
+            req[header] = value
+          end
+        end        
+      end
+    
+      def add_form_data(req,params)
+        if req.request_body_permitted? && params
+          req.set_form_data(params)
+        end
+      end
+    
+      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(conn,req,auth)
+        options = auth.reject do |key,value|
+          [:type,:consumer_key,:consumer_secret,:token,:token_secret].include?(key)
+        end
+        unless options.has_key?(:site)
+          options[:site] = oauth_site(conn,req)
+        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 oauth_site(conn,req)
+          site = "#{(conn.use_ssl? ? "https" : "http")}://#{conn.address}"
+          if (conn.use_ssl? && conn.port != 443) || (!conn.use_ssl? && conn.port != 80) 
+            site << ":#{conn.port}"
+          end
+          site
+        end
+        
+        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/utils.rb

@@ -0,0 +1,16 @@
+module Grackle
+  module Utils
+    
+    VALID_PROFILE_IMAGE_SIZES = [:bigger,:normal,:mini]
+    
+    #Easy method for getting different sized profile images using Twitter's naming scheme
+    def profile_image_url(url,size=:normal)
+      size = VALID_PROFILE_IMAGE_SIZES.find(:normal){|s| s == size.to_sym}
+      return url if url.nil? || size == :normal
+      url.sub(/_normal\./,"_#{size.to_s}.")
+    end
+  
+    module_function :profile_image_url    
+    
+  end
+end

data/lib/grackle.rb

@@ -0,0 +1,31 @@
+module Grackle
+
+  # :stopdoc:
+  VERSION = '0.1.5'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  def self.version
+    VERSION
+  end
+
+end  # module Grackle
+
+$:.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'
+require 'grackle/handlers'
+require 'grackle/client'

data/test/test_client.rb

@@ -0,0 +1,225 @@
+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, :last_instance, :responder
+    end
+   
+    def request(req)
+      self.class.last_instance = self
+      if self.class.responder
+        self.class.responder.call(self,req)        
+      else
+        self.class.request = req
+        self.class.response
+      end
+    end
+  end  
+  
+  #Mock responses that conform to HTTPResponse's interface
+  class MockResponse < Net::HTTPResponse
+    #include Net::HTTPHeader
+    attr_accessor :code, :body
+    def initialize(code,body,headers={})
+      super
+      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, :timeout
+    
+    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_redirects
+    redirects = 2 #Check that we can follow 2 redirects before getting to original request
+    req_count = 0
+    responder = Proc.new do |inst, req|
+      req_count += 1
+      #Store the original request
+      if req_count == 1
+        inst.class.request = req 
+      else
+        assert_equal("/somewhere_else#{req_count-1}.json",req.path)
+      end
+      if req_count <= redirects
+        MockResponse.new(302,"You are being redirected",'location'=>"http://twitter.com/somewhere_else#{req_count}.json")
+      else
+        inst.class.response
+      end
+    end
+    with_http_responder(responder) do
+      test_simple_get_request
+    end
+    assert_equal(redirects+1,req_count)
+  end
+  
+  def test_timeouts
+    client = new_client(200,'{"id":12345,"screen_name":"test_user"}')
+    assert_equal(60, client.timeout)
+    client.timeout = 30
+    assert_equal(30, client.timeout)
+  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(!Net::HTTP.last_instance.use_ssl?,'Net::HTTP instance should not be set to use SSL')
+    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)
+    assert(Net::HTTP.last_instance.use_ssl?,'Net::HTTP instance should be set to use SSL')
+  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)
+    
+    client.api = :v1
+    client.search? :q=>'test'
+    assert_equal('api.twitter.com',client.transport.url.host)
+    assert_match(%r{^/1/search},client.transport.url.path)
+
+    client.api = :rest
+    client[:v1].users.show.some_user?
+    assert_equal('api.twitter.com',client.transport.url.host)
+    assert_match(%r{^/1/users/show/some_user},client.transport.url.path)
+  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 with_http_responder(responder)
+      Net::HTTP.responder = responder
+      yield
+    ensure
+      Net::HTTP.responder = nil
+    end
+    
+    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

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification 
+name: grackle
+version: !ruby/object:Gem::Version 
+  version: 0.1.5
+platform: ruby
+authors: 
+- Hayes Davis
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-23 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  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 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Grackle is a lightweight library for the Twitter REST and Search API.
+email: hayes@appozite.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- CHANGELOG.rdoc
+- 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
+has_rdoc: true
+homepage: http://github.com/hayesdavis/grackle
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+- --main=README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: grackle
+rubygems_version: 1.3.5
+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. It supports both basic and OAuth authentication mechanisms.
+test_files: []
+