rom 0.7.1 → 0.8.0

data/lib/rom/global.rb

@@ -16,7 +16,7 @@ module ROM
       super
 
       rom.instance_variable_set('@adapters', {})
-      rom.instance_variable_set('@repositories', {})
+      rom.instance_variable_set('@gateways', {})
       rom.instance_variable_set('@plugin_registry', PluginRegistry.new)
     end
 
@@ -27,12 +27,12 @@ module ROM
     # @api private
     attr_reader :adapters
 
-    # An internal repo => identifier map used by the setup
+    # An internal gateway => identifier map used by the setup
     #
     # @return [Hash]
     #
     # @api private
-    attr_reader :repositories
+    attr_reader :gateways
 
     # An internal identifier => plugin map used by the setup
     #
@@ -60,29 +60,29 @@ module ROM
     # Starts the setup process for relations, mappers and commands.
     #
     # @overload setup(type, *args)
-    #   Sets up a single-repository environment given a repository type provided
-    #   under the ROM umbrella. For custom repositories, create an instance and
+    #   Sets up a single-gateway environment given a gateway type provided
+    #   under the ROM umbrella. For custom gateways, create an instance and
     #   pass it directly.
     #
     #   @param [Symbol] type
     #   @param [Array] *args
     #
-    # @overload setup(repository)
-    #   @param [Repository] repository
+    # @overload setup(gateway)
+    #   @param [Gateway] gateway
     #
-    # @overload setup(repositories)
-    #   Sets up multiple repositories.
+    # @overload setup(gateways)
+    #   Sets up multiple gateways.
     #
-    #   @param [Hash{Symbol=>Symbol,Array}] repositories
+    #   @param [Hash{Symbol=>Symbol,Array}] gateways
     #
     # @return [Setup] boot object
     #
     # @example
-    #   # Use the in-memory adapter shipped with ROM as the default repository.
+    #   # Use the in-memory adapter shipped with ROM as the default gateway.
     #   env = ROM.setup(:memory, 'memory://test')
-    #   # Use `rom-sql` with an in-memory sqlite database as default repository.
+    #   # Use `rom-sql` with an in-memory sqlite database as default gateway.
     #   ROM.setup(:sql, 'sqlite::memory')
-    #   # Registers a `default` and a `warehouse` repository.
+    #   # Registers a `default` and a `warehouse` gateway.
     #   env = ROM.setup(
     #     default: [:sql, 'sqlite::memory'],
     #     warehouse: [:sql, 'postgres://localhost/warehouse']
@@ -114,7 +114,7 @@ module ROM
     # @api public
     def setup(*args, &block)
       config = setup_config(*args)
-      @boot = Setup.new(setup_repositories(config), adapters.keys.first)
+      @boot = Setup.new(setup_gateways(config), adapters.keys.first)
 
       if block
         @boot.instance_exec(&block)
@@ -245,16 +245,16 @@ module ROM
       args.first.is_a?(Hash) ? args.first : { default: args }
     end
 
-    # Build repositories using the setup interface
+    # Build gateways using the setup interface
     #
     # @api private
-    def setup_repositories(config)
+    def setup_gateways(config)
       config.each_with_object({}) do |(name, spec), hash|
         identifier, *args = Array(spec)
-        repository = Repository.setup(identifier, *(args.flatten))
-        hash[name] = repository
+        gateway = Gateway.setup(identifier, *(args.flatten))
+        hash[name] = gateway
 
-        repositories[repository] = identifier unless identifier.is_a?(Repository)
+        gateways[gateway] = identifier unless identifier.is_a?(Gateway)
       end
     end
   end

data/lib/rom/header.rb

@@ -35,6 +35,11 @@ module ROM
     # @api private
     attr_reader :tuple_keys
 
+    # @return [Array] all attribute names that are popping from a tuple
+    #
+    # @api private
+    attr_reader :pop_keys
+
     # Coerce array with attribute definitions into a header object
     #
     # @param [Array<Array>] input attribute name/option pairs
@@ -62,6 +67,7 @@ module ROM
       @attributes = attributes
       initialize_mapping
       initialize_tuple_keys
