ruby_reddit_api-h 0.2.7

data/lib/ruby_reddit_api/api.rb

@@ -0,0 +1,87 @@
+module Reddit
+
+  # @author James Cook
+  class Api < Base
+    attr_accessor :user, :password
+    attr_reader :last_action, :debug
+
+    def initialize(user=nil,password=nil, options={})
+      @user     = user
+      @password = password
+      @debug    = StringIO.new
+    end
+
+    def inspect
+      "<Reddit::Api>"
+    end
+
+    # Browse submissions by subreddit
+    # @param [String] Subreddit to browse
+    # @return [Array<Reddit::Submission>]
+    def browse(subreddit, options={})
+      subreddit = sanitize_subreddit(subreddit)
+      options.merge! :handler => "Submission"
+      if options[:limit]
+        options.merge!({:query => {:limit => options[:limit]}})
+      end
+      read("/r/#{subreddit}.json", options )
+    end
+
+    # Search reddit
+    # @param [String, Hash] Search terms and options
+    # @example
+    #   search("programming", :in => "ruby", :sort => "relevance")
+    # @return [Array<Reddit::Submission>]
+    def search(terms=nil, options={})
+      http_options = {:verb => "get", :query => {}}
+      subreddit    = options[:in]
+      sort         = options.fetch(:sort){ "relevance" }
+      http_options[:query].merge!({:sort => sort})
+
+      if subreddit
+        http_options[:query].merge!({:restrict_sr => "1"})
+      end
+
+      if terms
+        http_options[:query].merge!({:q => terms})
+      end
+      path = subreddit.to_s == "" ? "/search.json" : "/r/#{subreddit}/search.json"
+      read(path, http_options)
+    end
+
+    # Read sent messages
+    # @return [Array<Reddit::Message>]
+    def sent_messages
+      messages :sent
+    end
+
+    # Read received messages
+    # @return [Array<Reddit::Message>]
+    def received_messages
+      messages :inbox
+    end
+
+    #Read unread messages
+    # @return [Array<Reddit::Message>]
+    def unread_messages
+      messages :unread
+    end
+
+    # Read received comments
+    # @return [Array<Reddit::Message>]
+    def comments
+      messages :comments
+    end
+
+    # Read post replies
+    # @return [Array<Reddit::Message>]
+    def post_replies
+      messages :selfreply
+    end
+
+    protected
+    def messages(kind)
+      read("/message/#{kind.to_s}.json", :handler => "Message")
+    end
+  end
+end

data/lib/ruby_reddit_api/base.rb

