lotus-model 0.1.2 → 0.2.0

data/lib/lotus/entity.rb

@@ -1,11 +1,12 @@
 require 'lotus/utils/kernel'
+require 'lotus/utils/attributes'
 
 module Lotus
   # An object that is defined by its identity.
-  # See Domain Driven Design by Eric Evans.
+  # See "Domain Driven Design" by Eric Evans.
   #
   # An entity is the core of an application, where the part of the domain
-  # logic is implemented. It's a small, cohesive object that express coherent
+  # logic is implemented. It's a small, cohesive object that expresses coherent
   # and meaningful behaviors.
   #
   # It deals with one and only one responsibility that is pertinent to the
@@ -21,18 +22,18 @@ module Lotus
   #
   #   class Person
   #     include Lotus::Entity
-  #     self.attributes = :name, :age
+  #     attributes :name, :age
   #   end
   #
-  # When a class includes `Lotus::Entity` the `.attributes=` method is exposed.
-  # By then calling the `.attributes=` class method, the following methods are
-  # added:
+  # When a class includes `Lotus::Entity` it receives the following interface:
   #
   #   * #id
   #   * #id=
   #   * #initialize(attributes = {})
   #
-  # If we expand the code above in pure Ruby, it would be:
+  # `Lotus::Entity` also provides the `.attributes=` for defining attribute accessors for the given names.
+  #
+  # If we expand the code above in **pure Ruby**, it would be:
   #
   # @example Pure Ruby
   #   class Person
@@ -43,11 +44,18 @@ module Lotus
   #     end
   #   end
   #
-  # Indeed, **Lotus::Model** ships `Entity` only for developers's convenience, but the
-  # rest of the framework is able to accept any object that implements the interface above.
+  # **Lotus::Model** ships `Lotus::Entity` for developers's convenience.
+  #
+  # **Lotus::Model** depends on a narrow and well-defined interface for an
+  # Entity - `#id`, `#id=`, `#initialize(attributes={})`.If your object
+  # implements that interface then that object can be used as an Entity in the
+  # **Lotus::Model** framework.
+  #
+  # However, we suggest to implement this interface by including
+  # `Lotus::Entity`, in case that future versions of the framework will expand
+  # it.
   #
-  # However, we suggest to implement this interface by including `Lotus::Entity`,
-  # in case that future versions of the framework will expand it.
+  # See Dependency Inversion Principle for more on interfaces.
   #
   # @since 0.1.0
   #
@@ -88,9 +96,9 @@ module Lotus
       # Please notice that the required `id` attribute is automatically defined
       # and can be omitted in the arguments.
       #
-      # @param attributes [Array<Symbol>] a set of arbitrary attribute names
+      # @param attrs [Array<Symbol>] a set of arbitrary attribute names
       #
-      # @since 0.1.0
+      # @since 0.2.0
       #
       # @see Lotus::Repository
       # @see Lotus::Model::Mapper
@@ -100,22 +108,59 @@ module Lotus
       #
       #   class User
       #     include Lotus::Entity
-      #     self.attributes = :name
+      #     attributes :name, :age
+      #   end
+      #   User.attributes => #<Set: {:id, :name, :age}>
+      #
+      # @example Given params is array of attributes
+      #   require 'lotus/model'
+      #
+      #   class User
+      #     include Lotus::Entity
+      #     attributes [:name, :age]
+      #   end
+      #   User.attributes => #<Set: {:id, :name, :age}>
+      #
+      # @example Extend entity
+      #   require 'lotus/model'
+      #
+      #   class User
+      #     include Lotus::Entity
+      #     attributes :name
       #   end
-      def attributes=(*attributes)
-        @attributes = Lotus::Utils::Kernel.Array(attributes.unshift(:id))
+      #
+      #   class DeletedUser < User
+      #     include Lotus::Entity
+      #     attributes :deleted_at
+      #   end
+      #
+      #   User.attributes => #<Set: {:id, :name}>
+      #   DeletedUser.attributes => #<Set: {:id, :name, :deleted_at}>
+      def attributes(*attrs)
+        if attrs.any?
+          self.attributes.merge Lotus::Utils::Kernel.Array(attrs)
 
-        class_eval %{
-          def initialize(attributes = {})
-        #{ @attributes.map {|a| "@#{a}" }.join(', ') }, = *attributes.values_at(#{ @attributes.map {|a| ":#{a}"}.join(', ') })
-          end
-        }
+          class_eval <<-END_EVAL, __FILE__, __LINE__
+            def initialize(attributes = {})
+              attributes = Lotus::Utils::Attributes.new(attributes)
+              #{@attributes.map do |a|
+                  "@#{a} = attributes.get(:#{a})"
+                 end.join("\n") }
+            end
+          END_EVAL
 
