mimi-core 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6d247ba31bb61a81362ff2cb8d260d0a1b718bb9
-  data.tar.gz: 332bd926feab1cdfd99e49e24c6a3b713c2ce254
+  metadata.gz: 4386bcac3a69eeb1f5a0422c445ba509e735ea4a
+  data.tar.gz: 6c583235d2e0069d255c0598b3e2cce4f4631bcb
 SHA512:
-  metadata.gz: fcbb60ca621ead3705f57f73216d6952461cebbd592a5891a755ebe0d09be9f2fd0ab88ec437671f289e2e1bf8eade0f994888744df9c2aa78e2f5084a00252d
-  data.tar.gz: 10df7f41b424a2fec0e460a2f242612ab7d23e508fbfe22428ca2f71cd4c5cb9fb480e81a05ac0807398266e90069b0a9ccd4bcb84d71ef7d36a823f63c53ec8
+  metadata.gz: d234685fd746173702527047e71aaa0c0d237da588e84b1de2f0fa23ecd74cca832569b91729af0e5968e53807d06d6eafb6077c73ac73d454cdfaa9ea041e92
+  data.tar.gz: db3ece3e5d363f942ebd3d98ff92b2c286fc198f74261378dcee0d1b67e38d4dd3f88fbbb443e3f2c648623dc85c2eefd679f6fc59a94f16f65bd8cf4e35533a

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/README.md

@@ -1,8 +1,205 @@
 # mimi-core
 
-Core module for *mimi*, microframework for microservices.
+Core module of the [Mimi framework](Mimi).
 
