hexx 5.4.0 → 6.0.0

data/lib/hexx/dependable.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+
+module Hexx
+
+  # Makes the class dependable from implementations through setter injections.
+  #
+  # Adds the private {#depends_on} helper method to the class.
+  # Basically the method is similar to the +attr_accessor+ with the following
+  # differencies:
+  #
+  # * it adds a semantics to the declaration.
+  # * it allows setting the default implementation.
+  # * dependency setters accepts classes and modules only and fails with
+  #   the +TypeError+ otherwise.
+  # * dependency getters fails with the +NotImplemented+ error if the
+  #   implementation hasn't been set.
+  # * if a default implementation is defined, the dependency cannot be
+  #   set to +nil+.
+  #
+  # @example
+  #   class MyClass
+  #     extend Hexx::Dependable
+  #
+  #     depends_on :another_class, default: AnotherClass
+  #     depends_on :looks_for_implementation
+  #   end
+  #
+  #   object = MyClass.new
+  #   object.another_class # => AnotherClass
+  #
+  #   object.looks_for_implementation
+  #   # => fails with NotImplementedError
+  #
+  #   object.looks_for_implementation = SomeInjection
+  #   object.looks_for_implementation # => SomeInjection
+  module Dependable
+
+    private
+
+    # @!method depends_on(name, options = {})
+    # Declares the dependency with its default implementation.
+    # @example (see Hexx::Dependable)
+    # @param   [String, Symbol] name The name of the dependency.
+    # @param   [Hash] options ({}) The dependency declaration options.
+    # @option  options [String, Symbol, Class] :default (nil) Optional default
+    #   implementation for the dependency.
+    def depends_on(name, default: nil)
+      Helpers::Dependency.add self, name, default
+    end
+  end
+end

data/lib/hexx/helpers/base.rb

@@ -0,0 +1,111 @@
+# encoding: utf-8
+
+module Hexx
+
+  # @api hide
+  # The module contains helper classes and modules.
+  #
+  # All the helpers injects some code into corresponding class or module.
+  #
+  # The content of the module is not a part of API, but its implementation
+  # details.
+  module Helpers
+
+    # @api hide
+    # @abstract
+    # The base class for attribute injection.
+    #
+    # The objects of the class validates its parameters and adds
+    # attribute's getter and setter into the target class or module.
+    class Base < Struct.new(:target, :name)
+
+      # @api hide
+      # @!method add(target, name)
+      # Injects an attribute to the target class.
+      #
+      # @param  [Module] target The class or module to inject the attribute to.
+      # @param  [String, Symbol] name The name of the attribute.
+      # @raise  (see Hexx::Helpers::Base#validate)
+      # @return [Hexx::Helpers::Base] the base class object.
+      def self.add(*args)
+        new(*args).validate.add_getter.add_setter
+      end
+
+      # @api hide
+      # @!attribute target
+      # The class to inject the attribute to
+      # @return [Class] the target for the injection
+
+      # @api hide
+      # @!attribute name
+      # The name of the attribute to be created in a target class
+      # @return [Class] the name of the attribute
+
+      # @api hide
+      # Validates parameters of the dependency declaration.
+      #
+      # @raise  (see Hexx::Helpers::Base#check_target)
+      # @raise  (see Hexx::Helpers::Base#check_name_type)
+      # @raise  (see Hexx::Helpers::Base#check_name_value)
+      # @return [Hexx::Helpers::Base] +self+
+      def validate
+        check_target
+        check_name_type
+        check_name_value
+        self
+      end
+
+      # @api hide
+      # Adds the parameter getter to the +target+ instance
+      # @return [Hexx::Helpers::Base] +self+
+      def add_getter
+        target.class_eval getter
+        self
+      end
+
+      # @api hide
+      # Adds the parameter setter to the +target+ instance
+      # @return [Hexx::Helpers::Base] +self+
+      def add_setter
+        target.class_eval setter
+        self
+      end
+
+      private
+
+      # @abstract
+      # @return [String] the getter definition
+      def getter
+        ""
+      end
+
+      # @abstract
+      # @return [String] the setter definition
+      def setter
+        ""
+      end
+
+      # @api hide
+      # @raise [TypeError] if a target to add the instance parameter to
+      #   is not a class.
+      def check_target
+        return if target.is_a? Class
+        fail TypeError.new "#{ target.inspect } is not a class"
+      end
+
+      # @api hide
+      # @raise [TypeError] if the attribute name is neither a string nor symbol.
+      def check_name_type
+        return if name.is_a?(String) || name.is_a?(Symbol)
+        fail TypeError.new "#{ name.inspect } is neither string nor symbol"
+      end
+
+      # @api hide
+      # @raise [AttributeError] it the name is blank.
+      def check_name_value
+        return unless name.to_s == ""
+        fail ArgumentError.new "Dependency should have a name"
+      end
+    end
+  end
+end