-        attr_accessor *@attributes
+          attr_accessor *@attributes
+        else
+          @attributes ||= Set.new([:id])
+        end
       end
 
-      def attributes
-        @attributes
+      protected
+
+      # @see Class#inherited
+      def inherited(subclass)
+        subclass.attributes *attributes
+        super
       end
     end
 
@@ -146,6 +191,44 @@ module Lotus
       self.class == other.class &&
          self.id == other.id
     end
+
+    # Return the hash of attributes
+    #
+    # @since 0.2.0
+    #
+    # @example
+    #   require 'lotus/model'
+    #   class User
+    #     include Lotus::Entity
+    #     attributes :name
+    #   end
+    #
+    #   user = User.new(id: 23, name: 'Luca')
+    #   user.to_h # => { :id => 23, :name => "Luca" }
+    def to_h
+      Hash[self.class.attributes.map { |a| [a, public_send(a)] }]
+    end
+
+    # Set attributes for entity
+    #
+    # @since 0.2.0
+    #
+    # @example
+    #   require 'lotus/model'
+    #   class User
+    #     include Lotus::Entity
+    #     attributes :name
+    #   end
+    #
+    #   user = User.new(name: 'Lucca')
+    #   user.update(name: 'Luca')
+    #   user.name # => 'Luca'
+    def update(attributes={})
+      attributes.each do |attribute, value|
+        public_send("#{attribute}=", value)
+      end
+    end
+
   end
 end
 

data/lib/lotus/model.rb

@@ -2,20 +2,13 @@ require 'lotus/model/version'
 require 'lotus/entity'
 require 'lotus/repository'
 require 'lotus/model/mapper'
+require 'lotus/model/configuration'
 
 module Lotus
   # Model
   #
   # @since 0.1.0
   module Model
-    # Error for not found entity
-    #
-    # @since 0.1.0
-    #
-    # @see Lotus::Repository.find
-    class EntityNotFound < ::StandardError
-    end
-
     # Error for non persisted entity
     # It's raised when we try to update or delete a non persisted entity.
     #
@@ -24,5 +17,173 @@ module Lotus
     # @see Lotus::Repository.update
     class NonPersistedEntityError < ::StandardError
     end
