ruby_reddit_api 0.1.9 → 0.2.0

data/README

@@ -1,6 +1,6 @@
-Ruby Reddit Client v0.1.9
+Ruby Reddit Client v0.2.0
 ==================
-Tested with 1.9.2
+Tested with ruby 1.9.2
 
 Usage:
 =======
@@ -12,9 +12,10 @@ Usage:
 Features:
 ========
 - Authentication
-- Parse submissions
-- Comments parsing
-- Vote on submission
+- Browse submissions
+- Read comments
+- Friend/unfriend redditors
+- Comment & submission voting
 
 
 Running Tests:

data/lib/ruby_reddit_api/api.rb

@@ -1,5 +1,6 @@
 module Reddit
 
+  # @author James Cook
   class Api < Base
     attr_reader :last_action, :debug
 
@@ -13,6 +14,9 @@ module Reddit
       "<Reddit::Api user='#{user}'>"
     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"
@@ -22,18 +26,26 @@ module Reddit
       read("/r/#{subreddit}.json", 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 received comments
+    # @return [Array<Reddit::Message>]
     def comments
       messages :comments
     end
 
+    # Read post replies
+    # @return [Array<Reddit::Message>]
     def post_replies
       messages :selfreply
     end

data/lib/ruby_reddit_api/base.rb

@@ -1,4 +1,7 @@
 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
 
@@ -10,47 +13,66 @@ module Reddit
       @debug    = StringIO.new
     end
 
+    # @return [String]
     def inspect
       "<Reddit::Base user='#{user}'>"
     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

data/lib/ruby_reddit_api/comment.rb

@@ -1,5 +1,7 @@
 module Reddit
-  class Comment < Api
+  # @author James Cook
+  class Comment < Thing
+
     include JsonListing
     attr_reader :body, :subreddit_id, :name, :created, :downs, :author, :created_utc, :body_html, :link_id, :parent_id, :likes, :replies, :subreddit, :ups, :debug, :kind
     def initialize(json)
@@ -11,33 +13,34 @@ module Reddit
       "<Reddit::Comment author='#{@author}' body='#{short_body}'>"
     end
 
-    def id
-      "#{kind}_#{@id}"
-    end
-
-    def author
-      @author_data ||= read("/user/#{@author}/about.json", :handler => "User")
-    end
-
+    # @return [String]
     def to_s
       body
     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
 
-    def hide # soft delete?
+    # 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
@@ -55,19 +58,15 @@ module Reddit
       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
 
-    def upvote
-      Vote.new(self).up
-    end
-
-    def downvote
-      Vote.new(self).down
-    end
-
+    # Trimmed comment body suitable for #inspect
+    # @return [String]
     def short_body
       str = body.to_s
       if str.size > 15

data/lib/ruby_reddit_api/json_listing.rb

@@ -1,3 +1,4 @@
+#@author James Cook
 module Reddit
   module JsonListing
     def self.included(base)
@@ -6,6 +7,9 @@ module Reddit
     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)
@@ -28,10 +32,14 @@ module Reddit
       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

data/lib/ruby_reddit_api/message.rb

@@ -1,16 +1,22 @@
+# @author James Cook
 module Reddit
   class Message < Base
     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
 
+    # 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
@@ -19,6 +25,8 @@ module Reddit
       "<Reddit::Message '#{short_body}'>"
     end
 
+    # Trimmed comment body suitable for #inspect
+    # @return [String]
     def short_body
       if body.size > 15
         body[0..15]

data/lib/ruby_reddit_api/submission.rb

@@ -1,58 +1,45 @@
+# @author James Cook
 module Reddit
-  class Submission < Base
+  class Submission < Thing
     include JsonListing
     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 initialize(data)
-      parse(data)
-      @debug    = StringIO.new
-    end
-
     def inspect
       "<Reddit::Submission id='#{id}' author='#{@author}' title='#{title}'>"
     end
 
-    def id
-      "#{kind}_#{@id}"
-    end
-
-    def author
-      @author_data ||= read("/user/#{@author}/about.json", :handler => "User")
-    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
 
-    def upvote
-      Reddit::Vote.new(self).up
-    end
-
-    def downvote
-      Reddit::Vote.new(self).down
-    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 report
-      toggle :report
-    end
-
     def moderator_distinguish
       add_distinction "yes"
     end
@@ -65,6 +52,9 @@ module Reddit
       add_distinction "no"
     end
 
+    # Fetch submission comments
+    # @todo Move to 'Thing' class
+    # @return [Array<Reddit::Comment>]
     def comments(more=false)
       #TODO Get morechildren to work correctly
       if more && last_comment_id
@@ -87,13 +77,5 @@ module Reddit
       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
-
-    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/thing.rb

@@ -0,0 +1,49 @@
+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
+      @author_data ||= read("/user/#{@author}/about.json", :handler => "User")
+    end
+
+    # Upvote thing
+    # @return [true,false]
+    def upvote
+      Reddit::Vote.new(self).up
+    end
+
+    # Downvote thing
+    # @return [true,false]
+    def downvote
+      Reddit::Vote.new(self).down
+    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

@@ -1,6 +1,7 @@
-
 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
@@ -11,37 +12,31 @@ module Reddit
       "<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
-
-    protected
-    def parse(json)
-      json.keys.each do |key|
-        instance_variable_set("@#{key}", json[key])
-      end
-    end
-
-    def self.parse(json)
-      kind, data = json["kind"], json["data"]
-      data["kind"] = kind
-      return self.new(data)
-    end
   end
 end

data/lib/ruby_reddit_api/version.rb

@@ -1,3 +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

@@ -1,3 +1,4 @@
+# @author James Cook
 module Reddit
   class Vote < Base
     attr_reader :submission
@@ -6,14 +7,19 @@ module Reddit
       @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

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 9
-  version: 0.1.9
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - James Cook
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-05 00:00:00 -04:00
+date: 2010-10-06 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -54,6 +54,7 @@ extra_rdoc_files: []
 
 files: 
 - lib/ruby_reddit_api.rb
+- lib/ruby_reddit_api/thing.rb
 - lib/ruby_reddit_api/user.rb
 - lib/ruby_reddit_api/comment.rb
 - lib/ruby_reddit_api/message.rb
@@ -78,7 +79,7 @@ files:
 - features/step_definitions/comment_steps.rb
 - features/step_definitions/base_steps.rb
 - features/support/base_helpers.rb
-has_rdoc: true
+has_rdoc: false
 homepage: http://github.com/jamescook/RubyRedditAPI
 licenses: []