redd 0.6.5 → 0.7.0

data/lib/redd/clients/base/read.rb

@@ -0,0 +1,66 @@
+module Redd
+  module Clients
+    class Base
+      # Methods that require the "read" scope
+      module Read
+        # @param [Array<String>] fnames A list of fullnames.
+        # @return [Objects::Listing<Objects::Thing>] A listing of things with
+        #   the fullname.
+        def from_fullname(*fnames)
+          names = fnames.join(",")
+          request_object(:get, "/api/info", id: names)
+        end
+
+        # @param [String] url The url of the thing.
+        # @return [Objects::Thing] The thing.
+        def from_url(url)
+          request_object(:get, "/api/info", url: url).first
+        end
+
+        # @param [String] name The username.
+        # @return [Objects::User] The user.
+        def user_from_name(name)
+          request_object(:get, "/user/#{name}/about.json")
+        end
+
+        # @param [String] name The subreddit's display name.
+        # @return [Objects::Subreddit] The subreddit if found.
+        def subreddit_from_name(name)
+          request_object(:get, "/r/#{name}/about.json")
+        end
+
+        # @!method get_hot(subreddit = nil, **params)
+        # @!method get_new(subreddit = nil, **params)
+        # @!method get_top(subreddit = nil, **params)
+        # @!method get_controversial(subreddit = nil, **params)
+        # @!method get_comments(subreddit = nil, **params)
+        #
+        # Get the appropriate listing.
+        # @param subreddit [Objects::Subreddit, String] The subreddit to query.
+        # @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>]
+        # @todo Move all listing methods into a helper?
+        %w(hot new top controversial comments).each do |sort|
+          define_method :"get_#{sort}" do |subreddit = nil, **params|
+            srname = property(subreddit, :display_name) if subreddit
+            path = "/#{sort}.json"
+            path = path.prepend("/r/#{srname}") if subreddit
+            request_object(:get, path, params)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/redd/clients/base/stream.rb

@@ -0,0 +1,74 @@
+require "set"
+
+module Redd
+  module Clients
+    class Base
+      # Methods that stream delicious content into your bot's lazy mouth.
+      module Stream
+        # A class similar to PRAW's implementation of a BoundedSet.
+        class PRAWBoundedQueueSet < Set
+          def initialize(max, *args, &block)
+            @max = max
+            @queue = []
+            super(*args, &block)
+          end
+
+          # Add an element to the front if it isn't already in the queue.
+          # @param element
+          # @return [PRAWBoundedQueueSet] self
+          def enqueue(element)
+            @queue.push(element) if add?(element)
+            dequeue! if size > @max
+            self
+          end
+          alias_method :enq, :enqueue
+
+          # Add an element to the front if it isn't already in the queue.
+          # @param element
+          # @return [Boolean] Whether the element was added to the queue.
+          def enqueue?(element)
+            added = add?(element)
+            if added
+              @queue.push(element)
+              dequeue if size > @max
+            end
+            added
+          end
+          alias_method :enq?, :enqueue?
+
+          # Remove the last element of the queue.
+          # @return The removed element.
+          def dequeue
+            element = @queue.shift
+            delete(element)
+            element
+          end
+          alias_method :deq, :dequeue
+        end
+
+        # Stream the results of a method call to the given block.
+        # @param [Symbol] meth A method that returns a listing and has a
+        #   keyword parameter named `:before`.
+        # @param [Array] args The arguments supplied to the method.
+        # @param [Hash] kwargs The keyword arguments supplied to the method.
+        # @yield An element of the returned listing.
+        def stream(meth = :get_new, *args, **kwargs)
+          bset = PRAWBoundedQueueSet.new(10)
+          before = ""
+          loop do
+            # Get the latest comments from the subreddit. By the way, this line
+            # is the one where the sleeping/rate-limiting happens.
+            params = kwargs.merge(before: before)
+            listing = send(meth, *args, **params)
+            # Run the loop for each of the item in the listing
+            listing.reverse_each do |thing|
+              yield thing if bset.enqueue?(thing.fullname)
+            end
+            # Set the latest comment.
+            before = listing.first.fullname unless listing.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/redd/clients/base/submit.rb

