twitter4r 0.1.1 → 0.2.0

data/lib/twitter/model.rb

@@ -0,0 +1,331 @@
+# Contains Twitter4R Model API.
+
+module Twitter
+  # Mixin module for model classes.  Includes generic class methods like
+  # unmarshal.
+  # 
+  # To create a new model that includes this mixin's features simply:
+  #  class NewModel
+  #    include Twitter::ModelMixin
+  #  end
+  # 
+  # This mixin module automatically includes <tt>Twitter::ClassUtilMixin</tt>
+  # features.
+  # 
+  # The contract for models to use this mixin correctly is that the class 
+  # including this mixin must provide an class method named <tt>attributes</tt>
+  # that will return an Array of attribute symbols that will be checked 
+  # in #eql? override method.  The following would be sufficient:
+  #  def self.attributes; @@ATTRIBUTES; end
+  module ModelMixin #:nodoc:
+    def self.included(base) #:nodoc:
+      base.send(:include, Twitter::ClassUtilMixin)
+      base.send(:include, InstanceMethods)
+      base.extend(ClassMethods)
+    end
+
+    # Class methods defined for <tt>Twitter::ModelMixin</tt> module.
+    module ClassMethods #:nodoc:
+      # Unmarshal object singular or plural array of model objects
+      # from JSON serialization.  Currently JSON is only supported 
+      # since this is all <tt>Twitter4R</tt> needs.
+      def unmarshal(raw)
+        input = JSON.parse(raw)
+        def unmarshal_model(hash)
+          self.new(hash)
+        end
+        return unmarshal_model(input) if input.is_a?(Hash) # singular case
+        result = []
+        input.each do |hash|
+          model = unmarshal_model(hash) if hash.is_a?(Hash)
+          result << model
+        end if input.is_a?(Array)
+        result # plural case
+      end
+    end
+    
+    # Instance methods defined for <tt>Twitter::ModelMixin</tt> module.
+    module InstanceMethods #:nodoc:
+      attr_accessor :client
+      # Equality method override of Object#eql? default.
+      # 
+      # Relies on the class using this mixin to provide a <tt>attributes</tt>
+      # class method that will return an Array of attributes to check are 
+      # equivalent in this #eql? override.
+      # 
+      # It is by design that the #eql? method will raise a NoMethodError
+      # if no <tt>attributes</tt> class method exists, to alert you that 
+      # you must provide it for a meaningful result from this #eql? override.
+      # Otherwise this will return a meaningless result.
+      def eql?(other)
+        attrs = self.class.attributes
+        attrs.each do |att|
+          return false unless self.send(att).eql?(other.send(att))
+        end
+        true
+      end
+      
+      # Returns integer representation of model object instance.
+      # 
+      # For example,
+      #  status = Twitter::Status.new(:id => 234343)
+      #  status.to_i #=> 234343
+      def to_i
+        @id
+      end
+      
+      # Returns string representation of model object instance.
+      # 
+      # For example,
+      #  status = Twitter::Status.new(:text => 'my status message')
+      #  status.to_s #=> 'my status message'
+      # 
+      # If a model class doesn't have a @text attribute defined 
+      # the default Object#to_s will be returned as the result.
+      def to_s
+        self.respond_to(:text) ? @text : super.to_s
+      end
+      
+      # Returns hash representation of model object instance.
+      # 
+      # For example,
+      #  u = Twitter::User.new(:id => 2342342, :screen_name => 'tony_blair_is_the_devil')
+      #  u.to_hash #=> {:id => 2342342, :screen_name => 'tony_blair_is_the_devil'}
+      # 
+      # This method also requires that the class method <tt>attributes</tt> be 
+      # defined to return an Array of attributes for the class.
+      def to_hash
+        attrs = self.class.attributes
+        result = {}
+        attrs.each do |att|
+          value = self.send(att)
+          value = value.to_hash if value.respond_to?(:to_hash)
+          result[att] = value if value
+        end
+        result
+      end
+      
+      # "Blesses" model object.
+      # 
+      # Should be overridden by model class if special behavior is expected
+      # 
+      # Expected to return blessed object (usually <tt>self</tt>)
+      def bless(client)
+        self.basic_bless(client)
+      end
+      
+      protected
+        # Basic "blessing" of model object 
+        def basic_bless(client)
+          self.client = client
+          self
+        end
+    end
+  end
+  
+  module AuthenticatedUserMixin
+  	def self.included(base)
+  		base.send(:include, InstanceMethods)
+  	end
+  	
+  	module InstanceMethods
+      # Returns an Array of user objects that represents the authenticated
+      # user's friends on Twitter.
+      def followers
+        @client.user(@id, :followers)
+      end
+      
+      # Adds given user as a friend.  Returns user object as given by 
+      # <tt>Twitter</tt> REST server response.
+      # 
+      # For <tt>user</tt> argument you may pass in the unique integer 
+      # user ID, screen name or Twitter::User object representation.
+      def befriend(user)
+      	@client.friend(:add, user)
+      end
+      
+      # Removes given user as a friend.  Returns user object as given by 
+      # <tt>Twitter</tt> REST server response.
+      # 
+      # For <tt>user</tt> argument you may pass in the unique integer 
+      # user ID, screen name or Twitter::User object representation.
+      def defriend(user)
+      	@client.friend(:remove, user)
+      end
+  	end
+  end
+
+  # Represents a <tt>Twitter</tt> user
+  class User
+    include ModelMixin
+    @@ATTRIBUTES = [:id, :name, :description, :location, :screen_name, :url]
+    attr_accessor *@@ATTRIBUTES
+
+    class << self
+      # Used as factory method callback
+      def attributes; @@ATTRIBUTES; end
+
+      # Returns user model object with given <tt>id</tt> using the configuration
+      # and credentials of the <tt>client</tt> object passed in.
+      # 
+      # You can pass in either the user's unique integer ID or the user's 
+      # screen name.
+      def find(id, client)
+        client.user(id)
+      end
+    end
+    
+    # Override of ModelMixin#bless method.
+    # 
+    # Adds #followers instance method when user object represents 
+    # authenticated user.  Otherwise just do basic bless.
+    # 
+    # This permits applications using <tt>Twitter4R</tt> to write 
+    # Rubyish code like this:
+    #  followers = user.followers if user.is_me?
+    # Or:
+    #  followers = user.followers if user.respond_to?(:followers)
+    def bless(client)
+      basic_bless(client)
+      self.instance_eval(%{
+      	self.class.send(:include, Twitter::AuthenticatedUserMixin)
+      }) if self.is_me? and not self.respond_to?(:followers)
+      self
+    end
+    
+    # Returns whether this <tt>Twitter::User</tt> model object
+    # represents the authenticated user of the <tt>client</tt>
+    # that blessed it.
+    def is_me?
+      # TODO: Determine whether we should cache this or not?
+      # Might be dangerous to do so, but do we want to support
+      # the edge case where this would cause a problem?  i.e. 
+      # changing authenticated user after initial use of 
+      # authenticated API.
+      # TBD: To cache or not to cache.  That is the question!
+      # Since this is an implementation detail we can leave this for 
+      # subsequent 0.2.x releases.  It doesn't have to be decided before 
+      # the 0.2.0 launch.
+      @screen_name == @client.instance_eval("@login")
+    end
+    
+    # Returns an Array of user objects that represents the authenticated
+    # user's friends on Twitter.
+    def friends
+      @client.user(@id, :friends)
+    end    
+  end # User
+  
+  # Represents a status posted to <tt>Twitter</tt> by a <tt>Twitter</tt> user.
+  class Status
+    include ModelMixin
+    @@ATTRIBUTES = [:id, :text, :created_at, :user]
+    attr_accessor *@@ATTRIBUTES
+
+    class << self
+      # Used as factory method callback
+      def attributes; @@ATTRIBUTES; end
+      
+      # Returns status model object with given <tt>status</tt> using the 
+      # configuration and credentials of the <tt>client</tt> object passed in.
+      def find(id, client)
+        client.status(:get, id)
+      end
+      
+      # Creates a new status for the authenticated user of the given 
+      # <tt>client</tt> context.
+      # 
+      # You MUST include a valid/authenticated <tt>client</tt> context 
+      # in the given <tt>params</tt> argument.
+      # 
+      # For example:
+      #  status = Twitter::Status.create(
+      #    :text => 'I am shopping for flip flops',
+      #    :client => client)
+      # 
+      # An <tt>ArgumentError</tt> will be raised if no valid client context
+      # is given in the <tt>params</tt> Hash.  For example,
+      #  status = Twitter::Status.create(:text => 'I am shopping for flip flops')
+      # The above line of code will raise an <tt>ArgumentError</tt>.
+      # 
+      # The same is true when you do not provide a <tt>:text</tt> key-value
+      # pair in the <tt>params</tt> argument given.
+      # 
+      # The Twitter::Status object returned after the status successfully
+      # updates on the Twitter server side is returned from this method.
+      def create(params)
+      	client, text = params[:client], params[:text]
+      	raise ArgumentError, 'Valid client context must be provided' unless client.is_a?(Twitter::Client)
+      	raise ArgumentError, 'Must provide text for the status to update' unless text.is_a?(String)
+      	client.status(:post, text)
+      end
+    end
+    
+    protected
+      # Constructor callback
+      def init
+        @user = User.new(@user) if @user.is_a?(Hash)
+        @created_at = Time.parse(@created_at) if @created_at.is_a?(String)
+      end    
+  end # Status
+  
+  # Represents a direct message on <tt>Twitter</tt> between <tt>Twitter</tt> users.
+  class Message
+    include ModelMixin
+    @@ATTRIBUTES = [:id, :recipient, :sender, :text, :created_at]
+    attr_accessor *@@ATTRIBUTES
+    
+    class << self
+      # Used as factory method callback
+      def attributes; @@ATTRIBUTES; end
+      
+      # Raises <tt>NotImplementedError</tt> because currently 
+      # <tt>Twitter</tt> doesn't provide a facility to retrieve 
+      # one message by unique ID.
+      def find(id, client)
+        raise NotImplementedError, 'Twitter has yet to implement a REST API for this.  This is not a Twitter4R library limitation.'
+      end
+      
+      # Creates a new direct message from the authenticated user of the 
+      # given <tt>client</tt> context.
+      # 
+      # You MUST include a valid/authenticated <tt>client</tt> context 
+      # in the given <tt>params</tt> argument.
+      # 
+      # For example:
+      #  status = Twitter::Message.create(
+      #    :text => 'I am shopping for flip flops',
+      #    :receipient => 'anotherlogin',
+      #    :client => client)
+      # 
+      # An <tt>ArgumentError</tt> will be raised if no valid client context
+      # is given in the <tt>params</tt> Hash.  For example,
+      #  status = Twitter::Status.create(:text => 'I am shopping for flip flops')
+      # The above line of code will raise an <tt>ArgumentError</tt>.
+      # 
+      # The same is true when you do not provide any of the following
+      # key-value pairs in the <tt>params</tt> argument given:
+      # * <tt>text</tt> - the String that will be the message text to send to <tt>user</tt>
+      # * <tt>recipient</tt> - the user ID, screen_name or Twitter::User object representation of the recipient of the direct message
+      # 
+      # The Twitter::Message object returned after the direct message is 
+      # successfully sent on the Twitter server side is returned from 
+      # this method.
+      def create(params)
+      	client, text, recipient = params[:client], params[:text], params[:recipient]
+      	raise ArgumentError, 'Valid client context must be given' unless client.is_a?(Twitter::Client)
+      	raise ArgumentError, 'Message text must be supplied to send direct message' unless text.is_a?(String)
+      	raise ArgumentError, 'Recipient user must be specified to send direct message' unless [Twitter::User, Integer, String].member?(recipient.class)
+      	client.message(:post, text, recipient)
+      end
+    end
+    
+    protected
+      # Constructor callback
+      def init
+        @sender = User.new(@sender) if @sender.is_a?(Hash)
+        @recipient = User.new(@recipient) if @recipient.is_a?(Hash)
+        @created_at = Time.parse(@created_at) if @created_at.is_a?(String)
+      end
+  end # Message
+end # Twitter