+
+    # Error for invalid mapper configuration
+    # It's raised when mapping is not configured correctly
+    #
+    # @since 0.2.0
+    #
+    # @see Lotus::Configuration#mapping
+    class InvalidMappingError < ::StandardError
+    end
+
+    include Utils::ClassAttribute
+
+    # Framework configuration
+    #
+    # @since 0.2.0
+    # @api private
+    class_attribute :configuration
+    self.configuration = Configuration.new
+
+    # Configure the framework.
+    # It yields the given block in the context of the configuration
+    #
+    # @param blk [Proc] the configuration block
+    #
+    # @since 0.2.0
+    #
+    # @see Lotus::Model
+    #
+    # @example
+    #   require 'lotus/model'
+    #
+    #   Lotus::Model.configure do
+    #     adapter type: :sql, uri: 'postgres://localhost/database'
+    #
+    #     mapping do
+    #       collection :users do
+    #         entity User
+    #
+    #         attribute :id,   Integer
+    #         attribute :name, String
+    #       end
+    #     end
+    #   end
+    #
+    # Adapter MUST follow the convention in which adapter class is inflection of adapter name
+    # The above example has name :sql, thus derived class will be `Lotus::Model::Adapters::SqlAdapter`
+    def self.configure(&blk)
+      configuration.instance_eval(&blk)
+      self
+    end
+
+    # Load the framework
+    #
+    # @since 0.2.0
+    # @api private
+    def self.load!
+      configuration.load!
+    end
+
+    # Unload the framework
+    #
+    # @since 0.2.0
+    # @api private
+    def self.unload!
+      configuration.unload!
+    end
+
+    # Duplicate Lotus::Model in order to create a new separated instance
+    # of the framework.
+    #
+    # The new instance of the framework will be completely decoupled from the
+    # original. It will inherit the configuration, but all the changes that
+    # happen after the duplication, won't be reflected on the other copies.
+    #
+    # @return [Module] a copy of Lotus::Model
+    #
+    # @since 0.2.0
+    # @api private
+    #
+    # @example Basic usage
+    #   require 'lotus/model'
+    #
+    #   module MyApp
+    #     Model = Lotus::Model.dupe
+    #   end
+    #
+    #   MyApp::Model == Lotus::Model # => false
+    #
+    #   MyApp::Model.configuration ==
+    #     Lotus::Model.configuration # => false
+    #
+    # @example Inheriting configuration
+    #   require 'lotus/model'
+    #
+    #   Lotus::Model.configure do
+    #     adapter type: :sql, uri: 'sqlite3://uri'
+    #   end
+    #
+    #   module MyApp
+    #     Model = Lotus::Model.dupe
+    #   end
+    #
+    #   module MyApi
+    #     Model = Lotus::Model.dupe
+    #     Model.configure do
+    #       adapter type: :sql, uri: 'postgresql://uri'
+    #     end
+    #   end
+    #
+    #   Lotus::Model.configuration.adapter_config.uri # => 'sqlite3://uri'
+    #   MyApp::Model.configuration.adapter_config.uri # => 'sqlite3://uri'
+    #   MyApi::Model.configuration.adapter_config.uri # => 'postgresql://uri'
+    def self.dupe
+      dup.tap do |duplicated|
+        duplicated.configuration = configuration.duplicate
+      end
+    end
+
+    # Duplicate the framework and generate modules for the target application
+    #
+    # @param mod [Module] the Ruby namespace of the application
+    # @param blk [Proc] an optional block to configure the framework
+    #
+    # @return [Module] a copy of Lotus::Model
+    #
+    # @since 0.2.0
+    #
+    # @see Lotus::Model#dupe
+    # @see Lotus::Model::Configuration
+    #
+    # @example Basic usage
+    #   require 'lotus/model'
+    #
+    #   module MyApp
+    #     Model = Lotus::Model.dupe
+    #   end
+    #
+    #   # It will:
+    #   #
+    #   # 1. Generate MyApp::Model
+    #   # 2. Generate MyApp::Entity
+    #   # 3. Generate MyApp::Repository
+    #
+    #   MyApp::Model      == Lotus::Model # => false
+    #   MyApp::Repository == Lotus::Repository # => false
+    #
+    # @example Block usage
+    #   require 'lotus/model'
+    #
+    #   module MyApp
+    #     Model = Lotus::Model.duplicate(self) do
+    #       adapter type: :memory, uri: 'memory://localhost'
+    #     end
+    #   end
+    #
+    #   Lotus::Model.configuration.adapter_config # => nil
+    #   MyApp::Model.configuration.adapter_config # => #<Lotus::Model::Config::Adapter:0x007ff0ff0244f8 @type=:memory, @uri="memory://localhost", @class_name="MemoryAdapter">
+    def self.duplicate(mod, &blk)
+      dupe.tap do |duplicated|
+        mod.module_eval %{
+          Entity = Lotus::Entity.dup
+          Repository = Lotus::Repository.dup
+        }
+
+        duplicated.configure(&blk) if block_given?
+      end
+    end
+
   end
 end

data/lib/lotus/model/adapters/abstract.rb

@@ -35,7 +35,8 @@ module Lotus
         #
         # @since 0.1.0
         def initialize(mapper, uri = nil)
-          @mapper, @uri = mapper, uri
+          @mapper = mapper
+          @uri    = uri
         end
 
         # Creates or updates a record in the database for the given entity.
@@ -96,7 +97,7 @@ module Lotus
           raise NotImplementedError
         end
 
-        # Returns an unique record from the given collection, with the given
+        # Returns a unique record from the given collection, with the given
         # identity.
         #
         # @param collection [Symbol] the target collection (it must be mapped).

data/lib/lotus/model/adapters/file_system_adapter.rb