data/lib/hexx/helpers/coersion.rb

@@ -0,0 +1,82 @@
+# encoding: utf-8
+require_relative "base"
+
+module Hexx
+  module Helpers
+
+    # @api hide
+    # Coerces class attribute getter and setter with given type.
+    #
+    # @example
+    #   Coersion.add MyClass, :name, Multibyte::Chars
+    #   object = MyClass.new
+    #
+    #   object.name = "Ivo"
+    #   object.name
+    #   # => #<Multibyte::Chars @wrapped_string="Ivo" >
+    class Coersion < Base
+
+      # @api hide
+      # @!scope class
+      # @!method add(target, name, type)
+      # Reloads the Base class initializer by adding the type of the attribute
+      # to coerce with.
+      #
+      # @example (see Hexx::Helpers::Coersion)
+      # @param  (see Hexx::Helpers::Base.add)
+      # @param  [Module] type The type of the attribute.
+      # @raise  (see Hexx::Helpers::Coersion#validate)
+      # @return [Hexx::Helpers::Coersion] the coersion object.
+      def initialize(target, name, type)
+        super target, name
+        @type = type
+      end
+
+      # @!attribute type
+      # The type to coerce the attribute with
+      # @return [Class] the type of the attribute
+      attr_accessor :type
+
+      # @api hide
+      # Validates parameters of the coersion declaration.
+      #
+      # Adds validation of the coersion type to the
+      # {Hexx::Helper::Base#validate}.
+      #
+      # @raise  (see Hexx::Helpers::Base.validate)
+      # @raise  (see Hexx::Helpers::Coersion#check_type)
+      # @return [Hexx::Helpers::Coersion] +self+
+      def validate
+        check_type
+        super
+      end
+
+      private
+
+      # @api hide
+      # The definition of the coerced attribute getter.
+      # To be reloaded for ActiveRecord models.
+      def getter
+        "def #{ name }=(value);
+           @#{ name } = #{ type.name }.new(value);
+         end"
+      end
+
+      # @api hide
+      # The definition of the coerced attribute setter.
+      # To be reloaded for ActiveRecord models.
+      def setter
+        "def #{ name };
+           #{ type.name }.new(@#{ name });
+         end"
+      end
+
+      # @api hide
+      # @raise [TypeError] if type is not a class
+      def check_type
+        return if type.is_a? Class
+        fail TypeError.new "#{ type.inspect } is not a class"
+      end
+    end
+  end
+end

data/lib/hexx/helpers/dependency.rb

@@ -0,0 +1,87 @@
+# encoding: utf-8
+require_relative "base"
+
+module Hexx
+  module Helpers
+
+    # @api hide
+    # @abstract
+    # The base class for both instance and module dependencies.
+    class Dependency < Base
+
+      # @api hide
+      # @!scope class
+      # @!method add(target, name, default)
+      # Reloads the Base class initializer by adding the default implementation
+      # for the dependency.
+      #
+      # @param  (see Hexx::Helpers::Base)
+      # @param  [Module] default The default implementation for the dependency.
+      # @raise  (see Hexx::Helpers::Dependency#validate)
+      # @return [Hexx::Helpers::Dependency] the dependency object.
+      def initialize(target, name, default)
+        super target, name
+        @default = default
+      end
+
+      # @!attribute default
+      # The default implementation for the dependency
+      # @return [Module] the default implementation
+      attr_accessor :default
+
+      # @api hide
+      # Validates parameters for the dependency declaration.
+      #
+      # Adds validation of the dependency default implementation to the
+      # {Hexx::Helper::Base#validate}.
+      #
+      # @raise  (see Hexx::Helpers::Base#validate)
+      # @raise  (see Hexx::Helpers::Dependency#check_default)
+      # @return [Hexx::Helpers::Dependency] +self+
+      def validate
+        check_default
+        super
+      end
+
+      private
+
+      # @api hide
+      # The dependency getter
+      def getter
+        "def #{ name };
+           @#{ name } ||= #{ default_name };
+           return @#{ name } if @#{ name };
+           fail NotImplementedError
+             .new \"DI: #{ target.name }##{ name } not implemented\";
+         end"
+      end
+
+      # @api hide
+      # The dependency setter
+      def setter
+        "def #{ name }=(value);
+           if value.nil? || value.is_a?(Module);
+             @#{ name } = value;
+             #{ name };
+           else;
+             fail TypeError.new \"DI: value.inspect is not a module\";
+           end;
+         end"
+      end
+
+      # @api hide
+      # @raise [TypeError] if the default implementation is neither a class,
+      #   nor module
+      def check_default
+        return if default.nil? || default.is_a?(Module)
+        fail TypeError.new "#{ default.inspect } is neither a class nor module"
+      end
+
+      # @api hide
+      # Returns the name of the default implementation of the dependency.
+      def default_name
+        @default_name ||= default ? default.name : "nil"
+      end
+    end
+  end
+end