-[in development]
+`mimi-core` defines the top-level Mimi namespace, provides a base for Mimi modules
+and offers some core extentions.
+
+
+## Mimi namespace
+
+At the top of hierarchy of the Mimi components there is a `Mimi` module that binds all components of the
+framework together. It allows Mimi modules to be used (included in the stack and configured), started
+and stopped.
+
+```ruby
+require 'mimi/core'
+
+Mimi # => Module
+```
+
+### Mimi.use(mod)
+
+Configures the given module and appends it to the list of **used modules**.
+
+### Mimi.start
+
+Starts the used modules in the order of appending.
+
+### Mimi.stop
+
+Stops the used modules in reverse order.
+
+### Example
+
+```ruby
+require 'mimi/db'
+
+Mimi.use Mimi::DB, db_adapter: 'sqlite', db_database: 'tmp/dev.db'
+Mimi.start
+
+Mimi.app_root_path # => <Pathname> -- guesses current application's root
+```
+
+## Mimi::Core::Module
+
+`Mimi::Core::Module` is a base for any Mimi module.
+
+Mimi modules are pluggable components that you can include in your applications.
+They provide some useful functionality, e.g. database abstraction layer, logging etc.
+
+Any Mimi module provides a standard list of methods to interact with it:
+
+```
+.configure(opts)
+.start
+.stop
+```
+
+A Mimi module is typically packaged as a gem and it can declare a `module_root_path`.
+Under this path the module may export some files, related to the module's offered functionality.
+For example `Mimi::DB` exposes some rake tasks to perform database clearing, migrations etc.
+
+
+### Creating a new module
+
+A Mimi component module can be created by including `Mimi::Core::Module` in a module or class
+of yours:
+
+```ruby
+# my_module.rb
+
+require 'mimi-core'
+
+module MyModule
+  include Mimi::Core::Module
+end
+
+Mimi.use MyModule, param: 1 # invokes MyModule.configure(param: 1)
+Mimi.start                  # invokes MyModule.start
+```
+
+
+### Configuring a module
+
+A Mimi module implements a `.manifest`, `.configure` and `.options` class methods.
+
+The `.configure` class method accepts a Hash of configurable parameter values and sets the options Hash
+available via `.options` class method. Which parameters can be set and whether there are any default
+values for the parameters is defined by the module *manifest*.
+
+```ruby
+Mimi.configure(param: 1)
+Mimi.options[:param] # => 1
+```
+
+### Module manifest
+
+The original `.configure` implementation in `Mimi::Core::Module` takes into consideration the
+module *manifest*.
+
+Module manifest is a set of formal definitions of configurable parameters.
+
+The manifest declares which configurable parameters are accepted by the module,
+which types of values are accepted, which are default values and so on.
+
+When designing your own module, you should redefine `.manifest` method to contain
+your module's actual manifest. The `.manifest` class method should return a Hash representation of the module manifest,
+where keys define the configurable parameter names, and values are Hash-es with the configurable parameter
+properties:
+
+
+```ruby
+# my_module.rb
+
+require 'mimi-core'
+
+module MyModule
+  include Mimi::Core::Module
+
+  def self.manifest
+    {
+      param1: {} # minimal definition of a configurable parameter
+    }
+  end
+end
+
+Mimi.configure(param: 1)
+Mimi.options[:param] # => 1
+```
+
+Recognised configurable parameter properties are:
+
+* `:desc` -- (default: `nil`) human readable description
+* `:type` -- (default: `:string`) accepted value type
+* `:default` -- (default: `nil`) default value for configurable parameter
+* `:const` -- (default: `false`) makes the configurable parameter constant
+* `:hidden` -- (default: `false`) omits the configurable parameter from a combined manifest
+
+
+Example:
+
+```ruby
+def self.manifest
+  {
+    param1: {
+      desc: 'My configurable param1',
+      type: :integer,
+      default: 1
+    },
+  }
+end
+```
+
+@see Mimi::Core::Manifest
+
+## Useful extensions
+
+`mimi-core` gem contains some useful extensions which are included automatically, once the gem
+is *require*-d:
+
+* Mimi::Core::InheritableProperty
+* Array and Hash extensions
+
+### Mimi::Core::InheritableProperty
+
+Makes `.inheritable_property` method available to the class.
+
+Example:
+
+```ruby
+class A
+  include Mimi::Core::InheritableProperty
+
+  inheritable_property :my_var
+end
+```
+@see Mimi::Core::InheritableProperty::ClassMethods#inheritable_property
+
+
+### Array and Hash extensions
+
+`Array` extensions:
+
+```
+Array#only(*values)     # select array elements only if listed in 'values'
+Array#only!(*values)    # as above, modify array in-place
+Array#except(*values)   # reject array elements listed in 'values'
+Array#except!(*values)  # as above, modify array in-place
+```
+
+`Hash` extensions:
+
+```
+Hash#only(*keys)        # keep only those key-value pairs of the Hash which keys are listed in 'keys'
+Hash#only!(*keys)       # as above, modify Hash in-place
+Hash#except(*keys)      # reject key-value pairs of the Hash which keys are listed in 'keys'
+Hash#except!(*keys)     # as above, modify Hash in-place
+Hash#deep_merge(other)  # deep-merges another Hash
+Hash#deep_dup           # deep-duplicates a Hash, taking care of nested Hashes and Arrays
+Hash#deep_symbolize_keys
+Hash#deep_stringify_keys
+```
 
 ## License
 

data/lib/mimi/core/core_ext.rb

@@ -1,5 +1,5 @@
-require 'active_support'
-require 'active_support/core_ext'
+# frozen_string_literal: true
+
 require 'hashie'
 
 class Hash
@@ -9,6 +9,10 @@ class Hash
     end
 
     def only!(*keys)
+      if keys.size == 1 && keys.first.is_a?(Array)
+        raise ArgumentError, 'Hash#only!() expects keys as list of arguments,' \
+          ' not an Array as first argument'
+      end
       select! { |k, _| keys.include?(k) }
       self
     end
@@ -20,6 +24,10 @@ class Hash
     end
 
     def except!(*keys)
+      if keys.size == 1 && keys.first.is_a?(Array)
+        raise ArgumentError, 'Hash#except!() expects keys as list of arguments,' \
+          ' not an Array as first argument'
+      end
       reject! { |k, _| keys.include?(k) }
       self
     end
@@ -28,6 +36,69 @@ class Hash
   unless instance_methods(false).include?(:deep_merge)
     include Hashie::Extensions::DeepMerge
   end
