lib/twitter/client/user.rb

   1 class Twitter::Client
   2   @@USER_URIS = {
   3         :info => '/users/show.json',
   4         :friends => '/statuses/friends.json',
   5         :followers => '/statuses/followers.json',
   6   }
   7
   8   # Provides access to Twitter's User APIs
   9   #
  10   # Returns user instance for the <tt>id</tt> given.  The <tt>id</tt>
  11   # can either refer to the numeric user ID or the user's screen name.
  12   #
  13   # For example,
  14   #  @twitter.user(234943) #=> Twitter::User object instance for user with numeric id of 234943
  15   #  @twitter.user('mylogin') #=> Twitter::User object instance for user with screen name 'mylogin'
  16   #
  17   # Where <tt>options</tt> is a +Hash+ of options that can include:
  18   # * <tt>:page</tt> - optional.  Retrieves the next set of friends.  There are 100 friends per page.  Default: 1.
  19   # * <tt>:lite</tt> - optional.  Prevents the inline inclusion of current status.  Default: false.
  20   # * <tt>:since</tt> - optional.  Only relevant for <tt>:friends</tt> action.  Narrows the results to just those friends added after the date given as value of this option.  Must be HTTP-formatted date.
  21   #
  22   # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt>
  23   # is given.  Valid actions are:
  24   # * +:info+
  25   # * +:friends+
  26   #
  27   # +Note:+ You should not use this method to attempt to retrieve the
  28   # authenticated user's followers.  Please use any of the following
  29   # ways of accessing this list:
  30   #  followers = client.my(:followers)
  31   # OR
  32   #  followers = client.my(:info).followers
  33   def user(id, action = :info, options = {})
  34     raise ArgumentError, "Invalid user action: #{action}" unless @@USER_URIS.keys.member?(action)
  35     id = id.to_i if id.is_a?(Twitter::User)
  36     id_param = id.is_a?(String) ? :screen_name : :user_id
  37     params = options.merge(id_param => id)
  38     response = rest_oauth_connect(:get, @@USER_URIS[action], params)
  39     bless_models(Twitter::User.unmarshal(response.body))
  40   end
  41
  42   # Syntactic sugar for queries relating to authenticated user in Twitter's User API
  43   #
  44   # Where <tt>action</tt> is one of the following:
  45   # * <tt>:info</tt> - Returns user instance for the authenticated user.
  46   # * <tt>:friends</tt> - Returns Array of users that are authenticated user's friends
  47   # * <tt>:followers</tt> - Returns Array of users that are authenticated user's followers
  48   #
  49   # Where <tt>options</tt> is a +Hash+ of options that can include:
  50   # * <tt>:page</tt> - optional.  Retrieves the next set of friends.  There are 100 friends per page.  Default: 1.
  51   # * <tt>:lite</tt> - optional.  Prevents the inline inclusion of current status.  Default: false.
  52   # * <tt>:since</tt> - optional.  Only relevant for <tt>:friends</tt> action.  Narrows the results to just those friends added after the date given as value of this option.  Must be HTTP-formatted date.
  53   #
  54   # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt>
  55   # is given.  Valid actions are:
  56   # * +:info+
  57   # * +:friends+
  58   # * +:followers+
  59   def my(action, options = {})
  60     raise ArgumentError, "Invalid user action: #{action}" unless @@USER_URIS.keys.member?(action)
  61     params = options.merge(:id => @login)
  62     response = rest_oauth_connect(:get, @@USER_URIS[action], params)
  63     users = Twitter::User.unmarshal(response.body)
  64     bless_models(users)
  65   end
  66 end