look-twitter-search 0.5.3

data/README.markdown

@@ -0,0 +1,79 @@
+# A Twitter Search client for Ruby.
+
+Access the Twitter Search API from your Ruby code.
+
+## Usage
+
+Install the gem.
+
+    sudo gem install dancroak-twitter-search -s http://gems.github.com
+
+Require the gem.
+
+    require 'twitter_search'
+
+Set up a TwitterSearch::Client. Name your client (a.k.a. 'user agent') to something meaningful, such as your app's name. This helps Twitter Search answer any questions about your use of the API.
+
+	@client = TwitterSearch::Client.new 'politweets'
+	
+Request tweets by calling the query method of your client. It takes either a String or a Hash of arguments.
+
+    @tweets = @client.query 'twitter search'
+
+The String form uses the default Twitter Search behavior, which in this example finds tweets containing both "twitter" and "search". It is identical to the more verbose, explicit version:
+
+    @tweets = @client.query :q => 'twitter search'
+
+Use the Twitter Search API's query operators with the :q key to access a variety of behavior.
+
+## Search Operators
+
+The following operator examples find tweets...
+
+* <a href="http://search.twitter.com/search?q=twitter+search">:q => 'twitter search'</a> - containing both "twitter" and "search". This is the default operator. 
+* <a href="http://search.twitter.com/search?q=%22happy+hour%22">:q => '<b>"</b>happy hour<b>"</b>'</a> - containing the exact phrase "happy hour".
+* <a href="http://search.twitter.com/search?q=obama+OR+hillary">:q => 'obama <b>OR</b> hillary'</a> - containing either "obama" or "hillary" (or both).
+* <a href="http://search.twitter.com/search?q=beer+-root">:q => 'beer <b>-</b>root'</a> - containing "beer" but not "root".
+* <a href="http://search.twitter.com/search?q=%23haiku">:q => '<b>#</b>haiku</a>' - containing the hashtag "haiku".
+* <a href="http://search.twitter.com/search?q=from%3Aalexiskold">:q => '<b>from:</b>alexiskold'</a> - sent from person "alexiskold".
+* <a href="http://search.twitter.com/search?q=to%3Atechcrunch">:q => '<b>to:</b>techcrunch</a>' - sent to person "techcrunch".
+* <a href="http://search.twitter.com/search?q=%40mashable">:q => '<b>@</b>mashable</a>' - referencing person "mashable".
+* <a href="http://search.twitter.com/search?q=superhero+since%3A2008-05-01">:q => 'superhero <b>since:</b>2008-05-01'</a> - containing "superhero" and sent since date "2008-05-01" (year-month-day).
+* <a href="http://search.twitter.com/search?q=ftw+until%3A2008-05-03">:q => 'ftw <b>until:</b>2008-05-03'</a> - containing "ftw" and sent up to date "2008-05-03".
+* <a href="http://search.twitter.com/search?q=movie+-scary+%3A%29">:q => 'movie -scary <b>:)</b>'</a> - containing "movie", but not "scary", and with a positive attitude.
+* <a href="http://search.twitter.com/search?q=flight+%3A%28">:q => 'flight <b>:(</b>'</a> - containing "flight" and with a negative attitude.
+* <a href="http://search.twitter.com/search?q=traffic+%3F">:q => 'traffic <b>?</b>'</a> - containing "traffic" and asking a question.
+* <a href="http://search.twitter.com/search?q=hilarious+filter%3Alinks">:q => 'hilarious <b>filter:links</b>'</a> - containing "hilarious" and linking to URLs.
+
+### Foreign Languages
+
+The Twitter Search API supports foreign languages, accessible via the :lang key. Use the [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) codes as the value:
+
+    @tweets = @client.query :q => 'programmé', :lang => 'fr'
+
+### Pagination
+
+Alter the number of Tweets returned per page with the :rpp key. Stick with 10, 15, 20, 25, 30, or 50.
+
+    @tweets = @client.query :q => 'Boston Celtics', :rpp => '30'
+
+## Gotchas
+
+* Searches are case-insenstive.
+* The "near" operator available in the Twitter Search web interface is not available via the API. You must geocode before making your Twitter Search API call, and use the :geocode key in your request using the pattern lat,lngmi or lat,lngkm:
+
+        @tweets = @client.query :q => 'Pearl Jam', :geocode => '43.4411,-70.9846mi'
+
+* Searching for a positive attitude :) returns tweets containing the text :), =), :D, and :-)
+
+## Authors
+
+Written by Dustin Sallings (dustin@spy.net), forked by Dan Croak (dcroak@thoughtbot.com).
+
+## Resources
+
+* [Official Twitter Search API](http://search.twitter.com/api)
+
+## License
+
+MIT License, same terms as Ruby.

data/Rakefile

@@ -0,0 +1,70 @@
+require 'rake'
+require 'rake/testtask'
+ 
+test_files_pattern = 'test/twitter_search_test.rb'
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = test_files_pattern
+  t.verbose = false
+end
+ 
+desc "Run the test suite"
+task :default => :test
+ 
+gem_spec = Gem::Specification.new do |gem_spec|
+  gem_spec.name        = "twitter-search"
+  gem_spec.version     = "0.5.2"
+  gem_spec.summary     = "Ruby client for Twitter Search."
+  gem_spec.email       = "dcroak@thoughtbot.com"
+  gem_spec.homepage    = "http://github.com/dancroak/twitter-search"
+  gem_spec.description = "Ruby client for Twitter Search."
+  gem_spec.authors     = ["Dustin Sallings", "Dan Croak"]
+  gem_spec.files       = FileList["[A-Z]*", "{generators,lib,shoulda_macros,rails}/**/*"]
+  gem_spec.add_dependency('json', '>= 1.1.2')
+end
+
+desc "Generate a gemspec file"
+task :gemspec do
+  File.open("#{gem_spec.name}.gemspec", 'w') do |f|
+    f.write gem_spec.to_yaml
+  end
+end
+
+require File.expand_path('lib/twitter_search', File.dirname(__FILE__))
+require 'rubygems'
+require 'yaml'
+
+namespace :yaml do
+  desc "Write Twitter Search results to yaml file so API is not hit every test."
+  task :write do    
+    write_yaml :tweets => 'Obama',                                     :file => 'obama'
+    write_yaml :tweets => 'twitter search',                            :file => 'twitter_search'
+    write_yaml :tweets => {:q => 'twitter search'},                    :file => 'twitter_search_and'
+    write_yaml :tweets => {:q => '"happy hour"'},                      :file => 'happy_hour_exact'  
+    write_yaml :tweets => {:q => 'obama OR hillary'},                  :file => 'obama_or_hillary'
+    write_yaml :tweets => {:q => 'beer -root'},                        :file => 'beer_minus_root'
+    write_yaml :tweets => {:q => '#haiku'},                            :file => 'hashtag_haiku'
+    write_yaml :tweets => {:q => 'from:alexiskold'},                   :file => 'from_alexiskold'
+    write_yaml :tweets => {:q => 'to:techcrunch'},                     :file => 'to_techcrunch'
+    write_yaml :tweets => {:q => '@mashable'},                         :file => 'reference_mashable'
+    write_yaml :tweets => {:q => '"happy hour" near:"san francisco"'}, :file => 'happy_hour_near_sf'
+    write_yaml :tweets => {:q => 'near:NYC within:15mi'},              :file => 'within_15mi_nyc'
+    write_yaml :tweets => {:q => 'superhero since:2008-05-01'},        :file => 'superhero_since'
+    write_yaml :tweets => {:q => 'ftw until:2008-05-03'},              :file => 'ftw_until'
+    write_yaml :tweets => {:q => 'movie -scary :)'},                   :file => 'movie_positive_tude'
+    write_yaml :tweets => {:q => 'flight :('},                         :file => 'flight_negative_tude'
+    write_yaml :tweets => {:q => 'traffic ?'},                         :file => 'traffic_question'
+    write_yaml :tweets => {:q => 'hilarious filter:links'},            :file => 'hilarious_links'
+    write_yaml :tweets => {:q => 'congratulations', :lang => 'en'},    :file => 'english'
+    write_yaml :tweets => {:q => 'با', :lang => 'ar'},                 :file => 'arabic'
+    write_yaml :tweets => {:q => 'Boston Celtics', :rpp => '30'},      :file => 'results_per_page'
+  end
+end
+
+def write_yaml(opts = {})
+  @client = TwitterSearch::Client.new 'twitter-search'
+  tweets  = @client.query(opts[:tweets])
+  File.open(File.join(File.dirname(__FILE__), 'test', 'yaml', "#{opts[:file]}.yaml"), 'w+') do |file| 
+    file.puts tweets.to_yaml
+  end
+end

data/TODO.markdown

@@ -0,0 +1,7 @@
+Add tests for:
+
+* since_id: returns tweets with status ids greater than the given id.
+* geocode: returns tweets by users located within a given radius of the given latitude/longitude, where the user's location is taken from their Twitter profile.
+* show_user: when "true", adds "<user>:" to the beginning of the tweet. This is useful for readers that do not display Atom's author field. The default is "false".
+* callback: if supplied, the response will use the JSONP format with a callback of the given name. E.g., http://search.twitter.com/search.json?callback=foo&q=twitter
+

data/lib/twitter_search.rb

@@ -0,0 +1,94 @@
+require 'rubygems'
+require 'net/http'
+require 'json'
+require 'cgi'
+
+module TwitterSearch
+
+  class Tweet
+    VARS = [:text, :from_user, :to_user, :to_user_id, :id, :iso_language_code, :from_user_id, :created_at, :profile_image_url, :source ]
+    attr_reader *VARS
+    attr_reader :language
+    
+    def initialize(opts)
+      @language = opts['iso_language_code']
+      VARS.each { |each| instance_variable_set "@#{each}", opts[each.to_s] }
+    end
+  end
+
+  class Tweets
+    VARS = [:since_id, :max_id, :results_per_page, :page, :query, :next_page]
+    attr_reader *VARS
+
+    include Enumerable
+
+    def initialize(opts)
+      @results = opts['results'].collect { |each| Tweet.new(each) }
+      VARS.each { |each| instance_variable_set "@#{each}", opts[each.to_s] }
+    end
+
+    def each(&block)
+      @results.each(&block)
+    end
+
+    def size
+      @results.size
+    end
+    
+    def [](index)
+      @results[index]
+    end
+  end
+
+  class Client
+    TWITTER_API_URL = 'http://search.twitter.com/search.json'
+    TWITTER_API_DEFAULT_TIMEOUT = 5
+    
+    attr_accessor :agent
+    
+    def initialize(agent = 'twitter-search')
+      @agent = agent
+    end
+    
+    def headers
+      { "Content-Type" => 'application/json',
+        "User-Agent"   => @agent }
+    end
+    
+    def timeout
+      TWITTER_API_DEFAULT_TIMEOUT
+    end
+    
+    def query(opts = {})
+      url       = URI.parse(TWITTER_API_URL)
+      url.query = sanitize_query(opts)
+      
+      req  = Net::HTTP::Get.new(url.path)
+      http = Net::HTTP.new(url.host, url.port)
+      http.read_timeout = timeout
+      
+      json = http.start { |http|
+        http.get("#{url.path}?#{url.query}", headers)
+      }.body
+      Tweets.new JSON.parse(json)
+    end
+
+    private
+
+      def sanitize_query(opts)
+        if opts.is_a? String
+          "q=#{CGI.escape(opts)}" 
+        elsif opts.is_a? Hash
+          "#{sanitize_query_hash(opts)}"
+        end
+      end
+
+      def sanitize_query_hash(query_hash)
+        query_hash.collect { |key, value| 
+          "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}" 
+        }.join('&')
+      end
+  
+  end
+
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: look-twitter-search
+version: !ruby/object:Gem::Version 
+  version: 0.5.3
+platform: ruby
+authors: 
+- Dustin Sallings
+- Dan Croak
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-03 21:00:00 -08: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: 1.1.2
+    version: 
+description: Ruby client for Twitter Search.
+email: dcroak@thoughtbot.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Rakefile
+- README.markdown
+- TODO.markdown
+- VERSION.yml
+- lib/twitter_search.rb
+has_rdoc: false
+homepage: http://github.com/dancroak/twitter-search
+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.2.0
+signing_key: 
+specification_version: 2
+summary: Ruby client for Twitter Search.
+test_files: []
+