+
+  unless instance_methods(false).include?(:deep_dup)
+    def deep_dup
+      map do |k, v|
+        v = v.respond_to?(:deep_dup) ? v.deep_dup : v.dup
+        [k, v]
+      end.to_h
+    end
+  end
+
+  unless instance_methods(false).include?(:symbolize_keys)
+    def symbolize_keys
+      map do |k, v|
+        k = k.respond_to?(:to_sym) ? k.to_sym : k
+        [k, v]
+      end.to_h
+    end
+
+    def symbolize_keys!
+      replace(symbolize_keys)
+    end
+  end
+
+  unless instance_methods(false).include?(:deep_symbolize_keys)
+    def deep_symbolize_keys
+      map do |k, v|
+        k = k.respond_to?(:to_sym) ? k.to_sym : k
+        v = v.respond_to?(:deep_symbolize_keys) ? v.deep_symbolize_keys : v
+        [k, v]
+      end.to_h
+    end
+
+    def deep_symbolize_keys!
+      replace(deep_symbolize_keys)
+    end
+  end
+
+  unless instance_methods(false).include?(:stringify_keys)
+    def stringify_keys
+      map do |k, v|
+        k = k.respond_to?(:to_s) ? k.to_s : k
+        [k, v]
+      end.to_h
+    end
+
+    def stringify_keys!
+      replace(stringify_keys)
+    end
+  end
+
+  unless instance_methods(false).include?(:deep_stringify_keys)
+    def deep_stringify_keys
+      map do |k, v|
+        k = k.respond_to?(:to_s) ? k.to_s : k
+        v = v.respond_to?(:deep_stringify_keys) ? v.deep_stringify_keys : v
+        [k, v]
+      end.to_h
+    end
+
+    def deep_stringify_keys!
+      replace(deep_stringify_keys)
+    end
+  end
 end
 
 class Array
@@ -37,6 +108,10 @@ class Array
     end
 
     def only!(*keys)
+      if keys.size == 1 && keys.first.is_a?(Array)
+        raise ArgumentError, 'Array#only!() expects keys as list of arguments,' \
+          ' not an Array as first argument'
+      end
       select! { |k| keys.include?(k) }
       self
     end
@@ -48,8 +123,20 @@ class Array
     end
 
     def except!(*keys)
+      if keys.size == 1 && keys.first.is_a?(Array)
+        raise ArgumentError, 'Array#except!() expects keys as list of arguments,' \
+          ' not an Array as first argument'
+      end
       reject! { |k| keys.include?(k) }
       self
     end
   end
+
+  unless instance_methods(false).include?(:deep_dup)
+    def deep_dup
+      map do |v|
+        v.respond_to?(:deep_dup) ? v.deep_dup : v.dup
+      end
+    end
+  end
 end

