twitter 5.0.0.rc.1 → 5.0.0

data/CHANGELOG.md

@@ -8,12 +8,15 @@
 * [Remove `Twitter#from_user`](https://github.com/sferik/twitter/commit/d2ae9f1cc1f5224bcdff06cda65fabdf9e7fbcb3)
 * [Remove `ClientError`, `ServerError`, and `ParserError`](https://github.com/sferik/twitter/commit/72843948d8a6f66345adc254fa91cf1097592b22)
 * [Remove global configuration](https://github.com/sferik/twitter/commit/239c5a8462fabb8c8ef9ec6a4cdded34561d572d)
+* [Remove ability to configure client with environment variables](https://github.com/sferik/twitter/commit/17e958579f65abf8932841f20058a5989abb994f)
+* [Remove Brittish English aliases](https://github.com/sferik/twitter/commit/572813b373a1c3001ff6c1bb729f092434d17bab)
 * [Replace `multi_json` with `json`](https://github.com/sferik/twitter/commit/e5fc292fee078567664acf6be4ed31a8ad077780)
 * [Rename `oauth_token` to `access_token`](https://github.com/sferik/twitter/commit/d360f8015c487c4599460abd0dd0bc7e59a522a3)
 * [Move `Twitter::Arguments` out of `REST::API` namespace](https://github.com/sferik/twitter/commit/8faa15309d906dd46fccc1b914ea4aa7a5da7c2d)
 * [Move `Twitter::Client` into `REST` namespace](https://github.com/sferik/twitter/commit/5b8c3fd243227888fc0886b0bf864ecd3a018f99)
 * [Add `Twitter::Streaming::Client`](https://github.com/sferik/twitter/commit/23afe90aa494229a4389c3e51f753102b34fc551)
 * [Add `Twitter::Error::AlreadyPosted`](https://github.com/sferik/twitter/commit/e11d2a27dd0dfbbe16c812a81b9c2ab2852a7790)
+* [Add `Twitter::REST::Client#reverse_token`](https://github.com/sferik/twitter/commit/39139c4df35b54b86fae29d1ac83a08f4aa293cd)
 * [Add `#url` methods to `Twitter::List`, `Twitter::Tweet`, and `Twitter::User`](https://github.com/sferik/twitter/commit/a89ec0f4e81097cc303b6c204e0375eb57ffd614)
 * [Add `Twitter::Place#contained_within` and `#contained_within?`](https://github.com/sferik/twitter/commit/23cc247bd20001ecbafa544bfb4546bdfc630429)
 * [Add `Twitter::GeoResults`](https://github.com/sferik/twitter/commit/be1a0a1425a6700267aae0f94a8835bff24dad56)
@@ -23,9 +26,12 @@
 * [Allow `URI` as argument](https://github.com/sferik/twitter/commit/c207567e674f108e4074e12c9e7343fb74e8a97c)
 * [Allow `String` in addition to `URI` objects](https://github.com/sferik/twitter/commit/89a46fbd3560109da87d5f87262dcf6bd2a336c6)
 * [Collection caching](https://github.com/sferik/twitter/commit/d484d7d7d7a0956f9b4fa6791a911ed7c9522cba)
-* [Memoize result within `Twitter::Base#new_or_null_object`](https://github.com/sferik/twitter/commit/45dd18a9feadbb56a60cea76424dd466d3e80c5e)
 * [Implement `Twitter::Cursor#each` without making an extra HTTP request](https://github.com/sferik/twitter/commit/8eeff57f5c6d6ca0a6f1ff5ebc31e652a71fc150)
 * [Make `Twitter::SearchResults` enumerable](https://github.com/sferik/twitter/commit/d5ce8537164912e79dffc5a054ecd9ae6ecb8075)
+* [Make `Twitter::Base` objects immutable](https://github.com/sferik/twitter/commit/69b1ef7edad32398b778c8449bc3605739a6c59a)
+* [Missing key now raises `KeyError`, not `ArgumentError`](https://github.com/sferik/twitter/commit/f56698caff608527b9f3c2c3dd4c18306589cb3b)
+* [Use `equalizer` instead of manually overwriting #==](https://github.com/sferik/twitter/commit/a7ddf718b119e9c5fc8b87e6784e8c3304707a72)
+* [Give methods more natural names](https://github.com/sferik/twitter/commit/e593194fb7bd689fca561e6334db1e6af622590a)
 * [Fix `Twitter::SearchResults#rpp` return value](https://github.com/sferik/twitter/commit/28d73200490ac2755c3e68d8d273fbc64a8d7066)
 
 4.8.1

data/CONTRIBUTING.md

@@ -1,25 +1,23 @@
 ## Contributing
 In the spirit of [free software][free-sw], **everyone** is encouraged to help
-improve this project.
+improve this project. Here are some ways *you* can contribute:
 
 [free-sw]: http://www.fsf.org/licensing/essays/free-sw.html
 
-Here are some ways *you* can contribute:
-
-* by using alpha, beta, and prerelease versions
-* by reporting bugs
-* by suggesting new features
-* by writing or editing documentation
-* by writing specifications
-* by writing code (**no patch is too small**: fix typos, add comments, clean up
-  inconsistent whitespace)
-* by refactoring code
-* by fixing [issues][]
-* by reviewing patches
-* [financially][pledgie]
+* Use alpha, beta, and pre-release versions.
+* Report bugs.
+* Suggest new features.
+* Write or edit documentation.
+* Write specifications.
+* Write code (**no patch is too small**: fix typos, add comments, clean up
+  inconsistent whitespace).
+* Refactor code.
+* Fix [issues][].
+* Review patches.
+* Financially pledge using [Pledgie][].
 
 [issues]: https://github.com/sferik/twitter/issues
-[pledgie]: http://pledgie.com/campaigns/18388
+[Pledgie]: http://pledgie.com/campaigns/18388
 
 ## Submitting an Issue
 We use the [GitHub issue tracker][issues] to track bugs and features. Before

data/README.md

@@ -74,17 +74,6 @@ client = Twitter::REST::Client.new do |config|
 end
 ```
 
-Alternately, you can configure a `Twitter::REST::Client` piecemeal, after it
-has been initialized, if that better suits your application:
-
-```ruby
-client = Twitter::REST::Client.new
-client.consumer_key        = "YOUR_CONSUMER_KEY"
-client.consumer_secret     = "YOUR_CONSUMER_SECRET"
-client.access_token        = "YOUR_ACCESS_TOKEN"
-client.access_token_secret = "YOUR_ACCESS_SECRET"
-```
-
 Note: `oauth_token` has been renamed to `access_token` and `oauth_token_secret`
 is now `access_token_secret` to conform to the terminology used in Twitter's
 developer documentation.
@@ -119,7 +108,7 @@ and [Tony Arcieri][tarcieri] for helping to develop this feature.
 **Configuration works just like `Twitter::REST::Client`**
 
 ```ruby
-client = Twitter::Streaming::Client.new do
+client = Twitter::Streaming::Client.new do |config|
   config.consumer_key        = "YOUR_CONSUMER_KEY"
   config.consumer_secret     = "YOUR_CONSUMER_SECRET"
   config.access_token        = "YOUR_ACCESS_TOKEN"
@@ -144,17 +133,19 @@ client.sample do |tweet|
 end
 ```
 
-**Stream tweets for the authenticated user**
+**Stream tweets, events and direct messages for the authenticated user**
 
 ```ruby
-client.user do |tweet|
-  puts tweet.text
+client.user do |message|
+  puts message 
 end
 ```
 
-Currently, this library will only stream tweets. The goal is to eventually
-handle all [streaming message types][messages]. Patches that add support for a
-new message type would be appreciated.
+`message` can be one of
+ + Twitter::Tweet
+ + Twitter::DirectMessage
+ + Twitter::Streaming::Event
+ + Twitter::Streaming::FriendList
 
 [messages]: https://dev.twitter.com/docs/streaming-apis/messages
 
@@ -250,7 +241,7 @@ simplicity and performance.
     </tr>
     <tr>
       <td>
-        Collect your 20 most recent friends (twice).
+        Collect your 20 most recent friends twice.
       </td>
       <td>
         <pre><code lang="ruby">friends = client.friends
@@ -345,7 +336,7 @@ removed:
 * `#profile_image_url`
 * `#profile_image_url_https`
 
-These attributes can be accessed on the `Twitter::User` object, returned
+These attributes can be accessed via the `Twitter::User` object, returned
 through the `#user` method.
 
 ### Users
@@ -354,8 +345,8 @@ been removed:
 
 * `#favorite_count` (use `#favorites_count`)
 * `#favoriters_count` (use `#favorites_count`)
-* `#favourite_count` (use `#favourites_count`)
-* `#favouriters_count` (use `#favourites_count`)
+* `#favourite_count` (use `#favorites_count`)
+* `#favouriters_count` (use `#favorites_count`)
 * `#follower_count` (use `#followers_count`)
 * `#friend_count` (use `#friends_count`)
 * `#status_count` (use `#statuses_count`)
@@ -364,6 +355,30 @@ been removed:
 * `#updates_count` (use `#tweets_count`)
 * `#translator` (use `#translator?`)
 
+### Remove British English aliases
+Earlier versions of this library aliased `favourites` to `favorites`. These
+aliases have been removed. Ruby is implemented in American English. The
+`initialize` method is spelled with a "z", not an "s", and Ruby provides no
+alias. Likewise, this library does not provide aliases for Commonwealthers.
+Merica. :us:
+
+### More natural method names
+All create, destroy, add, and remove methods have been renamed to put the verb
+at the beginning:
+
+* `#direct_message_create` is now `#create_direct_message`
+* `#direct_message_destroy` is now `#destroy_direct_message`
+* `#list_create` is now `#create_list`
+* `#list_destroy` is now `#destroy_list`
+* `#list_remove_member` is now `#remove_list_member`
+* `#list_remove_members` is now `#remove_list_members`
+* `#list_add_member` is now `#add_list_member`
+* `#list_add_members` is now `#add_list_members`
+* `#lists_owned` is now `#owned_list`
+* `#saved_search_create` is now `#create_saved_search`
+* `#saved_search_destroy` is now `#destroy_saved_search`
+* `#status_destroy` is now `#destroy_status`
+
 ### Errors
 The `Twitter::Error::ClientError` and `Twitter::Error::ServerError` class
 hierarchy has been removed. All errors now inherit directly from
@@ -432,20 +447,13 @@ You can pass configuration options as a block to `Twitter::REST::Client.new`.
 
 ```ruby
 client = Twitter::REST::Client.new do |config|
-  config.consumer_key = YOUR_APP_CONSUMER_KEY
-  config.consumer_secret = YOUR_APP_CONSUMER_SECRET
-  config.access_token = A_USER_ACCESS_TOKEN
-  config.access_token_secret = A_USER_ACCESS_SECRET
+  config.consumer_key        = "YOUR_CONSUMER_KEY"
+  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
+  config.access_token        = "YOUR_ACCESS_TOKEN"
+  config.access_token_secret = "YOUR_ACCESS_SECRET"
 end
 ```
 
-Alternately, you can set the following environment variables:
-
-    TWITTER_CONSUMER_KEY
-    TWITTER_CONSUMER_SECRET
-    TWITTER_ACCESS_TOKEN
-    TWITTER_ACCESS_TOKEN_SECRET
-
 After configuration, requests can be made like so:
 
 ```ruby
@@ -548,6 +556,18 @@ client.search("#ruby -rt", :lang => "ja").first.text
 ```
 For more usage examples, please see the full [documentation][].
 
+## Object Graph
+
+![Entity-relationship diagram][erd]
+
+[erd]: https://github.com/sferik/twitter/raw/master/etc/erd.png "Entity-relationship diagram"
+
+This entity-relationship diagram is generated programatically. If you add or
+remove any Twitter objects, please regenerate the ERD with the following
+command:
+
+    bundle exec rake erd
+
 ## Supported Ruby Versions
 This library aims to support and is [tested against][travis] the following Ruby
 implementations:

data/Rakefile

@@ -7,5 +7,11 @@ RSpec::Core::RakeTask.new(:spec)
 task :test => :spec
 task :default => :spec
 
+task :erd do
+  `bundle exec ruby ./etc/erd.rb > ./etc/erd.dot`
+  `dot -Tpng ./etc/erd.dot -o ./etc/erd.png`
+  `open ./etc/erd.png`
+end
+
 require 'yard'
 YARD::Rake::YardocTask.new

data/lib/twitter/arguments.rb

@@ -2,6 +2,9 @@ module Twitter
   class Arguments < Array
     attr_reader :options
 
+    # Initializes a new Arguments object
+    #
+    # @return [Twitter::Arguments]
     def initialize(args)
       @options = args.last.is_a?(::Hash) ? args.pop : {}
       super(args)

data/lib/twitter/base.rb

@@ -1,106 +1,116 @@
 require 'forwardable'
+require 'memoizable'
 require 'twitter/null_object'
 require 'uri'
 
 module Twitter
   class Base
     extend Forwardable
+    include Memoizable
     attr_reader :attrs
     alias to_h attrs
     alias to_hash attrs
     alias to_hsh attrs
-    def_delegators :attrs, :delete, :update
 
-    # Define methods that retrieve the value from attributes
-    #
-    # @param attrs [Array, Symbol]
-    def self.attr_reader(*attrs)
-      attrs.each do |attr|
-        define_attribute_method(attr)
-        define_predicate_method(attr)
+    class << self
+
+      # Construct an object from a response hash
+      #
+      # @param response [Hash]
+      # @return [Twitter::Base]
+      def from_response(response={})
+        new(response[:body])
       end
-    end
 
-    # Define object methods from attributes
-    #
-    # @param klass [Symbol]
-    # @param key1 [Symbol]
-    # @param key2 [Symbol]
-    def self.object_attr_reader(klass, key1, key2=nil)
-      define_attribute_method(key1, klass, key2)
-      define_predicate_method(key1)
-    end
+      # Define methods that retrieve the value from attributes
+      #
+      # @param attrs [Array, Symbol]
+      def attr_reader(*attrs)
+        attrs.each do |attr|
+          define_attribute_method(attr)
+          define_predicate_method(attr)
+        end
+      end
 
-    # Define URI methods from attributes
-    #
-    # @param attrs [Array, Symbol]
-    def self.uri_attr_reader(*attrs)
-      attrs.each do |uri_key|
-        array = uri_key.to_s.split("_")
-        index = array.index("uri")
-        array[index] = "url"
-        url_key = array.join("_").to_sym
-        define_uri_method(uri_key, url_key)
-        define_predicate_method(uri_key, url_key)
-        alias_method(url_key, uri_key)
-        alias_method("#{url_key}?", "#{uri_key}?")
+      # Define object methods from attributes
+      #
+      # @param klass [Symbol]
+      # @param key1 [Symbol]
+      # @param key2 [Symbol]
+      def object_attr_reader(klass, key1, key2=nil)
+        define_attribute_method(key1, klass, key2)
+        define_predicate_method(key1)
       end
-    end
 
-    # Dynamically define a method for a URI
-    #
-    # @param key1 [Symbol]
-    # @param key2 [Symbol]
-    def self.define_uri_method(key1, key2)
-      define_method(key1) do
-        memoize(key1) do
-          ::URI.parse(@attrs[key2]) if @attrs[key2]
+      # Define URI methods from attributes
+      #
+      # @param attrs [Array, Symbol]
+      def uri_attr_reader(*attrs)
+        attrs.each do |uri_key|
+          array = uri_key.to_s.split("_")
+          index = array.index("uri")
+          array[index] = "url"
+          url_key = array.join("_").to_sym
+          define_uri_method(uri_key, url_key)
+          alias_method(url_key, uri_key)
+          define_predicate_method(uri_key, url_key)
+          alias_method(:"#{url_key}?", :"#{uri_key}?")
         end
       end
-    end
 
-    # Dynamically define a method for an attribute
-    #
-    # @param key1 [Symbol]
-    # @param klass [Symbol]
-    # @param key2 [Symbol]
-    def self.define_attribute_method(key1, klass=nil, key2=nil)
-      define_method(key1) do
-        memoize(key1) do
+      # Define display_uri attribute methods
+      def display_uri_attr_reader
+        define_attribute_method(:display_url)
+        alias_method(:display_uri, :display_url)
+        define_predicate_method(:display_uri, :display_url)
+        alias_method(:display_url?, :display_uri?)
+      end
+
+    private
+
+      # Dynamically define a method for a URI
+      #
+      # @param key1 [Symbol]
+      # @param key2 [Symbol]
+      def define_uri_method(key1, key2)
+        define_method(key1) do ||
+          URI.parse(@attrs[key2]) if @attrs[key2]
+        end
+        memoize(key1)
+      end
+
+      # Dynamically define a method for an attribute
+      #
+      # @param key1 [Symbol]
+      # @param klass [Symbol]
+      # @param key2 [Symbol]
+      def define_attribute_method(key1, klass=nil, key2=nil)
+        define_method(key1) do ||
           if klass.nil?
             @attrs[key1]
           else
             if @attrs[key1]
-              if key2.nil?
-                Twitter.const_get(klass).new(@attrs[key1])
-              else
-                attrs = @attrs.dup
-                value = attrs.delete(key1)
-                Twitter.const_get(klass).new(value.update(key2 => attrs))
-              end
+              attrs = attrs_for_object(key1, key2)
+              Twitter.const_get(klass).new(attrs)
             else
-              Twitter::NullObject.instance
+              NullObject.new
             end
           end
         end
+        memoize(key1)
       end
-    end
 
-    # Dynamically define a predicate method for an attribute
-    #
-    # @param key [Symbol]
-    def self.define_predicate_method(key1, key2=key1)
-      define_method(:"#{key1}?") do
-        !!@attrs[key2]
+      # Dynamically define a predicate method for an attribute
+      #
+      # @param key1 [Symbol]
+      # @param key2 [Symbol]
+      def define_predicate_method(key1, key2=key1)
+        define_method(:"#{key1}?") do ||
+          !!@attrs[key2]
+        end
+        memoize(:"#{key1}?")
       end
-    end
 
-    # Construct an object from a response hash
-    #
-    # @param response [Hash]
-    # @return [Twitter::Base]
-    def self.from_response(response={})
-      new(response[:body])
     end
 
     # Initializes a new object
@@ -120,26 +130,15 @@ module Twitter
       nil
     end
 
-    def memoize(key, &block)
-      ivar = :"@#{key}"
-      return instance_variable_get(ivar) if instance_variable_defined?(ivar)
-      result = block.call
-      instance_variable_set(ivar, result)
-    end
-
   private
 
-    # @param attr [Symbol]
-    # @param other [Twitter::Base]
-    # @return [Boolean]
-    def attr_equal(attr, other)
-      self.class == other.class && !other.send(attr.to_sym).nil? && send(attr.to_sym) == other.send(attr.to_sym)
-    end
-
-    # @param other [Twitter::Base]
-    # @return [Boolean]
-    def attrs_equal(other)
-      self.class == other.class && !other.attrs.empty? && attrs == other.attrs
+    def attrs_for_object(key1, key2=nil)
+      if key2.nil?
+        @attrs[key1]
+      else
+        attrs = @attrs.dup
+        attrs.delete(key1).merge(key2 => attrs)
+      end
     end
 
   end