rom 0.7.1 → 0.8.0

data/lib/rom/mapper.rb

@@ -1,12 +1,12 @@
 require 'rom/mapper/dsl'
 
 module ROM
-  # Mapper is a simple object that uses a transformer to load relations
+  # Mapper is a simple object that uses transformers to load relations
   #
   # @private
   class Mapper
     include DSL
-    include Equalizer.new(:transformer, :header)
+    include Equalizer.new(:transformers, :header)
 
     defines :relation, :register_as, :symbolize_keys,
       :prefix, :prefix_separator, :inherit_header, :reject_keys
@@ -15,12 +15,12 @@ module ROM
     reject_keys false
     prefix_separator '_'.freeze
 
-    # @return [Object] transformer object built by a processor
+    # @return [Object] transformers object built by a processor
     #
     # @api private
-    attr_reader :transformer
+    attr_reader :transformers
 
-    # @return [Header] header that was used to build the transformer
+    # @return [Header] header that was used to build the transformers
     #
     # @api private
     attr_reader :header
@@ -50,13 +50,26 @@ module ROM
       processors.update(name => processor)
     end
 
+    # Prepares an array of headers for a potentially multistep mapper
+    #
+    # @return [Array<Header>]
+    #
+    # @api private
+    def self.headers(header)
+      return [header] if steps.empty?
+      return steps.map(&:header) if attributes.empty?
+      raise(MapperMisconfiguredError, "cannot mix outer attributes and steps")
+    end
+
     # Build a mapper using provided processor type
     #
     # @return [Mapper]
     #
     # @api private
     def self.build(header = self.header, processor = :transproc)
-      new(Mapper.processors.fetch(processor).build(header), header)
+      processor = Mapper.processors.fetch(processor)
+      transformers = headers(header).map(&processor.method(:build))
+      new(transformers, header)
     end
 
     # @api private
@@ -68,8 +81,8 @@ module ROM
     end
 
     # @api private
-    def initialize(transformer, header)
-      @transformer = transformer
+    def initialize(transformers, header)
+      @transformers = Array(transformers)
       @header = header
     end
 
@@ -80,11 +93,11 @@ module ROM
       header.model
     end
 
-    # Process a relation using the transformer
+    # Process a relation using the transformers
     #
     # @api private
     def call(relation)
-      transformer[relation.to_a]
+      transformers.reduce(relation.to_a) { |a, e| e.call(a) }
     end
   end
 end

data/lib/rom/mapper/attribute_dsl.rb

@@ -14,8 +14,7 @@ module ROM
     class AttributeDSL
       include ModelDSL
 
-      attr_reader :attributes, :options, :symbolize_keys, :prefix,
-        :prefix_separator, :reject_keys
+      attr_reader :attributes, :options, :symbolize_keys, :reject_keys, :steps
 
       # @param [Array] attributes accumulator array
       # @param [Hash] options
@@ -28,6 +27,39 @@ module ROM
         @prefix = options.fetch(:prefix)
         @prefix_separator = options.fetch(:prefix_separator)
         @reject_keys = options.fetch(:reject_keys)
+        @steps = []
+      end
+
+      # Redefine the prefix for the following attributes
+      #
+      # @example
+      #
+      #   dsl = AttributeDSL.new([])
+      #   dsl.attribute(:prefix, 'user')
+      #
+      # @api public
+      def prefix(value = Undefined)
+        if value.equal?(Undefined)
+          @prefix
+        else
+          @prefix = value
+        end
+      end
+
+      # Redefine the prefix separator for the following attributes
+      #
+      # @example
+      #
+      #   dsl = AttributeDSL.new([])
+      #   dsl.attribute(:prefix_separator, '.')
+      #
+      # @api public
+      def prefix_separator(value = Undefined)
+        if value.equal?(Undefined)
+          @prefix_separator
+        else
+          @prefix_separator = value
+        end
       end
 
       # Define a mapping attribute with its options and/or block
