rom 0.5.0 → 0.6.0.beta1

data/lib/rom/header.rb

@@ -31,9 +31,9 @@ module ROM
 
     # Coerce array with attribute definitions into a header object
     #
-    # @param [Array<Array>] attribute name/option pairs
+    # @param [Array<Array>] input attribute name/option pairs
     #
-    # @param [Class] optional model
+    # @param [Class] model optional
     #
     # @return [Header]
     #
@@ -63,8 +63,8 @@ module ROM
     # @yield [Attribute]
     #
     # @api private
-    def each(&block)
-      attributes.values.each(&block)
+    def each
+      attributes.each_value { |attribute| yield(attribute) }
     end
 
     # Return if there are any aliased attributes
@@ -150,7 +150,7 @@ module ROM
     #
     # @api private
     def initialize_tuple_keys
-      @tuple_keys = mapping.keys + non_primitives.map(&:tuple_keys).flatten
+      @tuple_keys = mapping.keys + non_primitives.flat_map(&:tuple_keys)
     end
   end
 end

data/lib/rom/header/attribute.rb

@@ -33,7 +33,7 @@ module ROM
 
       # Return attribute class for a give meta hash
       #
-      # @param [Hash] hash with type information and optional transformation info
+      # @param [Hash] meta hash with type information and optional transformation info
       #
       # @return [Class]
       #
@@ -52,7 +52,7 @@ module ROM
 
       # Coerce an array with attribute meta-data into an attribute object
       #
-      # @param [Array<Symbol,Hash>] name/options pair
+      # @param [Array<Symbol,Hash>] input attribute name/options pair
       #
       # @return [Attribute]
       #

data/lib/rom/lint/enumerable_dataset.rb

@@ -0,0 +1,52 @@
+require 'rom/lint/linter'
+
+module ROM
+  module Lint
+    # Ensures that a [ROM::EnumerableDataset] extension correctly yields
+    # arrays and tuples
+    #
+    # @api public
+    class EnumerableDataset < ROM::Lint::Linter
+      # The linted subject
+      #
+      # @api public
+      attr_reader :dataset
+
+      # The expected data
+      #
+      # @api public
+      attr_reader :data
+
+      # Create a linter for EnumerableDataset
+      #
+      # @param [EnumerableDataset] dataset the linted subject
+      # @param [Object] data the expected data
+      #
+      # @api public
+      def initialize(dataset, data)
+        @dataset = dataset
+        @data = data
+      end
+
+      # Lint: Ensure that +dataset+ yield tuples via +each+
+      #
+      # @api public
+      def lint_each
+        result = []
+        dataset.each { |tuple| result << tuple }
+        return if result == data
+
+        complain "#{dataset.class}#each must yield tuples"
+      end
+
+      # Lint: Ensure that +dataset+'s array equals to expected +data+
+      #
+      # @api public
+      def lint_to_a
+        return if dataset.to_a == data
+
+        complain "#{dataset.class}#to_a must cast dataset to an array"
+      end
+    end
+  end
+end

data/lib/rom/lint/linter.rb

@@ -0,0 +1,64 @@
+module ROM
+  module Lint
+    # Base class for building linters that check source code
+    #
+    # Linters are used by authors of ROM adapters to verify that their
+    # integration complies with the ROM api.
+    #
+    # Most of the time, authors won't need to construct linters directly
+    # because the provided test helpers will automatically run when required
+    # in tests and specs.
+    #
+    # @example
+    #   require 'rom/lint/spec'
+    #
+    #
+    # @api public
+    class Linter
+      # A failure raised by +complain+
+      Failure = Class.new(StandardError)
+
+      # Iterate over all lint methods
+      #
+      # @yield [String, ROM::Lint]
+      #
+      # @api public
+      def self.each_lint
+        return to_enum unless block_given?
+        lints.each { |lint| yield lint, self }
+      end
+
+      # Run a lint method
+      #
+      # @param [String] name
+      #
+      # @raise [ROM::Lint::Linter::Failure] if linting fails
+      #
+      # @api public
+      def lint(name)
+        public_send name
+        true # for assertions
+      end
+
+      private
+
+      # Return a list a lint methods
+      #
+      # @return [String]
+      #
+      # @api private
+      def self.lints
+        public_instance_methods(true).grep(/^lint_/).map(&:to_s)
+      end
+
+      # Raise a failure if a lint verification fails
+      #
+      # @raise [ROM::Lint::Linter::Failure]
+      #
+      # @api private
+      def complain(*args)
+        raise Failure, *args
+      end
+    end
+  end
+end

