twitter4r 0.1.1 → 0.2.0

data/lib/twitter/core.rb

@@ -1,198 +1,136 @@
 # The Twitter4R API provides a nicer Ruby object API to work with 
 # instead of coding around the REST API.
 
-require('net/https')
-require('uri')
-require('json')
-
-# Encapsules the Twitter4R API.
+# Module to encapsule the Twitter4R API.
 module Twitter
+  # Mixin module for classes that need to have a constructor similar to
+  # Rails' models, where a <tt>Hash</tt> is provided to set attributes
+  # appropriately.
+  # 
+  # To define a class that uses this mixin, use the following code:
+  #  class FilmActor
+  #    include ClassUtilMixin
+  #  end
   module ClassUtilMixin #:nodoc:
-    def self.included(base)
+    def self.included(base) #:nodoc:
       base.send(:include, InstanceMethods)
     end
     
+    # Instance methods defined for <tt>Twitter::ModelMixin</tt> module.
     module InstanceMethods #:nodoc:
+      # Constructor/initializer that takes a hash of parameters that 
+      # will initialize *members* or instance attributes to the 
+      # values given.  For example,
+      # 
+      #  class FilmActor
+      #    include Twitter::ClassUtilMixin
+      #    attr_accessor :name
+      #  end
+      #  
+      #  class Production
+      #    include Twitter::ClassUtilMixin
+      #    attr_accessor :title, :year, :actors
+      #  end
+      #  
+      #  # Favorite actress...
+      #  jodhi = FilmActor.new(:name => "Jodhi May")
+      #  jodhi.name # => "Jodhi May"
+      #  
+      #  # Favorite actor...
+      #  robert = FilmActor.new(:name => "Robert Lindsay")
+      #  robert.name # => "Robert Lindsay"
+      #  
+      #  # Jane is also an excellent pick...gotta love her accent!
+      #  jane = FilmActor.new(name => "Jane Horrocks")
+      #  jane.name # => "Jane Horrocks"
+      #  
+      #  # Witty BBC series...
+      #  mrs_pritchard = Production.new(:title => "The Amazing Mrs. Pritchard", 
+      #                                 :year => 2005, 
+      #                                 :actors => [jodhi, jane])
+      #  mrs_pritchard.title  # => "The Amazing Mrs. Pritchard"
+      #  mrs_pritchard.year   # => 2005
+      #  mrs_pritchard.actors # => [#<FilmActor:0xb79d6bbc @name="Jodhi May">, 
+      #  <FilmActor:0xb79d319c @name="Jane Horrocks">]
+      #  # Any Ros Pritchard's out there to save us from the Tony Blair
+      #  # and Gordon Brown *New Labour* debacle?  You've got my vote! 
+      #  
+      #  jericho = Production.new(:title => "Jericho", 
+      #                           :year => 2005, 
+      #                           :actors => [robert])
+      #  jericho.title   # => "Jericho"
+      #  jericho.year    # => 2005
+      #  jericho.actors  # => [#<FilmActor:0xc95d3eec @name="Robert Lindsay">]
+      # 
+      # Assuming class <tt>FilmActor</tt> includes 
+      # <tt>Twitter::ClassUtilMixin</tt> in the class definition 
+      # and has an attribute of <tt>name</tt>, then that instance 
+      # attribute will be set to "Jodhi May" for the <tt>actress</tt> 
+      # object during object initialization (aka construction for 
+      # you Java heads).
       def initialize(params = {})
         params.each do |key,val|
           self.send("#{key}=", val) if self.respond_to? key
         end
+        self.send(:init) if self.respond_to? :init
       end
+      
+      protected
+        # Helper method to provide an easy and terse way to require 
+        # a block is provided to a method.
+        def require_block(block_given)
+          raise ArgumentError, "Must provide a block" unless block_given
+        end
     end
   end # ClassUtilMixin
   