@@ -50,17 +82,22 @@ module ROM
         end
       end
 
-      # Remove an attribute
+      def exclude(name)
+        attributes << [name, { exclude: true }]
+      end
+
+      # Perform transformations sequentially
       #
       # @example
-      #   dsl = AttributeDSL.new([[:name]])
+      #   dsl = AttributeDSL.new()
       #
-      #   dsl.exclude(:name)
-      #   dsl.attributes # => []
+      #   dsl.step do
+      #     attribute :name
+      #   end
       #
       # @api public
-      def exclude(*names)
-        attributes.delete_if { |attr| names.include?(attr.first) }
+      def step(options = EMPTY_HASH, &block)
+        steps << new(options, &block)
       end
 
       # Define an embedded attribute
@@ -92,8 +129,9 @@ module ROM
           mapper = options[:mapper]
 
           if mapper
+            embedded_options = { type: :array }.update(options)
             attributes_from_mapper(
-              mapper, name, { type: :array }.update(attr_options)
+              mapper, name, embedded_options.update(attr_options)
             )
           else
             dsl = new(options, &block)
@@ -125,6 +163,8 @@ module ROM
       #
       # @api public
       def wrap(*args, &block)
+        ensure_mapper_configuration('wrap', args, block_given?)
+
         with_name_or_options(*args) do |name, options, mapper|
           wrap_options = { type: :hash, wrap: true }.update(options)
 
@@ -136,9 +176,34 @@ module ROM
         end
       end
 
+      # Define an embedded hash attribute that requires "unwrapping" transformation
+      #
+      # Typically this is used in no-sql context to normalize data before
+      # inserting to sql gateway.
+      #
+      # @example
+      #   dsl = AttributeDSL.new([])
+      #
+      #   dsl.unwrap(address: [:street, :zipcode, :city])
+      #
+      #   dsl.unwrap(:address) do
+      #     attribute :street
+      #     attribute :zipcode
+      #     attribute :city
+      #   end
+      #
+      # @see AttributeDSL#embedded
+      #
+      # @api public
       def unwrap(*args, &block)
-        with_name_or_options(*args) do |name, options|
-          dsl(name, { type: :hash, unwrap: true }.update(options), &block)
+        with_name_or_options(*args) do |name, options, mapper|
+          unwrap_options = { type: :hash, unwrap: true }.update(options)
+
+          if mapper
+            attributes_from_mapper(mapper, name, unwrap_options)
+          else
+            dsl(name, unwrap_options, &block)
+          end
         end
       end
 
@@ -160,6 +225,8 @@ module ROM
       #
       # @api public
       def group(*args, &block)
+        ensure_mapper_configuration('group', args, block_given?)
+
         with_name_or_options(*args) do |name, options, mapper|
           group_options = { type: :array, group: true }.update(options)
 
@@ -171,6 +238,24 @@ module ROM
         end
       end
 
+      # Define an embedded array attribute that requires "ungrouping" transformation
+      #
+      # Typically this is used in non-sql context being prepared for import to sql.
+      #
+      # @example
+      #   dsl = AttributeDSL.new([])
+      #   dsl.ungroup(tags: [:name])
+      #
+      # @see AttributeDSL#embedded
+      #
+      # @api public
+      def ungroup(*args, &block)
+        with_name_or_options(*args) do |name, options, *|
+          ungroup_options = { type: :array, ungroup: true }.update(options)
+          dsl(name, ungroup_options, &block)
+        end
+      end
+
       # Define an embedded hash attribute that requires "fold" transformation
       #
       # Typically this is used in sql context to fold single joined field
@@ -184,10 +269,40 @@ module ROM
       # @see AttributeDSL#embedded
       #
       # @api public
-      def fold(*args)
+      def fold(*args, &block)
         with_name_or_options(*args) do |name, *|
           fold_options = { type: :array, fold: true }
