Add Twitter::GeoResults class

Closes #418.

README.md

@@ -218,7 +218,7 @@ The last example might seem contrived ("Why would I need to call
 each time you called one of those methods, it would perform *n+1* HTTP
 requests. In version 5, it will only perform those HTTP requests the first time
 one of those methods is called. Each subsequent call fetches data from a
-[cache][cache].
+[cache][].
 
 [enumerable]: http://ruby-doc.org/core-2.0/Enumerable.html
 [cache]: https://github.com/sferik/twitter/commit/7d8b2727af9400643ac397207185fd54e3f6387b
@@ -252,6 +252,14 @@ This object exposes the recency of the trend (via `#as_of`), when the trend
 started (via `#created_at`), and the location of the trend (via `#location`).
 This information was previously unavailable.
 
+### Geo Results
+The `Twitter::API::PlacesAndGeo#reverse_geocode`,
+`Twitter::API::PlacesAndGeo#geo_search`, and
+`Twitter::API::PlacesAndGeo#similar_places` methods now return an
+[`Enumerable`][enumerable] `Twitter::GeoResults` object instead of an array.
+This object exposes the token to create a new place (via `#token`), which was
+previously unavailable.
+
 ### Users
 The `Twitter::User` object has been cleaned up. The following methods have been
 removed:
@@ -300,7 +308,7 @@ elsif status.geo?
 end
 ```
 
-### URL methods
+### URL Methods
 `Twitter::List`, `Twitter::Tweet`, and `Twitter::User` objects all have `#url`
 methods, which generate an HTTPS URL to twitter.com. You may specify a
 different protocol by passing it to the `#url` method. For example:
@@ -312,8 +320,7 @@ status.url("http") #=> http://twitter.com/sferik/status/55709764298092545
 ```
 
 `Twitter::User` previously had a method called `#url`, which returned the URL
-to the user's website. The URL is now accessible via the `#website` method.
-
+to the user's website. This URL is now accessible via the `#website` method.
 
 These methods are aliased to `#uri`, for users who prefer that nomenclature.
 This clobbers the `Twitter::List#uri` method, which previously returned the

lib/twitter/api/places_and_geo.rb

@@ -1,4 +1,5 @@
 require 'twitter/api/utils'
+require 'twitter/geo_results'
 require 'twitter/place'
 
 module Twitter
@@ -38,7 +39,7 @@ def place(place_id, options={})
       # @example Return an array of places within the specified region
       #   Twitter.reverse_geocode(:lat => "37.7821120598956", :long => "-122.400612831116")
       def reverse_geocode(options={})
-        geo_objects_from_response(:get, "/1.1/geo/reverse_geocode.json", options)
+        object_from_response(Twitter::GeoResults, :get, "/1.1/geo/reverse_geocode.json", options)
       end
 
       # Search for places that can be attached to a {Twitter::API::Tweets#update}
@@ -61,7 +62,7 @@ def reverse_geocode(options={})
       # @example Return an array of places near the IP address 74.125.19.104
       #   Twitter.geo_search(:ip => "74.125.19.104")
       def geo_search(options={})
-        geo_objects_from_response(:get, "/1.1/geo/search.json", options)
+        object_from_response(Twitter::GeoResults, :get, "/1.1/geo/search.json", options)
       end
       alias places_nearby geo_search
 
@@ -82,7 +83,7 @@ def geo_search(options={})
       # @example Return an array of places similar to Twitter HQ
       #   Twitter.similar_places(:lat => "37.7821120598956", :long => "-122.400612831116", :name => "Twitter HQ")
       def similar_places(options={})
-        geo_objects_from_response(:get, "/1.1/geo/similar_places.json", options)
+        object_from_response(Twitter::GeoResults, :get, "/1.1/geo/similar_places.json", options)
       end
       alias places_similar similar_places
 
@@ -106,16 +107,6 @@ def place_create(options={})
         object_from_response(Twitter::Place, :post, "/1.1/geo/place.json", options)
       end
 
-    private
-
-      # @param request_method [Symbol]
-      # @param path [String]
-      # @param params [Hash]
-      # @return [Array]
-      def geo_objects_from_response(request_method, path, params={})
-        objects_from_array(Twitter::Place, send(request_method.to_sym, path, params)[:body][:result][:places])
-      end
-
     end
   end
 end

lib/twitter/geo_results.rb

@@ -0,0 +1,47 @@
+require 'twitter/creatable'
+require 'twitter/null_object'
+
+module Twitter
+  class GeoResults
+    include Enumerable
+    include Twitter::Creatable
+    attr_reader :attrs
+    alias to_h attrs
+    alias to_hash attrs
+    alias to_hsh attrs
+
+    # Construct a new SearchResults object from a response hash
+    #
+    # @param response [Hash]
+    # @return [Twitter::Base]
+    def self.from_response(response={})
+      new(response[:body])
+    end
+
+    # Initializes a new SearchResults object
+    #
+    # @param attrs [Hash]
+    # @return [Twitter::GeoResults]
+    def initialize(attrs={})
+      @attrs = attrs
+      @collection = Array(@attrs[:result][:places]).map do |place|
+        Twitter::Place.new(place)
+      end
+    end
+
+    # @return [Enumerator]
+    def each(start = 0, &block)
+      return to_enum(:each) unless block_given?
+      Array(@collection[start..-1]).each do |element|
+        yield element
+      end
+      self
+    end
+
+    # @return [String]
+    def token
+      @attrs[:token]
+    end
+
+  end
+end

lib/twitter/search_results.rb

@@ -17,7 +17,7 @@ def self.from_response(response={})
     # Initializes a new SearchResults object
     #
     # @param attrs [Hash]
-    # @return [Twitter::Base]
+    # @return [Twitter::SearchResults]
     def initialize(attrs={})
       @attrs = attrs
       @collection = Array(@attrs[:statuses]).map do |tweet|

lib/twitter/trend_results.rb

@@ -21,7 +21,7 @@ def self.from_response(response={})
     # Initializes a new SearchResults object
     #
     # @param attrs [Hash]
-    # @return [Twitter::Base]
+    # @return [Twitter::TrendResults]
     def initialize(attrs={})
       @attrs = attrs
       @collection = Array(@attrs[:trends]).map do |trend|

lib/twitter/tweet.rb

@@ -81,17 +81,9 @@ def place?
 
     # @return [Boolean]
     def reply?
-      !!in_reply_to_status_id
+      !in_reply_to_status_id.nil?
     end
 
-    # @return [Boolean]
-    def retweeted_status?
-      !!retweeted_status
-    end
-    alias retweet? retweeted_status?
-    alias retweeted? retweeted_status?
-    alias retweeted_tweet? retweeted_status?
-
     # If this Tweet is a retweet, the original Tweet is available here.
     #
     # @return [Twitter::Tweet]
@@ -106,6 +98,7 @@ def retweeted_status?
       !retweeted_status.nil?
     end
     alias retweet? retweeted_status?
+    alias retweeted? retweeted_status?
     alias retweeted_tweet? retweeted_status?
 
     # @note Must include entities in your request for this method to work

spec/twitter/api/geo_spec.rb

@@ -30,7 +30,7 @@
     end
     it "returns places" do
       places = @client.reverse_geocode(:lat => "37.7821120598956", :long => "-122.400612831116")
-      expect(places).to be_an Array
+      expect(places).to be_a Twitter::GeoResults
       expect(places.first.name).to eq "Bernal Heights"
     end
   end
@@ -45,7 +45,7 @@
     end
     it "returns nearby places" do
       places = @client.geo_search(:ip => "74.125.19.104")
-      expect(places).to be_an Array
+      expect(places).to be_a Twitter::GeoResults
       expect(places.first.name).to eq "Bernal Heights"
     end
   end
@@ -60,7 +60,7 @@
     end
     it "returns similar places" do
       places = @client.similar_places(:lat => "37.7821120598956", :long => "-122.400612831116", :name => "Twitter HQ")
-      expect(places).to be_an Array
+      expect(places).to be_a Twitter::GeoResults
       expect(places.first.name).to eq "Bernal Heights"
     end
   end

spec/twitter/geo_results_spec.rb

@@ -0,0 +1,35 @@
+require 'helper'
+
+describe Twitter::GeoResults do
+
+  describe "#each" do
+    before do
+      @geo_results = Twitter::GeoResults.new(:result => {:places => [{:id => 1}, {:id => 2}, {:id => 3}, {:id => 4}, {:id => 5}, {:id => 6}]})
+    end
+    it "iterates" do
+      count = 0
+      @geo_results.each{count += 1}
+      expect(count).to eq 6
+    end
+    context "with start" do
+      it "iterates" do
+        count = 0
+        @geo_results.each(5){count += 1}
+        expect(count).to eq 1
+      end
+    end
+  end
+
+  describe "#token" do
+    it "returns a String when token is set" do
+      geo_results = Twitter::GeoResults.new(:result => {}, :token => "abc123")
+      expect(geo_results.token).to be_a String
+      expect(geo_results.token).to eq "abc123"
+    end
+    it "returns nil when token is not set" do
+      geo_results = Twitter::GeoResults.new(:result => {})
+      expect(geo_results.token).to be_nil
+    end
+  end
+
+end

spec/twitter/trend_results_spec.rb

@@ -4,34 +4,34 @@
 
   describe "#as_of" do
     it "returns a Time when as_of is set" do
-      trend_result = Twitter::TrendResults.new(:id => 1, :as_of => "2012-08-24T23:25:43Z")
-      expect(trend_result.as_of).to be_a Time
+      trend_results = Twitter::TrendResults.new(:id => 1, :as_of => "2012-08-24T23:25:43Z")
+      expect(trend_results.as_of).to be_a Time
     end
     it "returns nil when as_of is not set" do
-      trend_result = Twitter::TrendResults.new(:id => 1)
-      expect(trend_result.as_of).to be_nil
+      trend_results = Twitter::TrendResults.new(:id => 1)
+      expect(trend_results.as_of).to be_nil
     end
   end
 
   describe "#created_at" do
     it "returns a Time when created_at is set" do
-      trend_result = Twitter::TrendResults.new(:id => 1, :created_at => "2012-08-24T23:24:14Z")
-      expect(trend_result.created_at).to be_a Time
+      trend_results = Twitter::TrendResults.new(:id => 1, :created_at => "2012-08-24T23:24:14Z")
+      expect(trend_results.created_at).to be_a Time
     end
     it "returns nil when created_at is not set" do
-      trend_result = Twitter::TrendResults.new(:id => 1)
-      expect(trend_result.created_at).to be_nil
+      trend_results = Twitter::TrendResults.new(:id => 1)
+      expect(trend_results.created_at).to be_nil
     end
   end
 
   describe "#created?" do
     it "returns true when created_at is set" do
-      trend_result = Twitter::TrendResults.new(:id => 1, :created_at => "2012-08-24T23:24:14Z")
-      expect(trend_result.created?).to be_true
+      trend_results = Twitter::TrendResults.new(:id => 1, :created_at => "2012-08-24T23:24:14Z")
+      expect(trend_results.created?).to be_true
     end
     it "returns false when created_at is not set" do
-      trend_result = Twitter::TrendResults.new(:id => 1)
-      expect(trend_result.created?).to be_false
+      trend_results = Twitter::TrendResults.new(:id => 1)
+      expect(trend_results.created?).to be_false
     end
   end
 
@@ -55,23 +55,23 @@
 
   describe "#location" do
     it "returns a Twitter::Place when location is set" do
-      trend_result = Twitter::TrendResults.new(:id => 1, :locations => [{:name => "Worldwide", :woeid => 1}])
-      expect(trend_result.location).to be_a Twitter::Place
+      trend_results = Twitter::TrendResults.new(:id => 1, :locations => [{:name => "Worldwide", :woeid => 1}])
+      expect(trend_results.location).to be_a Twitter::Place
     end
     it "returns nil when location is not set" do
-      trend_result = Twitter::TrendResults.new(:id => 1)
-      expect(trend_result.location).to be_nil
+      trend_results = Twitter::TrendResults.new(:id => 1)
+      expect(trend_results.location).to be_nil
     end
   end
 
   describe "#location?" do
     it "returns true when location is set" do
-      trend_result = Twitter::TrendResults.new(:id => 1, :locations => [{:name => "Worldwide", :woeid => 1}])
-      expect(trend_result.location?).to be_true
+      trend_results = Twitter::TrendResults.new(:id => 1, :locations => [{:name => "Worldwide", :woeid => 1}])
+      expect(trend_results.location?).to be_true
     end
     it "returns false when location is not set" do
-      trend_result = Twitter::TrendResults.new(:id => 1)
-      expect(trend_result.location?).to be_false
+      trend_results = Twitter::TrendResults.new(:id => 1)
+      expect(trend_results.location?).to be_false
     end
   end