data/lib/rom/lint/repository.rb

@@ -0,0 +1,78 @@
+require 'rom/lint/linter'
+
+module ROM
+  module Lint
+    # Ensures that a [ROM::Repository] extension provides datasets through the
+    # expected methods
+    #
+    # @api public
+    class Repository < ROM::Lint::Linter
+      # The repository identifier e.g. +:memory+
+      #
+      # @api public
+      attr_reader :identifier
+
+      # The repository class
+      #
+      # @api public
+      attr_reader :repository
+
+      # The optional URI
+      #
+      # @api public
+      attr_reader :uri
+
+      # Create a repository linter
+      #
+      # @param [Symbol] identifier
+      # @param [Class] repository
+      # @param [String] uri optional
+      def initialize(identifier, repository, uri = nil)
+        @identifier = identifier
+        @repository = repository
+        @uri = uri
+      end
+
+      # Lint: Ensure that +repository+ setups up its instance
+      #
+      # @api public
+      def lint_repository_setup
+        return if repository_instance.instance_of? repository
+
+        complain <<-STRING
+          #{repository}.setup must return a repository instance but
+          returned #{repository_instance.inspect}
+        STRING
+      end
+
+      # Lint: Ensure that +repository_instance+ responds to +[]+
+      #
+      # @api public
+      def lint_dataset_reader
+        return if repository_instance.respond_to? :[]
+
+        complain "#{repository_instance} must respond to []"
+      end
+
+      # Lint: Ensure that +repository_instance+ responds to +dataset?+
+      #
+      # @api public
+      def lint_dataset_predicate
+        return if repository_instance.respond_to? :dataset?
+
+        complain "#{repository_instance} must respond to dataset?"
+      end
+
+      # Setup repository instance
+      #
+      # @api public
+      def repository_instance
+        if uri
+          ROM::Repository.setup(identifier, uri)
+        else
+          ROM::Repository.setup(identifier)
+        end
+      end
+    end
+  end
+end

data/lib/rom/lint/spec.rb

@@ -0,0 +1,20 @@
+require 'rom/lint/repository'
+require 'rom/lint/enumerable_dataset'
+
+RSpec.shared_examples "a rom repository" do
+  ROM::Lint::Repository.each_lint do |name, linter|
+    it name do
+      result = linter.new(identifier, repository, uri).lint(name)
+      expect(result).to be_truthy
+    end
+  end
+end
+
+RSpec.shared_examples "a rom enumerable dataset" do
+  ROM::Lint::EnumerableDataset.each_lint do |name, linter|
+    it name do
+      result = linter.new(dataset, data).lint(name)
+      expect(result).to be_truthy
+    end
+  end
+end

data/lib/rom/lint/test.rb

@@ -0,0 +1,98 @@
+require 'rom/lint/repository'
+require 'rom/lint/enumerable_dataset'
+
+module ROM
+  module Lint
+    # A module that helps to define test methods
+    module Test
+      # Defines a test method converting lint failures to assertions
+      #
+      # @param [String] name
+      #
+      # @api private
+      def define_test_method(name, &block)
+        define_method "test_#{name}" do
+          begin
+            instance_eval(&block)
+          rescue ROM::Lint::Linter::Failure => f
+            raise Minitest::Assertion, f.message
+          end
+        end
+      end
+    end
+
+    # This is a simple lint-test for repository class to ensure the
+    # basic interfaces are in place
+    #
+    # @example
+    #
+    #   class MyRepoTest < Minitest::Test
+    #     include ROM::Lint::TestRepository
+    #
+    #     def setup
+    #       @repository = MyRepository
+    #       @uri = "super_db://something"
+    #     end
+    #   end
+    #
+    # @api public
+    module TestRepository
+      extend ROM::Lint::Test
+
+      # Returns the repository identifier e.g. +:memory+
+      #
+      # @api public
+      attr_reader :identifier
+
+      # Returns the repository class
+      #
+      # @api public
+      attr_reader :repository
+
+      # Returns repostory's URI e.g. "super_db://something"
+      #
+      # @api public
+      attr_reader :uri
+
+      ROM::Lint::Repository.each_lint do |name, linter|
+        define_test_method name do
+          assert linter.new(identifier, repository, uri).lint(name)
+        end
+      end
+    end
+
+    # This is a simple lint-test for an repository dataset class to ensure the
+    # basic behavior is correct
+    #
+    # @example
+    #
+    #  class MyDatasetLintTest < Minitest::Test
+    #    include ROM::Repository::Lint::TestEnumerableDataset
+    #
+    #     def setup
+    #       @data  = [{ name: 'Jane', age: 24 }, { name: 'Joe', age: 25 }]
+    #       @dataset = MyDataset.new(@data, [:name, :age])
+    #     end
+    #   end
+    # @api public
+    module TestEnumerableDataset
+      extend ROM::Lint::Test
+
+      # Returns the dataset instance
+      #
+      # @api public
+      attr_reader :dataset
+
+      # Returns the expected data
+      #
+      # @api public
+      attr_reader :data
+
+      ROM::Lint::EnumerableDataset.each_lint do |name, linter|
+        define_test_method name do
+          assert linter.new(dataset, data).lint(name)
+        end
+      end
+    end
+  end
+end