-  # Error subclass raised when there is an error encountered upon 
-  # querying or posting to the REST API.
+  # Exception subclass raised when there is an error encountered upon 
+  # querying or posting to the remote Twitter REST API.
+  # 
+  # To consume and query any <tt>RESTError</tt> raised by Twitter4R:
+  #  begin
+  #    # Do something with your instance of <tt>Twitter::Client</tt>.
+  #    # Maybe something like:
+  #    timeline = twitter.timeline_for(:public)
+  #  rescue RESTError => re
+  #    puts re.code, re.message, re.uri
+  #  end
+  # Which on the code raising a <tt>RESTError</tt> will output something like:
+  #  404
+  #  Resource Not Found
+  #  /i_am_crap.json
   class RESTError < Exception
     include ClassUtilMixin
     attr_accessor :code, :message, :uri
     
+    # Returns string in following format:
+    #  "HTTP #{@code}: #{@message} at #{@uri}"
+    # For example,
+    #  "HTTP 404: Resource Not Found at /i_am_crap.json"
     def to_s
-      "HTTP #{code}: #{message} at #{uri}"
+      "HTTP #{@code}: #{@message} at #{@uri}"
     end
   end # RESTError
-
-  # Represents a user of Twitter
-  class User
-    include ClassUtilMixin
-    attr_accessor :id, :name, :description, :location, :screen_name, :url
-    
-    def eql?(obj)
-      [:id, :name, :description, :location, 
-      :screen_name, :url].each do |att|
-        return false unless self.send(att).eql?(obj.send(att))
-      end
-      true
-    end
-  end # User
   