@@ -0,0 +1,133 @@
+module Reddit
+  # Base module all other classes descend from. Stores the cookie, modhash and user info for many API calls. Handles authentication and directs JSON
+  # to the relevant handler.
+  # @author James Cook
+  class Base
+    include HTTParty
+
+    attr_reader :last_action, :debug
+    base_uri "www.reddit.com"
+    class << self; attr_reader :cookie, :modhash, :user_id, :user, :throttle_duration end
+
+    @throttle_duration = 1.0
+
+    def initialize(options={})
+      @debug    = StringIO.new
+    end
+
+    # @return [String]
+    def inspect
+      "<Reddit::Base>"
+    end
+
+    # Login to Reddit and capture the cookie
+    # @return [Boolean] Login success or failure
+    def login
+      capture_session(self.class.post( "/api/login", {:body => {:user => @user, :passwd => @password}, :debug_output => @debug} ) )
+      logged_in?
+    end
+
+    # Remove the cookie to effectively logout of Reddit
+    # @return [nil]
+    def logout
+      Reddit::Base.instance_variable_set("@cookie",nil)
+    end
+
+    # @return [String, nil]
+    def cookie
+      Reddit::Base.cookie
+    end
+
+    # A kind of authenticity token for many API calls
+    # @return [String, nil]
+    def modhash
+      Reddit::Base.modhash
+    end
+
+    # Reddit's displayed ID for the logged in user
+    # @return [String]
+    def user_id
+      Reddit::Base.user_id
+    end
+
+    # Logged in user
+    # @return [String]
+    def user
+      Reddit::Base.user
+    end
+
+    # The session is authenticated if the captured cookie shows a valid session is in place
+    # @return [true,false]
+    def logged_in?
+      !!(cookie && (cookie =~ /reddit_session/) != nil)
+    end
+
+    # @return String
+    def user_agent
+      self.class.user_agent
+    end
+
+    # HTTP headers to be sent in all API requests. At a minimum, 'User-agent' and 'Cookie' are needed.
+    # @return Hash
+    def base_headers
+      self.class.base_headers
+    end
+
+    # Base communication function for nearly all API calls
+    # @return [Reddit::Submission, Reddit::Comment, Reddit::User, false] Various reddit-related, json parseable objects
+    def read(url, options={})
+      unless throttled?
+        @debug.rewind
+        verb      = (options[:verb] || "get")
+        param_key = (verb == "get") ? :query : :body
+        resp      = self.class.send( verb, url, {param_key => (options[param_key] || {}), :headers => base_headers, :debug_output => @debug})
+        if valid_response?(resp)
+          @last_action = Time.now
+          klass = Reddit.const_get(options[:handler] || "Submission")
+          resp  = klass.parse( JSON.parse(resp.body, :max_nesting => 9_999) )
+          return resp
+        else
+          return false
+        end
+      end
+    end
+
+    protected
+    def valid_response?(response)
+      response.code == 200 && response.headers["content-type"].to_s =~ /json/
+    end
+
+    def capture_session(response)
+      cookies = response.headers["set-cookie"]
+      Reddit::Base.instance_variable_set("@cookie", cookies)
+      Reddit::Base.instance_variable_set("@user",   @user)
+    end
+
+    def capture_user_id
+      return true if user_id
+      this_user = read("/user/#{user}/about.json", :handler => "User")[0]
+      Reddit::Base.instance_variable_set("@user_id", this_user.id)
+    end
+
+    def throttled?
+      @last_action && ( ( Time.now - @last_action ) < Reddit::Base.throttle_duration )
+    end
+
+    def sanitize_subreddit(subreddit)
+      subreddit.gsub!(/^\/?r\//,'')
+      subreddit.gsub!(/\.json\Z/,'')
+      subreddit
+    end
+
+    class << self
+
+      def base_headers
+        {'Cookie' => Reddit::Base.cookie.to_s, 'user-agent' => user_agent}
+      end
+
+      def user_agent
+        "Ruby Reddit Client v#{Reddit::VERSION}"
+      end
+    end
+  end
+end

data/lib/ruby_reddit_api/comment.rb

@@ -0,0 +1,125 @@
+module Reddit
+  # @author James Cook
+  class Comment < Thing
+    include Voteable
+    include JsonListing
+
+    attr_reader :body, :subreddit_id, :name, :created, :downs, :author, :created_utc, :body_html, :link_id, :parent_id, :likes, :num_comments, :subreddit, :ups, :debug, :kind, :replies
+    def initialize(json, options={})
+      mode = options.fetch(:mode){ :json }
+      if mode == :json
+        parse(json)
+      end
+
+      if mode == :replies
+        json.keys.each do |key|
+          instance_variable_set("@#{key}", json[key])
+        end
+      end
+
+      if replies.is_a?(Hash)
+        handle_replies(replies)
+      end
+
+      @debug = StringIO.new
+    end
+
+    def inspect
+      "<Reddit::Comment author='#{@author}' body='#{short_body}' replies='#{replies.size}' ups='#{ups}' downs='#{downs}'>"
+    end
+
+    # @return [String]
+    def to_s
+      body
+    end
+
+    # Fetch comments
+    # @return [Array<Reddit::Comment>]
+    def comments
+      opts = {:handler => "Comment",
+              :verb => "post",
+              :body =>
+                {:link_id => id, :depth => 10, :r => subreddit, :uh => modhash, :renderstyle => "json", :pv_hex => "", :id => id}
+              }
+      return read("/api/morechildren", opts )
+    end
+
+    # Modify a comment
+    # @return [true,false]
+    def edit(newtext)
+      resp=self.class.post("/api/editusertext", {:body => {:thing_id => id, :uh => modhash, :r => subreddit, :text => newtext }, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    # Hide a comment
+    # @return [true,false]
+    def hide
+      resp=self.class.post("/api/del", {:body => {:id => id, :uh => modhash, :r => subreddit, :executed => "removed" }, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    # Remove a comment
+    # @return [true,false]
+    def remove
+      resp=self.class.post("/api/remove", {:body => {:id => id, :uh => modhash, :r => subreddit}, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    # Approve a comment
+    # @return [true,false]
+    def approve
+      resp=self.class.post("/api/approve", {:body => {:id => id, :uh => modhash, :r => subreddit}, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    def moderator_distinguish
+      add_distinction "yes"
+    end
+
+    def admin_distinguish
+      add_distinction "admin"
+    end
+
+    def indistinguish
+      add_distinction "no"
+    end
+
+    # Reply to another comment
+    # @return [true,false]
+    def reply(text)
+      resp = self.class.post("/api/comment", {:body => {:thing_id => id, :text => text, :uh => modhash, :r => subreddit }, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    # Trimmed comment body suitable for #inspect
+    # @return [String]
+    def short_body
+      str = body.to_s.strip
+      if str.size > 15
+        sb = str[0..15] + "..."
+      else
+        sb = body
+      end
+
+      sb.gsub(/[\n\r]/,'\n')
+    end
+
+    def add_distinction(verb)
+      resp=self.class.post("/api/distinguish/#{verb}", {:body => {:id => id, :uh => modhash, :r => subreddit, :executed => "distinguishing..."}, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    # Parse nested comment hashes into a Comment
+    # @param  [Hash] JSON containing reply data
+    # @return [true]
+    def handle_replies(data)
+       dup = data.dup
+       _kind, data       = dup["kind"],     dup["data"]
+       modhash, children = data["modhash"], data["children"]
+       if children.is_a?(Array)
+         @replies = children.map{|reply| Comment.new(reply["data"], :mode => :replies) }
+       end
+       true
+    end
+  end
+end

data/lib/ruby_reddit_api/json_listing.rb

@@ -0,0 +1,46 @@
+#@author James Cook
+module Reddit
+  module JsonListing
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.send(:include, InstanceMethods)
+    end
+
+    module ClassMethods
+
+      # @param [Hash] JSON received from Reddit
+      # @return [Array<Reddit::Submission, Reddit::User, Reddit::Comment, Reddit::Message>]
+      def parse(json)
+        results = []
+        if json.is_a?(Array)
+          json.each do |j|
+            results << parse(j)
+          end
+        else
+          data     = json["data"]
+          Reddit::Base.instance_variable_set("@modhash", data["modhash"]) # Needed for api calls
+
+          children = data["children"] || [{"data" => data, "kind" => json["kind"] }]
+          children.each do |message|
+            kind     = message["kind"]
+            message["data"]["kind"] = kind
+            results << self.new(message["data"])
+          end
+        end
+
+        return results.flatten
+      end
+    end
+    module InstanceMethods
+      # Iterate over JSON and set instance variables that map to each JSON key
+      # @param [Hash] JSON received from Reddit
+      # @return [true]
+      def parse(json)
+        json.keys.each do |key|
+          instance_variable_set("@#{key}", json[key])
+        end
+        true
+      end
+    end
+  end
+end

data/lib/ruby_reddit_api/message.rb

@@ -0,0 +1,63 @@
+# @author James Cook
+module Reddit
+  class Message < Thing
+    include JsonListing
+
+    attr_reader :body, :was_comment, :kind, :first_message, :name, :created, :dest, :created_utc, :body_html, :subreddit, :parent_id, :context, :replies, :subject, :debug
+    def initialize(json)
+      parse(json)
+      @debug    = StringIO.new
+    end
+
+    # The reddit ID of this message
+    # @return [String]
+    def id
+      "#{kind}_#{@id}"
+    end
+
+    def unread?
+      @new == true
+    end
+
+    def read?
+      @new == false
+    end
+
+    # The author of the message. The data is lazy-loaded and cached on the message
+    # @return [Reddit::User]
+    def author
+      @author_data ||= read("/user/#{@author}/about.json", :handler => "User")
+    end
+
+    # Reply to this message
+    # @return [true,false]
+    def reply(text)
+      resp = self.class.post("/api/comment", {:body => {:thing_id => id, :text => text, :uh => modhash, :r => subreddit }, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    def mark_unread
+      resp = self.class.post("/api/unread_message", {:body => {:id => id, :uh => modhash}, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    def mark_read
+      resp = self.class.post("/api/read_message", {:body => {:id => id, :uh => modhash }, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    def inspect
+      "<Reddit::Message '#{short_body}'>"
+    end
+
+    # Trimmed comment body suitable for #inspect
+    # @return [String]
+    def short_body
+      if body.size > 15
+        body[0..15]
+      else
+        body
+      end
+    end
+  end
+end

data/lib/ruby_reddit_api/message_group.rb

@@ -0,0 +1,39 @@
+# @author James Cook
+module Reddit
+  class MessageGroup < Thing
+    include JsonListing
+    attr_reader :debug
+
+    def initialize
+      @debug = StringIO.new
+    end
+
+    def mark_read(messages)
+      mark messages, "read"
+    end
+
+    def mark_unread(messages)
+      mark messages, "unread"
+    end
+
+    protected
+    def mark(messages, action)
+      ids = ids(messages) 
+      action = action == "read" ? "read_message" : "unread_message"
+      resp = self.class.post("/api/#{action}", {:body => {:id => ids.join(','), :uh => modhash }, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    def ids(messages)
+      if messages.is_a?(Array)
+        if messages.first.is_a?(Reddit::Message)
+          return messages.map{|m| m.id }
+        else
+          return messages # assume array of String
+        end
+      else
+        return [ messages.id ]
+      end
+    end
+  end
+end

data/lib/ruby_reddit_api/submission.rb

@@ -0,0 +1,73 @@
+# @author James Cook
+module Reddit
+  class Submission < Thing
+    include JsonListing
+    include Voteable
+
+    attr_reader :domain, :media_embed, :subreddit, :selftext_html, :selftext, :likes, :saved, :clicked, :media, :score, :over_18, :hidden, :thumbnail, :subreddit_id, :downs, :is_self, :permalink, :name, :created, :url, :title, :created_utc, :num_comments, :ups, :kind, :last_comment_id
+
+    def inspect
+      "<Reddit::Submission id='#{id}' author='#{@author}' title='#{title}'>"
+    end
+
+    # Add a comment to a submission
+    # @param [String] Comment text
+    # @return [true,false]
+    def add_comment(text)
+      resp = self.class.post("/api/comment", {:body => {:thing_id => id, :text => text, :uh => modhash, :r => subreddit }, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    # Save submission
+    # @return [true,false]
+    def save
+      toggle :save
+    end
+
+    # Unsave submission
+    # @return [true,false]
+    def unsave
+      toggle :unsave
+    end
+
+    # Hide submission
+    # @return [true,false]
+    def hide
+      toggle :hide
+    end
+
+    # Unhide submission
+    # @return [true,false]
+    def unhide
+      toggle :unhide
+    end
+
+    def moderator_distinguish
+      add_distinction "yes"
+    end
+
+    def admin_distinguish
+      add_distinction "admin"
+    end
+
+    def indistinguish
+      add_distinction "no"
+    end
+
+    # Fetch submission comments
+    # @todo Move to 'Thing' class
+    # @return [Array<Reddit::Comment>]
+    def comments
+      _comments = read( permalink + ".json", {:handler => "Comment", :query => {:limit => 250}} )
+      @last_comment_id = _comments.last.id if _comments && _comments.any?
+      _comments.shift # First 'comment' is actually the submission
+      return _comments
+    end
+
+    protected
+    def add_distinction(verb)
+      resp=self.class.post("/api/distinguish/#{verb}", {:body => {:id => id, :uh => modhash, :r => subreddit, :executed => "distinguishing..."}, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+  end
+end

data/lib/ruby_reddit_api/thing.rb

@@ -0,0 +1,38 @@
+module Reddit
+  # @author James Cook
+  class Thing < Base
+    include JsonListing
+
+    def initialize(data)
+      parse(data)
+      @debug    = StringIO.new
+    end
+
+    # The reddit ID of this entity
+    # @return [String]
+    def id
+      "#{kind}_#{@id}"
+    end
+
+    # The author of the entity. The data is lazy-loaded and cached on the object
+    # @return [Reddit::User]
+    def author
+      response = read("/user/#{@author}/about.json", :handler => "User") if @author
+      @author_data ||= response[0] if response
+    end
+
+    # Report thing
+    # @return [true,false]
+    def report
+      toggle :report
+    end
+
+    def toggle(which)
+      return false unless logged_in?
+      mapping = {:save => "save", :unsave => "unsave", :hide => "hidden", :unhide => "unhidden", :report => "report"}
+      mode = mapping[which]
+      resp = self.class.post("/api/#{which}", {:body => {:id => id, :uh => modhash, :r => subreddit, :executed => mode }, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+  end
+end

data/lib/ruby_reddit_api/user.rb

@@ -0,0 +1,42 @@
+module Reddit
+  # @author James Cook
+  class User < Api
+    include JsonListing
+    attr_reader :name, :debug, :created, :created_utc, :link_karma, :comment_karma, :is_mod, :has_mod_mail, :kind
+    def initialize(json)
+      @debug = StringIO.new
+      parse(json)
+    end
+
+    def inspect
+      "<Reddit::User name='#{name}'>"
+    end
+
+    # The reddit ID of this submission
+    # @return [String]
+    def id
+      "#{kind}_#{@id}"
+    end
+
+    # @return [String]
+    def to_s
+      name
+    end
+
+    # Add redditor as friend. Requires a authenticated user.
+    # @return [true,false]
+    def friend
+      capture_user_id
+      resp=self.class.post("/api/friend", {:body => {:name => name, :container => user_id, :type => "friend", :uh => modhash}, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+
+    # Remove redditor as friend. Requires a authenticated user.
+    # @return [true,false]
+    def unfriend
+      capture_user_id
+      resp=self.class.post("/api/unfriend", {:body => {:name => name, :container => user_id, :type => "friend", :uh => modhash}, :headers => base_headers, :debug_output => @debug })
+      resp.code == 200
+    end
+  end
+end

data/lib/ruby_reddit_api/version.rb

@@ -0,0 +1,6 @@
+# @author James Cook
+module Reddit
+  # Capture the code version from the VERSION file
+  # @return [String]
+  VERSION = File.exist?("VERSION") ? File.read("VERSION").chomp : ""
+end

data/lib/ruby_reddit_api/vote.rb

@@ -0,0 +1,39 @@
+# @author James Cook
+module Reddit
+  class Vote < Base
+    attr_reader :submission
+
+    def initialize(submission)
+      @submission = submission
+    end
+
+    # Upvote submission or comment
+    # @return [true,false]
+    def up
+      vote(:up)
+    end
+
+    # Downvote submission or comment
+    # @return [true,false]
+    def down
+      vote(:down)
+    end
+
+    #@return [String]
+    def inspect
+      "<Reddit::Vote>"
+    end
+
+    protected
+    def vote(direction)
+      return false unless logged_in?
+      up_or_down = direction == :up ? 1 : -1
+      resp = self.class.post( "/api/vote", {:body => {:id => submission.id, :dir => up_or_down, :uh => modhash}, :headers => base_headers})
+      if resp.code == 200
+        return true
+      else
+        return false
+      end
+    end
+  end
+end