data/lib/twitter/version.rb

@@ -1,12 +1,17 @@
+# version.rb contains <tt>Twitter::Version</tt> that provides helper
+# methods related to versioning of the <tt>Twitter4R</tt> project.
+
 module Twitter::Version #:nodoc:
   MAJOR = 0
-  MINOR = 1
-  REVISION = 1
+  MINOR = 2
+  REVISION = 0
   class << self
+    # Returns X.Y.Z formatted version string
     def to_version
       "#{MAJOR}.#{MINOR}.#{REVISION}"
     end
     
+    # Returns X-Y-Z formatted version name
     def to_name
       "#{MAJOR}_#{MINOR}_#{REVISION}"
     end

data/lib/twitter.rb

@@ -1,14 +1,25 @@
+# 
+
 module Twitter; end
 
-def resolve_path(suffix)
-  File.expand_path(File.join(File.dirname(__FILE__), suffix))
+def require_local(suffix)
+  require(File.expand_path(File.join(File.dirname(__FILE__), suffix)))
 end
 
 # For better unicode support
 $KCODE = 'u'
 require 'jcode'
 
+# External requires
+require('net/https')
+require('uri')
+require('json')
+
 # Ordering matters...pay attention here!
-require(resolve_path('twitter/version'))
-require(resolve_path('twitter/meta'))
-require(resolve_path('twitter/core'))
+require_local('twitter/ext')
+require_local('twitter/version')
+require_local('twitter/meta')
+require_local('twitter/core')
+require_local('twitter/model')
+require_local('twitter/config')
+require_local('twitter/client')