-          dsl(name, fold_options)
+          dsl(name, fold_options, &block)
+        end
+      end
+
+      # Define an embedded hash attribute that requires "unfold" transformation
+      #
+      # Typically this is used in non-sql context to convert array of
+      # values (like in Cassandra 'SET' or 'LIST' types) to array of tuples.
+      #
+      # Source values are assigned to the first key, the other keys being left blank.
+      #
+      # @example
+      #   dsl = AttributeDSL.new([])
+      #
+      #   dsl.unfold(tags: [:name, :type], from: :tags_list)
+      #
+      #   dsl.unfold :tags, from: :tags_list do
+      #     attribute :name, from: :tag_name
+      #     attribute :type, from: :tag_type
+      #   end
+      #
+      # @see AttributeDSL#embedded
+      #
+      # @api public
+      def unfold(name, options = EMPTY_HASH)
+        with_attr_options(name, options) do |attr_options|
+          old_name = attr_options.fetch(:from, name)
+          dsl(old_name, type: :array, unfold: true) do
+            attribute name, attr_options
+            yield if block_given?
+          end
         end
       end
 
@@ -234,13 +349,23 @@ module ROM
 
       private
 
+      # Remove the attribute used somewhere else (in wrap, group, model etc.)
+      #
+      # @api private
+      def remove(*names)
+        attributes.delete_if { |attr| names.include?(attr.first) }
+      end
+
       # Handle attribute options common for all definitions
       #
       # @api private
       def with_attr_options(name, options = EMPTY_HASH)
         attr_options = options.dup
 
-        attr_options[:from] ||= :"#{prefix}#{prefix_separator}#{name}" if prefix
+        if @prefix
+          attr_options[:from] ||= "#{@prefix}#{@prefix_separator}#{name}"
+          attr_options[:from] = attr_options[:from].to_sym if name.is_a? Symbol
+        end
 
         if symbolize_keys
           attr_options.update(from: attr_options.fetch(:from) { name }.to_s)
@@ -285,7 +410,7 @@ module ROM
         dsl = new(options, &block)
         header = dsl.header
         add_attribute(name, options.update(header: header))
-        header.each { |attr| exclude(attr.key) unless name == attr.key }
+        header.each { |attr| remove(attr.key) unless name == attr.key }
       end
 
       # Define attributes from the `name => attributes` hash syntax
@@ -297,7 +422,7 @@ module ROM
         hash.each do |name, header|
           with_attr_options(name, options) do |attr_options|
             add_attribute(name, attr_options.update(header: header.zip))
-            header.each { |attr| exclude(attr) unless name == attr }
+            header.each { |attr| remove(attr) unless name == attr }
           end
         end
       end
@@ -319,7 +444,7 @@ module ROM
       #
       # @api private
       def add_attribute(name, options)
-        exclude(name, name.to_s)
+        remove(name, name.to_s)
         attributes << [name, options]
       end
 
@@ -330,9 +455,23 @@ module ROM
       # @api private
       def new(options, &block)
         dsl = self.class.new([], @options.merge(options))
-        dsl.instance_exec(&block)
+        dsl.instance_exec(&block) unless block.nil?
         dsl
       end
+
+      # Ensure the mapping configuration isn't ambiguous
+      #
+      # @api private
+      def ensure_mapper_configuration(method_name, args, block_present)
+        if args.first.is_a?(Hash) && block_present
+          raise MapperMisconfiguredError,
+                "Cannot configure `#{method_name}#` using both options and a block"
+        end
+        if args.first.is_a?(Hash) && args.first[:mapper]
+          raise MapperMisconfiguredError,
+                "Cannot configure `#{method_name}#` using both options and a mapper"
+        end
+      end
     end
   end
 end

data/lib/rom/memory.rb

@@ -1,4 +1,4 @@
+require 'rom/memory/gateway'
 require 'rom/memory/relation'