data/lib/hexx/helpers/module_dependency.rb

@@ -0,0 +1,57 @@
+# encoding: utf-8
+require_relative "dependency"
+
+module Hexx
+  module Helpers
+
+    # @api hide
+    # Module dependency constructor.
+    #
+    # Adds the dependency to selected module.
+    #
+    # @example
+    #   ModuleDependency.add(MyModule, :some_module, DefaultImplementation)
+    #
+    #   MyModule.some_module
+    #   # => DefaultImplementation
+    #
+    #   MyModule.some_module = AnotherImplementation
+    #   # => AnotherImplementation
+    #
+    #   MyModule.some_module = 1
+    #   # fails with #<TypeError @message="1 is not a module" >
+    class ModuleDependency < Dependency
+
+      # @api hide
+      # Adds the dependency to given module
+      # @example (see Hexx::Helpers::ModuleDependency)
+      # @param [Module] target The module to declare the dependency of.
+      # @param [String, Symbol] name The name of the dependency.
+      # @param [Module] default The default implementation of the dependency.
+
+      # @api hide
+      # Adds the module dependency getter
+      # @return [ModuleDependency] +self+.
+      def add_getter
+        target.instance_eval getter
+        self
+      end
+
+      # @api hide
+      # Adds the module dependency setter
+      # @return [ModuleDependency] +self+.
+      def add_setter
+        target.instance_eval setter
+        self
+      end
+
+      private
+
+      # @raise [TypeError] if a target to add the dependency is not a module.
+      def check_target
+        return if target.is_a? Module
+        fail TypeError.new "#{ target.inspect } is not a module"
+      end
+    end
+  end
+end

data/lib/hexx/helpers/parameter.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+require_relative "base"
+
+module Hexx
+  module Helpers
+
+    # @api hide
+    # Adds setter and getter for the instance parameter.
+    #
+    # @example
+    #   # Providing that MyClass#params returns a hash
+    #   Parameter.add MyClass, :name
+    #   object = MyClass.new
+    #
+    #   object.params["name"] # => nil
+    #   object.name           # => nil
+    #
+    #   object.params["name"] = "Ivan"
+    #   object.params["name"] # => "Ivan"
+    #   object.name           # => "Ivan"
+    #
+    #   object.name = "Ivo"
+    #   object.params["name"] # => "Ivo"
+    #   object.name           # => "Ivo"
+    class Parameter < Base
+
+      private
+
+      # @api hide
+      def setter
+        "def #{ name }; params[\"#{ name }\"]; end"
+      end
+
+      # @api hide
+      def getter
+        "def #{ name }=(value); params[\"#{ name }\"] = value; end"
+      end
+    end
+  end
+end

data/lib/hexx/service.rb

@@ -1,4 +1,5 @@
 # encoding: utf-8
+require_relative "dependable"
 
 module Hexx
 
@@ -19,24 +20,99 @@ module Hexx
   #   service.run
   #   # => This will call the listener's method #on_found(item).
   class Service
+    extend Dependable
     include Wisper::Publisher
     include ActiveModel::Validations
-    include Parameters
 
-    # @!scope class
-    # @!method new(options = {})
-    # Constructs the service object.
+    # @api hide
+    # Returns the list of allowed parameters for service objects.
+    #
+    # The parameters are added to the list by the {.allow_params} private
+    # helper method.
     #
     # @example
-    #   service = Hexx::Service.new name: name
+    #   class Service < Hexx::Service
+    #     allow_params :name
+    #   end
+    #
+    #   Service.params # => "name"
+    #
+    # @return [Array<String>] The list of allowed instance parameters.
+    def self.params
+      @params ||= []
+    end
+
+    # @!scope class
+    # @!method validates(attribute, options)
+    # Adds a standard validation for the attribute.
+    # @param [Symbol, String] attribute The name of the attribute to validate.
+    # @param [Hash] options The list of validation options.
+    # @see ActiveModel validations {APIdocs}[
+    #   http://apidock.com/rails/ActiveModel/Validations/ClassMethods/validates]
+
+    # @!scope class
+    # @!method validate(method, options)
+    # Adds a custom validation (calls given method).
+    # @param [Symbol, String] method The name of the validation method.
+    # @param [Hash] options The list of validation options.
+    # @see ActiveModel validations {APIdocs}[
+    #   http://apidock.com/rails/ActiveModel/Validations/ClassMethods/validate]
+
+    # @!scope class
+    # @!method new(params = {})
+    # Constructs the service object with given parameters.
     #
