twitter-search-watcher.rb in devfu-twitter-search-watcher-0.1.2

- old
+ new

@@ -1,7 +1,12 @@
 %w( rubygems cgi json open-uri ostruct ).each {|lib| require lib }
 
+# 
+# = Usage
+#
+#   coming soon
+#
 class TwitterSearchWatcher
 
   TWITTER_SEARCH_URL      = 'http://search.twitter.com/search.json'
   DEFAULT_USER_AGENT      = 'TwitterSearchWatcher RubyGem http://github.com/devfu/twitter-search-watcher'
   QUERY_STRING_ATTRIBUTES = [ :q, :to, :from, :since_id, :page, :max_id, :rpp ]
@@ -85,11 +90,11 @@
     @user_agent || DEFAULT_USER_AGENT
   end
 
   # Performs a search.  Accepts the same parameters as #search_url
   def search! additional_parameters = nil
-    JSON.parse open( search_url(additional_parameters), 'User-Agent' => user_agent ).read
+    json search_url(additional_parameters)
   end
 
   # Performs a search, given the response from another search.
   #
   # If a response if given, the search will only return tweets newer than the given response's tweets.
@@ -110,9 +115,71 @@
   # this will return the next page.  Else, this will return nil.
   #
   # Accepts additional parameters (same as #search_url)
   def search_more! response, additional_parameters = nil
     search!( (additional_parameters || {}).merge( :page => (response['page'] + 1), :max_id => response['max_id'] ) ) if response['next_page']
+  end
+
+  # Performs a search! and search_more! as needed to return a response with *all* pages of tweets.
+  #
+  # This respects max_pages and will only make max_pages number of additional requests to get paginated tweets.
+  #
+  # The response object returned is similar to the responses returned by all other methods, but we only 
+  # currently have a 'results' key on the Hash returned.  If you're used to getting some of the other keys 
+  # returned by the other methods (which Twitter returns), be warned!
+  #
+  # To get the tweets off of the response:
+  #
+  #   tweets = watcher.search_with_pagination!['results']
+  def search_with_pagination! additional_parameters = nil
+    response     = search! additional_parameters
+
+    max_requests = max_pages
+    max_requests = additional_parameters[:max_pages] if additional_parameters && additional_parameters[:max_pages]
+
+    tweets = { 'results' => [] }
+    pages_requested_so_far = 0
+
+    if response['next_page']
+      while response = search_more!(response)
+        tweets['results'] << response['results']
+        pages_requested_so_far += 1
+
+        break if max_requests && pages_requested_so_far >= max_requests
+      end
+    end
+
+    tweets
+  end
+
+  # Helper to do an HTTP GET request and return the response body
+  def get url
+    TwitterSearchWatcher.get url, 'User-Agent' => user_agent
+  end
+
+  # Helper to do an HTTP GET request and return the response body
+  def self.get url, options = {}
+    open( url, { 'User-Agent' => DEFAULT_USER_AGENT }.merge(options) ).read
+  end
+
+  # Helper to #get a url and return the response body parsed as JSON
+  def json url
+    JSON.parse get(url)
+  end
+
+  # Helper to #get a url and return the response body parsed as JSON
+  def self.json url
+    JSON.parse get(url)
+  end
+
+  # Instantiates a new TwitterSearchWatcher given the search_string and options and then 
+  # calls search_with_pagination! on the instance, returning the response.
+  #
+  #   tweets_json = TwitterSearchWatcher.search_with_pagination!('foo')['results']
+  #
+  def self.search_with_pagination! search_string, options = nil
+    watcher = TwitterSearchWatcher.new search_string, options
+    watcher.search_with_pagination!
   end
 
   # Instantiates a new TwitterSearchWatcher given the search_string and options and then 
   # calls #watch on the instance using the block given.
   def self.watch! search_string, options = nil, &block