redd 0.6.5 → 0.7.0

data/lib/redd/objects/subreddit.rb

@@ -0,0 +1,152 @@
+require_relative "thing"
+
+module Redd
+  module Objects
+    # A comment made on links.
+    # @todo #subscribe! and #unsubscribe!
+    class Subreddit < Thing
+      include Thing::Messageable
+      include Thing::Refreshable
+
+      alias_property :header_image, :header_img
+      alias_property :nsfw?, :over18
+      alias_property :users_online, :accounts_active
+      alias_property :type, :subreddit_type
+      alias_property :times_gilded, :gilded
+
+      # @return [String] The url for the subreddit's stylesheet.
+      def stylesheet_url
+        get("/r/#{display_name}/stylesheet").headers["location"]
+      end
+
+      # @return [String] The css for the subreddit.
+      def stylesheet
+        Faraday.get(stylesheet_url).body
+      end
+
+      # Accept a moderator invite from a subreddit.
+      def accept_moderator_invite!
+        post("/r/#{display_name}/api/accept_moderator_invite")
+      end
+
+      # Stop being a contributor of the subreddit.
+      def leave_contributor_status!
+        post("/api/leavecontributor", id: fullname)
+      end
+
+      # Stop being a moderator of the subreddit.
+      def leave_moderator_status!
+        post("/api/leavemoderator", id: fullname)
+      end
+
+      # Get a list of everbody on the subreddit with a user flair.
+      #
+      # @param [Hash] params A list of params to send with the request.
+      # @option params [String] :after Return results after the given
+      #   fullname.
+      # @option params [String] :before Return results before the given
+      #   fullname.
+      # @option params [Integer] :count The number of items already seen in the
+      #   listing.
+      # @option params [1..1000] :limit The maximum number of things to
+      #   return.
+      # @option params [String] :name The username when getting the flair of
+      #   just one user.
+      # @return [Objects::Listing<Hash>] A listing of flair hashes.
+      def get_flairlist(**params)
+        body = get("/r/#{display_name}/api/flairlist.json", params).body
+        client.object_from_body(
+          kind: "Listing",
+          data: {
+            children: body[:users],
+            before: body[:prev],
+            after: body[:next]
+          }
+        )
+      end
+
+      # Get the flair of a user.
+      #
+      # @param [Objects::User, String] user The user to find.
+      # @return [Hash, nil] Flair info about the user or nil if nobody was
+      #   found.
+      def get_flair(user)
+        username = client.property(user, :name)
+        flair = get_flairlist(user: username).first
+        flair if flair[:user].casecmp(username) == 0
+      end
+
+      # Set the flair of a user or link.
+      # @param [Objects::Subreddit, Objects::User] thing The user or link to
+      #   set the flair to.
+      # @param [:user, :link] type The type of thing.
+      # @param [String] text The text to set the flair to.
+      # @param [String] css_class The css_class of the flair.
+      def set_flair(thing, type = nil, text = nil, css_class = nil)
+        if thing.is_a?(Objects::User) || type == :user
+          params[:name] = client.property(thing, :name)
+        elsif thing.is_a?(Objects::Submission) || type == :user
+          params[:link] = client.property(thing, :fullname)
+        else
+          fail "You should provide a proper type."
+        end
+
+        post("/r/#{display_name}/api/flair", text: text, css_class: css_class)
+      end
+
+      # @!method get_hot(**params)
+      # @!method get_new(**params)
+      # @!method get_top(**params)
+      # @!method get_controversial(**params)
+      # @!method get_comments(**params)
+      #
+      # Get the appropriate listing.
+      # @param params [Hash] A list of params to send with the request.
+      # @option params [String] :after Return results after the given
+      #   fullname.
+      # @option params [String :before Return results before the given
+      #   fullname.
+      # @option params [Integer] :count (0) The number of items already seen
+      #   in the listing.
+      # @option params [1..100] :limit (25) The maximum number of things to
+      #   return.
+      # @option params [:hour, :day, :week, :month, :year, :all] :t The
+      #   time period to consider when sorting.
+      #
+      # @note The option :t only applies to the top and controversial sorts.
+      # @return [Objects::Listing<Objects::Thing>]
+      %w(hot new top controversial comments).each do |sort|
+        define_method :"get_#{sort}" do |**params|
+          client.send(:"get_#{sort}", self, **params)
+        end
+      end
+
+      # @!method get_reports(**params)
+      # @!method get_spam(**params)
+      # @!method get_modqueue(**params)
+      # @!method get_unmoderated(**params)
+      # @!method get_edited(**params)
+      #
+      # Get the appropriate moderator listing.
+      # @param [Hash] params A list of params to send with the request.
+      # @option params [String] :after Return results after the given
+      #   fullname.
+      # @option params [String] :before Return results before the given
+      #   fullname.
+      # @option params [Integer] :count The number of items already seen
+      #   in the listing.
+      # @option params [1..100] :limit The maximum number of things to
+      #   return.
+      # @option params :location No idea what this does.
+      # @option params [:links, :comments] :only The type of things to show.
+      #
+      # @return [Objects::Listing<Objects::Thing>]
+      # @see https://www.reddit.com/dev/api#GET_about_{location}
+      %w(reports spam modqueue unmoderated edited).each do |sort|
+        define_method :"get_#{sort}" do |**params|
+          request_object(:get, "/r/#{display_name}/about/#{sort}", params)
+        end
+      end
+    end
+  end
+end

