rom-mapper 0.1.1 → 0.2.0

data/lib/rom/mapper/dsl.rb

@@ -0,0 +1,120 @@
+require 'rom/support/class_macros'
+require 'rom/mapper/attribute_dsl'
+
+module ROM
+  class Mapper
+    # Mapper class-level DSL including Attribute DSL and Model DSL
+    module DSL
+      # Extend mapper class with macros and DSL methods
+      #
+      # @api private
+      def self.included(klass)
+        klass.extend(ClassMacros)
+        klass.extend(ClassMethods)
+      end
+
+      # Class methods for all mappers
+      #
+      # @private
+      module ClassMethods
+        # Set base ivars for the mapper class
+        #
+        # @api private
+        def inherited(klass)
+          super
+
+          klass.instance_variable_set('@attributes', nil)
+          klass.instance_variable_set('@header', nil)
+          klass.instance_variable_set('@dsl', nil)
+        end
+
+        # include a registered plugin in this mapper
+        #
+        # @param [Symbol] plugin
+        # @param [Hash] options
+        # @option options [Symbol] :adapter (:default) first adapter to check for plugin
+        #
+        # @api public
+        def use(plugin, options = {})
+          adapter = options.fetch(:adapter, :default)
+
+          ROM.plugin_registry.mappers.fetch(plugin, adapter).apply_to(self)
+        end
+
+        # Return base_relation used for creating mapper registry
+        #
+        # This is used to "gather" mappers under same root name
+        #
+        # @api private
+        def base_relation
+          if superclass.relation
+            superclass.relation
+          else
+            relation
+          end
+        end
+
+        # Return header of the mapper
+        #
+        # This is memoized so mutating mapper class won't have an effect wrt
+        # header after it was initialized for the first time.
+        #
+        # TODO: freezing mapper class here is probably a good idea
+        #
+        # @api private
+        def header
+          @header ||= dsl.header
+        end
+
+        # @api private
+        def respond_to_missing?(name, _include_private = false)
+          dsl.respond_to?(name) || super
+        end
+
+        private
+
+        # Return default Attribute DSL options based on settings of the mapper
+        # class
+        #
+        # @api private
+        def options
+          { prefix: prefix,
+            prefix_separator: prefix_separator,
+            symbolize_keys: symbolize_keys,
+            reject_keys: reject_keys }
+        end
+
+        # Return default attributes that might have been inherited from the
+        # superclass
+        #
+        # @api private
+        def attributes
+          @attributes ||=
+            if superclass.respond_to?(:attributes, true) && inherit_header
+              superclass.attributes.dup
+            else
+              []
+            end
+        end
+
+        # Create the attribute DSL instance used by the mapper class
+        #
+        # @api private
+        def dsl
+          @dsl ||= AttributeDSL.new(attributes, options)
+        end
+
+        # Delegate Attribute DSL method to the dsl instance
+        #
+        # @api private
+        def method_missing(name, *args, &block)
+          if dsl.respond_to?(name)
+            dsl.public_send(name, *args, &block)
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rom/mapper/model_dsl.rb

@@ -0,0 +1,55 @@
+require 'rom/model_builder'
+
+module ROM
+  class Mapper
+    # Model DSL allows setting a model class
+    #
+    # @private
+    module ModelDSL
+      attr_reader :attributes, :builder, :klass
+
+      DEFAULT_TYPE = :poro
+
+      # Set or generate a model
+      #
+      # @example
+      #   class MyDefinition
+      #     include ROM::Mapper::ModelDSL
+      #
+      #     def initialize
+      #       @attributes = [[:name], [:title]]
+      #     end
+      #   end
+      #
+      #   definition = MyDefinition.new
+      #
+      #   # just set a model constant
+      #   definition.model(User)
+      #
+      #   # generate model class for the attributes
+      #   definition.model(name: 'User')
+      #
+      # @api public
+      def model(options = nil)
+        if options.is_a?(Class)
+          @klass = options
+        elsif options
+          type = options.fetch(:type) { DEFAULT_TYPE }
+          @builder = ModelBuilder[type].new(options)
+        end
+
+        build_class unless options
+      end
+
+      private
+
+      # Build a model class using a specialized builder
+      #
+      # @api private
+      def build_class
+        return klass if klass
+        return builder.call(attributes.map(&:first)) if builder
+      end
+    end
+  end
+end

data/lib/rom/mapper/version.rb

@@ -1,9 +1,5 @@
-# encoding: utf-8
-
 module ROM
   class Mapper