-    # @param [Hash] options The options to be assigned to the {#params}.
+    # @example (see Hexx::Service)
+    # @param [Hash] params ({}) The parameters of the service object to be
+    #   assigned to the {#params} attribute.
     # @return [Hexx::Service] The service object.
-    def initialize(options = {})
-      super(options)
+
+    # @api hide
+    # Initializes the service object.
+    # @param  (see Hexx::Service.new)
+    # @return (see Hexx::Service.new)
+    def initialize(params = {})
+      @params = params.dup.stringify_keys.slice(*(self.class.params))
       @messages = []
     end
 
+    # @!attribute [r] params
+    # The list of service object parameters.
+    #
+    # The attribute is assigned via the {.new} method options.
+    # On initialization the parameters (keys) are stringified and whitelisted.
+    #
+    # Allowed parameters should be explicitly declared with the {.allow_params}.
+    #
+    # @example Only whitelisted params are being assigned.
+    #   class GetItem < Hexx::Service
+    #     allow_params :name
+    #   end
+    #
+    #   service = GetItem.new name: "Олег", family: "Рюрикович"
+    #   service.params # => { "name" => "Олег" }
+    # @return [Hash] the service object parameters.
+
+    # @!attribute [r] messages
+    # The array of service messages (instances of {Hexx::Service::Message})
+    # with +text+ and +type+ attributes.
+    #
+    # @example
+    #   class Test < Hexx::Service
+    #     def run
+    #       add_message "info", :ok
+    #     end
+    #   end
+    #
+    #   service = Test.new
+    #   service.run # adds message
+    #   service.messages
+    #   # => [#<Hexx::Service::Message @text="ok" @type="info" >]
+    #
+    # @return [Array<Hexx::Service::Message>] The array of messages.
+
+    attr_reader :params, :messages
+
     # @!scope class
     # @!visibility private
     # @!method allow_params(*params)
@@ -54,28 +130,6 @@ module Hexx
     #
     # @param [Array<Symbol, String>] params The list of allowed keys.
 
-    # @!scope class
-    # @!method validates(attribute, options)
-    # Adds a standard validation for the attribute.
-    # @note The method is defined in the {ActiveModel::Validations} module.
-
-    # @!scope class
-    # @!method validate(method, options)
-    # Adds a custom validation (calls given method).
-    # @note The method is defined in the {ActiveModel::Validations} module.
-
-    # @!attribute params [r] The list of service object parameters.
-    #   The attribute is assigned via the {.new} method options.
-    #   The keys should be explicitly declared by the {.allow_params} helper.
-    #
-    #   @example Only whitelisted params are being assigned.
-    #     class GetItem < Hexx::Service
-    #       allow_params :name
-    #     end
-    #
-    #     service = GetItem.new name: "Олег", family: "Рюрикович"
-    #     service.params # => { "name" => "Олег" }
-
     # @!method subscribe(listener, options = {})
     # Subscribes the listener to service object's notifications.
     # The <tt>:prefix</tt> sets the prefix to be added to a notification name
@@ -90,8 +144,8 @@ module Hexx
 
     # @abstract
     # Runs the service object.
-    # @note The method does nothing and should be reloaded by a specific
-    #   service class.
+    #
+    # The method does nothing. To be reloaded by a specific service class.
     def run
     end
 
@@ -119,27 +173,18 @@ module Hexx
       WithCallbacks.new(self, prefix: prefix)
     end
 
-    # @!attribute [r] messages
-    # The array of service messages (instances of {Hexx::Service::Message})
-    # with +text+ and +type+ attributes.
-    #
-    # @example
-    #   class Test < Hexx::Service
-    #     def run
-    #       add_message "info", :ok
-    #     end
-    #   end
-    #
-    #   service = Test.new
-    #   service.run # adds message
-    #   service.messages
-    #   # => [#<Hexx::Service::Message @text="ok" @type="info" >]
-    #
-    # @return [Array<Hexx::Service::Message>] The array of messages.
-    attr_reader :messages
-
     private
 
+    # Sets a list of allowed parameters for the class constructor and
+    # defines the corresponding instance attributes.
+    #
+    # @example (see Hexx::Service::Parameters.params)
+    # @param [Array<Symbol, String>] keys The list of allowed parameters.
+    def self.allow_params(*keys)
+      @params = keys.map(&:to_s)
+      params.each { |name| Helpers::Parameter.add self, name }
+    end
+
     # The helper runs another service object and subscribes +self+ for the
     # service object's notifications.
     #