twitter-search-watcher 0.1.4

data/lib/twitter-search-watcher.rb

@@ -0,0 +1,259 @@
+%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 ]
+
+  # The User-Agent header value to send along with all Twitter Search API requests
+  attr_accessor :user_agent
+
+  # A string you want to search twitter for
+  attr_accessor :q
+  
+  # The username of someone you want to search replies to
+  attr_accessor :to
+
+  # The username of someone you want to search replies from
+  attr_accessor :from
+
+  # Get a particular page of Twitter search results (pagination).
+  # Typically used in conjunction with :max_id
+  attr_accessor :page
+
+  # Used for pagination, so you can get page=3 where the max_id of the first page was 1234
+  attr_accessor :max_id
+
+  # Only get tweets with ID's greater than this ID (useful for only getting new tweets)
+  attr_accessor :since_id
+
+  # Number of results per page (max 100)
+  attr_accessor :rpp
+
+  # The number of seconds to wait between Twitter calls.  Default: 60 (seconds)
+  attr_accessor :check_every
+
+  # The maximum number of pages to check for tweets
+  #
+  # If nil, we'll check until there are no more pages (when :next_page isn't present)
+  attr_accessor :max_pages
+
+  def rpp= value
+    raise "The maximum rpp (Results per Page) value is 100" if value > 100
+    @rpp = value
+  end
+
+  def check_every
+    @check_every || 60
+  end
+
+  # Create a new TwitterSearchWatcher
+  #
+  #   TwitterSearchWatcher.new 'string to search'
+  #   TwitterSearchWatcher.new 'string to search', :check_every => 60
+  #   TwitterSearchWatcher.new :to => 'barackobama', :from => 'SenJohnMcCain'
+  #
+  def initialize search_string = nil, options = nil
+    if search_string.is_a? Hash
+      options = search_string
+    else
+      self.q = search_string
+    end
+
+    options.each {|k,v| send "#{k}=", v } if options
+  end
+
+  # Returns the URL we'll use to call the Twitter Search API.
+  #
+  # Without parameters, it'll generate a URL just from this TwitterSearchWatcher instance.
+  #
+  # With parameters, it'll override the TwitterSearchWatcher instance's options with 
+  # whatever you pass, eg.
+  #
+  #   >> TwitterSearchWatcher.new( 'foo', :rpp => 15 ).search_url
+  #   => "http://search.twitter.com/search.json?q=foo&rpp=15"
+  #
+  #   >> TwitterSearchWatcher.new( 'foo', :rpp => 15 ).search_url( :rpp => 99 )
+  #   => "http://search.twitter.com/search.json?q=foo&rpp=99"
+  #
+  def search_url additional_parameters = nil
+    TWITTER_SEARCH_URL + build_query_string(additional_parameters)
+  end
+
+  def user_agent
+    @user_agent || DEFAULT_USER_AGENT
+  end
+
+  # Performs a search.  Accepts the same parameters as #search_url
+  def search! additional_parameters = nil
+    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.
+  # If a response is not given, this performs a normal search.
+  #
+  # Accepts additional parameters (same as #search_url)
+  def search_newer! response = nil, additional_parameters = nil
+    if response
+      search!( (additional_parameters || {}).merge( :since_id => response['max_id'] ) )
+    else
+      search! additional_parameters
+    end
+  end
+
+  # Performs a search, given the response from another search.
+  #
+  # If the response given is paginated (ie. there are additional tweets available on additional pages), 
+  # 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' => response['results'] }
+    pages_requested_so_far = 1
+
+    if response['next_page'] and (max_requests.nil? or max_requests > 1) # we've already dony 1 request
+      while response = search_more!(response, additional_parameters)
+        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
+    watcher = TwitterSearchWatcher.new search_string, options
+    watcher.watch! &block
+  end
+
+  # Starts watching this search in a loop.
+  # It will wait #check_every seconds between new requests (except requests to get additional pages).
+  # Every time a new tweet is found, that tweet is passed to the block given.
+  #
+  #   TwitterSearchWatcher.new('foo').watch! {|tweet| puts "got tweet: #{ tweet.text }" }
+  #
+  def watch! additional_parameters = nil, &block
+    @max_id_found_so_far = 0
+  
+    trap('INT'){ puts "\nexiting ..."; exit }
+    puts "Watching for tweets: #{ search_url(additional_parameters) }"
+
+    loop do
+
+      @last_response = search_newer!(@last_response, additional_parameters)
+      call_tweet_callbacks(@last_response, block)
+      update_max_id @last_response
+
+      # this is kindof icky ... but it works
+      if @last_response['next_page']
+        response = @last_response
+        num_pages_searched = 0
+        while (response = search_more!(response, additional_parameters)) && (num_pages_searched <= max_pages if max_pages)
+          num_pages_searched += 1
+          call_tweet_callbacks(response, block)
+          update_max_id response
+        end
+      end
+
+      sleep check_every
+    end
+  end
+
+private
+
+  def update_max_id response
+    @max_id_found_so_far = response['max_id'] if response['max_id'] > @max_id_found_so_far
+  end
+
+  def call_tweet_callbacks response, block
+    response['results'].each do |tweet|
+      tweet['tweet_id'] = tweet.delete 'id'
+      block.call OpenStruct.new(tweet)
+    end
+  end
+
+  def escape string
+    CGI.escape(string.to_s).gsub('%22','"').gsub(' ','+')
+  end
+
+  def build_query_string additional_parameters = nil
+    parameter_values = QUERY_STRING_ATTRIBUTES.inject({}){|all, attr|
+      all[attr] = send(attr) if send(attr)
+      all
+    }
+
+    # if additional parameters are passed, we override the watcher's parameters with these
+    if additional_parameters
+      additional_parameter_values = QUERY_STRING_ATTRIBUTES.inject({}){|all, attr|
+        all[attr] = additional_parameters[attr] if additional_parameters.keys.include?(attr)
+        all
+      }
+      parameter_values.merge! additional_parameter_values
+    end
+
+    '?' + parameter_values.map {|k,v| "#{ k }=#{ escape(v) }" if v }.compact.join('&')
+  end
+
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification 
+name: twitter-search-watcher
+version: !ruby/object:Gem::Version 
+  version: 0.1.4
+platform: ruby
+authors: []
+
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-05 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: for watching a particular Twitter search and calling code whenever there are new tweets
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/twitter-search-watcher.rb
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: for watching a Twitter search
+test_files: []
+