otoroshi 0.0.3 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cec895aa30d2fb89c0b824b38c2b0b710558419aa7ef1308769b8550969924ba
-  data.tar.gz: a8f06adce33632af173d95282440685ab009c6095f6db889e21b25ffd4cccb40
+  metadata.gz: fba1623080c055e87c2055001a7f2370e459b5fe1a28774375cef3dd9e7da802
+  data.tar.gz: 4c01c52a123157e572b4fdcef7c2e7eb6f0cc6ef2162e49237b5a49785708b70
 SHA512:
-  metadata.gz: 581a9bb26d5c1f861fa5f3c0e60d554c9a4f0e2f47c17df3856d957202ab1909ec74da411b2f0878c7ab0f0e59e904c1220b77e71f67dc1543a5959da0aa3f77
-  data.tar.gz: 7811ee410f737e3f53d133eee22d62d0ed1e6b140d45801cad33aff475ced6a2e6b1e91acd92b4047f4c38c12b53ce64256dd935a3571e49758fa41f760d2e75
+  metadata.gz: 8b89127bff4d54b14be27fe723db61e6f0786b7f0f9f6d4df612ed49b3d86d59f1a1df55038178662e5ce247c4b2f6af16b35e05650730d8b9889debd354ed48
+  data.tar.gz: 177fbc07e846a1cb9cbc7b3e595ce5c0878ff153d6293d9e0ccf986745a0b898e3b2a9be144218b97425ad87b78b4170848b20496ca39bf232ee898f5b1fcb19

data/lib/otoroshi.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'otoroshi/sanctuary'
+require_relative 'otoroshi/exceptions'
+
+# Otoroshi entry-point
+#
+module Otoroshi; end

data/lib/otoroshi/exceptions.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Otoroshi
+  class Error < StandardError; end
+
+  # Manages errors raised when value type is not as expected
+  class WrongTypeError < Error
+    # Initialize an error
+    #
+    # @param property [Symbol] name of the property
+    # @param type [Class] class to match
+    # @param collection [true, false] define if it is a collection
+    def initialize(property, type, collection: false)
+      expected_type = type.is_a?(Array) ? type.first || Object : type
+      msg =
+        if collection
+          ":#{property} contains elements that are not instances of #{expected_type}"
+        else
+          ":#{property} is not an instance of #{expected_type}"
+        end
+      super(msg)
+    end
+  end
+
+  # Manages errors raised when value should be an collection
+  class NotAnArray < Error
+    # Initialize an error
+    #
+    # @param property [Symbol] name of the property
+    def initialize(property)
+      msg = ":#{property} is not an array"
+      super(msg)
+    end
+  end
+
+  # Manages errors raised when value is not accepted (not included in the "one_of")
+  class NotAcceptedError < Error
+    # Initialize an error
+    #
+    # @param property [Symbol] name of the property
+    # @param accepted_values [Array] accepted values
+    # @param collection [true, false] define if it is an collection
+    def initialize(property, accepted_values, collection: false)
+      # reintegrate the colon for symbols which is lost during interpolation
+      to_s = ->(v) { v.is_a?(Symbol) ? ":#{v}" : v }
+      accepted_values_list = accepted_values.map { |v| to_s.call(v) }.join(', ')
+      msg =
+        if collection
+          ":#{property} contains elements that are not included in [#{accepted_values_list}]"
+        else
+          ":#{property} is not included in [#{accepted_values_list}]"
+        end
+      super(msg)
+    end
+  end
+
+  # Manages errors raised when value does not pass the assertion
+  class AssertionError < Error
+    # Initialize an error
+    #
+    # @param property [Symbol] name of the property
+    # @param collection [true, false] define if it is an collection
+    def initialize(property, collection: false)
+      msg =
+        if collection
+          ":#{property} contains elements that do not respect the assertion"
+        else
+          ":#{property} does not respect the assertion"
+        end
+      super(msg)
+    end
+  end
+end

