lib/twitter/client/timeline.rb

   1 class Twitter::Client
   2   @@TIMELINE_URIS = {
   3     :public => '/statuses/public_timeline.json',
   4     :friends => '/statuses/friends_timeline.json',
   5     :friend => '/statuses/friends_timeline.json',
   6     :user => '/statuses/user_timeline.json',
   7     :me => '/statuses/user_timeline.json',
   8     :replies => '/statuses/replies.json',
   9     :mentions => '/statuses/mentions.json'
  10   }
  11
  12   # Provides access to Twitter's Timeline APIs
  13   #
  14   # Returns timeline for given <tt>type</tt>.
  15   #
  16   # <tt>type</tt> can take the following values:
  17   # * <tt>public</tt>
  18   # * <tt>friends</tt> or <tt>friend</tt>
  19   # * <tt>user</tt> or <tt>me</tt>
  20   #
  21   # <tt>:id</tt> is on key applicable to be defined in </tt>options</tt>:
  22   # * the id or screen name (aka login) for :friends
  23   # * the id or screen name (aka login) for :user
  24   # * meaningless for the :me case, since <tt>twitter.timeline_for(:user, 'mylogin')</tt> and <tt>twitter.timeline_for(:me)</tt> are the same assuming 'mylogin' is the authenticated user's screen name (aka login).
  25   #
  26   # Examples:
  27   #  # returns the public statuses since status with id of 6543210
  28   #  twitter.timeline_for(:public, id => 6543210)
  29   #  # returns the statuses for friend with user id 43210
  30   #  twitter.timeline_for(:friend, :id => 43210)
  31   #  # returns the statuses for friend with screen name (aka login) of 'otherlogin'
  32   #  twitter.timeline_for(:friend, :id => 'otherlogin')
  33   #  # returns the statuses for user with screen name (aka login) of 'otherlogin'
  34   #  twitter.timeline_for(:user, :id => 'otherlogin')
  35   #
  36   # <tt>options</tt> can also include the following keys:
  37   # * <tt>:id</tt> is the user ID, screen name of Twitter::User representation of a <tt>Twitter</tt> user.
  38   # * <tt>:since</tt> is a Time object specifying the date-time from which to return results for.  Applicable for the :friend, :friends, :user and :me cases.
  39   # * <tt>:count</tt> specifies the number of statuses to retrieve.  Only applicable for the :user case.
  40   # * <tt>since_id</tt> is the status id of the public timeline from which to retrieve statuses for <tt>:public</tt>.  Only applicable for the :public case.
  41   #
  42   # You can also pass this method a block, which will iterate through the results
  43   # of the requested timeline and apply the block logic for each status returned.
  44   #
  45   # Example:
  46   #  twitter.timeline_for(:public) do |status|
  47   #    puts status.user.screen_name, status.text
  48   #  end
  49   #
  50   #  twitter.timeline_for(:friend, :id => 'myfriend', :since => 30.minutes.ago) do |status|
  51   #    puts status.user.screen_name, status.text
  52   #  end
  53   #
  54   #  timeline = twitter.timeline_for(:me) do |status|
  55   #    puts status.text
  56   #  end
  57   #
  58   # An <tt>ArgumentError</tt> will be raised if an invalid <tt>type</tt>
  59   # is given.  Valid types are:
  60   # * +:public+
  61   # * +:friends+
  62   # * +:friend+
  63   # * +:user+
  64   # * +:me+
  65   def timeline_for(type, options = {}, &block)
  66     raise ArgumentError, "Invalid timeline type: #{type}" unless @@TIMELINE_URIS.keys.member?(type)
  67     uri = @@TIMELINE_URIS[type]
  68     response = http_connect {|conn| create_http_get_request(uri, options) }
  69     timeline = Twitter::Status.unmarshal(response.body)
  70     timeline.each {|status| bless_model(status); yield status if block_given? }
  71     timeline
  72   end
  73 end