drape 1.0.0.beta1

data/lib/drape/decorated_association.rb

@@ -0,0 +1,33 @@
+module Drape
+  # @private
+  class DecoratedAssociation
+    def initialize(owner, association, options)
+      options.assert_valid_keys(:with, :scope, :context)
+
+      @owner = owner
+      @association = association
+
+      @scope = options[:scope]
+
+      decorator_class = options[:with]
+      context = options.fetch(:context, -> (inner_context) { inner_context })
+      @factory = Drape::Factory.new(with: decorator_class, context: context)
+    end
+
+    def call
+      decorate unless defined?(@decorated)
+      @decorated
+    end
+
+    private
+
+    attr_reader :factory, :owner, :association, :scope
+
+    def decorate
+      associated = owner.object.send(association)
+      associated = associated.send(scope) if scope
+
+      @decorated = factory.decorate(associated, context_args: owner.context)
+    end
+  end
+end

data/lib/drape/decorates_assigned.rb

@@ -0,0 +1,44 @@
+module Drape
+  module DecoratesAssigned
+    # @overload decorates_assigned(*variables, options = {})
+    #   Defines a helper method to access decorated instance variables.
+    #
+    #   @example
+    #     # app/controllers/articles_controller.rb
+    #     class ArticlesController < ApplicationController
+    #       decorates_assigned :article
+    #
+    #       def show
+    #         @article = Article.find(params[:id])
+    #       end
+    #     end
+    #
+    #     # app/views/articles/show.html.erb
+    #     <%= article.decorated_title %>
+    #
+    #   @param [Symbols*] variables
+    #     names of the instance variables to decorate (without the `@`).
+    #   @param [Hash] options
+    #   @option options [Decorator, CollectionDecorator] :with (nil)
+    #     decorator class to use. If nil, it is inferred from the instance
+    #     variable.
+    #   @option options [Hash, #call] :context
+    #     extra data to be stored in the decorator. If a Proc is given, it will
+    #     be passed the controller and should return a new context hash.
+    def decorates_assigned(*variables)
+      factory = Drape::Factory.new(variables.extract_options!)
+
+      variables.each do |variable|
+        undecorated = "@#{variable}"
+        decorated = "@decorated_#{variable}"
+
+        define_method variable do
+          return instance_variable_get(decorated) if instance_variable_defined?(decorated)
+          instance_variable_set decorated, factory.decorate(instance_variable_get(undecorated), context_args: self)
+        end
+
+        helper_method variable
+      end
+    end
+  end
+end

data/lib/drape/decorator.rb

