rom 0.5.0 → 0.6.0.beta1

data/lib/rom/model_builder.rb

@@ -1,8 +1,31 @@
 module ROM
-  # @api private
+  # 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 :options, :const_name, :namespace, :klass
+    include Options
 
+    option :name, reader: true
+
+    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
@@ -11,14 +34,19 @@ module ROM
       end
     end
 
+    # Build a model class
+    #
+    # @return [Class]
+    #
+    # @api private
     def self.call(*args)
       new(*args).call
     end
 
+    # @api private
     def initialize(options = {})
-      @options = options
+      super
 
-      name = options[:name]
       if name
         parts = name.split('::')
 
@@ -26,23 +54,34 @@ module ROM
 
         @namespace =
           if parts.any?
-            Inflecto.constantize(parts.join('::'))
+            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

data/lib/rom/processor.rb

@@ -5,7 +5,7 @@ module ROM
   #
   # Every ROM processor should inherit from this class
   #
-  # @public
+  # @api public
   class Processor
     # Hook used to auto-register a processor class
     #

data/lib/rom/processor/transproc.rb

@@ -4,66 +4,146 @@ 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
 
-      attr_reader :header, :model, :mapping, :tuple_proc
+      # @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
+
+      # Default no-op row_proc
       EMPTY_FN = -> tuple { tuple }.freeze
 
+      # 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_tuple_proc
+        initialize_row_proc
       end
 
+      # Coerce mapper header to a transproc data mapping function
+      #
+      # @return [Transproc::Function]
+      #
+      # @api private
       def to_transproc
         compose(EMPTY_FN) do |ops|
           ops << header.groups.map { |attr| visit_group(attr, true) }
-          ops << t(:map_array!, tuple_proc) if tuple_proc
+          ops << t(:map_array, row_proc) if row_proc
         end
       end
 
       private
 
+      # Visit an attribute from the header
+      #
+      # This forwards to a specialized visitor based on the attribute type
+      #
+      # @param [Header::Attribute] attribute
+      #
+      # @api private
       def visit(attribute)
         type = attribute.class.name.split('::').last.downcase
         send("visit_#{type}", attribute)
       end
 
+      # Visit plain attribute
+      #
+      # If it's a typed attribute a coercion transformation is added
+      #
+      # @param [Header::Attribute] attribute
+      #
+      # @api private
       def visit_attribute(attribute)
         if attribute.typed?
-          t(:map_key!, attribute.name, t(:"to_#{attribute.type}"))
+          t(:map_key, attribute.name, t(:"to_#{attribute.type}"))
         end
       end
 
+      # Visit hash attribute
+      #
+      # @param [Header::Attribute::Hash] attribute
+      #
+      # @api private
       def visit_hash(attribute)
-        with_tuple_proc(attribute) do |tuple_proc|
-          t(:map_key!, attribute.name, tuple_proc)
+        with_row_proc(attribute) do |row_proc|
+          t(:map_key, attribute.name, row_proc)
         end
       end
 
+      # Visit array attribute
+      #
+      # @param [Header::Attribute::Array] attribute
+      #
+      # @api private
       def visit_array(attribute)
