craigtmackenzie-twitter4r 0.3.1

data/lib/twitter/config.rb

@@ -0,0 +1,77 @@
+# config.rb contains classes, methods and extends existing Twitter4R classes 
+# to provide easy configuration facilities.
+
+module Twitter
+  # Represents global configuration for Twitter::Client.
+  # Can override the following configuration options:
+  # * <tt>protocol</tt> - <tt>:http</tt>, <tt>:https</tt> or <tt>:ssl</tt> supported.  <tt>:ssl</tt> is an alias for <tt>:https</tt>.  Defaults to <tt>:ssl</tt>
+  # * <tt>host</tt> - hostname to connect to for the Twitter service.  Defaults to <tt>'twitter.com'</tt>.
+  # * <tt>port</tt> - port to connect to for the Twitter service.  Defaults to <tt>443</tt>.
+  # * <tt>proxy_host</tt> - proxy host to use.  Defaults to nil.
+  # * <tt>proxy_port</tt> - proxy host to use.  Defaults to nil.
+  # * <tt>proxy_user</tt> - proxy username to use.  Defaults to nil.
+  # * <tt>proxy_pass</tt> - proxy password to use.  Defaults to nil.
+  # * <tt>user_agent</tt> - user agent string to use for each request of the HTTP header.
+  # * <tt>application_name</tt> - name of your client application.  Defaults to 'Twitter4R'
+  # * <tt>application_version</tt> - version of your client application.  Defaults to current <tt>Twitter::Version.to_version</tt>.
+  # * <tt>application_url</tt> - URL of your client application.  Defaults to http://twitter4r.rubyforge.org.
+  # * <tt>source</tt> - the source id given to you by Twitter to identify your application in their web interface.  Note: you must contact Twitter.com developer directly so they can configure their servers appropriately.
+  class Config
+    include ClassUtilMixin
+    @@ATTRIBUTES = [
+      :protocol, 
+      :host, 
+      :port, 
+      :search_protocol,
+      :search_host,
+      :search_port,
+      :proxy_host, 
+      :proxy_port, 
+      :proxy_user, 
+      :proxy_pass, 
+      :user_agent,
+      :application_name,
+      :application_version,
+      :application_url,
+      :source,
+    ]
+    attr_accessor *@@ATTRIBUTES
+    
+    # Override of Object#eql? to ensure RSpec specifications run 
+    # correctly. Also done to follow Ruby best practices.
+    def eql?(other)
+      return true if self == other
+      @@ATTRIBUTES.each do |att|
+        return false unless self.send(att).eql?(other.send(att))
+      end
+      true
+    end
+  end
+
+  class Client
+    @@defaults = { :host => 'twitter.com', 
+                   :port => 443, 
+                   :protocol => :ssl,
+                   :search_host => 'search.twitter.com',
+                   :search_port => 80,
+                   :search_protocol => :http,
+                   :proxy_host => nil,
+                   :proxy_port => nil,
+                   :user_agent => "default",
+                   :application_name => 'Twitter4R',
+                   :application_version => Twitter::Version.to_version,
+                   :application_url => 'http://twitter4r.rubyforge.org',
+                   :source => 'twitter4r',
+    }
+    @@config = Twitter::Config.new(@@defaults)
+
+    # Twitter::Client class methods
+    class << self
+      # Yields to given <tt>block</tt> to configure the Twitter4R API.
+      def configure(&block)
+        raise ArgumentError, "Block must be provided to configure" unless block_given?
+        yield @@config
+      end # configure
+    end # class << self    
+  end # Client class
+end # Twitter module

data/lib/twitter/console.rb

@@ -0,0 +1,31 @@
+# Contains hooks for the twitter console
+
+require('optparse')
+
+module Twitter
+  class Client
+    class << self
+      # Helper method mostly for irb shell prototyping.
+      # 
+      # Reads in login/password Twitter credentials from YAML file
+      # found at the location given by <tt>config_file</tt> that has 
+      # the following format:
+      #  envname:
+      #    login: mytwitterlogin
+      #    password: mytwitterpassword
+      # 
+      # Where <tt>envname</tt> is the name of the environment like 'test', 
+      # 'dev' or 'prod'.  The <tt>env</tt> argument defaults to 'test'.
+      # 
+      # To use this in the shell you would do something like the following 
+      # examples:
+      #  twitter = Twitter::Client.from_config('config/twitter.yml', 'dev')
+      #  twitter = Twitter::Client.from_config('config/twitter.yml')
+      def from_config(config_file, env = 'test')
+        yaml_hash = YAML.load(File.read(config_file))
+        self.new yaml_hash[env]
+      end
+    end # class << self
+  end
+end
+

data/lib/twitter/core.rb

@@ -0,0 +1,137 @@
+# The Twitter4R API provides a nicer Ruby object API to work with 
+# instead of coding around the REST 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) #: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
+  
+  # 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 < RuntimeError 
+    include ClassUtilMixin
+    @@ATTRIBUTES = [:code, :message, :uri]
+    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}"
+    end
+  end # RESTError
+  
+  # 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.rb

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

data/lib/twitter/ext/stdlib.rb

@@ -0,0 +1,52 @@
+# 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}=#{CGI.escape(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"
+  # You can also pass in an option <tt>format</tt> argument that 
+  # corresponds to acceptable values according to ActiveSupport's 
+  # +Time#to_formatted_s+ method.
+  def to_s(format = nil)
+    format ? self.to_formatted_s(format) : self.rfc2822
+  end
+end
+
+# Extension to Kernel to add #gem_present? without any exceptions raised
+module Kernel
+
+  # Returns whether or not a gem exists without raising a Gem::LoadError exception
+  def gem_present?(gem_name, version = nil)
+    present = false
+    begin
+      present = !!(version ? gem(gem_name, version) : gem(gem_name))
+    rescue Gem::LoadError => le
+      present = false
+      warn("Gem load error: Couldn't load #{gem_name} #{version ? "with version requirement #{version}: #{le.to_s}": ""}")
+    end
+    present
+  end
+end

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

@@ -0,0 +1,56 @@
+# 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')
+
+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)
+    s = ryaml.result(binding)
+    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/**/*_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|
+        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
+  end
+end

data/lib/twitter/model.rb

@@ -0,0 +1,356 @@
+# 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(options = {})
+        @client.my(:followers, options)
+      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, 
+      :protected, :profile_image_url, :profile_background_color, 
+      :profile_text_color, :profile_link_color, :profile_sidebar_fill_color, 
+      :profile_sidebar_border_color, :profile_background_image_url, 
+      :profile_background_tile, :utc_offset, :time_zone, 
+      :following, :notifications, :favourites_count, :followers_count, 
+      :friends_count, :statuses_count, :created_at,  ]
+    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, :source, :truncated, :created_at, :user, 
+                    :favorited, :in_reply_to_status_id, :in_reply_to_user_id,
+                    :in_reply_to_screen_name]
+    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
+
+    def reply?
+      !!@in_reply_to_status_id
+    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
+  
+  # RateLimitStatus provides information about how many requests you have left 
+  # and when you can resume more requests if your remaining_hits count is zero.
+  class RateLimitStatus
+    include ModelMixin
+    @@ATTRIBUTES = [:remaining_hits, :hourly_limit, :reset_time_in_seconds, :reset_time]
+    attr_accessor *@@ATTRIBUTES
+    
+    class << self
+      # Used as factory method callback
+      def attributes; @@ATTRIBUTES; end
+    end
+  end
+end # Twitter