data/spec/spec_helper.rb

@@ -1,8 +1,52 @@
 require 'spec'
 require 'twitter'
+require 'twitter/console'
+require 'twitter/extras'
 
 # Add helper methods here if relevant to multiple _spec.rb files
 
+# Spec helper that sets attribute <tt>att</tt> for given objects <tt>obj</tt> 
+# and <tt>other</tt> to given <tt>value</tt>.
+def equalizer(obj, other, att, value)
+  setter = "#{att}="
+  obj.send(setter, value)
+  other.send(setter, value)
+end
+
+# Spec helper that nil-izes objects passed in
+def nilize(*objects)
+  objects.each {|obj| obj = nil }
+end
+
+# Returns default <tt>client</tt> context object
+def client_context(file = 'config/twitter.yml')
+  Twitter::Client.from_config(file)
+end
+
+# Spec helper that returns a mocked <tt>Twitter::Config</tt> object
+# with stubbed attributes and <tt>attrs</tt> for overriding attribute 
+# values.
+def stubbed_twitter_config(config, attrs = {})
+  opts = { 
+    :protocol => :ssl,
+    :host => 'twitter.com',
+    :port => 443,
+    :proxy_host => 'proxy.host',
+    :proxy_port => 8080,
+  }.merge(attrs)
+  config.stub!(:protocol).and_return(opts[:protocol])
+  config.stub!(:host).and_return(opts[:host])
+  config.stub!(:port).and_return(opts[:port])
+  config.stub!(:proxy_host).and_return(opts[:proxy_host])
+  config.stub!(:proxy_port).and_return(opts[:proxy_port])
+  config
+end
+
+def mas_twitter_config(attrs = {})
+  config = mock(Twitter::Config)
+  stubbed_twitter_conf(config, attrs)
+end
+
 # Spec helper that returns the project root directory as absolute path string
 def project_root_dir
   File.expand_path(File.join(File.dirname(__FILE__), '..'))
