redd 0.7.10 → 0.8.0.pre.1

data/lib/redd/models/access.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'basic_model'
+
+module Redd
+  module Models
+    # Models access_token and related keys.
+    class Access < BasicModel
+      def expired?(grace_period = 60)
+        Time.now > @created_at + (get_attribute(:expires_in) - grace_period)
+      end
+
+      private
+
+      def after_initialize
+        @created_at = Time.now
+      end
+    end
+  end
+end

data/lib/redd/models/basic_model.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Redd
+  module Models
+    # The base class for all models.
+    class BasicModel
+      class << self
+        # @abstract Create an instance from a partial hash containing an id. The difference between
+        # this and {#initialize} is that from_response is supposed to know how to build the whole
+        # response from the partial.
+        # @param client [APIClient] the api client to initialize the object with
+        # @param hash [Hash] a partial hash
+        # @return [BasicModel]
+        def from_response(client, hash)
+          new(client, hash)
+        end
+
+        # @abstract Create an instance from a value.
+        # @param _client [APIClient] the api client to initialize the object with
+        # @param _value [Object] the object to coerce
+        # @return [BasicModel]
+        def from_id(_client, _value)
+          # TODO: abstract this out?
+          raise "coercion not implemented for #{name}"
+        end
+
+        # @return [Hash<Symbol, #from_id>] a mapping of keys to models
+        def coerced_attributes
+          @coerced_attributes ||= {}
+        end
+
+        # Mark an attribute to coerce.
+        # @param name [Symbol] the attribute to coerce
+        # @param model [#from_id, nil] a model to coerce it to
+        def coerce_attribute(name, model = nil)
+          coerced_attributes[name] = model
+        end
+      end
+
+      # @return [APIClient] the client the model was initialized with
+      attr_reader :client
+
+      # Create a non-lazily initialized class.
+      # @param client [APIClient] the client that the model uses to make requests
+      # @param attributes [Hash] the class's attributes
+      def initialize(client, attributes = {})
+        @client = client
+        @attributes = attributes
+        @to_coerce = self.class.coerced_attributes.keys
+        after_initialize
+      end
+
+      # @return [Hash] a Hash representation of the object
+      def to_h
+        coerce_all_attributes
+        @attributes
+      end
+
+      # Checks whether an attribute is supported by method_missing.
+      # @param method_name [Symbol] the method name or attribute to check
+      # @param include_private [Boolean] whether to also include private methods
+      # @return [Boolean] whether the method is handled by method_missing
+      def respond_to_missing?(method_name, include_private = false)
+        attribute?(method_name) || attribute?(depredicate(method_name)) || super
+      end
+
+      # Return an attribute or raise a NoMethodError if it doesn't exist.
+      # @param method_name [Symbol] the name of the attribute
+      # @return [Object] the result of the attribute check
+      def method_missing(method_name, *args, &block)
+        return get_attribute(method_name) if attribute?(method_name)
+        return get_attribute(depredicate(method_name)) if attribute?(depredicate(method_name))
+        super
+      end
+
+      private
+
+      # @abstract Lets us plug in custom code without making a mess
+      def after_initialize; end
+
+      # Coerces an attribute into a class using the {.from_id} method.
+      # @param attribute [Symbol] the attribute to coerce
+      def coerce_attribute(attribute)
+        return unless @to_coerce.include?(attribute) && @attributes.include?(attribute)
+        klass = self.class.coerced_attributes.fetch(attribute)
+        @attributes[attribute] =
+          if klass.nil?
+            @client.unmarshal(@attributes[attribute])
+          else
+            klass.from_id(@client, @attributes[attribute])
+          end
+        @to_coerce.delete(attribute)
+      end
+
+      # Coerce every attribute that can be coerced.
+      def coerce_all_attributes
+        @to_coerce.each { |a| coerce_attribute(a) }
+      end
+
+      # Remove a trailing '?' from a symbol name.
+      # @param method_name [Symbol] the symbol to "depredicate"
+      # @return [Symbol] the symbol but with the '?' removed
+      def depredicate(method_name)
+        method_name.to_s.chomp('?').to_sym
+      end
+
+      # Get an attribute, raising KeyError if not present.
+      # @param name [Symbol] the attribute to check and get
+      # @return [Object] the value of the attribute
+      def get_attribute(name)
+        # Coerce the attribute if it exists and needs to be coerced.
+        coerce_attribute(name) if @to_coerce.include?(name) && @attributes.key?(name)
+        # Fetch the attribute, raising a KeyError if it doesn't exist.
+        @attributes.fetch(name)
+      end
+
+      # @param name [Symbol] the name of the attribute to check
+      # @return [Boolean] whether the attribute exists
+      def attribute?(name)
+        @attributes.key?(name)
+      end
+    end
+  end
+end