data/lib/otoroshi/initializer.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Otoroshi
+  # Drawing of #initialize method
+  #
+  class Initializer
+    class << self
+      # Draw a stringified initialize method
+      #
+      # @param properties [Hash] a description of the class properties
+      #
+      # @return [String]
+      #
+      # @example
+      #   <<-RUBY
+      #   def initialize(foo:, bar: 0)
+      #     self.foo = foo
+      #     self.bar = bar
+      #   end
+      #   RUBY
+      def draw(properties)
+        new(properties).draw
+      end
+    end
+
+    # Initialize an instance
+    #
+    # @param properties [Hash] a description of the class properties
+    def initialize(properties = {})
+      @properties = properties
+    end
+
+    # Draws a stringified initialize method
+    #
+    # @return [String]
+    #
+    # @example
+    #   <<-RUBY
+    #   def initialize(foo:, bar: 0)
+    #     self.foo = foo
+    #     self.bar = bar
+    #   end
+    #   RUBY
+    def draw
+      <<-RUBY
+        def initialize(#{initialize_parameters})
+          #{initialize_assignments}
+          #{initialize_push_singletons}
+        end
+      RUBY
+    end
+
+    private
+
+    attr_reader :properties
+
+    # Generates initialize method parameters
+    #
+    # @return [String]
+    #
+    # @example Given properties { foo: { allow_nil: false, default: nil }, { allow_nil: true, default: 0 } }
+    #   redefine_initialize #=> "foo:, bar: 0"
+    def initialize_parameters
+      parameters =
+        properties.map do |key, options|
+          "#{key}:#{default_parameter_for(options)}"
+        end
+      parameters.join(', ')
+    end
+
+    # Fixes the default value of a parameter depending on options
+    #
+    # @return [String]
+    #
+    # @example when nil is allowed and default is set
+    #   default_parameter_for #=> " 0"
+    # @example when nil is allowed and default is not set
+    #   default_parameter_for #=> " nil"
+    # @example when nil is not allowed
+    #   default_parameter_for #=> ""
+    def default_parameter_for(options)
+      default, allow_nil = options.values_at(:default, :allow_nil)
+      if default
+        symbol_prefix = default.is_a?(Symbol) ? ':' : ''
+        " #{symbol_prefix}#{default}"
+      else
+        allow_nil ? ' nil' : ''
+      end
+    end
+
+    # Generates initialize method assignments
+    #
+    # @return [String]
+    #
+    # @example Given properties { foo: { allow_nil: false, default: nil }, { allow_nil: true, default: 0 } }
+    #   initialize_body #=> "self.foo = foo\nself.bar = bar"
+    def initialize_assignments
+      assignments =
+        properties.keys.map do |name|
+          "self.#{name} = #{name}"
+        end
+      assignments.join("\n")
+    end
+
+    # Generates push singleton for each array property
+    #
+    # @return [String]
+    def initialize_push_singletons
+      collections =
+        properties.select do |_, options|
+          options[:type].is_a?(Array) || options[:type] == Array
+        end
+      singletons =
+        collections.keys.map do |name|
+          initialize_push_singleton(name)
+        end
+      singletons.join("\n")
+    end
+
+    # Generates singleton on collection instance variable to overide <<
+    # so value is validated before being added to the collection
+    #
+    # @return [String]
+    def initialize_push_singleton(name)
+      <<-RUBY
+      bind = self
+      @#{name}.singleton_class.send(:define_method, :<<) do |v|
+        bind.send(:"validate_#{name}_type!", [v])
+        bind.send(:"validate_#{name}_inclusion!", [v])
+        bind.send(:"validate_#{name}_assertion!", [v])
+
+        push(v)
+      end
+      RUBY
+    end
+  end
+end

data/lib/otoroshi/sanctuary.rb

@@ -1,232 +1,259 @@
 # frozen_string_literal: true
 
+require_relative 'initializer'
+
 module Otoroshi
-  # Help setting and validating instance arguments
+  # This module is designed to be included in a class. This will provide
+  # the "property" ({Sanctuary::ClassMethods.property}) method for defining class properties.
+  #
+  # @example
+  #   class Importer
+  #     include Otoroshi::Sanctuary
+  #
+  #     property :whatever
+  #     property :number, Integer
+  #     property :numbers, [Integer]
+  #     property :positive_number, Integer, verify: ->(v) { v >= 0 }
+  #     property :number_or_nil, Integer, allow_nil: true
+  #     property :number_with_default, Integer, default: 42
+  #     property :number_in_collection, Integer, one_of: [1, 2, 3, 5, 8, 13, 21, 34]
+  #   end
   module Sanctuary
-    # Initialize an instance
-    # This method will be redefined each time a property is added to the class
-    def initialize; end
-
     class << self
-      # Extend class method to the included class
+      # Extend ClassMethods for the base class
       def included(base)
         base.extend ClassMethods
       end
     end
 
-    # Define class methods
+    # Class methods extended for the base class
     module ClassMethods
-      # Add a new property to the class
-      # -------------------------------
-      #
-      # / Examples
-      #
-      # property name, type: String, validate: ->(v) { v.length > 3 }, allow_nil: true
-      # property score, type: Integer, validate: ->(v) { v >= 0 }, default: 0
-      #
-      def property(name, type = Object, validate: ->(_) { true }, allow_nil: false, default: nil)
-        add_to_properties(name, allow_nil, default)
-        define_validate_type!(name, type, allow_nil)
-        define_validate_lambda!(name, validate, allow_nil)
+      # Adds a new "property" to the class
+      #
+      # @param name [Symbol] the property name
+      # @param type [Class, Array<Class>] the expected value or values type
+      # @param one_of [Array] the accepted values
+      # @param assert [Proc] a lambda processing the value and returning true or false
+      # @param allow_nil [true, false] allow nil as a value
+      # @param default [Object] default value if not set on initialization
+      #
+      # @return [void]
+      #
+      # @example
+      #   property name, type: String, assert: ->(v) { v.length > 3 }, allow_nil: true
+      # @example
+      #   property scores, type: [Integer], assert: ->(v) { v >= 0 }, default: []
+      def property(name, type = Object, one_of: nil, assert: ->(_) { true }, allow_nil: false, default: nil)
+        add_to_properties(name, type, allow_nil, default)
+        collection = type == Array || type.is_a?(Array)
+        define_validate_type!(name, type, collection, allow_nil)
+        define_validate_inclusion!(name, collection, one_of, allow_nil)
+        define_validate_assertion!(name, collection, assert, allow_nil)
         define_getter(name)
         define_setter(name)
-        redefine_initialize
+        class_eval Initializer.draw(properties), __FILE__, __LINE__ + 1
       end
 
-      # Return the (inherited) class properties
-      # (this method will be updated by ::add_to_properties)
+      # Returns the class properties
+      #
+      # @return [Hash]
       #
+      # @note this method will be updated by {add_to_properties}
       def properties
         {}
       end
 
       private
 
-      # Update the ::properties method to add new property to the current list
+      # Updates {properties} to add new property to the returned ones
       #
-      def add_to_properties(name, allow_nil, default)
+      # @return [void]
+      def add_to_properties(name, type, allow_nil, default)
         current_state = properties
-        current_state[name] = { allow_nil: allow_nil, default: default }
+        current_state[name] = {
+          type: type,
+          allow_nil: allow_nil,
+          default: default
+        }
         define_singleton_method(:properties) { current_state }
       end
 
-      # Define a private method that raises an error if type is not respected
-      #
-      # / Examples
-      #
-      # ::define_validate_type!("score", Integer, false) --> will define:
+      # Defines a private method that raises an error if type is not respected
       #
-      # def validate_score_type!(value)
-      #   return if allow_nil && value.nil?
-      #   return if value.is_a?(Integer)
+      # @return [void]
       #
-      #   raise ArgumentError, ":score does not match required type"
-      # end
+      # @example
+      #   define_validate_type!(:score, Integer, false) => def validate_score_type!(value) ...
+      # @example Generated method
+      #   # given name: :score, type: Integer, allow_nil: false
+      #   def validate_score_type!(value)
+      #     return if Integer.nil? || false && value.nil?
+      #     return if value.is_a? Integer
       #
-      def define_validate_type!(name, type, allow_nil)
+      #     raise ArgumentError, ":score does not match required type"
+      #   end
+      def define_validate_type!(name, type, collection, allow_nil)
         lambda = type_validation(type)
+        check_collection = ->(v) { v.is_a?(Array) || raise(Otoroshi::NotAnArray, name) }
         define_method :"validate_#{name}_type!" do |value|
-          return if type.nil? || allow_nil && value.nil?
+          return if allow_nil && value.nil?
+
+          collection && check_collection.call(value)
           return if lambda.call(value)
 
-          raise ArgumentError, ":#{name} does not match required type"
+          raise Otoroshi::WrongTypeError.new(name, type, collection: collection)
         end
         private :"validate_#{name}_type!"
       end
 
-      # Define a lambda to be call to validate that value match the type
-      # ----------------------------------------------------------------
+      # Defines a lambda to be called to validate that value matches the type
       #
-      # / Examples
+      # @return [Proc] the lambda to use in order to test that the value matches the type
       #
-      # ::type_validation(Integer) --> will return:
-      # ->(v) { v.is_a? Integer }
-      #
-      # :type_validation([String, Symbol]) --> will return:
-      # ->(v) { [String, Symbol].any? { |t| v.is_a? t } }
+      # @example
+      #   type_validation(Integer) #=> ->(v) { v.is_a? Integer }
+      # @example
+      #   type_validation([String, Symbol]) #=> ->(v) { [String, Symbol].any? { |t| v.is_a? t } }
       #
+      # @note params are used for binding in define_method scope
       def type_validation(type)
-        if type.is_a? Array
-          ->(v) { type.any? { |t| v.is_a? t } }
+        if type == Array
+          # no expected type for each element, return nil
+          ->(_) {}
+        elsif type.is_a?(Array)
+          # get the real expected type
+          # e.g. if type is [Integer] then element_type should be Integer
+          # e.g. if type is [] then element_type should be Object
+          element_type = type.first || Object
+          # apply type_validation lambda on each element
+          ->(v) { v.all? { |e| type_validation(element_type).call(e) } }
         else
+          # check the value matches the type
           ->(v) { v.is_a? type }
         end
       end
 
-      # Define a private method that raises an error if validate block returns false
-      # ----------------------------------------------------------------------------
-      #
-      # / Examples
-      #
-      # ::define_validate_lambda!("score", ->(v) { v >= 0 }, false) --> will define:
-      #
-      # def validate_score_lambda!(value)
-      #   return if false && value.nil?
-      #   return if value >= 0
-      #
-      #   raise ArgumentError, ":score does not match validation"
-      # end
-      #
-      def define_validate_lambda!(name, validate, allow_nil)
-        define_method :"validate_#{name}_lambda!" do |value|
-          return if allow_nil && value.nil?
-          return if instance_exec(value, &validate)
-
-          raise ArgumentError, ":#{name} does not match validation"
+      # Defines a private method that raises an error if value is not included in the accepted ones
+      #
+      # @return [void]
+      #
+      # @example
+      #   # given @name = :side
+      #   define_validate_inclusion!(:side, ...) => def validate_side_type!(value) ...
+      # @example Generated method
+      #   # given name: :side, collection: false, one_of: [:left, :right], allow_nil: false
+      #   def validate_side_type!(value)
+      #     return if false && value.nil?
+      #     return if [:left, :right].include? value
+      #
+      #     raise ArgumentError, ":side is not included in accepted values"
+      #   end
+      def define_validate_inclusion!(name, collection, one_of, allow_nil)
+        validator = collection ? each_inside?(name, one_of) : inside?(name, one_of)
+        if one_of
+          define_method(:"validate_#{name}_inclusion!") do |value|
+            allow_nil && value.nil? || validator.call(value)
+          end
+        else
+          define_method(:"validate_#{name}_inclusion!") { |_| }
         end
-        private :"validate_#{name}_lambda!"
+        private :"validate_#{name}_inclusion!"
       end
 
-      # Define a getter method for the property
-      # ---------------------------------------
+      # Defines a lambda to be called to validate that value is included in accepted ones
       #
-      # / Examples
-      #
-      # ::define_getter("score") --> will define:
-      #
-      # def score
-      #   @score
-      # end
-      #
-      def define_getter(name)
-        define_method(name) { instance_variable_get("@#{name}") }
+      # @return [Proc] the lambda to use in order to test that value is included in accepted ones
+      def inside?(name, one_of)
+        lambda do |v|
+          one_of.include?(v) || raise(Otoroshi::NotAcceptedError.new(name, one_of))
+        end
       end
 
-      # Define a setter method for the property
-      # ---------------------------------------
-      #
-      # / Examples
-      #
-      # ::define_setter("score") --> will define:
+      # Defines a lambda to be called to validate that each value is included in accepted ones
       #
-      # def score=(value)
-      #   validate_score_type!(value)
-      #   validate_score!(value)
-      #   @score = value
-      # end
-      #
-      def define_setter(name)
-        define_method :"#{name}=" do |value|
-          __send__(:"validate_#{name}_type!", value)
-          __send__(:"validate_#{name}_lambda!", value)
-          instance_variable_set("@#{name}", value)
+      # @return [Proc] the lambda to use in order to test that each value is included in accepted ones
+      def each_inside?(name, one_of)
+        lambda do |v|
+          v.all? { |e| one_of.include? e } || raise(Otoroshi::NotAcceptedError.new(name, one_of, collection: true))
         end
       end
 
-      # Redefine the initialize method
-      # ------------------------------
-      #
-      # / Examples
-      #
-      # Given the properties:
-      #   foo: { allow_nil: false, default: nil }
-      #   bar: { allow_nil: true, default: 0 }
-      #
-      # ::define_initialize --> will define:
-      #
-      # def initialize(foo:, bar: 0)
-      #   self.foo = foo
-      #   self.bar = bar
-      # end
-      #
-      def redefine_initialize
-        class_eval <<-RUBY, __FILE__, __LINE__ + 1
-          def initialize(#{initialize_parameters})
-            #{initialize_body}
-          end
-        RUBY
+      # Defines a private method that raises an error if assert lambda returns false
+      #
+      # @return [void]
+      #
+      # @example
+      #   define_validate_assertion!(:score, ...) #=> def validate_score_assertion!(value) ...
+      # @example Generated instance method
+      #   # given name: :score, assert: >(v) { v >= 0 }, allow_nil: false
+      #   def validate_score_assertion!(value)
+      #     return if false && value.nil?
+      #     return if value >= 0
+      #
+      #     raise ArgumentError, ":score does not match validation"
+      #   end
+      def define_validate_assertion!(name, collection, assert, allow_nil)
+        validator = collection ? each_assert?(name, assert) : assert?(name, assert)
+        define_method :"validate_#{name}_assertion!" do |value|
+          allow_nil && value.nil? || validator.call(value)
+        end
+        private :"validate_#{name}_assertion!"
       end
 
-      # Define initialize method parameters
-      # -----------------------------------
-      #
-      # / Examples
-      #
-      # Given the properties:
-      #   foo: { allow_nil: false, default: nil }
-      #   bar: { allow_nil: true, default: 0 }
-      #
-      # ::initialize_parameters --> will return:
-      # "foo:, bar: 0"
+      # Defines a lambda to be called to validate that value respects the specific
       #
-      def initialize_parameters
-        properties.map { |key, options| "#{key}:#{default_parameter_for(options)}" }.join(', ')
+      # @return [Proc] the lambda to use in order to test that value respects the specific
+      def assert?(name, assert)
+        lambda do |value|
+          instance_exec(value, &assert) || raise(Otoroshi::AssertionError, name)
+        end
       end
 
-      # Define the default value of a parameter depending on options
-      # ------------------------------------------------------------
-      #
-      # / Examples
-      #
-      # default_parameter_for(allow_nil: true, default: 0) --> will return
-      #   ' 0'
+      # Defines a lambda to be called to validate that value respects the specific
       #
-      # default_parameter_for(allow_nil: true, default: nil) --> will return
-      #   ' nil'
-      #
-      # default_parameter_for(allow_nil: false, default: nil) --> will return
-      #   ''
-      #
-      def default_parameter_for(options)
-        return " #{options[:default]}" if options[:default]
-
-        options[:allow_nil] ? ' nil' : ''
+      # @return [Proc] the lambda to use in order to test that each value respects the specific
+      def each_assert?(name, assert)
+        lambda do |value|
+          value.all? { |e| instance_exec(e, &assert) } ||
+            raise(Otoroshi::AssertionError.new(name, collection: true))
+        end
       end
 
-      # Define initialize method body
-      # -----------------------------
+      # Defines a getter method for the property
       #
-      # / Examples
+      # @return [void]
       #
-      # Given the properties:
-      #   :foo, :bar
-      #
-      # ::initialize_body --> will return:
-      #   "self.foo = foo
-      #    self.bar = bar"
-      #
-      def initialize_body
-        properties.keys.map { |key| "self.#{key} = #{key}" }.join("\n")
+      # @example
+      #   define_getter(:score) #=> def score ...
+      # @example Generated instance method
+      #   # given name: :score
+      #   def score
+      #     instance_variable_get(@score)
+      #   end
+      def define_getter(name)
+        define_method(name) { instance_variable_get("@#{name}") }
+      end
+
+      # Defines a setter method for the property
+      #
+      # @return [void]
+      #
+      # @example
+      #   define_setter(:score) #=> def score=(value) ...
+      # @example Generated instance method
+      #   # given name: :score
+      #   def score=(value)
+      #     validate_score_type!(value)
+      #     validate_score!(value)
+      #     instance_variable_set(@score, value)
+      #   end
+      def define_setter(name)
+        define_method :"#{name}=" do |value|
+          __send__(:"validate_#{name}_type!", value)
+          __send__(:"validate_#{name}_inclusion!", value)
+          __send__(:"validate_#{name}_assertion!", value)
+          instance_variable_set("@#{name}", value)
+        end
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: otoroshi
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.8
 platform: ruby
 authors:
 - Edouard Piron
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-10-10 00:00:00.000000000 Z
+date: 2020-10-16 00:00:00.000000000 Z
 dependencies: []
 description: Help defining class properties
 email: ed.piron@gmail.com
@@ -16,6 +16,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/otoroshi.rb
+- lib/otoroshi/exceptions.rb
+- lib/otoroshi/initializer.rb
 - lib/otoroshi/sanctuary.rb
 homepage: https://rubygems.org/gems/otoroshi
 licenses: