hayesdavis-grackle 0.0.1 → 0.0.4

data/README.txt

@@ -1,7 +1,8 @@
-grackle
-    by Hayes Davis
-    http://www.appozite.com
-    http://hayesdavis.net
+=grackle
+by Hayes Davis
+	hayes@appozite.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 
@@ -17,6 +18,7 @@ will potentially require, however, some modifications to your code that uses Gra
 ==USING GRACKLE
 
 ===Creating a Grackle::Client
+
   require 'grackle'
   client = Grackle::Client(:username=>'your_user',:password=>'yourpass')
 
@@ -27,10 +29,10 @@ Grackle uses a method syntax that corresponds to the Twitter API URLs with a few
 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
+- 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
 Invoking the API method "/users/show" in XML format for the Twitter user "some_user" looks like
@@ -59,17 +61,25 @@ Or, with JSON
 Or, using the default format
   client.statuses.update! :status=>'this status is from grackle' #POST to http://twitter.com/statuses/update.json
 
-===Search
-Search works the same as everything else but your queries get submitted to search.twitter.com
-  client.search? :q=>'grackle' #http://search.twitter.com/search.json?q=grackle
+===Toggling APIs
+By default, the Grackle::Client sends all requests to the 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? :exclue=>'hashtags'
+  client[:rest].users.show? :id=>'hayesdavis'
+ 
+Search and REST requests are all built using the same method chaining and termination conventions.
 
 ===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
+- 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 a Grackle::TwitterStruct (which is mostly just an OpenStruct) of data. The attributes 
+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
@@ -77,6 +87,8 @@ If the request to Twitter does not return a status code of 200, then a TwitterEr
 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 currently supports JSON and XML. 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 
@@ -85,8 +97,8 @@ 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_pure
+- httpclient 
 
 == INSTALL:
 

data/grackle.gemspec

@@ -2,12 +2,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{grackle}
-  s.version = "0.0.1"
+  s.version = "0.0.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Hayes Davis"]
-  s.date = %q{2009-03-22}
-  s.description = %q{Grackle is a library for the Twitter REST and Search API that aims to go with the flow.}
+  s.date = %q{2009-03-23}
+  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", "bin/grackle", "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.has_rdoc = true
@@ -16,7 +16,7 @@ Gem::Specification.new do |s|
   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}
+  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.}
 
   if s.respond_to? :specification_version then
     current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
@@ -24,16 +24,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>, [">= 2.1.4"])
+      s.add_runtime_dependency(%q<httpclient>, [">= 0"])
       s.add_development_dependency(%q<bones>, [">= 2.4.2"])
     else
       s.add_dependency(%q<json>, [">= 0"])
-      s.add_dependency(%q<httpclient>, [">= 2.1.4"])
+      s.add_dependency(%q<httpclient>, [">= 0"])
       s.add_dependency(%q<bones>, [">= 2.4.2"])
     end
   else
     s.add_dependency(%q<json>, [">= 0"])
-    s.add_dependency(%q<httpclient>, [">= 2.1.4"])
+    s.add_dependency(%q<httpclient>, [">= 0"])
     s.add_dependency(%q<bones>, [">= 2.4.2"])
   end
-end
+end

data/lib/grackle/client.rb

@@ -7,52 +7,65 @@ module Grackle
   class TwitterError < StandardError
     attr_accessor :method, :request_uri, :status, :response_body, :response_object
   
-    def initialize(method, request_uri, status, response_body)
+    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("#{self.method} #{self.request_uri} => #{self.status}: #{self.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.
   class Client
         
     class Request
-      attr_accessor :path, :method
+      attr_accessor :path, :method, :api, :ssl
       
-      def method
-        @method ||= :get
+      def initialize(api=:rest,ssl=true)
+        self.api = api
+        self.ssl = ssl
+        self.method = :get
+        self.path = ''
       end
       
       def <<(path)
         self.path << path
       end
       
-      def path
-        @path ||= ''
-      end
-      
       def path?
         path.length > 0
       end
+    
+      def url
+        "#{scheme}://#{host}#{path}"
+      end
+         
+      def host
+        APIS[api]
+      end
+    
+      def scheme
+        ssl ? 'https' :'http'
+      end
     end
     
     VALID_METHODS = [:get,:post,:put,:delete]
     VALID_FORMATS = [:json,:xml,:atom,:rss]
+
+    APIS = {:rest=>'twitter.com',:search=>'search.twitter.com'}
     
-    REST_API_DOMAIN = 'twitter.com'
-    SEARCH_API_DOMAIN = 'search.twitter.com'
-    
-    attr_accessor :username, :password, :handlers, :default_format, :headers, :ssl, :transport, :request
+    attr_accessor :username, :password, :handlers, :default_format, :headers, :ssl, :api, :transport, :request 
     
     # Arguments (all are optional):
-    #   :username - twitter username to authenticate with
-    #   :password - twitter password to authenticate with
-    #   :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)
-    #   :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://)
+    # - :username       - twitter username to authenticate with
+    # - :password       - twitter password to authenticate with
+    # - :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
     def initialize(options={})
       self.transport = Transport.new
       self.username = options.delete(:username)
@@ -62,15 +75,10 @@ module Grackle
       self.default_format = options[:default_format] || :json 
       self.headers = {'User-Agent'=>'Grackle/1.0'}.merge!(options[:headers]||{})
       self.ssl = options[:ssl] == true
+      self.api = options[:api] || :rest
     end
                
     def method_missing(name,*args)
-      #Check for HTTP method and apply it to the request. 
-      #Can use this for an explict HTTP method
-      if http_method_invocation?(name)
-        self.request.method = name
-        return self
-      end
       #If method is a format name, execute using that format
       if format_invocation?(name)
         return call_with_format(name,*args)
@@ -92,35 +100,57 @@ module Grackle
       self
     end
     
-    protected
-      def rest_api_domain
-        REST_API_DOMAIN
-      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
     
-      def search_api_domain
-        SEARCH_API_DOMAIN
-      end
-
+    #Clears any pending request built up by chained methods but not executed
+    def clear
+      self.request = nil
+    end
+    
+    protected
       def call_with_format(format,params={})
         id = params.delete(:id)
-        self.request << "/#{id}" if id
-        self.request << ".#{format}"
-        url = "#{scheme}://#{request_host}#{self.request.path}"
-        req_info = self.request
-        self.request = nil
-        res = transport.request(
-          req_info.method,url,:username=>self.username,:password=>self.password,:headers=>headers,:params=>params
-        )
-        fmt_handler = handler(format) 
-        unless res.status == 200
-          handle_error_response(res,fmt_handler)
-        else
-          fmt_handler.decode_response(res.body)
+        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,:username=>self.username,:password=>self.password,:headers=>headers,:params=>params
+          )
+        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
+        @request ||= Request.new(api,ssl)
       end
       
       def handler(format)
@@ -133,21 +163,8 @@ module Grackle
         raise err        
       end
       
-      def http_method_invocation?(name)
-        !self.request.path? && VALID_METHODS.include?(name)
-      end
-      
       def format_invocation?(name)
         self.request.path? && VALID_FORMATS.include?(name)
       end
-            
-      def request_host
-        self.request.path =~ /^\/search/ ? search_api_domain : rest_api_domain
-      end
-    
-      def scheme
-        self.ssl ? 'https' :'http'
-      end
-    
   end
 end

data/lib/grackle/handlers.rb

@@ -3,7 +3,7 @@ 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+ method which accepts the response body 
+  # is intended to provide a +decode_response+ method which accepts the response body 
   # as a string.
   module Handlers
     

data/lib/grackle.rb

@@ -1,7 +1,7 @@
 module Grackle
 
   # :stopdoc:
-  VERSION = '0.0.1'
+  VERSION = '0.0.4'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   # :startdoc:
@@ -24,4 +24,4 @@ require 'json'
 require 'grackle/utils'
 require 'grackle/transport'
 require 'grackle/handlers'
-require 'grackle/client'
+require 'grackle/client'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: hayesdavis-grackle
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
+  version: 0.0.4
 platform: ruby
 authors: 
 - Hayes Davis
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-22 00:00:00 -07:00
+date: 2009-03-23 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -30,7 +30,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 2.1.4
+        version: "0"
     version: 
 - !ruby/object:Gem::Dependency 
   name: bones
@@ -42,7 +42,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 2.4.2
     version: 
-description: Grackle is a library for the Twitter REST and Search API that aims to go with the flow.
+description: Grackle is a lightweight library for the Twitter REST and Search API.
 email: hayes@appozite.com
 executables: []
 
@@ -90,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
+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.
 test_files: []