+      initialize_pop_keys
     end
 
     # Iterate over attributes
@@ -98,13 +104,31 @@ module ROM
       attributes.fetch(name)
     end
 
-    # Return all Group attributes
+    # Return all Combined attributes
+    #
+    # @return [Array<Combined>]
+    #
+    # @api private
+    def combined
+      by_type(Combined)
+    end
+
+    # Returns all attributes that require preprocessing
+    #
+    # @return [Array<Group,Fold>]
+    #
+    # @api private
+    def preprocessed
+      by_type(Group, Fold)
+    end
+
+    # Returns all attributes that require postprocessing
     #
-    # @return [Array<Group>]
+    # @return [Array<Ungroup,Unfold>]
     #
     # @api private
-    def groups
-      by_type(Group)
+    def postprocessed
+      by_type(Ungroup, Unfold)
     end
 
     # Return all Wrap attributes
@@ -116,12 +140,16 @@ module ROM
       by_type(Wrap)
     end
 
+    # Return all non-primitive attributes that don't require mapping
+    #
+    # @return [Array<Group,Fold,Ungroup,Unfold,Wrap,Unwrap>]
+    #
     # @api private
-    def combined
-      by_type(Combined)
+    def non_primitives
+      preprocessed + wraps
     end
 
-    # Return all primitive attributes (no Group and Wrap)
+    # Return all primitive attributes that require mapping
     #
     # @return [Array<Attribute>]
     #
@@ -130,15 +158,6 @@ module ROM
       to_a - non_primitives
     end
 
-    # Return all non-primitive attributes (only Group and Wrap types)
-    #
-    # @return [Array<Group,Wrap>]
-    #
-    # @api private
-    def non_primitives
-      groups + wraps
-    end
-
     private
 
     # Find all attribute matching specific attribute class (not kind)
@@ -163,5 +182,12 @@ module ROM
     def initialize_tuple_keys
       @tuple_keys = mapping.keys + non_primitives.flat_map(&:tuple_keys)
     end
+
+    # Set all tuple keys from all attributes popping from Unwrap and Ungroup
+    #
+    # @api private
+    def initialize_pop_keys
+      @pop_keys = mapping.values + non_primitives.flat_map(&:tuple_keys)
+    end
   end
 end

data/lib/rom/header/attribute.rb

@@ -39,21 +39,8 @@ module ROM
       #
       # @api private
       def self.[](meta)
-        type = meta[:type]
-
-        if meta[:combine]
-          Combined
-        elsif meta[:unwrap]
-          Unwrap
-        elsif type.equal?(:hash)
-          meta[:wrap] ? Wrap : Hash
-        elsif meta[:fold]
-          Group
-        elsif type.equal?(:array)
-          meta[:group] ? Group : Array
-        else
-          self
-        end
+        key = (meta.keys & TYPE_MAP.keys).first
+        TYPE_MAP.fetch(key || meta[:type], self)
       end
 
       # Coerce an array with attribute meta-data into an attribute object
@@ -135,6 +122,10 @@ module ROM
       def tuple_keys
         header.tuple_keys
       end
+
+      def pop_keys
+        header.pop_keys
+      end
     end
 
     # Array is an embedded attribute type
@@ -158,5 +149,36 @@ module ROM
     # Group is a special type of Array attribute that requires grouping
     # transformation
     Group = Class.new(Array)
+
+    # Ungroup is a special type of Array attribute that requires ungrouping
+    # transformation
+    Ungroup = Class.new(Array)
+
+    # Fold is a special type of Array attribute that requires folding
+    # transformation
+    Fold = Class.new(Array)
+
+    # Unfold is a special type of Array attribute that requires unfolding
+    # transformation
+    Unfold = Class.new(Array)
+
+    # Exclude is a special type of Attribute to be removed
+    Exclude = Class.new(Attribute)
+
+    # TYPE_MAP is a (hash) map of ROM::Header identifiers to ROM::Header types
+    #
+    # @private
+    TYPE_MAP = {
+      combine: Combined,
+      wrap: Wrap,
+      unwrap: Unwrap,
+      group: Group,
+      ungroup: Ungroup,
+      fold: Fold,
+      unfold: Unfold,
+      hash: Hash,
+      array: Array,
+      exclude: Exclude
+    }
   end
 end