-
-    VERSION = '0.1.1'.freeze
-
-  end # Mapper
-end # ROM
+    VERSION = '0.2.0'.freeze
+  end
+end

data/lib/rom/model_builder.rb

@@ -0,0 +1,99 @@
+module ROM
+  # Model builders can be used to build model classes for mappers
+  #
+  # This is used when you define a mapper and setup a model using :name option.
+  #
+  # @example
+  #   # this will define User model for you
+  #   class UserMapper < ROM::Mapper
+  #     model name: 'User'
+  #     attribute :id
+  #     attribute :name
+  #   end
+  #
+  # @private
+  class ModelBuilder
+    attr_reader :name
+
+    attr_reader :const_name, :namespace, :klass
+
+    # Return model builder subclass based on type
+    #
+    # @param [Symbol] type
+    #
+    # @return [Class]
+    #
+    # @api private
+    def self.[](type)
+      case type
+      when :poro then PORO
+      else
+        raise ArgumentError, "#{type.inspect} is not a supported model type"
+      end
+    end
+
+    # Build a model class
+    #
+    # @return [Class]
+    #
+    # @api private
+    def self.call(*args)
+      new(*args).call
+    end
+
+    # @api private
+    def initialize(options = {})
+      @name = options[:name]
+
+      if name
+        parts = name.split('::')
+
+        @const_name = parts.pop
+
+        @namespace =
+          if parts.any?
+            Inflector.constantize(parts.join('::'))
+          else
+            Object
+          end
+      end
+    end
+
+    # Define a model class constant
+    #
+    # @api private
+    def define_const
+      namespace.const_set(const_name, klass)
+    end
+
+    # Build a model class supporting specific attributes
+    #
+    # @return [Class]
+    #
+    # @api private
+    def call(attrs)
+      define_class(attrs)
+      define_const if const_name
+      @klass
+    end
+
+    # PORO model class builder
+    #
+    # @private
+    class PORO < ModelBuilder
+      def define_class(attrs)
+        @klass = Class.new
+
+        @klass.send(:attr_reader, *attrs)
+
+        @klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def initialize(params)
+            #{attrs.map { |name| "@#{name} = params[:#{name}]" }.join("\n")}
+          end
+        RUBY
+
+        self
+      end
+    end
+  end
+end

data/lib/rom/processor.rb

@@ -0,0 +1,28 @@
+require 'rom/mapper'
+
+module ROM
+  # Abstract processor class
+  #
+  # Every ROM processor should inherit from this class
+  #
+  # @api public
+  class Processor
+    # Hook used to auto-register a processor class
+    #
+    # @api private
+    def self.inherited(processor)
+      Mapper.register_processor(processor)
+    end
+
+    # Required interface to be implemented by descendants
+    #
+    # @return [Processor]
+    #
+    # @abstract
+    #
+    # @api private
+    def self.build
+      raise NotImplementedError, "+build+ must be implemented"
+    end
+  end
+end

data/lib/rom/processor/transproc.rb