data/lib/rom/mapper.rb

@@ -1,8 +1,19 @@
+require 'rom/mapper/dsl'
+
 module ROM
   # Mapper is a simple object that uses a transformer to load relations
   #
   # @private
   class Mapper
+    include DSL
+    include Equalizer.new(:transformer, :header)
+
+    defines :relation, :register_as, :symbolize_keys,
+      :prefix, :prefix_separator, :inherit_header
+
+    inherit_header true
+    prefix_separator '_'.freeze
+
     # @return [Object] transformer object built by a processor
     #
     # @api private
@@ -13,6 +24,14 @@ module ROM
     # @api private
     attr_reader :header
 
+    # Register suclasses during setup phase
+    #
+    # @api private
+    def self.inherited(klass)
+      super
+      ROM.register_mapper(klass)
+    end
+
     # @return [Hash] registered processors
     #
     # @api private
@@ -35,8 +54,16 @@ module ROM
     # @return [Mapper]
     #
     # @api private
-    def self.build(header, processor = :transproc)
-      new(processors.fetch(processor).build(header), header)
+    def self.build(header = self.header, processor = :transproc)
+      new(Mapper.processors.fetch(processor).build(header), header)
+    end
+
+    # @api private
+    def self.registry(descendants)
+      descendants.each_with_object({}) do |klass, h|
+        name = klass.register_as || klass.relation
+        (h[klass.base_relation] ||= {})[name] = klass.build
+      end
     end
 
     # @api private
@@ -52,11 +79,11 @@ module ROM
       header.model
     end
 
-    # Process a relation using the transfomer
+    # Process a relation using the transformer
     #
     # @api private
-    def process(relation, &block)
-      transformer[relation.to_a].each(&block)
+    def call(relation)
+      transformer[relation.to_a]
     end
   end
 end

data/lib/rom/mapper/attribute_dsl.rb