@@ -0,0 +1,54 @@
+module Redd
+  module Clients
+    class Base
+      # Methods that require the "submit" scope
+      module Submit
+        # Submit a link or a text post to a subreddit.
+        #
+        # @param [Objects::Submission, String] subreddit The subreddit
+        #   to submit to.
+        # @param [String] title The title of the submission.
+        # @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.
+        # @param [String] text The text of the self-post.
+        # @param [String] url The URL of the link.
+        # @param [Boolean] resubmit Whether to post a link to a subreddit
+        #   despite it having been posted there before (you monster).
+        # @param [Boolean] sendreplies Whether to send the replies to your
+        #   inbox.
+        # @return [Objects::Thing] The returned result (url, id and name).
+        def submit(
+          subreddit, title, captcha = nil, identifier = nil, text: nil,
+          url: nil, resubmit: false, sendreplies: true
+        )
+
+          params = {
+            extension: "json", title: title,
+            resubmit: resubmit, sendreplies: sendreplies,
+            sr: property(subreddit, :display_name)
+          }
+
+          params << {captcha: captcha, iden: identifier} if captcha
+          params[:kind], params[:text] = :self, text if text
+          params[:kind], params[:url] = :link, url if url
+
+          response = post("/api/submit", params)
+          Objects::Thing.new(self, response.body[:json][:data])
+        end
+
+        # Add a comment to a link, reply to a comment or reply to a message.
+        # Bit of an all-purpose method, this one.
+        # @param thing [Objects::Submission, Objects::Comment,
+        #   Objects::PrivateMessage] A thing to add a comment to.
+        # @param text [String] The text to comment.
+        # @return [Objects::Comment, Objects::PrivateMessage] The reply.
+        def add_comment(thing, text)
+          response = post("/api/comment", text: text, thing_id: thing.fullname)
+          object_from_body(response.body[:json][:data][:things][0])
+        end
+      end
+    end
+  end
+end

data/lib/redd/clients/base/utilities.rb

@@ -0,0 +1,80 @@
+require_relative "../../objects/base"
+require_relative "../../objects/thing"
+require_relative "../../objects/listing"
+require_relative "../../objects/wiki_page"
+require_relative "../../objects/more_comments"
+require_relative "../../objects/comment"
+require_relative "../../objects/user"
+require_relative "../../objects/submission"
+require_relative "../../objects/private_message"
+require_relative "../../objects/subreddit"
+
+module Redd
+  module Clients
+    class Base
+      # Internal methods that make life easier.
+      # @todo Move this out to Redd::Utils?
+      module Utilities
+        # The kind strings and the objects that should be used for them.
+        OBJECT_KINDS = {
+          "Listing"  => Objects::Listing,
+          "wikipage" => Objects::WikiPage,
+          "more"     => Objects::MoreComments,
+          "t1"       => Objects::Comment,
+          "t2"       => Objects::User,
+          "t3"       => Objects::Submission,
+          "t4"       => Objects::PrivateMessage,
+          "t5"       => Objects::Subreddit
+        }
+
+        # Request and create an object from the response.
+        # @param [Symbol] meth The method to use.
+        # @param [String] path The path to visit.
+        # @param [Hash] params The data to send with the request.
+        # @return [Objects::Base] The object returned from the request.
+        def request_object(meth, path, params = {})
+          body = send(meth, path, params).body
+          object_from_body(body)
+        end
+
+        # Create an object instance with the correct attributes when given a
+        # body.
+        #
+        # @param [Hash] body A JSON hash.
+        # @return [Objects::Thing, Objects::Listing]
+        def object_from_body(body)
+          return body unless body.is_a?(Hash) || body.key?(:kind)
+          object = object_from_kind(body[:kind])
+          flat = flatten_body(body)
+          object.new(self, flat)
+        end
+
+        private
+
+        # Get a given property of a given object.
+        # @param [Objects::Base, String] object The object with the property.
+        # @param [Symbol] property The property to get.
+        def property(object, property)
+          object.respond_to?(property) ? object.send(property) : object.to_s
+        end
+
+        # Take a multilevel body ({kind: "tx", data: {...}}) and flatten it
+        # into something like {kind: "tx", ...}
+        # @param [Hash] body The response body.
+        # @return [Hash] The flattened hash.
+        def flatten_body(body)
+          data = body[:data]
+          data[:kind] = body[:kind]
+          data
+        end
+
+        # @param [String] kind A kind in the format /t[1-5]/.
+        # @return [Objects::Base, Objects::Listing] The appropriate object for
+        #   a given kind.
+        def object_from_kind(kind)
+          OBJECT_KINDS.fetch(kind, Objects::Base)
+        end
+      end
+    end
+  end
+end

data/lib/redd/clients/base/wikiread.rb

@@ -0,0 +1,33 @@
+module Redd
+  module Clients
+    class Base
+      # Methods that require the "wikiread" scope.
+      # @note This method is not limited to {Objects::Subreddit} because there
+      #   are also top-level wiki pages.
+      module Wikiread
+        # Get a list of pages in the subreddit wiki.
+        # @param subreddit [Objects::Subreddit, String] The subreddit to
+        #   look in.
+        # @return [Array<String>] An array of wikipage titles.
+        def get_wikipages(subreddit = nil)
+          path = "/wiki/pages.json"
+          name = property(subreddit, :display_name)
+          path.prepend("/r/#{name}") if subreddit
+          get(path).body[:data]
+        end
+
+        # Get a wiki page.
+        # @param page [String] The title of the wiki page.
+        # @param subreddit [Objects::Subreddit, String] The subreddit to
+        #   look in.
+        # @return [Objects::WikiPage] A wiki page.
+        def wikipage(page, subreddit = nil)
+          path = "/wiki/#{page}.json"
+          name = property(subreddit, :display_name)
+          path.prepend("/r/#{name}") if subreddit
+          request_object(:get, path)
+        end
+      end
+    end
+  end
+end

data/lib/redd/clients/installed.rb