data/lib/rom/lint/gateway.rb

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

data/lib/rom/lint/spec.rb

@@ -1,10 +1,22 @@
-require 'rom/lint/repository'
+require 'rom/lint/gateway'
 require 'rom/lint/enumerable_dataset'
 
 RSpec.shared_examples "a rom repository" do
-  ROM::Lint::Repository.each_lint do |name, linter|
+  before(:all) do
+    ROM::Deprecations.announce "[Adapter]::Repository is", <<-MSG
+      Please use [Adapter]::Gateway instead.
+    MSG
+  end
+
+  let(:gateway) { repository }
+
+  include_examples "a rom gateway"
+end
+
+RSpec.shared_examples "a rom gateway" do
+  ROM::Lint::Gateway.each_lint do |name, linter|
     it name do
-      result = linter.new(identifier, repository, uri).lint(name)
+      result = linter.new(identifier, gateway, uri).lint(name)
       expect(result).to be_truthy
     end
   end

data/lib/rom/lint/test.rb

@@ -1,4 +1,4 @@
-require 'rom/lint/repository'
+require 'rom/lint/gateway'
 require 'rom/lint/enumerable_dataset'
 
 module ROM
@@ -21,53 +21,84 @@ module ROM
       end
     end
 
-    # This is a simple lint-test for repository class to ensure the
+    # This is a simple lint-test for gateway class to ensure the
     # basic interfaces are in place
     #
     # @example
     #
-    #   class MyRepoTest < Minitest::Test
-    #     include ROM::Lint::TestRepository
+    #   class MyGatewayTest < Minitest::Test
+    #     include ROM::Lint::TestGateway
     #
     #     def setup
-    #       @repository = MyRepository
+    #       @gateway = MyGateway
     #       @uri = "super_db://something"
     #     end
     #   end
     #
     # @api public
-    module TestRepository
+    module TestGateway
       extend ROM::Lint::Test
 
-      # Returns the repository identifier e.g. +:memory+
+      # Returns the gateway identifier e.g. +:memory+
       #
       # @api public
       attr_reader :identifier
 
-      # Returns the repository class
+      # Returns the gateway class
       #
       # @api public
-      attr_reader :repository
+      attr_reader :gateway
 
-      # Returns repostory's URI e.g. "super_db://something"
+      # Returns gateway's URI e.g. "super_db://something"
       #
       # @api public
       attr_reader :uri
 
-      ROM::Lint::Repository.each_lint do |name, linter|
+      ROM::Lint::Gateway.each_lint do |name, linter|
         define_test_method name do
-          assert linter.new(identifier, repository, uri).lint(name)
+          assert linter.new(identifier, gateway, uri).lint(name)
         end
       end
     end
 
-    # This is a simple lint-test for an repository dataset class to ensure the
+    # This is a transitional lint-test loader for repository class
+    # to ensure that the basic interfaces are in place
+    #
+    #   class MyRepositoryTest < Minitest::Test
+    #     include ROM::Lint::TestRepository
+    #
+    #     def setup
+    #       @repository = MyRepository
+    #       @uri = "super_db://something"
+    #     end
+    #   end
+    #
+    # @see [ROM::Lint::TestGateway]
+    #
+    # @api public
+    module TestRepository
+      extend TestGateway
+
+      # Returns the reposiotry class
+      #
+      # @api public
+      attr_reader :repository
+
+      def setup
+        ROM::Deprecations.announce "[Adapter]::Repository is", <<-MSG
+          Please use [Adapter]::Gateway instead.
+        MSG
+        @gateway = repository
+      end
+    end
+
+    # This is a simple lint-test for a gateway dataset class to ensure the
     # basic behavior is correct
     #
     # @example
     #
     #  class MyDatasetLintTest < Minitest::Test
-    #    include ROM::Repository::Lint::TestEnumerableDataset
+    #    include ROM::Lint::TestEnumerableDataset
     #
     #     def setup
     #       @data  = [{ name: 'Jane', age: 24 }, { name: 'Joe', age: 25 }]