@@ -0,0 +1,282 @@
+module Drape
+  class Decorator
+    include Drape::ViewHelpers
+    extend Drape::Delegation
+
+    include ActiveModel::Serialization
+    include ActiveModel::Serializers::JSON
+    include ActiveModel::Serializers::Xml
+
+    # @return the object being decorated.
+    attr_reader :object
+    alias model object
+    alias source object # TODO: deprecate this
+    alias to_source object # TODO: deprecate this
+
+    # @return [Hash] extra data to be used in user-defined methods.
+    attr_accessor :context
+
+    # Wraps an object in a new instance of the decorator.
+    #
+    # Decorators may be applied to other decorators. However, applying a
+    # decorator to an instance of itself will create a decorator with the same
+    # source as the original, rather than redecorating the other instance.
+    #
+    # @param [Object] object
+    #   object to decorate.
+    # @option options [Hash] :context ({})
+    #   extra data to be stored in the decorator and used in user-defined
+    #   methods.
+    def initialize(object, options = {})
+      options.assert_valid_keys(:context)
+      @object = object
+      @context = options.fetch(:context, {})
+      handle_multiple_decoration(options) if object.instance_of?(self.class)
+    end
+
+    class << self
+      alias decorate new
+    end
+
+    # Automatically delegates instance methods to the source object. Class
+    # methods will be delegated to the {object_class}, if it is set.
+    #
+    # @return [void]
+    def self.delegate_all
+      include Drape::AutomaticDelegation
+    end
+
+    # Sets the source class corresponding to the decorator class.
+    #
+    # @note This is only necessary if you wish to proxy class methods to the
+    #   source (including when using {decorates_finders}), and the source class
+    #   cannot be inferred from the decorator class (e.g. `ProductDecorator`
+    #   maps to `Product`).
+    # @param [String, Symbol, Class] object_class
+    #   source class (or class name) that corresponds to this decorator.
+    # @return [void]
+    def self.decorates(object_class)
+      @object_class = object_class.to_s.camelize.constantize
+      alias_object_to_object_class_name
+    end
+
+    # Returns the source class corresponding to the decorator class, as set by
+    # {decorates}, or as inferred from the decorator class name (e.g.
+    # `ProductDecorator` maps to `Product`).
+    #
+    # @return [Class] the source class that corresponds to this decorator.
+    def self.object_class
+      @object_class ||= inferred_object_class
+    end
+
+    # Checks whether this decorator class has a corresponding {object_class}.
+    def self.object_class?
+      object_class
+    rescue Drape::UninferrableSourceError
+      false
+    end
+
+    class << self # TODO deprecate this
+      alias source_class object_class
+      alias source_class? object_class?
+    end
+
+    # Automatically decorates ActiveRecord finder methods, so that you can use
+    # `ProductDecorator.find(id)` instead of
+    # `ProductDecorator.decorate(Product.find(id))`.
+    #
+    # Finder methods are applied to the {object_class}.
+    #
+    # @return [void]
+    def self.decorates_finders
+      extend Drape::Finders
+    end
+
+    # Automatically decorate an association.
+    #
+    # @param [Symbol] association
+    #   name of the association to decorate (e.g. `:products`).
+    # @option options [Class] :with
+    #   the decorator to apply to the association.
+    # @option options [Symbol] :scope
+    #   a scope to apply when fetching the association.
+    # @option options [Hash, #call] :context
+    #   extra data to be stored in the associated decorator. If omitted, the
+    #   associated decorator's context will be the same as the parent
+    #   decorator's. If a Proc is given, it will be called with the parent's
+    #   context and should return a new context hash for the association.
+    # @return [void]
+    def self.decorates_association(association, options = {})
+      options.assert_valid_keys(:with, :scope, :context)
+      define_method(association) do
+        decorated_associations[association] ||= Drape::DecoratedAssociation.new(self, association, options)
+        decorated_associations[association].call
+      end
+    end
+
+    # @overload decorates_associations(*associations, options = {})
+    #   Automatically decorate multiple associations.
+    #   @param [Symbols*] associations
+    #     names of the associations to decorate.
+    #   @param [Hash] options
+    #     see {decorates_association}.
+    #   @return [void]
+    def self.decorates_associations(*associations)
+      options = associations.extract_options!
+      associations.each do |association|
+        decorates_association(association, options)
+      end
+    end
+
+    # Decorates a collection of objects. The class of the collection decorator
+    # is inferred from the decorator class if possible (e.g. `ProductDecorator`
+    # maps to `ProductsDecorator`), but otherwise defaults to
+    # {Drape::CollectionDecorator}.
+    #
+    # @param [Object] object
+    #   collection to decorate.
+    # @option options [Class, nil] :with (self)
+    #   the decorator class used to decorate each item. When `nil`, it is
+    #   inferred from each item.
+    # @option options [Hash] :context
+    #   extra data to be stored in the collection decorator.
+    def self.decorate_collection(object, options = {})
+      options.assert_valid_keys(:with, :context)
+      collection_decorator_class.new(object, options.reverse_merge(with: self))
+    end
+
+    # @return [Array<Class>] the list of decorators that have been applied to
+    #   the object.
+    def applied_decorators
+      chain = object.respond_to?(:applied_decorators) ? object.applied_decorators : []
+      chain << self.class
+    end
+
+    # Checks if a given decorator has been applied to the object.
+    #
+    # @param [Class] decorator_class
+    def decorated_with?(decorator_class)
+      applied_decorators.include?(decorator_class)
+    end
+
+    # Checks if this object is decorated.
+    #
+    # @return [true]
+    def decorated?
+      true
+    end
+
+    # Compares the source object with a possibly-decorated object.
+    #
+    # @return [Boolean]
+    def ==(other)
+      Drape::Decoratable::Equality.test(object, other)
+    end
+
+    # Delegates equality to :== as expected
+    #
+    # @return [Boolean]
+    def eql?(other)
+      self == other
+    end
+
+    # Returns a unique hash for a decorated object based on
+    # the decorator class and the object being decorated.
+    #
+    # @return [Fixnum]
+    def hash
+      self.class.hash ^ object.hash
+    end
+
+    # Checks if `self.kind_of?(klass)` or `object.kind_of?(klass)`
+    #
+    # @param [Class] klass
+    def kind_of?(klass)
+      super || object.is_a?(klass)
+    end
+    alias is_a? kind_of?
+
+    # Checks if `self.instance_of?(klass)` or `object.instance_of?(klass)`
+    #
+    # @param [Class] klass
+    def instance_of?(klass)
+      super || object.instance_of?(klass)
+    end
+
+    delegate :to_s
+
+    # In case object is nil
+    delegate :present?, :blank?
+
+    # ActiveModel compatibility
+    # @private
+    def to_model
+      self
+    end
+
+    # @return [Hash] the object's attributes, sliced to only include those
+    # implemented by the decorator.
+    def attributes
+      object.attributes.select { |attribute, _| respond_to?(attribute) }
+    end
+
+    # ActiveModel compatibility
+    delegate :to_param, :to_partial_path
+
+    # ActiveModel compatibility
+    singleton_class.delegate :model_name, to: :object_class
+
+    # @return [Class] the class created by {decorate_collection}.
+    def self.collection_decorator_class
+      name = collection_decorator_name
+      name.constantize
+    rescue NameError => error
+      raise if name && !error.missing_name?(name)
+      Drape::CollectionDecorator
+    end
+
+    def self.inherited(subclass)
+      subclass.alias_object_to_object_class_name
+      super
+    end
+
+    def self.alias_object_to_object_class_name
+      alias_method object_class.name.underscore, :object if object_class?
+    end
+
+    def self.object_class_name
+      raise NameError if name.nil? || name.demodulize !~ /.+Decorator$/
+      name.chomp('Decorator')
+    end
+
+    def self.inferred_object_class
+      name = object_class_name
+      name.constantize
+    rescue NameError => error
+      raise if name && !error.missing_name?(name)
+      raise Drape::UninferrableSourceError, self
+    end
+
+    def self.collection_decorator_name
+      plural = object_class_name.pluralize
+      raise NameError if plural == object_class_name
+      "#{plural}Decorator"
+    end
+
+    private
+
+    def handle_multiple_decoration(options)
+      if object.applied_decorators.last == self.class
+        @context = object.context unless options.key?(:context)
+        @object = object.object
+      else
+        warn "Reapplying #{self.class} decorator to target that is already decorated with it. " +
+             "Call stack:\n#{caller(1).join("\n")}"
+      end
+    end
+
+    def decorated_associations
+      @decorated_associations ||= {}
+    end
+  end
+end

data/lib/drape/delegation.rb

@@ -0,0 +1,13 @@
+module Drape
+  module Delegation
+    # @overload delegate(*methods, options = {})
+    #   Overrides {http://api.rubyonrails.org/classes/Module.html#method-i-delegate Module.delegate}
+    #   to make `:object` the default delegation target.
+    #
+    #   @return [void]
+    def delegate(*methods)
+      options = methods.extract_options!
+      super(*methods, options.reverse_merge(to: :object))
+    end
+  end
+end

data/lib/drape/factory.rb

@@ -0,0 +1,91 @@
+module Drape
+  class Factory
+    # Creates a decorator factory.
+    #
+    # @option options [Decorator, CollectionDecorator] :with (nil)
+    #   decorator class to use. If nil, it is inferred from the object
+    #   passed to {#decorate}.
+    # @option options [Hash, #call] context
+    #   extra data to be stored in created decorators. If a proc is given, it
+    #   will be called each time {#decorate} is called and its return value
+    #   will be used as the context.
+    def initialize(options = {})
+      options.assert_valid_keys(:with, :context)
+      @decorator_class = options.delete(:with)
+      @default_options = options
+    end
+
+    # Decorates an object, inferring whether to create a singular or collection
+    # decorator from the type of object passed.
+    #
+    # @param [Object] object
+    #   object to decorate.
+    # @option options [Hash] context
+    #   extra data to be stored in the decorator. Overrides any context passed
+    #   to the constructor.
+    # @option options [Object, Array] context_args (nil)
+    #   argument(s) to be passed to the context proc.
+    # @return [Decorator, CollectionDecorator] the decorated object.
+    def decorate(object, options = {})
+      return nil if object.nil?
+      Worker.new(decorator_class, object).call(options.reverse_merge(default_options))
+    end
+
+    private
+
+    attr_reader :decorator_class, :default_options
+
+    # @private
+    class Worker
+      def initialize(decorator_class, object)
+        @decorator_class = decorator_class
+        @object = object
+      end
+
+      def call(options)
+        update_context options
+        decorator.call(object, options)
+      end
+
+      def decorator
+        return decorator_method(decorator_class) if decorator_class
+        return object_decorator if decoratable?
+        return decorator_method(Drape::CollectionDecorator) if collection?
+        raise Drape::UninferrableDecoratorError, object.class
+      end
+
+      private
+
+      attr_reader :decorator_class, :object
+
+      def object_decorator
+        if collection?
+          ->(object, options) { object.decorator_class.decorate_collection(object, options.reverse_merge(with: nil)) }
+        else
+          ->(object, options) { object.decorate(options) }
+        end
+      end
+
+      def decorator_method(klass)
+        if collection? && klass.respond_to?(:decorate_collection)
+          klass.method(:decorate_collection)
+        else
+          klass.method(:decorate)
+        end
+      end
+
+      def collection?
+        object.respond_to?(:first) && !object.is_a?(Struct)
+      end
+
+      def decoratable?
+        object.respond_to?(:decorate)
+      end
+
+      def update_context(options)
+        args = options.delete(:context_args)
+        options[:context] = options[:context].call(*Array.wrap(args)) if options[:context].respond_to?(:call)
+      end
+    end
+  end
+end