rom 0.5.0 → 0.6.0.beta1

data/lib/rom/commands/delete.rb

@@ -1,3 +1,5 @@
+require 'rom/command'
+
 module ROM
   module Commands
     # Delete command
@@ -5,10 +7,11 @@ module ROM
     # This command removes tuples from its target relation
     #
     # @abstract
-    class Delete < AbstractCommand
+    class Delete < Command
       attr_reader :target
 
-      def initialize(relation, options)
+      # @api private
+      def initialize(relation, options = {})
         super
         @target = options[:target] || relation
       end
@@ -18,29 +21,6 @@ module ROM
         assert_tuple_count
         super
       end
-
-      # Execute the command
-      #
-      # @abstract
-      #
-      # @return [Array] an array with removed tuples
-      #
-      # @api private
-      def execute
-        raise(
-          NotImplementedError,
-          "#{self.class}##{__method__} must be implemented"
-        )
-      end
-
-      # Create a new delete command scoped to specific relation and execute it
-      #
-      # @api private
-      def new(*args, &block)
-        new_options = options.merge(target: relation.public_send(*args, &block))
-        command = self.class.new(relation, new_options)
-        command.call
-      end
     end
   end
 end

data/lib/rom/commands/result.rb

@@ -2,7 +2,7 @@ module ROM
   module Commands
     # Abstract result class for success and error results
     #
-    # @public
+    # @api public
     class Result
       # Return command execution result
       #
@@ -26,11 +26,11 @@ module ROM
 
       # Success result has a value and no error
       #
-      # @public
+      # @api public
       class Success < Result
         # @api private
         def initialize(value)
-          @value = value
+          @value = value.is_a?(self.class) ? value.value : value
         end
 
         # Call next command on continuation
@@ -46,13 +46,13 @@ module ROM
         #
         # @api public
         def to_ary
-          value
+          value.to_ary
         end
       end
 
       # Failure result has an error and no value
       #
-      # @public
+      # @api public
       class Failure < Result
         # @api private
         def initialize(error)

data/lib/rom/commands/update.rb

@@ -1,4 +1,4 @@
-require 'rom/commands/with_options'
+require 'rom/command'
 
 module ROM
   module Commands
@@ -7,37 +7,13 @@ module ROM
     # This command updates all tuples in its relation with new attributes
     #
     # @abstract
-    class Update < AbstractCommand
-      include WithOptions
-
-      alias_method :set, :call
-
+    class Update < Command
       # @see AbstractCommand#call
       def call(*args)
         assert_tuple_count
         super
       end
-
-      # Execute the update command
-      #
-      # @return [Array] an array with updated tuples
-      #
-      # @abstract
-      #
-      # @api private
-      def execute(_params)
-        raise(
-          NotImplementedError,
-          "#{self.class}##{__method__} must be implemented"
-        )
-      end
-
-      # Return new update command with new relation
-      #
-      # @api private
-      def new(*args, &block)
-        self.class.new(relation.public_send(*args, &block), options)
-      end
+      alias_method :set, :call
     end
   end
 end

data/lib/rom/constants.rb

@@ -0,0 +1,19 @@
+# Constants and errors common in the whole library
+module ROM
+  Undefined = Object.new.freeze
+
+  AdapterLoadError = Class.new(StandardError)
+
+  EnvAlreadyFinalizedError = Class.new(StandardError)
+  RelationAlreadyDefinedError = Class.new(StandardError)
+  NoRelationError = Class.new(StandardError)
+  CommandError = Class.new(StandardError)
+  TupleCountMismatchError = Class.new(CommandError)
+  MapperMissingError = Class.new(StandardError)
+
+  InvalidOptionValueError = Class.new(StandardError)
+  InvalidOptionKeyError = Class.new(StandardError)
+
+  EMPTY_ARRAY = [].freeze
+  EMPTY_HASH = {}.freeze
+end

data/lib/rom/env.rb

@@ -1,33 +1,102 @@
+require 'rom/relation/loaded'
+
 module ROM
-  # Exposes defined repositories, schema, relations and mappers
+  # Exposes defined repositories, relations and mappers
   #
   # @api public
   class Env
-    include Adamantium::Flat
-    include Equalizer.new(
-      :repositories, :schema, :relations, :mappers, :commands
-    )
+    include Equalizer.new(:repositories, :relations, :mappers, :commands)
+
+    # @return [Hash] configured repositories
+    #
+    # @api public
+    attr_reader :repositories
+
+    # @return [RelationRegistry] relation registry
+    #
+    # @api public
+    attr_reader :relations
+
+    # @return [ReaderRegistry] reader registry
+    #
+    # @api public
+    attr_reader :readers
+
+    # @return [Registry] command registry
+    #
+    # @api public
+    attr_reader :commands
 
-    attr_reader :repositories, :schema, :relations, :mappers, :commands
+    # @return [Registry] mapper registry
+    #
+    # @api public
+    attr_reader :mappers
 
     # @api private
-    def initialize(repositories, schema, relations, mappers, commands)
+    def initialize(repositories, relations, readers, commands)
       @repositories = repositories
-      @schema = schema
       @relations = relations
-      @mappers = mappers
+      @readers = readers
       @commands = commands
+      initialize_mappers
+      freeze
+    end
+
+    # Load relation by name
+    #
+    # @example
+    #
+    #   rom.relation(:users)
+    #   rom.relation(:users) { |r| r.by_name('Jane') }
+    #
+    #   # with mapping
+    #   rom.relation(:users).map_with(:presenter)
+    #
+    #   rom.relation(:users) { |r| r.page(1) }.map_with(:presenter, :json_serializer)
+    #
+    # @param [Symbol] name of the relation to load
+    #
+    # @yield [Relation]
+    #
+    # @return [Relation::Loaded]
+    #
+    # @api public
+    def relation(name, &block)
+      relation =
+        if block
+          yield(relations[name])
+        else
+          relations[name]
+        end
+
+      if mappers.elements.key?(name)
+        relation.to_lazy(mappers: mappers[name])
+      else
+        relation.to_lazy
+      end
     end
 
     # Returns a reader with access to defined mappers
     #
     # @example
     #
+    #   # with a mapper derived from relation access path "users.adults"
     #   rom.read(:users).adults.to_a
     #
+    #   # or with explicit mapper name
+    #   rom.read(:users).with(:some_mapper).to_a
+    #
+    # @param [Symbol] name of the registered reader
+    #
     # @api public
-    def read(name)
-      mappers[name]
+    def read(name, &block)
+      reader = readers[name]
+
+      if block
+        yield(reader)
+      else
+        reader
+      end
     end
 
     # Returns commands registry for the given relation
@@ -41,33 +110,14 @@ module ROM
       commands[name]
     end
 
-    # Return repository identified by its name
-    #
-    # @return [Repository]
-    #
-    # @api private
-    def [](name)
-      repositories.fetch(name)
-    end
-
-    # @api private
-    def respond_to_missing?(name, include_private = false)
-      repositories.key?(name) || super
-    end
-
     private
 
-    # Return repository if the method matches repository name
-    #
-    # @return [Repository]
-    #
     # @api private
-    def method_missing(name, *args, &block)
-      if repositories.key?(name)
-        repositories[name]
-      else
-        super
-      end
+    def initialize_mappers
+      elements = readers.each_with_object({}) { |(name, reader), h|
+        h[name] = reader.mappers
+      }
+      @mappers = Registry.new(elements)
     end
   end
 end

data/lib/rom/global.rb

@@ -1,13 +1,85 @@
+require 'rom/setup'
+require 'rom/repository'
+
 module ROM
   # Globally accessible public interface exposed via ROM module
   #
-  # @public
+  # @api public
   module Global
-    # Starts the setup process for schema, relations, mappers and commands
+    # Set base global registries in ROM constant
+    #
+    # @api private
+    def self.extended(rom)
+      super
+
+      rom.instance_variable_set('@adapters', {})
+      rom.instance_variable_set('@repositories', {})
+    end
+
+    # An internal adapter identifier => adapter module map used by setup
+    #
+    # @return [Hash<Symbol=>Module>]
+    #
+    # @api private
+    attr_reader :adapters
+
+    # An internal repo => identifier map used by the setup
+    #
+    # @return [Hash]
+    #
+    # @api private
+    attr_reader :repositories
+
+    # Setup object created during env setup phase
+    #
+    # This gets set to nil after setup is finalized
+    #
+    # @return [Setup]
+    #
+    # @api private
+    attr_reader :boot
+
+    # Return global default ROM environment configured by the setup
+    #
+    # @return [Env]
+    #
+    # @api public
+    attr_reader :env
+
+    # 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
+    #   pass it directly.
+    #
+    #   @param [Symbol] type
+    #   @param [Array] *args
+    #
+    # @overload setup(repository)
+    #   @param [Repository] repository
+    #
+    # @overload setup(repositories)
+    #   Sets up multiple repositories.
+    #
+    #   @param [Hash{Symbol=>Symbol,Array}] repositories
+    #
+    # @return [Setup] boot object
     #
     # @example