-  # Represents a status posted to Twitter by a user of Twitter.
-  class Status
-    include ClassUtilMixin
-    attr_accessor :id, :text, :created_at, :user
-
-    def eql?(obj)
-      [:id, :text, :created_at, :user].each do |att|
-        return false unless self.send(att).eql?(obj.send(att))
-      end
-      true
-    end
-  end # Status
-
-  # Used to query or post to the Twitter REST API to simplify code.
-  class Client
-    include ClassUtilMixin
-    attr_accessor :login, :password
-    
-    @@CONF = {
-    	:host => 'twitter.com',
-    	:port => 80,
-    	:ssl => false,
-    }
-    @@URIS = {:public => '/statuses/public_timeline.json',
-              :friends => '/statuses/friends_timeline.json',
-              :friends_statues => '/statuses/friends.json',
-              :followers => '/statuses/followers.json',
-              :update => '/statuses/update.json',
-              :send_direct_message => '/direct_messages/new.json', }
-
-    class << self
-    	# The following configuration options can be passed in a hash to this method:
-    	# * <tt>host</tt> - host of the REST server, defaults to twitter.com.  Should only be changed for integration testing.
-    	# * <tt>port</tt> - port of the REST server, defaults to 443.
-    	# * <tt>ssl</tt> - SSL flag, defaults to false.  Do not use :use_ssl anymore.
-    	# * <tt>proxy_host</tt> - proxy host.  No default.
-    	# * <tt>proxy_port</tt> - proxy port.  No default.
-    	# * <tt>proxy_user</tt> - proxy username.  No default.
-    	# * <tt>proxy_pass</tt> - proxy password.  No default.
-      def config(conf)
-      	@@CONF.merge!(conf)
-      end
-      
-      # Mostly helper method for irb shell prototyping
-      # TODO: move this out as class extension for twitter4r console script
-      def from_config(config_file, env = 'test')
-        yaml_hash = YAML.load(File.read(config_file))
-        self.new yaml_hash[env]
-      end
-    end # class << self
-
-    def timeline(type = :public)
-      http = create_http_connection
-      http.start do |http|
-        timeline_request(type, http)
-      end # http.start block
-    end # timeline
-    
-    def public_timeline
-      timeline :public
-    end
-    
-    def friend_timeline
-      timeline :friends
-    end
-    
-    def friend_statuses
-      timeline :friends_statuses
-    end
-
-    def follower_statuses
-      timeline :followers
-    end
-
-    def update(message)
-      uri = @@URIS[:update]
-      http = create_http_connection
-      http.start do |http|
-        request = Net::HTTP::Post.new(uri)
-        request.basic_auth(@login, @password)
-        response = http.request(request, "status=#{URI.escape(message)}")
-        handle_rest_response(response, uri)
-      end
-    end
-    
-    def send_direct_message(user, message)
-      login = user.respond_to?(:screen_name) ? user.screen_name : user
-      uri = @@URIS[:send_direct_message]
-      http = create_http_connection
-      http.start do |http|
-        request = Net::HTTP::Post.new(uri)
-        request.basic_auth(@login, @password)
-        response = http.request(request, "user=#{login}&text=#{URI.escape(message)}")
-        handle_rest_response(response, uri)
-      end
-    end
-
-    protected
-      attr_accessor :login, :password, :host, :port
-      
-      def unmarshall_statuses(status_array)
-        status_array.collect do |status|
-          Status.new(:id => status['id'], 
-                     :text => status['text'],
-                     :user => unmarshall_user(status['user']),
-                     :created_at => Time.parse(status['created_at'])
-                     )
-        end      
-      end
-      
-      def unmarshall_user(map)
-        User.new(:id => map['id'], :name => map['name'],
-                  :screen_name => map['screen_name'], 
-                  :description => map['description'],
-                  :location => map['location'],
-                  :url => map['url'])
-      end
-      
-      def timeline_request(type, http)
-        uri = @@URIS[type]
-        request = Net::HTTP::Get.new(uri)
-        request.basic_auth(@login, @password)
-        response = http.request(request)
-
-        handle_rest_response(response, uri)
-        unmarshall_statuses(JSON.parse(response.body))
-      end
-      
-      def create_http_connection
-      	conn = Net::HTTP.new(@@CONF[:host], @@CONF[:port], 
-      								       @@CONF[:proxy_host], @@CONF[:proxy_port], 
-                             @@CONF[:proxy_user], @@CONF[:proxy_pass])
-        conn.use_ssl = @@CONF[:ssl]
-        conn.verify_mode = OpenSSL::SSL::VERIFY_NONE if @@CONF[:ssl]
-        conn
-      end
-      
-      def raise_rest_error(response, uri = nil)
-        raise RESTError.new(:code => response.code, 
-                            :message => response.message,
-                            :uri => uri)        
-      end
-      
-      def handle_rest_response(response, uri)
-        unless ["200", "201"].member?(response.code)
-          raise_rest_error(response, uri)
-        end
-      end
+  # Remote REST API interface representation
+  # 
+  class RESTInterfaceSpec
+  	include ClassUtilMixin
+  	
+  end
+  
+  # Remote REST API method representation
+  # 
+  class RESTMethodSpec
+  	include ClassUtilMixin
+  	attr_accessor :uri, :method, :parameters
+  end
+  
+  # Remote REST API method parameter representation
+  # 
+  class RESTParameterSpec
+  	include ClassUtilMixin
+  	attr_accessor :name, :type, :required
+  	def required?; @required; end
   end
 end

data/lib/twitter/ext/stdlib.rb

@@ -0,0 +1,32 @@
+# Contains Ruby standard library extensions specific to <tt>Twitter4R</tt> library.
+
+# Extension to Hash to create URL encoded string from key-values
+class Hash
+  # Returns string formatted for HTTP URL encoded name-value pairs.
+  # For example,
+  #  {:id => 'thomas_hardy'}.to_http_str 
+  #  # => "id=thomas_hardy"
+  #  {:id => 23423, :since => Time.now}.to_http_str
+  #  # => "since=Thu,%2021%20Jun%202007%2012:10:05%20-0500&id=23423"
+  def to_http_str
+    result = ''
+    return result if self.empty?
+    self.each do |key, val|
+      result << "#{key}=#{URI.encode(val.to_s)}&"
+    end
+    result.chop # remove the last '&' character, since it can be discarded
+  end
+end
+
+# Extension to Time that outputs RFC2822 compliant string on #to_s
+class Time
+  alias :old_to_s :to_s
+  # Returns RFC2822 compliant string for <tt>Time</tt> object.
+  # For example,
+  #  # Tony Blair's last day in office (hopefully)
+  #  best_day_ever = Time.local(2007, 6, 27)
+  #  best_day_ever.to_s # => "Wed, 27 Jun 2007 00:00:00 +0100"
+  def to_s
+    self.rfc2822
+  end
+end