data/lib/redd/objects/thing.rb

@@ -0,0 +1,33 @@
+require_relative "base"
+
+module Redd
+  module Objects
+    # A reddit thing.
+    # @see http://www.reddit.com/dev/api#fullnames
+    class Thing < Base
+      # Load up all the possible mixins for the thing.
+      Dir[File.join(File.dirname(__FILE__), "thing", "*.rb")].each do |file|
+        require(file)
+      end
+
+      # Check for equality.
+      # @param other The other object.
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(Thing) && fullname == other.fullname
+      end
+
+      # @return [String] The fullname of the thing.
+      def fullname
+        self[:name] || "#{kind}_#{id}"
+      end
+
+      private
+
+      def response_merge!(meth, path, params = {})
+        body = client.send(meth, path, params).body
+        deep_merge!(body[:data])
+      end
+    end
+  end
+end

data/lib/redd/objects/thing/editable.rb

@@ -0,0 +1,22 @@
+module Redd
+  module Objects
+    class Thing
+      # Things that can be edited and deleted.
+      module Editable
+        # Edit a thing.
+        # @param text [String] The new text.
+        # @return [Thing] The edited thing.
+        def edit(text)
+          post("/api/editusertext", thing_id: fullname, text: text)
+          self[(self.is_a?(Submission) ? :selftext : :body)] = text
+          self
+        end
+
+        # Delete the thing
+        def delete!
+          post("/api/del", id: fullname)
+        end
+      end
+    end
+  end
+end

data/lib/redd/objects/thing/hideable.rb

@@ -0,0 +1,18 @@
+module Redd
+  module Objects
+    class Thing
+      # Things that can be hidden from the user.
+      module Hideable
+        # Hide a link from the user.
+        def hide
+          post("/api/hide", id: fullname)
+        end
+
+        # Unhide a previously hidden link.
+        def unhide
+          post("/api/unhide", id: fullname)
+        end
+      end
+    end
+  end
+end

data/lib/redd/objects/thing/inboxable.rb

@@ -0,0 +1,25 @@
+module Redd
+  module Objects
+    class Thing
+      # Things that can be sent to a user's inbox.
+      module Inboxable
+        # Mark this thing as read.
+        def mark_as_read
+          post("/api/read_message", id: fullname)
+        end
+
+        # Mark one or more messages as unread.
+        def mark_as_unread
+          post("/api/unread_message", id: fullname)
+        end
+
+        # Reply to the thing.
+        # @param text [String] The text to comment.
+        # @return [Objects::Comment, Objects::PrivateMessage] The reply.
+        def reply(text)
+          client.add_comment(self, text)
+        end
+      end
+    end
+  end
+end

data/lib/redd/objects/thing/messageable.rb

@@ -0,0 +1,34 @@
+module Redd
+  module Objects
+    class Thing
+      # Things that can be sent a message.
+      module Messageable
+        # Compose a message to a person or the moderators of a subreddit.
+        #
+        # @param [String] subject The subject of the message.
+        # @param [String] text The message text.
+        # @param [String] from_sr The subreddit to send the message on behalf
+        #   of or nil if from the user.
+        # @param [String] captcha A possible captcha result to send if one
+        #   is required.
+        # @param [String] identifier The identifier for the captcha if one
+        #   is required.
+        def send_message(
+          subject, text, from_sr = nil, captcha = nil, identifier = nil
+        )
+          params = {subject: subject, text: text}
+          params << {captcha: captcha, iden: identifier} if captcha
+          params[:from_sr] = client.property(from_sr, :display_name) if from_sr
+          params[:to] =
+            if respond_to?(:display_name)
+              "/r/#{self[:display_name]}"
+            else
+              self[:name]
+            end
+
+          post("/api/compose", params)
+        end
+      end
+    end
+  end
+end

data/lib/redd/objects/thing/moderatable.rb