-require 'rom/memory/repository'
 
 ROM.register_adapter(:memory, ROM::Memory)

data/lib/rom/memory/commands.rb

@@ -13,10 +13,13 @@ module ROM
         adapter :memory
 
         # @see ROM::Commands::Create#execute
-        def execute(tuple)
-          attributes = input[tuple]
-          validator.call(attributes)
-          [relation.insert(attributes.to_h).to_a.last]
+        def execute(tuples)
+          Array([tuples]).flatten.map do |tuple|
+            attributes = input[tuple]
+            validator.call(attributes)
+            relation.insert(attributes.to_h)
+            attributes
+          end.to_a
         end
       end
 
@@ -42,11 +45,10 @@ module ROM
 
         # @see ROM::Commands::Delete#execute
         def execute
-          tuples = target.to_a
-          tuples.each do |tuple|
-            relation.delete(tuple)
+          relation.to_a.map do |tuple|
+            source.delete(tuple)
+            tuple
           end
-          tuples
         end
       end
     end

data/lib/rom/memory/dataset.rb

@@ -51,9 +51,21 @@ module ROM
 
       # Sort a dataset
       #
+      # @param [Array<Symbol>] names
+      #   Names of fields to order tuples by
+      #
+      # @option [Boolean] :nils_first (false)
+      #   Whether `nil` values should be placed before others
+      #
       # @api public
-      def order(*names)
-        sort_by { |tuple| tuple.values_at(*names) }
+      def order(*fields)
+        nils_first = fields.pop[:nils_first] if fields.last.is_a?(Hash)
+
+        sort do |a, b|
+          fields # finds the first difference between selected fields of tuples
+            .map { |n| __compare__ a[n], b[n], nils_first }
+            .detect(-> { 0 }) { |r| r != 0 }
+        end
       end
 
       # Insert tuple into a dataset
@@ -72,6 +84,14 @@ module ROM
         data.delete(tuple)
         self
       end
+
+      private
+
+      # Compares two values, that are either comparable, or can be nils
+      def __compare__(a, b, nils_first)
+        return a <=> b unless a.nil? ^ b.nil?
+        (nils_first ^ b.nil?) ? -1 : 1
+      end
     end
   end
 end

data/lib/rom/memory/{repository.rb → gateway.rb}

@@ -1,18 +1,18 @@
-require 'rom/repository'
+require 'rom/gateway'
 require 'rom/memory/storage'
 require 'rom/memory/commands'
 
 module ROM
   module Memory
-    # In-memory repository interface
+    # In-memory gateway interface
     #
     # @example
-    #   repository = ROM::Memory::Repository.new
-    #   repository.dataset(:users)
-    #   repository[:users].insert(name: 'Jane')
+    #   gateway = ROM::Memory::Gateway.new
+    #   gateway.dataset(:users)
+    #   gateway[:users].insert(name: 'Jane')
     #
     # @api public
-    class Repository < ROM::Repository
+    class Gateway < ROM::Gateway
       # @return [Object] default logger
       #
       # @api public
@@ -23,7 +23,7 @@ module ROM
         @connection = Storage.new
       end
 
-      # Set default logger for the repository
+      # Set default logger for the gateway
       #
       # @param [Object] logger object
       #
@@ -32,7 +32,7 @@ module ROM
         @logger = logger
       end
 
-      # Register a dataset in the repository
+      # Register a dataset in the gateway
       #
       # If dataset already exists it will be returned
       #
@@ -43,14 +43,14 @@ module ROM
         self[name] || connection.create_dataset(name)
       end
 
-      # @see ROM::Repository#dataset?
+      # @see ROM::Gateway#dataset?
       def dataset?(name)
         connection.key?(name)
       end
 
       # Return dataset with the given name
       #
-      # @param (see ROM::Repository#[])
+      # @param (see ROM::Gateway#[])
       # @return [Memory::Dataset]
       #
       # @api public