@@ -0,0 +1,272 @@
+require 'thread'
+require 'pathname'
+require 'lotus/model/adapters/memory_adapter'
+
+module Lotus
+  module Model
+    module Adapters
+      # In memory adapter with file system persistence.
+      # It behaves like the SQL adapter, but it doesn't support all the SQL
+      # features offered by that kind of databases.
+      #
+      # This adapter SHOULD be used only for development or testing purposes.
+      # Each read/write operation is wrapped by a `Mutex` and persisted to the
+      # disk.
+      #
+      # For those reasons it's really unefficient, but great for quick
+      # prototyping as it's schema-less.
+      #
+      # It works exactly like the `MemoryAdapter`, with the only difference
+      # that it persist data to the disk.
+      #
+      # The persistence policy uses Ruby `Marshal` `dump` and `load` operations.
+      # Please be aware of the limitations this model.
+      #
+      # @see Lotus::Model::Adapters::Implementation
+      # @see Lotus::Model::Adapters::MemoryAdapter
+      # @see http://www.ruby-doc.org/core/Marshal.html
+      #
+      # @api private
+      # @since 0.2.0
+      class FileSystemAdapter < MemoryAdapter
+        # Default writing mode
+        #
+        # Binary, write only, create file if missing or erase if don't.
+        #
+        # @see http://ruby-doc.org/core/File/Constants.html
+        #
+        # @since 0.2.0
+        # @api private
+        WRITING_MODE = File::WRONLY|File::BINARY|File::CREAT
+
+        # Default chmod
+        #
+        # @see http://en.wikipedia.org/wiki/Chmod
+        #
+        # @since 0.2.0
+        # @api private
+        CHMOD        = 0644
+
+        # File scheme
+        #
+        # @see https://tools.ietf.org/html/rfc3986
+        #
+        # @since 0.2.0
+        # @api private
+        FILE_SCHEME  = 'file:///'.freeze
+
+        # Initialize the adapter.
+        #
+        # @param mapper [Object] the database mapper
+        # @param uri [String] the connection uri
+        #
+        # @return [Lotus::Model::Adapters::FileSystemAdapter]
+        #
+        # @see Lotus::Model::Mapper
+        #
+        # @api private
+        # @since 0.2.0
+        def initialize(mapper, uri)
+          super
+          prepare(uri)
+
+          @_mutex = Mutex.new
+        end
+
+        # Returns all the records for the given collection
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Array] all the records
+        #
+        # @api private
+        # @since 0.2.0
+        def all(collection)
+          _synchronize do
+            read(collection)
+            super
+          end
+        end
+
+        # Returns a unique record from the given collection, with the given
+        # id.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param id [Object] the identity of the object.
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.2.0
+        def find(collection, id)
+          _synchronize do
+            read(collection)
+            super
+          end
+        end
+
+        # Returns the first record in the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Object] the first entity
+        #
+        # @api private
+        # @since 0.2.0
+        def first(collection)
+          _synchronize do
+            read(collection)
+            super
+          end
+        end
+
+        # Returns the last record in the given collection.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @return [Object] the last entity
+        #
+        # @api private
+        # @since 0.2.0
+        def last(collection)
+          _synchronize do
+            read(collection)
+            super
+          end
+        end
+
+        # Creates a record in the database for the given entity.
+        # It assigns the `id` attribute, in case of success.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id=] the entity to create
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.2.0
+        def create(collection, entity)
+          _synchronize do
+            super
+            write(collection)
+          end
+        end
+
+        # Updates a record in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id] the entity to update
+        #
+        # @return [Object] the entity
+        #
+        # @api private
+        # @since 0.2.0
+        def update(collection, entity)
+          _synchronize do
+            super
+            write(collection)
+          end
+        end
+
+        # Deletes a record in the database corresponding to the given entity.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param entity [#id] the entity to delete
+        #
+        # @api private
+        # @since 0.2.0
+        def delete(collection, entity)
+          _synchronize do
+            super
+            write(collection)
+          end
+        end
+
+        # Deletes all the records from the given collection and resets the
+        # identity counter.
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        #
+        # @api private
+        # @since 0.2.0
+        def clear(collection)
+          _synchronize do
+            super
+            write(collection)
+          end
+        end
+
+        # Fabricates a query
+        #
+        # @param collection [Symbol] the target collection (it must be mapped).
+        # @param blk [Proc] a block of code to be executed in the context of
+        #   the query.
+        #
+        # @return [Lotus::Model::Adapters::Memory::Query]
+        #
+        # @see Lotus::Model::Adapters::Memory::Query
+        #
+        # @api private
+        # @since 0.2.0
+        def query(collection, context = nil, &blk)
+          # _synchronize do
+            read(collection)
+            super
+          # end
+        end
+
+        # Database informations
+        #
+        # @return [Hash] per collection informations
+        #
+        # @api private
+        # @since 0.2.0
+        def info
+          @collections.each_with_object({}) do |(collection,_), result|
+            result[collection] = query(collection).count
+          end
+        end
+
+        private
+        # @api private
+        # @since 0.2.0
+        def prepare(uri)
+          @root = Pathname.new(uri.sub(FILE_SCHEME, ''))
+          @root.mkpath
+        end
+
+        # @api private
+        # @since 0.2.0
+        def _synchronize
+          @_mutex.synchronize { yield }
+        end
+
+        # @api private
+        # @since 0.2.0
+        def write(collection)
+          path = @root.join("#{ collection }")
+          path.open(WRITING_MODE, CHMOD) {|f| f.write _dump( @collections.fetch(collection) ) }
+        end
+
+        # @api private
+        # @since 0.2.0
+        def read(collection)
+          path = @root.join("#{ collection }")
+          @collections[collection] = _load(path.read) if path.exist?
+        end
+
+        # @api private
+        # @since 0.2.0
+        def _dump(contents)
+          Marshal.dump(contents)
+        end
+
+        # @api private
+        # @since 0.2.0
+        def _load(contents)
+          Marshal.load(contents)
+        end
+      end
+    end
+  end
+end