data/lib/redd/models/comment.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'lazy_model'
+require_relative 'inboxable'
+require_relative 'moderatable'
+require_relative 'postable'
+require_relative 'replyable'
+
+require_relative 'listing'
+require_relative 'subreddit'
+require_relative 'user'
+
+module Redd
+  module Models
+    # A comment.
+    class Comment < LazyModel
+      include Inboxable
+      include Moderatable
+      include Postable
+      include Replyable
+
+      coerce_attribute :replies
+      coerce_attribute :author, User
+      coerce_attribute :subreddit, Subreddit
+
+      # Make a Comment from its id.
+      # @option hash [String] :name the comment's fullname (e.g. t1_abc123)
+      # @option hash [String] :id the comment's id (e.g. abc123)
+      # @return [Comment]
+      def self.from_response(client, hash)
+        # Ensure we have the comment's id.
+        id = hash.fetch(:id, hash.fetch(:name).tr('t1_', ''))
+
+        # If we have the link_id, we can load the listing with replies.
+        if hash.key?(:link_id)
+          link_id = hash[:link_id].tr('t3_', '')
+          return new(client, hash) do |c|
+            # The second half contains a single-item listing containing the comment
+            c.get("/comments/#{link_id}/_/#{id}").body[1][:data][:children][0][:data]
+          end
+        end
+
+        # We can only load the comment in isolation if we don't have the link_id.
+        new(client, hash) do |c|
+          # Returns a single-item listing containing the comment
+          c.get('/api/info', id: "t1_#{id}").body[:data][:children][0][:data]
+        end
+      end
+    end
+  end
+end

data/lib/redd/models/front_page.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative 'basic_model'
+require_relative '../utilities/stream'
+
+module Redd
+  module Models
+    # The front page.
+    # FIXME: deal with serious code duplication from Subreddit
+    class FrontPage < BasicModel
+      # @return [Array<String>] reddit's base wiki pages
+      def wiki_pages
+        @client.get('/wiki/pages').body[:data]
+      end
+
+      # Get a wiki page by its title.
+      # @param title [String] the page's title
+      # @return [WikiPage]
+      def wiki_page(title)
+        WikiPage.from_response(@client, title: title)
+      end
+
+      # Get the appropriate listing.
+      # @param sort [:hot, :new, :top, :controversial, :comments, :rising] the type of 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 the number of items already seen in the listing
+      # @option params [1..100] :limit the maximum number of things to return
+      # @option params [:hour, :day, :week, :month, :year, :all] :time the time period to consider
+      #   when sorting.
+      #
+      # @note The option :time only applies to the top and controversial sorts.
+      # @return [Listing<Submission>]
+      def listing(sort, **params)
+        params[:t] = params.delete(:time) if params.key?(:time)
+        @client.model(:get, "/#{sort}.json", params)
+      end
+
+      # @!method hot(**params)
+      # @!method new(**params)
+      # @!method top(**params)
+      # @!method controversial(**params)
+      # @!method comments(**params)
+      # @!method rising(**params)
+      #
+      # @see #listing
+      %i(hot new top controversial comments rising).each do |sort|
+        define_method(sort) { |**params| listing(sort, **params) }
+      end
+
+      # Stream newly submitted posts.
+      def post_stream(**params, &block)
+        params[:limit] ||= 100
+        stream = Utilities::Stream.new do |before|
+          listing(:new, params.merge(before: before))
+        end
+        block_given? ? stream.stream(&block) : stream.enum_for(:stream)
+      end
+
+      # Stream newly submitted comments.
+      def comment_stream(**params, &block)
+        params[:limit] ||= 100
+        stream = Utilities::Stream.new do |before|
+          listing(:comments, params.merge(before: before))
+        end
+        block_given? ? stream.stream(&block) : stream.enum_for(:stream)
+      end
+    end
+  end
+end

data/lib/redd/models/inboxable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Redd
+  module Models
+    # Things that can be sent to a user's inbox.
+    module Inboxable
+      # Block the user that sent this item.
+      def block
+        @client.post('/api/block', id: get_attribute(:fullname))
+      end
+
+      # Mark this thing as read.
+      def mark_as_read
+        @client.post('/api/read_message', id: get_attribute(:fullname))
+      end
+
+      # Mark one or more messages as unread.
+      def mark_as_unread
+        @client.post('/api/unread_message', id: get_attribute(:fullname))
+      end
+    end
+  end
+end

data/lib/redd/models/lazy_model.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'basic_model'
+
+module Redd
+  module Models
+    # The base class for lazily-initializable models.
+    class LazyModel < BasicModel
+      # Create a lazily initialized class.
+      # @param client [APIClient] the client that the model uses to make requests
+      # @param base_attributes [Hash] the already-known attributes that do not need to be looked up
+      # @yield [client] the model's client
+      # @yieldparam client [APIClient]
+      # @yieldreturn [Hash] the response of "initializing" the lazy model
+      def initialize(client, base_attributes = {}, &block)
+        super(client, base_attributes)
+        @lazy_loader = block
+        @definitely_fully_loaded = false
+      end
+
+      # @return [Boolean] whether the model can be to be lazily initialized
+      def lazy?
+        !@lazy_loader.nil?
+      end
+
+      # Force the object to make a request to reddit.
+      # @return [self]
+      def force_load
+        return unless lazy?
+        @attributes.merge!(@lazy_loader.call(@client))
+        @definitely_fully_loaded = true
+        self
+      end
+      alias reload force_load
+
+      # Convert the object to a hash, making a request to fetch additional attributes if needed.
+      # @return [Hash]
+      def to_h
+        ensure_fully_loaded
+        super
+      end
+
+      private
+
+      # Make sure the model is loaded at least once.
+      def ensure_fully_loaded
+        force_load if lazy? && !@definitely_fully_loaded
+      end
+
+      # Gets the attribute and loads it if it may be available from the response.
+      def get_attribute(name)
+        ensure_fully_loaded unless @attributes.key?(name)
+        super
+      end
+
+      # Checks whether an attribute exists, loading it first if necessary.
+      def attribute?(name)
+        ensure_fully_loaded unless @attributes.key?(name)
+        super
+      end
+    end
+  end
+end

data/lib/redd/models/listing.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'basic_model'
+
+module Redd
+  module Models
+    # A backward-expading listing of items.
+    # @see Stream
+    class Listing < BasicModel
+      include Enumerable
+
+      # Make a Listing from a basic Hash.
+      # @return [Listing]
+      def self.from_response(client, hash)
+        hash[:children].map! { |el| client.unmarshal(el) }
+        new(client, hash)
+      end
+
+      %i([] each empty? length size).each do |method_name|
+        define_method(method_name) do |*args, &block|
+          get_attribute(:children).public_send(method_name, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/redd/models/messageable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Redd
+  module Models
+    # A model that can be messaged (i.e. Users and Subreddits).
+    module Messageable
+      # Compose a message to a person or the moderators of a subreddit.
+      #
+      # @param to [String] the thing to send the message to (overriden by User and Subreddit)
+      # @param subject [String] the subject of the message
+      # @param text [String] the message text
+      # @param from [Subreddit, nil] the subreddit to send the message on behalf of
+      def send_message(to:, subject:, text:, from: nil)
+        params = { to: to, subject: subject, text: text }
+        params[:from_sr] = from.display_name if from
+        @client.post('/api/compose', params)
+      end
+    end
+  end
+end

data/lib/redd/models/moderatable.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Redd
+  module Models
+    # A model that can be managed by a moderator (i.e. Submissions and Comments).
+    module Moderatable
+      # Approve a submission.
+      def approve
+        @client.post('/api/approve', id: get_attribute(:name))
+      end
+
+      # Remove a submission.
+      # @param spam [Boolean] whether or not this item is removed due to it being spam
+      def remove(spam: false)
+        @client.post('/api/remove', id: get_attribute(:name), spam: spam)
+      end
+
+      # Distinguish a link or comment with a sigil to show that it has
+      # been created by a moderator.
+      # @param how [:yes, :no, :admin, :special] how to distinguish the thing
+      def distinguish(how = :yes)
+        @client.post('/api/distinguish', id: get_attribute(:name), 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
+        @client.post('/api/ignore_reports', id: get_attribute(:name))
+      end
+
+      # Start getting moderator-related reports on the thing again.
+      def unignore_reports
+        @client.post('/api/unignore_reports', id: get_attribute(:name))
+      end
+    end
+  end
+end