data/lib/twitter/ext.rb

@@ -0,0 +1,2 @@
+
+require_local('twitter/ext/stdlib')

data/lib/twitter/extras.rb

@@ -0,0 +1,39 @@
+# extra.rb contains features that are not considered part of the core library.
+# This file is not imported by doing <tt>require('twitter')</tt>, so you will 
+# need to import this file separately like:
+#  require('twitter')
+#  require('twitter/extras')
+
+require('twitter')
+
+class Twitter::Client
+  @@FEATURED_URIS = {
+    :users => 'http://twitter.com/statuses/featured.json'
+  }
+  
+  # Provides access to the Featured Twitter API.
+  # 
+  # Currently the only value for <tt>type</tt> accepted is <tt>:users</tt>,
+  # which will return an Array of blessed Twitter::User objects that 
+  # represent Twitter's featured users.
+  def featured(type)
+    uri = @@FEATURED_URIS[type]
+    response = http_connect {|conn| create_http_get_request(uri) }
+    bless_models(Twitter::User.unmarshal(response.body))
+  end
+end
+
+class Twitter::User
+  class << self
+    # Provides access to the Featured Twitter API via the Twitter4R Model 
+    # interface.
+    # 
+    # The following lines of code are equivalent to each other:
+    #  users1 = Twitter::User.features(client)
+    #  users2 = client.featured(:users)
+    # where <tt>users1</tt> and <tt>users2</tt> would be logically equivalent.
+    def featured(client)
+      client.featured(:users)
+    end
+  end
+end

data/lib/twitter/meta.rb

@@ -1,3 +1,6 @@
+# meta.rb contains <tt>Twitter::Meta</tt> and related classes that
+# help define the metadata of the <tt>Twitter4R</tt> project.
+
 require('rubygems')
 require('erb')
 
@@ -5,10 +8,12 @@ class Twitter::Meta #:nodoc:
   attr_accessor :root_dir
   attr_reader :gem_spec, :project_files, :spec_files
 
+  # Initializer for Twitter::Meta class.  Takes <tt>root_dir</tt> as parameter.
   def initialize(root_dir)
     @root_dir = root_dir
   end
 
+  # Returns package information defined in <tt>root_dir</tt>/pkg-info.yml
   def pkg_info
     yaml_file = File.join(@root_dir, 'pkg-info.yml')
     ryaml = ERB.new(File.read(yaml_file), 0)
@@ -16,24 +21,34 @@ class Twitter::Meta #:nodoc:
     YAML.load(s)
   end
   
+  # Returns RubyGems spec information
   def spec_info
     self.pkg_info['spec'] if self.pkg_info
   end
   
+  # Returns list of project files
   def project_files
     @project_files ||= Dir.glob(File.join(@root_dir, 'lib/**/*.rb'))
     @project_files
   end
   
+  # Returns list of specification files
   def spec_files
     @spec_files ||= Dir.glob(File.join(@root_dir, 'spec/**/*.rb'))
     @spec_files
   end
   
+  # Returns RubyGem specification for Twitter4R project
   def gem_spec
     @gem_spec ||= Gem::Specification.new do |spec|
       self.spec_info.each do |key, val|
-        spec.send("#{key}=", val)
+        if val.is_a?(Hash)
+          val.each do |k, v|
+            spec.send(key, k, v)
+          end
+        else
+          spec.send("#{key}=", val)
+        end
       end
     end
     @gem_spec