@@ -0,0 +1,388 @@
+require 'transproc/all'
+
+require 'rom/processor'
+
+module ROM
+  class Processor
+    # Data mapping transformer builder using Transproc
+    #
+    # This builds a transproc function that is used to map a whole relation
+    #
+    # @see https://github.com/solnic/transproc too
+    #
+    # @private
+    class Transproc < Processor
+      include ::Transproc::Composer
+
+      module Functions
+        extend ::Transproc::Registry
+
+        import ::Transproc::Coercions
+        import ::Transproc::ArrayTransformations
+        import ::Transproc::HashTransformations
+        import ::Transproc::ClassTransformations
+
+        def self.identity(tuple)
+          tuple
+        end
+
+        def self.filter_empty(arr)
+          arr.reject { |row| row.values.all?(&:nil?) }
+        end
+      end
+
+      # @return [Header] header from a mapper
+      #
+      # @api private
+      attr_reader :header
+
+      # @return [Class] model class from a mapper
+      #
+      # @api private
+      attr_reader :model
+
+      # @return [Hash] header's attribute mapping
+      #
+      # @api private
+      attr_reader :mapping
+
+      # @return [Proc] row-processing proc
+      #
+      # @api private
+      attr_reader :row_proc
+
+      # Build a transproc function from the header
+      #
+      # @param [ROM::Header] header
+      #
+      # @return [Transproc::Function]
+      #
+      # @api private
+      def self.build(header)
+        new(header).to_transproc
+      end
+
+      # @api private
+      def initialize(header)
+        @header = header
+        @model = header.model
+        @mapping = header.mapping
+        initialize_row_proc
+      end
+
+      # Coerce mapper header to a transproc data mapping function
+      #
+      # @return [Transproc::Function]
+      #
+      # @api private
+      def to_transproc
+        compose(t(:identity)) do |ops|
+          combined = header.combined
+          ops << t(:combine, combined.map(&method(:combined_args))) if combined.any?
+          ops << header.preprocessed.map { |attr| visit(attr, true) }
+          ops << t(:map_array, row_proc) if row_proc
+          ops << header.postprocessed.map { |attr| visit(attr, true) }
+        end
+      end
+
+      private
+
+      # Visit an attribute from the header
+      #
+      # This forwards to a specialized visitor based on the attribute type
+      #
+      # @param [Header::Attribute] attribute
+      # @param [Array] args Allows to send `preprocess: true`
+      #
+      # @api private
+      def visit(attribute, *args)
+        type = attribute.class.name.split('::').last.downcase
+        send("visit_#{type}", attribute, *args)
+      end
+
+      # Visit plain attribute
+      #
+      # It will call block transformation if it's used
+      #
+      # If it's a typed attribute a coercion transformation is added
+      #
+      # @param [Header::Attribute] attribute
+      #
+      # @api private
+      def visit_attribute(attribute)
+        coercer = attribute.meta[:coercer]
+        if coercer
+          t(:map_value, attribute.name, coercer)
+        elsif attribute.typed?
+          t(:map_value, attribute.name, t(:"to_#{attribute.type}"))
+        end
+      end
+
+      # Visit hash attribute
+      #
+      # @param [Header::Attribute::Hash] attribute
+      #
+      # @api private
+      def visit_hash(attribute)
+        with_row_proc(attribute) do |row_proc|
+          t(:map_value, attribute.name, row_proc)
+        end
+      end
+
+      # Visit combined attribute
+      #
+      # @api private
+      def visit_combined(attribute)
+        op = with_row_proc(attribute) do |row_proc|
+          array_proc =
+            if attribute.type == :hash
+              t(:map_array, row_proc) >> -> arr { arr.first }
+            else
+              t(:map_array, row_proc)
+            end
+
+          t(:map_value, attribute.name, array_proc)
+        end
+
+        if op
+          op
+        elsif attribute.type == :hash
+          t(:map_value, attribute.name, -> arr { arr.first })
+        end
+      end
+
+      # Visit array attribute
+      #
+      # @param [Header::Attribute::Array] attribute
+      #
+      # @api private
+      def visit_array(attribute)
+        with_row_proc(attribute) do |row_proc|
+          t(:map_value, attribute.name, t(:map_array, row_proc))
+        end
+      end
+
+      # Visit wrapped hash attribute
+      #
+      # :nest transformation is added to handle wrapping
+      #
+      # @param [Header::Attribute::Wrap] attribute
+      #
+      # @api private
+      def visit_wrap(attribute)
+        name = attribute.name
+        keys = attribute.tuple_keys
+
+        compose do |ops|
+          ops << t(:nest, name, keys)
+          ops << visit_hash(attribute)
+        end
+      end
+
+      # Visit unwrap attribute
+      #
+      # :unwrap transformation is added to handle unwrapping
+      #
+      # @param [Header::Attributes::Unwrap]
+      #
+      # @api private
+      def visit_unwrap(attribute)
+        name = attribute.name
+        keys = attribute.pop_keys
+
+        compose do |ops|
+          ops << visit_hash(attribute)
+          ops << t(:unwrap, name, keys)
+        end
+      end
+
+      # Visit group hash attribute
+      #
+      # :group transformation is added to handle grouping during preprocessing.
+      # Otherwise we simply use array visitor for the attribute.
+      #
+      # @param [Header::Attribute::Group] attribute
+      # @param [Boolean] preprocess true if we are building a relation preprocessing
+      #                             function that is applied to the whole relation
+      #
+      # @api private
+      def visit_group(attribute, preprocess = false)
+        if preprocess
+          name = attribute.name
+          header = attribute.header
+          keys = attribute.tuple_keys
+
+          others = header.preprocessed
+
+          compose do |ops|
+            ops << t(:group, name, keys)
+            ops << t(:map_array, t(:map_value, name, t(:filter_empty)))
+            ops << others.map { |attr|
+              t(:map_array, t(:map_value, name, visit(attr, true)))
+            }
+          end
+        else
+          visit_array(attribute)
+        end
+      end
+
+      # Visit ungroup attribute
+      #
+      # :ungroup transforation is added to handle ungrouping during preprocessing.
+      # Otherwise we simply use array visitor for the attribute.
+      #
+      # @param [Header::Attribute::Ungroup] attribute
+      # @param [Boolean] preprocess true if we are building a relation preprocessing
+      #                             function that is applied to the whole relation
+      #
+      # @api private
+      def visit_ungroup(attribute, preprocess = false)
+        if preprocess
+          name = attribute.name
+          header = attribute.header
+          keys = attribute.pop_keys
+
+          others = header.postprocessed
+
+          compose do |ops|
+            ops << others.map { |attr|
+              t(:map_array, t(:map_value, name, visit(attr, true)))
+            }
+            ops << t(:ungroup, name, keys)
+          end
+        else
+          visit_array(attribute)
+        end
+      end
+
+      # Visit fold hash attribute
+      #
+      # :fold transformation is added to handle folding during preprocessing.
+      #
+      # @param [Header::Attribute::Fold] attribute
+      # @param [Boolean] preprocess true if we are building a relation preprocessing
+      #                             function that is applied to the whole relation
+      #
+      # @api private
+      def visit_fold(attribute, preprocess = false)
+        if preprocess
+          name = attribute.name
+          keys = attribute.tuple_keys
+
+          compose do |ops|
+            ops << t(:group, name, keys)
+            ops << t(:map_array, t(:map_value, name, t(:filter_empty)))
+            ops << t(:map_array, t(:fold, name, keys.first))
+          end
+        end
+      end
+
+      # Visit unfold hash attribute
+      #
+      # :unfold transformation is added to handle unfolding during preprocessing.
+      #
+      # @param [Header::Attribute::Unfold] attribute
+      # @param [Boolean] preprocess true if we are building a relation preprocessing
+      #                             function that is applied to the whole relation
+      #
+      # @api private
+      def visit_unfold(attribute, preprocess = false)
+        if preprocess
+          name = attribute.name
+          header = attribute.header
+          keys = attribute.pop_keys
+          key = keys.first
+
+          others = header.postprocessed
+
+          compose do |ops|
+            ops << others.map { |attr|
+              t(:map_array, t(:map_value, name, visit(attr, true)))
+            }
+            ops << t(:map_array, t(:map_value, name, t(:insert_key, key)))
+            ops << t(:map_array, t(:reject_keys, [key] - [name]))
+            ops << t(:ungroup, name, [key])
+          end
+        end
+      end
+
+      # Visit excluded attribute
+      #
+      # @param [Header::Attribute::Exclude] attribute
+      #
+      # @api private
+      def visit_exclude(attribute)
+        t(:reject_keys, [attribute.name])
+      end
+
+      # @api private
+      def combined_args(attribute)
+        other = attribute.header.combined
+
+        if other.any?
+          children = other.map(&method(:combined_args))
+          [attribute.name, attribute.meta[:keys], children]
+        else
+          [attribute.name, attribute.meta[:keys]]
+        end
+      end
+
+      # Build row_proc
+      #
+      # This transproc function is applied to each row in a dataset
+      #
+      # @api private
+      def initialize_row_proc
+        @row_proc = compose { |ops|
+          process_header_keys(ops)
+
+          ops << t(:rename_keys, mapping) if header.aliased?
+          ops << header.map { |attr| visit(attr) }
+          ops << t(:constructor_inject, model) if model
+        }
+      end
+
+      # Process row_proc header keys
+      #
+      # @api private
+      def process_header_keys(ops)
+        if header.reject_keys
+          all_keys = header.tuple_keys + header.non_primitives.map(&:key)
+          ops << t(:accept_keys, all_keys)
+        end
+        ops
+      end
+
+      # Yield row proc for a given attribute if any
+      #
+      # @param [Header::Attribute] attribute
+      #
+      # @api private
+      def with_row_proc(attribute)
+        row_proc = row_proc_from(attribute)
+        yield(row_proc) if row_proc
+      end
+
+      # Build a row_proc from a given attribute
+      #
+      # This is used by embedded attribute visitors
+      #
+      # @api private
+      def row_proc_from(attribute)
+        new(attribute.header).row_proc
+      end
+
+      # Return a new instance of the processor
+      #
+      # @api private
+      def new(*args)
+        self.class.new(*args)
+      end
+
+      # @api private
+      def t(*args)
+        Functions[*args]
+      end
+    end
+  end
+end