data/lib/mimi/core/inheritable_property.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Mimi
+  module Core
+    #
+    # Makes `.inheritable_property` method available to the class.
+    #
+    # Example:
+    #
+    # ```
+    # class A
+    #   include Mimi::Core::InheritableProperty
+    #
+    #   inheritable_property :my_var
+    # end
+    # ```
+    # @see Mimi::Core::InheritableProperty::ClassMethods#inheritable_property
+    #
+    module InheritableProperty
+      def self.included(base)
+        base.send :extend, ClassMethods
+      end
+
+      module ClassMethods
+        #
+        # Declares an inheritable property.
+        #
+        # The inheritable property is a special class variable, that is accessible
+        # in descendant classes, but each of the descendant classes can alter only its local value.
+        #
+        # Once a property is declared, a class method with the name of the property
+        # becomes available.
+        #
+        # ```
+        # class A
+        #   include Mimi::Core::InheritableProperty
+        #
+        #   inheritable_property :var1, default: 1
+        # end
+        #
+        # class B < A
+        # end
+        #
+        # A.var1 # => 1
+        # B.var1 # => 1
+        # ```
+        #
+        # A class method with the name of the property accepts one optional argument -- a new value
+        # for the property. If the argument is omitted, current inherited value is returned.
+        #
+        # If the argument is present, it sets a new property value for this class
+        # and its subclasses, but not for the parent class.
+        #
+        # ```
+        # class A
+        #   include Mimi::Core::InheritableProperty
+        #
+        #   inheritable_property :var1, default: 1
+        # end
+        #
+        # class B < A
+        #   var1 123 # sets new value for B.var1
+        # end
+        #
+        # class C < B
+        # end
+        #
+        # A.var1 # => 1, the default value, unchanged
+        # B.var1 # => 123
+        # C.var1 # => 123
+        # ```
+        #
+        # Working with Hash values
+        # ===
+        # An `inherited_property` can be declared having the type `:hash`, then the inherited
+        # values are deep-merged in subclasses.
+        #
+        # ```
+        # class A
+        #   include Mimi::Core::InheritableProperty
+        #
+        #   inheritable_property :var1, default: { a: 1 }
+        # end
+        #
+        # class B < A
+        #   var1 b: 2
+        # end
+        #
+        # class C < B
+        # end
+        #
+        # A.var1 # => { a: 1 }
+        # B.var1 # => { a: 1, b: 2 }
+        # C.var1 # => { a: 1, b: 2 }
+        # ```
+        #
+        # Proc as default value
+        # ===
+        # A Proc can be specified instead of literal default value, in which case it will
+        # be evaluated when the inherited property value is queried. The passed block will
+        # be evaluated in the context of the current class.
+        #
+        # ```
+        # class A
+        #   include Mimi::Core::InheritableProperty
+        #
+        #   inheritable_property :var1, default: -> { self.name }
+        # end
+        #
+        # class B < A
+        # end
+        #
+        # class C < B
+        # end
+        #
+        # A.var1 # => "A"
+        # B.var1 # => "B"
+        # ```
+        #
+        # @param name [Symbol] a name for the new inheritable property
+        # @param opts [Hash,nil] optional parameters for the inheritable property
+        # @option opts [Object,Proc] :default specifies the literal or Proc as the default value
+        #   for the property
+        # @option opts [:hash,nil] :type instructs that the property is a Hash or a simple value
+        #   (inherited values are deep-merged for Hash'es)
+        #
+        def inheritable_property(name, opts = {})
+          unless name.is_a?(Symbol)
+            raise ArgumentError, 'Symbol is expected as inheritable_property name'
+          end
+          var_name = :"@#{name}"
+          ip_get_name = :"inheritable_property_get_#{name}"
+          ip_set_name = :"inheritable_property_set_#{name}"
+          opts_default = opts[:default] && opts[:default].dup
+
+          define_singleton_method(ip_get_name) do |caller|
+            if opts[:type] == :hash
+              # combine this class' value with a superclass' value
+              self_value = instance_variable_get(var_name) || {}
+              super_value =
+                (superclass.respond_to?(ip_get_name) && superclass.send(ip_get_name, caller)) ||
+                (opts_default.is_a?(Proc) ? caller.instance_exec(&opts_default) : opts_default)
+              super_value.deep_merge(self_value)
+            else
+              instance_variable_get(var_name) ||
+                (superclass.respond_to?(ip_get_name) && superclass.send(ip_get_name, caller)) ||
+                (opts_default.is_a?(Proc) ? caller.instance_exec(&opts_default) : opts_default)
+            end
+          end
+
+          define_singleton_method(ip_set_name) do |arg|
+            if opts[:type] == :hash && !arg.is_a?(Hash) && !arg.nil?
+              raise ArgumentError, "Hash or nil is expected as a value for property #{self}.#{name}"
+            end
+            instance_variable_set(var_name, arg)
+          end
+
+          define_singleton_method(name) do |*args|
+            if args.empty?
+              send(:"inheritable_property_get_#{name}", self)
+            else
+              send(:"inheritable_property_set_#{name}", args.first)
+            end
+          end
+
+          define_singleton_method("#{name}!".to_sym) do
+            send(name) || (raise "Property #{self}.#{name} is not set")
+          end
+        end
+      end # module ClassMethods
+    end # module InheritableProperty
+  end # module Core
+end # module Mimi