-        with_tuple_proc(attribute) do |tuple_proc|
-          t(:map_key!, attribute.name, t(:map_array!, tuple_proc))
+        with_row_proc(attribute) do |row_proc|
+          t(:map_key, 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 << t(:nest, name, keys)
           ops << visit_hash(attribute)
         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
@@ -76,7 +156,7 @@ module ROM
             ops << t(:group, name, keys)
 
             ops << other.map { |attr|
-              t(:map_array!, t(:map_key!, name, visit_group(attr, true)))
+              t(:map_array, t(:map_key, name, visit_group(attr, true)))
             }
           end
         else
@@ -84,19 +164,32 @@ module ROM
         end
       end
 
-      def initialize_tuple_proc
-        @tuple_proc = compose do |ops|
-          ops << t(:map_hash!, mapping) if header.aliased?
+      # Build row_proc
+      #
+      # This transproc function is applied to each row in a dataset
+      #
+      # @api private
+      def initialize_row_proc
+        @row_proc = compose do |ops|
+          ops << t(:map_hash, mapping) if header.aliased?
           ops << header.map { |attr| visit(attr) }
           ops << t(-> tuple { model.new(tuple) }) if model
         end
       end
 
-      def with_tuple_proc(attribute)
-        tuple_proc = new(attribute.header).tuple_proc
-        yield(tuple_proc) if tuple_proc
+      # Yield row proc for a given attribute if any
+      #
+      # @param [Header::Attribute] attribute
+      #
+      # @api private
+      def with_row_proc(attribute)
+        row_proc = new(attribute.header).row_proc
+        yield(row_proc) if row_proc
       end
 
+      # Return a new instance of the processor
+      #
+      # @api private
       def new(*args)
         self.class.new(*args)
       end

data/lib/rom/reader.rb

@@ -5,11 +5,16 @@ module ROM
   #
   # @api public
   class Reader
-    MapperMissingError = Class.new(StandardError)
-
     include Enumerable
     include Equalizer.new(:path, :relation, :mapper)
 
+    # Map relation to an array using a mapper
+    #
+    # @return [Array]
+    #
+    # @api public
+    alias_method :to_ary, :to_a
+
     # @return [String] access path used to read a relation
     #
     # @api private
@@ -30,58 +35,55 @@ module ROM
     # @api private
     attr_reader :mapper
 
-    # Build a reader subclass for the relation and instantiate it
-    #
-    # This method defines public methods on the class narrowing down data access
-    # only to the methods exposed by a given relation
+    # Builds a reader instance for the provided relation
     #
     # @param [Symbol] name of the root relation
     # @param [Relation] relation that the reader will use
-    # @param [MapperRegistry] registry of mappers
-    # @param [Array<Symbol>] a list of method names exposed by the relation
+    # @param [MapperRegistry] mappers registry of mappers
+    # @param [Array<Symbol>] method_names a list of method names exposed by the relation
     #
     # @return [Reader]
     #
     # @api private
     def self.build(name, relation, mappers, method_names = [])
-      klass = Class.new(self)
-
-      klass_name = "#{self.name}[#{Inflecto.camelize(relation.name)}]"
-
-      klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-        def self.name
-          #{klass_name.inspect}
-        end
-
-        def self.inspect
-          name
-        end
+      klass = build_class(relation, method_names)
+      klass.new(name, relation, mappers)
+    end
 
-        def self.to_s
-          name
+    # Build a reader subclass for the relation
+    #
+    # This method defines public methods on the class narrowing down data access
+    # only to the methods exposed by a given relation
+    #
+    # @param [Relation] relation that the reader will use
+    # @param [Array<Symbol>] method_names a list of method names exposed by the relation
+    #
+    # @return [Class]
+    #
+    # @api private
+    def self.build_class(relation, method_names)
+      klass_name = "#{Reader.name}[#{Inflector.camelize(relation.name)}]"
+
+      ClassBuilder.new(name: klass_name, parent: Reader).call do |klass|
+        method_names.each do |method_name|
+          klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{method_name}(*args, &block)
+              new_relation = relation.send(#{method_name.inspect}, *args, &block)
+              self.class.new(
+                new_path(#{method_name.to_s.inspect}), new_relation, mappers
+              )
+            end
+          RUBY
         end
-      RUBY
-
-      method_names.each do |method_name|
-        klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          def #{method_name}(*args, &block)
-            new_relation = relation.send(#{method_name.inspect}, *args, &block)
-            self.class.new(
-              new_path(#{method_name.to_s.inspect}), new_relation, mappers
-            )
-          end
-        RUBY
       end
-
-      klass.new(name, relation, mappers)
     end
 
     # @api private
-    def initialize(path, relation, mappers = {})
+    def initialize(path, relation, mappers, mapper = nil)
       @path = path.to_s
       @relation = relation
       @mappers = mappers
-      @mapper = mappers.by_path(@path) || raise(MapperMissingError, path)
+      @mapper = mapper || mappers.by_path(@path)
     end
 
     # @api private
@@ -101,13 +103,63 @@ module ROM
     #
     # @api public
     def each
-      mapper.process(relation) { |tuple| yield(tuple) }
+      mapper.call(relation).each { |tuple| yield(tuple) }
+    end
+
+    # Returns a single tuple from the relation if there is one.
+    #
+    # @raise [ROM::TupleCountMismatchError] if the relation contains more than
+    #   one tuple
+    #
+    # @api public
+    def one
+      if relation.count > 1
+        raise(
+          TupleCountMismatchError,
+          'The relation consists of more than one tuple'
+        )
+      else
+        mapper.call(relation).first
+      end
+    end
+
+    # Like [one], but additionally raises an error if the relation is empty.
+    #
+    # @raise [ROM::TupleCountMismatchError] if the relation does not contain
+    #   exactly one tuple
+    #
+    # @api public
+    def one!
+      one || raise(
+        TupleCountMismatchError,
+        'The relation does not contain any tuples'
+      )
+    end
+
+    # Map tuples using a specific mapper if name is provided
+    #
+    # Defaults to Enumerable#map behavior
+    #
+    # @example
+    #
+    #   rom.read(:users).map(:my_mapper_name)
+    #   rom.read(:users).map { |user| ... }
+    #
+    # @return [Array,Reader]
+    #
+    # @api public
+    def map(*args)
+      if args.any?
+        mappers[args[0]].call(relation)
+      else
+        super
+      end
     end
 
     private
 
     # @api private
-    def method_missing(name)
+    def method_missing(name, *)
       raise(
         NoRelationError,
         "undefined relation #{name.inspect} within #{path.inspect}"