@@ -16,16 +60,14 @@ def stubbed_net_http(response, obj_stubs = {}, host = 'twitter.com', port = 80)
   http = Net::HTTP.new(host, port)
   Net::HTTP.stub!(:new).and_return(http)
   http.stub!(:request).and_return(response)
-  http.stub!(:use_ssl=)
-  http.stub!(:verify_mode=)
   http
 end
 
 # Spec helper that returns a mocked <tt>Net::HTTP</tt> object and 
 # stubs out the <tt>request</tt> method to return the given 
 # <tt>response</tt>
-def mas_net_http(response)
-  http = mock(Net::HTTP)
+def mas_net_http(response, obj_stubs = {})
+  http = mock(Net::HTTP, obj_stubs)
   Net::HTTP.stub!(:new).and_return(http)
   http.stub!(:request).and_return(response)
   http.stub!(:start).and_yield(http)
@@ -87,4 +129,5 @@ end
 def _create_http_response(mock_response, code, message)
   mock_response.stub!(:code).and_return(code)
   mock_response.stub!(:message).and_return(message)
+  mock_response.stub!(:is_a?).and_return(true) if ["200", "201"].member?(code)
 end

data/spec/twitter/client/base_spec.rb

@@ -0,0 +1,232 @@
+require File.join(File.dirname(__FILE__), '..', '..', 'spec_helper')
+
+describe "Twitter::Client" do
+  before(:each) do
+    @init_hash = { :login => 'user', :password => 'pass' }
+  end
+
+  it ".new should accept login and password as initializer hash keys and set the values to instance values" do
+    client = nil
+    lambda do
+      client = Twitter::Client.new(@init_hash)
+    end.should_not raise_error
+    client.send(:login).should eql(@init_hash[:login])
+    client.send(:password).should eql(@init_hash[:password])
+  end  
+end
+
+describe Twitter::Client, "#http_header" do
+  before(:each) do
+    @user_agent = 'myapp'
+    @application_name = @user_agent
+    @application_version = '1.2.3'
+    @application_url = 'http://myapp.url'
+    Twitter::Client.configure do |conf|
+      conf.user_agent = @user_agent
+      conf.application_name = @application_name
+      conf.application_version = @application_version
+      conf.application_url = @application_url
+    end
+    @expected_headers = {
+      'Accept' => 'text/x-json',
+      'X-Twitter-Client' => @application_name,
+      'X-Twitter-Client-Version' => @application_version,
+      'X-Twitter-Client-URL' => @application_url,
+      'User-Agent' => "Twitter4R v#{Twitter::Version.to_version} [#{@user_agent}]",
+    }
+    @twitter = client_context
+    # resent @@http_header class variable in Twitter::Client class
+    Twitter::Client.class_eval("@@http_header = nil")
+  end
+  
+  it "should always return expected HTTP headers" do
+    headers = @twitter.send(:http_header)
+    headers.should eql(@expected_headers)
+  end
+  
+  it "should cache HTTP headers Hash in class variable after first invocation" do
+    cache = Twitter::Client.class_eval("@@http_header")
+    cache.should be_nil
+    @twitter.send(:http_header)
+    cache = Twitter::Client.class_eval("@@http_header")
+    cache.should_not be_nil
+    cache.should eql(@expected_headers)
+  end
+  
+  after(:each) do
+    nilize(@user_agent, @application_name, @application_version, @application_url, @twitter, @expected_headers)
+  end
+end
+
+describe Twitter::Client, "#create_http_get_request" do
+  before(:each) do
+  	@uri = '/some/path'
+  	@expected_get_request = mock(Net::HTTP::Get)
+    @twitter = client_context
+  	@default_header = @twitter.send(:http_header)
+  end
+  
+  it "should create new Net::HTTP::Get object with expected initialization arguments" do
+  	Net::HTTP::Get.should_receive(:new).with(@uri, @default_header).and_return(@expected_get_request)
+		@twitter.send(:create_http_get_request, @uri)
+  end
+  
+  after(:each) do
+    nilize(@twitter, @uri, @expected_get_request, @default_header)
+  end
+end
+
+describe Twitter::Client, "#create_http_post_request" do
+  before(:each) do
+  	@uri = '/some/path'
+  	@expected_post_request = mock(Net::HTTP::Post)
+  	@twitter = client_context
+  	@default_header = @twitter.send(:http_header)
+  end
+    
+  it "should create new Net::HTTP::Post object with expected initialization arguments" do
+  	Net::HTTP::Post.should_receive(:new).with(@uri, @default_header).and_return(@expected_post_request)
+    @twitter.send(:create_http_post_request, @uri)
+  end
+  
+  after(:each) do
+    nilize(@twitter, @uri, @expected_post_request, @default_header)    
+  end
+end
+
+describe Twitter::Client, "#create_http_delete_request" do
+  before(:each) do
+    @uri = '/a/stupid/path/that/is/not/restful/since/twitter.com/cannot/do/consistent/restful/apis'
+    @expected_delete_request = mock(Net::HTTP::Delete)
+    @twitter = client_context
+    @default_header = @twitter.send(:http_header)
+  end
+  
+  it "should create new Net::HTTP::Delete object with expected initialization arguments" do
+    Net::HTTP::Delete.should_receive(:new).with(@uri, @default_header).and_return(@expected_delete_request)
+    @twitter.send(:create_http_delete_request, @uri)
+  end
+  
+  after(:each) do
+    nilize(@twitter, @uri, @expected_delete_request, @default_header)
+  end
+end
+
+describe Twitter::Client, "#http_connect" do
+  before(:each) do
+    @request = mas_net_http_get(:basic_auth => nil)
+    @good_response = mas_net_http_response(:success)
+    @bad_response = mas_net_http_response(:server_error)
+    @http_stubs = {:is_a? => true}
+    @block = Proc.new do |conn|
+      conn.is_a?(Net::HTTP).should be(true)
+      @has_yielded = true
+      @request
+    end
+    @twitter = client_context
+    @has_yielded = false
+  end
+  
+  def generate_bad_response
+    @http = mas_net_http(@bad_response, @http_stubs)
+    Net::HTTP.stub!(:new).and_return(@http)
+  end
+  
+  def generate_good_response
+    @http = mas_net_http(@good_response, @http_stubs)
+    Net::HTTP.stub!(:new).and_return(@http)
+  end
+  
+  it "should yield HTTP connection when response is good" do
+    generate_good_response
+    @http.should_receive(:is_a?).with(Net::HTTP).and_return(true)
+    lambda do
+      @twitter.send(:http_connect, &@block)
+    end.should_not raise_error
+    @has_yielded.should be(true)
+  end
+  
+  it "should yield HTTP connection when response is bad" do
+    generate_bad_response
+    @http.should_receive(:is_a?).with(Net::HTTP).and_return(true)
+    lambda {
+      @twitter.send(:http_connect, &@block)
+    }.should raise_error(Twitter::RESTError)
+    @has_yielded.should be(true)
+  end
+  
+  after(:each) do
+    nilize(@good_response, @bad_response, @http)
+  end
+end
+
+describe Twitter::Client, "#bless_model" do
+  before(:each) do
+    @twitter = client_context
+    @model = Twitter::User.new
+  end
+  
+  it "should recieve #client= message on given model to self" do
+  	@model.should_receive(:client=).with(@twitter)
+    model = @twitter.send(:bless_model, @model)
+  end
+  
+  it "should set client attribute on given model to self" do
+    model = @twitter.send(:bless_model, @model)
+    model.client.should eql(@twitter)
+  end
+
+  # if model is nil, it doesn't not necessarily signify an exceptional case for this method's usage.
+  it "should return nil when receiving nil and not raise any exceptions" do
+    model = @twitter.send(:bless_model, nil)
+    model.should be_nil
+  end
+  
+  # needed to alert developer that the model needs to respond to #client= messages appropriately.
+  it "should raise an error if passing in a non-nil object that doesn't not respond to the :client= message" do
+    lambda {
+      @twitter.send(:bless_model, Object.new)      
+    }.should raise_error(NoMethodError)
+  end
+  
+  after(:each) do
+    nilize(@twitter)
+  end
+end
+
+describe Twitter::Client, "#bless_models" do
+  before(:each) do
+    @twitter = client_context
+    @models = [
+    	Twitter::Status.new(:text => 'message #1'),
+    	Twitter::Status.new(:text => 'message #2'),
+    ]
+  end
+
+  it "should set client attributes for each model in given Array to self" do
+    models = @twitter.send(:bless_models, @models)
+    models.each {|model| model.client.should eql(@twitter) }
+  end
+  
+  it "should set client attribute for singular model given to self" do
+    model = @twitter.send(:bless_models, @models[0])
+    model.client.should eql(@twitter)
+  end
+  
+  it "should delegate to bless_model for singular model case" do
+    model = @models[0]
+    @twitter.should_receive(:bless_model).with(model).and_return(model)
+    @twitter.send(:bless_models, model)
+  end
+  
+  it "should return nil when receiving nil and not raise any exceptions" do
+    lambda {
+      value = @twitter.send(:bless_models, nil)
+      value.should be_nil
+    }.should_not raise_error
+  end
+  
+  after(:each) do
+    nilize(@twitter, @models)
+  end
+end