@@ -0,0 +1,43 @@
+module Redd
+  module Objects
+    class Thing
+      # Things that a moderator can manage.
+      module Moderatable
+        # Approve a submission.
+        def approve
+          post("/api/approve", id: fullname)
+        end
+
+        # Remove a submission.
+        # @param [Boolean] spam Whether or not this item is removed due to it
+        #   being spam.
+        def remove(spam = false)
+          post("/api/remove", id: fullname, spam: spam)
+        end
+
+        # Distinguish a link or comment with a sigil to show that it has
+        # been created by a moderator.
+        # @param [:yes, :no, :admin, :special] how How to distinguish the
+        #   thing.
+        def distinguish(how = :yes)
+          post("/api/distinguish", id: fullname, how: how)
+        end
+
+        # Remove the sigil that shows a thing was created by a moderator.
+        def undistinguish
+          distinguish(:no)
+        end
+
+        # Stop getting any moderator-related reports on the thing.
+        def ignore_reports
+          post("/api/ignore_reports", id: fullname)
+        end
+
+        # Start getting moderator-related reports on the thing again.
+        def unignore_reports
+          post("/api/unignore_reports", id: fullname)
+        end
+      end
+    end
+  end
+end

data/lib/redd/objects/thing/refreshable.rb

@@ -0,0 +1,14 @@
+module Redd
+  module Objects
+    class Thing
+      # Things that can be refreshed with the current data.
+      module Refreshable
+        # Refresh the thing.
+        def refresh!
+          body = get("/api/info", id: fullname).body[:data][:children][0]
+          deep_merge!(body[:data])
+        end
+      end
+    end
+  end
+end

data/lib/redd/objects/thing/saveable.rb

@@ -0,0 +1,21 @@
+module Redd
+  module Objects
+    class Thing
+      # Things that can be saved to a user's account.
+      module Saveable
+        # Save a link or comment (if gilded) to the user's account.
+        # @param [String] category A category to save to (if gilded).
+        def save(category = nil)
+          params = {id: fullname}
+          params << {category: category} if category
+          post("/api/save", params)
+        end
+
+        # Remove the link or comment from the user's saved links.
+        def unsave
+          post("/api/unsave", id: fullname)
+        end
+      end
+    end
+  end
+end

data/lib/redd/objects/thing/votable.rb

@@ -0,0 +1,33 @@
+module Redd
+  module Objects
+    class Thing
+      # Things that can be voted upon.
+      module Votable
+        # Upvote the thing.
+        def upvote
+          vote(1)
+        end
+
+        # Downvote the thing.
+        def downvote
+          vote(-1)
+        end
+
+        # Remove your vote on the thing.
+        def clear_vote
+          vote(0)
+        end
+        alias_method :unvote, :clear_vote
+
+        private
+
+        # Send a vote.
+        # @param [-1, 0, 1] direction The direction to vote in.
+        def vote(direction)
+          post("/api/vote", id: fullname, dir: direction)
+          self[:ups] += direction
+        end
+      end
+    end
+  end
+end

data/lib/redd/objects/user.rb

@@ -0,0 +1,52 @@
+require_relative "thing"
+
+module Redd
+  module Objects
+    # The model for a reddit user
+    class User < Thing
+      include Thing::Messageable
+
+      # @!method get_overview(**params)
+      # @!method get_submitted(**params)
+      # @!method get_comments(**params)
+      # @!method get_liked(**params)
+      # @!method get_disliked(**params)
+      # @!method get_hidden(**params)
+      # @!method get_saved(**params)
+      # @!method get_gilded(**params)
+      #
+      # Get the appropriate listing.
+      # @option params [String] :after Return results after the given
+      #   fullname.
+      # @option params [String] :before Return results before the given
+      #   fullname.
+      # @option params [Integer] :count The number of items already seen
+      #   in the listing.
+      # @option params [1..100] :limit The maximum number of things to
+      #   return.
+      # @option params [:hot, :new, :top, :controversial] :sort The type of
+      #   sort to use.
+      # @option params [:hour, :day, :week, :month, :year, :all] :t The
+      #   time period to consider when sorting.
+      # @option params [:given] :show For {#get_gilded}, whether to show the
+      #   gildings given.
+      # @note The option :t only applies to the top and controversial sorts.
+      # @return [Listing<Submission>]
+      %w(
+        overview submitted comments liked disliked hidden saved gilded
+      ).each do |type|
+        define_method :"get_#{type}" do |**params|
+          client.request_object(
+            :get, "/user/#{name}/#{type}.json",
+          )
+        end
+      end
+
+      # Get posts that the user has gilded.
+      # @see #get_gilded
+      def get_gildings_given(**params)
+        get_gilded(**params.merge(show: "given"))
+      end
+    end
+  end
+end