@@ -0,0 +1,240 @@
+require 'rom/header'
+require 'rom/mapper/model_dsl'
+
+module ROM
+  class Mapper
+    # Mapper attribute DSL exposed by mapper subclasses
+    #
+    # This class is private even though its methods are exposed by mappers.
+    # Typically it's not meant to be used directly.
+    #
+    # @private
+    class AttributeDSL
+      include ModelDSL
+
+      attr_reader :attributes, :options, :symbolize_keys, :prefix, :prefix_separator
+
+      # @param [Array] attributes accumulator array
+      # @param [Hash] options
+      #
+      # @api private
+      def initialize(attributes, options)
+        @attributes = attributes
+        @options = options
+        @symbolize_keys = options.fetch(:symbolize_keys)
+        @prefix = options.fetch(:prefix)
+        @prefix_separator = options.fetch(:prefix_separator)
+      end
+
+      # Define a mapping attribute with its options
+      #
+      # @example
+      #   dsl = AttributeDSL.new([])
+      #
+      #   dsl.attribute(:name)
+      #   dsl.attribute(:email, from: 'user_email')
+      #
+      # @api public
+      def attribute(name, options = EMPTY_HASH)
+        with_attr_options(name, options) do |attr_options|
+          add_attribute(name, attr_options)
+        end
+      end
+
+      # Remove an attribute
+      #
+      # @example
+      #   dsl = AttributeDSL.new([[:name]])
+      #
+      #   dsl.exclude(:name)
+      #   dsl.attributes # => []
+      #
+      # @api public
+      def exclude(*names)
+        attributes.delete_if { |attr| names.include?(attr.first) }
+      end
+
+      # Define an embedded attribute
+      #
+      # Block exposes the attribute dsl too
+      #
+      # @example
+      #   dsl = AttributeDSL.new([])
+      #
+      #   dsl.embedded :tags, type: :array do
+      #     attribute :name
+      #   end
+      #
+      #   dsl.embedded :address, type: :hash do
+      #     model Address
+      #     attribute :name
+      #   end
+      #
+      # @param [Symbol] name attribute
+      #
+      # @param [Hash] options
+      # @option options [Symbol] :type Embedded type can be :hash or :array
+      # @option options [Symbol] :prefix Prefix that should be used for
+      #                                  its attributes
+      #
+      # @api public
+      def embedded(name, options, &block)
+        with_attr_options(name) do |attr_options|
+          dsl = new(options, &block)
+
+          attr_options.update(options)
+
+          add_attribute(
+            name, { header: dsl.header, type: :array }.update(attr_options)
+          )
+        end
+      end
+
+      # Define an embedded hash attribute that requires "wrapping" transformation
+      #
+      # Typically this is used in sql context when relation is a join.
+      #
+      # @example
+      #   dsl = AttributeDSL.new([])
+      #
+      #   dsl.wrap(address: [:street, :zipcode, :city])
+      #
+      #   dsl.wrap(:address) do
+      #     model Address
+      #     attribute :street
+      #     attribute :zipcode
+      #     attribute :city
+      #   end
+      #
+      # @see AttributeDSL#embedded
+      #
+      # @api public
+      def wrap(*args, &block)
+        with_name_or_options(*args) do |name, options|
+          dsl(name, { type: :hash, wrap: true }.update(options), &block)
+        end
+      end
+
+      # Define an embedded hash attribute that requires "grouping" transformation
+      #
+      # Typically this is used in sql context when relation is a join.
+      #
+      # @example
+      #   dsl = AttributeDSL.new([])
+      #
+      #   dsl.group(tags: [:name])
+      #
+      #   dsl.group(:tags) do
+      #     model Tag
+      #     attribute :name
+      #   end
+      #
+      # @see AttributeDSL#embedded
+      #
+      # @api public
+      def group(*args, &block)
+        with_name_or_options(*args) do |name, options|
+          dsl(name, { type: :array, group: true }.update(options), &block)
+        end
+      end
+
+      # Generate a header from attribute definitions
+      #
+      # @return [Header]
+      #
+      # @api private
+      def header
+        Header.coerce(attributes, model)
+      end
+
+      private
+
+      # 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 symbolize_keys
+          attr_options.update(from: attr_options.fetch(:from) { name }.to_s)
+        end
+
+        yield(attr_options)
+      end
+
+      # Handle "name or options" syntax used by `wrap` and `group`
+      #
+      # @api private
+      def with_name_or_options(*args)
+        name, options =
+          if args.size > 1
+            args
+          else
+            [args.first, {}]
+          end
+
+        yield(name, options)
+      end
+
+      # Create another instance of the dsl for nested definitions
+      #
+      # This is used by embedded, wrap and group
+      #
+      # @api private
+      def dsl(name_or_attrs, options, &block)
+        if block
+          attributes_from_block(name_or_attrs, options, &block)
+        else
+          attributes_from_hash(name_or_attrs, options)
+        end
+      end
+
+      # Define attributes from a nested block
+      #
+      # Used by embedded, wrap and group
+      #
+      # @api private
+      def attributes_from_block(name, options, &block)
+        dsl = new(options, &block)
+        header = dsl.header
+        add_attribute(name, options.update(header: header))
+        header.each { |attr| exclude(attr.key) }
+      end
+
+      # Define attributes from the `name => attributes` hash syntax
+      #
+      # Used by wrap and group
+      #
+      # @api private
+      def attributes_from_hash(hash, options)
+        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) }
+          end
+        end
+      end
+
+      # Add a new attribute and make sure it overrides previous definition
+      #
+      # @api private
+      def add_attribute(name, options)
+        exclude(name, name.to_s)
+        attributes << [name, options]
+      end
+
+      # Create a new dsl instance of potentially overidden options
+      #
+      # Embedded, wrap and group can override top-level options like `prefix`
+      #
+      # @api private
+      def new(options, &block)
+        dsl = self.class.new([], @options.merge(options))
+        dsl.instance_exec(&block)
+        dsl
+      end
+    end
+  end
+end