+    #   # Use the in-memory adapter shipped with ROM as the default repository.
+    #   env = ROM.setup(:memory, 'memory://test')
+    #   # Use `rom-sql` with an in-memory sqlite database as default repository.
+    #   ROM.setup(:sql, 'sqlite::memory')
+    #   # Registers a `default` and a `warehouse` repository.
+    #   env = ROM.setup(
+    #     default: [:sql, 'sqlite::memory'],
+    #     warehouse: [:sql, 'postgres://localhost/warehouse']
+    #   )
     #
-    #   ROM.setup('sqlite::memory')
+    # @example A full environment
+    #
+    #   ROM.setup(:memory, 'memory://test')
     #
     #   ROM.relation(:users) do
     #     # ...
@@ -28,80 +100,139 @@ module ROM
     #   ROM.finalize # builds the env
     #   ROM.env # returns the env registry
     #
-    # @param [Hash] options repository URIs
-    #
-    # @return [Setup] boot object
-    #
     # @api public
     def setup(*args, &block)
-      config = Config.build(*args)
-
-      adapters = config.each_with_object({}) do |(name, uri_or_opts), hash|
-        uri, opts =
-          if uri_or_opts.is_a?(Hash)
-            uri_or_opts.values_at(:uri, :options)
-          else
-            [uri_or_opts, {}]
-          end
-
-        hash[name] = Adapter.setup(uri, opts)
-      end
-
-      repositories = adapters.each_with_object({}) do |(name, adapter), hash|
-        hash[name] = Repository.new(adapter)
-      end
-
-      boot = Setup.new(repositories)
+      config = setup_config(*args)
+      @boot = Setup.new(setup_repositories(config), adapters.keys.first)
 
       if block
-        boot.instance_exec(&block)
-        boot.finalize
+        @boot.instance_exec(&block)
+        @boot.finalize
       else
-        @boot = boot
+        @boot
       end
     end
 
-    # @see ROM::Setup#schema
+    # Global relation setup DSL
     #
-    # @api public
-    def schema(&block)
-      boot.schema(&block)
-    end
-
-    # @see ROM::Setup#relation
+    # @example
+    #   ROM.setup(:memory)
+    #
+    #   ROM.relation(:users) do
+    #     def by_name(name)
+    #       restrict(name: name)
+    #     end
+    #   end
     #
     # @api public
     def relation(*args, &block)
       boot.relation(*args, &block)
     end
 
+    # Global commands setup DSL
+    #
+    # @example
+    #   ROM.setup(:memory)
+    #
+    #   ROM.commands(:users) do
+    #     define(:create) do
+    #       # ..
+    #     end
+    #   end
+    #
     # @api public
     def commands(*args, &block)
       boot.commands(*args, &block)
     end
 
+    # Global mapper setup DSL
+    #
+    # @example
+    #   ROM.setup(:memory)
+    #
+    #   ROM.mappers do
+    #     define(:uses) do
+    #       # ..
+    #     end
+    #   end
+    #
     # @api public
     def mappers(*args, &block)
       boot.mappers(*args, &block)
     end
 
-    # @api public
-    def env
-      @env
-    end
-
+    # Finalize the setup and store default global env under ROM.env
+    #
+    # @example
+    #   ROM.setup(:memory)
+    #   ROM.finalize # => ROM
+    #   ROM.boot # => nil
+    #   ROM.env # => the env
+    #
+    # @return [ROM]
+    #
     # @api public
     def finalize
       @env = boot.finalize
+      self
+    ensure
       @boot = nil
+    end
+
+    # Register adapter namespace under a specified identifier
+    #
+    # @param [Symbol] identifier
+    # @param [Class,Module] adapter
+    #
+    # @return [self]
+    #
+    # @api private
+    def register_adapter(identifier, adapter)
+      adapters[identifier] = adapter
       self
     end
 
+    # Relation subclass registration during setup phase
+    #
+    # @api private
+    def register_relation(klass)
+      boot.register_relation(klass) if boot
+    end
+
+    # Mapper subclass registration during setup phase
+    #
+    # @api private
+    def register_mapper(klass)
+      boot.register_mapper(klass) if boot
+    end
+
+    # Command subclass registration during setup phase
+    #
+    # @api private
+    def register_command(klass)
+      boot.register_command(klass) if boot
+    end
+
     private
 
+    # Helper method to handle single- or multi-repo setup options
+    #
+    # @api private
+    def setup_config(*args)
+      args.first.is_a?(Hash) ? args.first : { default: args }
+    end
+
+    # Build repositories using the setup interface
+    #
     # @api private
-    def boot
-      @boot
+    def setup_repositories(config)
+      config.each_with_object({}) do |(name, spec), hash|
+        identifier, *args = Array(spec)
+        repository = Repository.setup(identifier, *(args.flatten))
+        hash[name] = repository
+
+        repositories[repository] = identifier unless identifier.is_a?(Repository)
+      end
     end
   end
 end