@@ -0,0 +1,55 @@
+require "cgi"
+require_relative "base"
+
+module Redd
+  module Clients
+    # The client for installed apps that can't keep a secret.
+    # It might even work with Rubymotion (fingers crossed).
+    class Installed < Base
+      # @!attribute [r] client_id
+      attr_reader :client_id
+
+      # @!attribute [r] redirect_uri
+      attr_reader :redirect_uri
+
+      # @param [Hash] options The options to create the client with.
+      # @see Redd.it
+      def initialize(client_id, redirect_uri, **options)
+        @client_id = client_id
+        @redirect_uri = redirect_uri
+        super(**options)
+      end
+
+      # @param [String] state A random string to double-check later.
+      # @param [Array<String>] scope The scope to request access to.
+      # @param [:temporary, :permanent] duration
+      # @return [String] The url to redirect the user to.
+      def auth_url(state, scope = ["identity"], duration = :temporary)
+        query = {
+          response_type: "token",
+          client_id: @client_id,
+          redirect_uri: @redirect_uri,
+          state: state,
+          scope: scope.join(","),
+          duration: duration
+        }
+
+        url = URI.join(auth_endpoint, "/api/v1/authorize")
+        url.query = URI.encode_www_form(query)
+        url.to_s
+      end
+
+      # Authorize using the url fragment.
+      # @param [String] fragment The part of the url after the "#".
+      # @return [Access] The access given by reddit.
+      def authorize!(fragment)
+        parsed = CGI.parse(fragment)
+        @access = Access.new(
+          access_token: parsed[:access_token].first,
+          expires_in: parsed[:expires_in].first,
+          scope: parsed[:scope]
+        )
+      end
+    end
+  end
+end

data/lib/redd/clients/script.rb

@@ -0,0 +1,37 @@
+require_relative "base"
+
+module Redd
+  module Clients
+    # The client for an account you own (e.g. bots).
+    class Script < Base
+      # @!attribute [r] client_id
+      attr_reader :client_id
+
+      # @!attribute [r] username
+      attr_reader :username
+
+      # @param [Hash] options The options to create the client with.
+      # @see Redd.it
+      def initialize(client_id, secret, username, password, **options)
+        @client_id = client_id
+        @secret = secret
+        @username = username
+        @password = password
+        super(**options)
+      end
+
+      # Authorize using the given data.
+      # @return [Access] The access given by reddit.
+      def authorize!
+        response = auth_connection.post(
+          "/api/v1/access_token",
+          grant_type: "password",
+          username: @username,
+          password: @password
+        )
+
+        @access = Access.new(response.body)
+      end
+    end
+  end
+end

data/lib/redd/clients/userless.rb

@@ -0,0 +1,31 @@
+require_relative "base"
+
+module Redd
+  module Clients
+    # The client that doesn't need a user to function.
+    # @note Of course, that means many editing methods throw an error.
+    class Userless < Base
+      # @!attribute [r] client_id
+      attr_reader :client_id
+
+      # @param [Hash] options The options to create the client with.
+      # @see Redd.it
+      def initialize(client_id, secret, **options)
+        @client_id = client_id
+        @secret = secret
+        super(**options)
+      end
+
+      # Authorize using the given data.
+      # @return [Access] The access given by reddit.
+      def authorize!
+        response = auth_connection.post(
+          "/api/v1/access_token",
+          grant_type: "client_credentials"
+        )
+
+        @access = Access.new(response.body)
+      end
+    end
+  end
+end

data/lib/redd/clients/web.rb

@@ -0,0 +1,57 @@
+require "uri"
+require_relative "base"
+
+module Redd
+  module Clients
+    # The client for a web-based flow (e.g. "login with reddit")
+    class Web < Base
+      # @!attribute [r] client_id
+      attr_reader :client_id
+
+      # @!attribute [r] redirect_uri
+      attr_reader :redirect_uri
+
+      # @param [Hash] options The options to create the client with.
+      # @see Redd.it
+      def initialize(client_id, secret, redirect_uri, **options)
+        @client_id = client_id
+        @secret = secret
+        @redirect_uri = redirect_uri
+        super(**options)
+      end
+
+      # @param [String] state A random string to double-check later.
+      # @param [Array<String>] scope The scope to request access to.
+      # @param [:temporary, :permanent] duration
+      # @return [String] The url to redirect the user to.
+      def auth_url(state, scope = ["identity"], duration = :temporary)
+        query = {
+          response_type: "code",
+          client_id: @client_id,
+          redirect_uri: @redirect_uri,
+          state: state,
+          scope: scope.join(","),
+          duration: duration
+        }
+
+        url = URI.join(auth_endpoint, "/api/v1/authorize")
+        url.query = URI.encode_www_form(query)
+        url.to_s
+      end
+
+      # Authorize using the code given.
+      # @param [String] code The code from the get params.
+      # @return [Access] The access given by reddit.
+      def authorize!(code)
+        response = auth_connection.post(
+          "/api/v1/access_token",
+          grant_type: "authorization_code",
+          code: code,
+          redirect_uri: @redirect_uri
+        )
+
+        @access = Access.new(response.body)
+      end
+    end
+  end
+end