otoroshi 0.0.1 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2993a278f341533c1590cd6bdea9291033167104f94018808577f67cbcd2f0ae
-  data.tar.gz: 725a187567625f428485a80edd5025b0ae7e3a859bebd4d73ea14557353a89ad
+  metadata.gz: e31c6e00090297fb9709600d1580a24a4729ee1a9af094015ea7c197fde884d3
+  data.tar.gz: 033526ab6473e809a19c812104cf05cadba29485d617161c1799f6664777f9fc
 SHA512:
-  metadata.gz: c14d31b349b599ff5ef0db40dbaed8723b47bd53de648589ace6ac8ccfeba85b926d263070fe7d13a0746168399508127cd4e3a33df032ff8cfef5d5a9d5380c
-  data.tar.gz: 19311d09a63ee50e89bd3b3c7dead8faeaba0bd1a4803dfba363c422b0c13704fbeb3bb60799cfac9d681736e209d1587b44be76840bc5736aff4822c6cf9c24
+  metadata.gz: a5e9595b7c246dde6897fc4f314cdf0c9ef00576dd042cc9c4e34c60de249d4d346ebc2f661f1190708a26211cacbdd1a9f457a9e5802e57049b5f5d831dc9d1
+  data.tar.gz: 42aace4283c39b3d956022e643635d73a9b3a5feb74070f0dd441d8ef165b5d9c76475a7bd274b94e4da8f85aa0ecb08868116842c6af98b1cdf4112a93bbe77

data/lib/otoroshi/sanctuary.rb

@@ -1,77 +1,109 @@
 # frozen_string_literal: true
 
 module Otoroshi
-  # help setting and validating instance arguments
-  class Sanctuary
+  # 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 :file_path, String, validate: ->(v) { v.match? /.+\.csv/ }
+  #     property :headers, [TrueClass, FalseClass], default: false
+  #     property :col_sep, String, validate: ->(v) { v.in? [',', ';', '\s', '\t', '|'] }, default: ','
+  #     property :converters, Symbol, validate: ->(v) { v.in? %i[integer float date] }, allow_nil: true
+  #   end
+  module Sanctuary
     class << self
-      # Add a new property to the class (called by inherited class)
-      # Example: property name, type: String, validate: ->(v) { v.length > 3 }, optional: true
-      def property(name, type = Object, validate: ->(_) { true }, optional: false, default: nil)
-        define_default(name, default)
-        define_validate_type!(name, type, optional)
-        define_validate!(name, validate, optional)
+      # Extend ClassMethods for the base class
+      def included(base)
+        base.extend ClassMethods
+      end
+    end
+
+    # Class methods extended for the base class
+    module ClassMethods
+      # Adds a new "property" to the class
+      #
+      # @param name [Symbol] the property name
+      # @param type [Class] the expected value type
+      # @param validate [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, validate: ->(v) { v.length > 3 }, allow_nil: true
+      # @example
+      #   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)
         define_getter(name)
         define_setter(name)
-        add_to_properties(name)
+        redefine_initialize
       end
 
-      # Return the (inherited) class properties
-      # (this method will be updated by ::add_to_properties(name))
+      # 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
-      def add_to_properties(name)
-        current = properties
-        define_singleton_method :properties do
-          current << name
-        end
-      end
-
-      # Define a private method that returns the default value
-      #
-      # ::define_default("score", 0)
-      # --------------------------
-      # def default_score
-      #   0
-      # end
+      # Updates {properties} to add new property to the returned ones
       #
-      def define_default(name, default)
-        define_method(:"default_#{name}") { default }
-        private :"default_#{name}"
+      # @return [void]
+      def add_to_properties(name, allow_nil, default)
+        current_state = properties
+        current_state[name] = { 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
+      # Defines a private method that raises an error if type is not respected
       #
-      # ::define_validate_type!("score", Integer, false)
-      # ----------------------------------------------
-      # def validate_score_type!(value)
-      #   return if optional && value.nil?
-      #   return if value.is_a?(Integer)
+      # @param name [Symbol] the property name
+      # @param type [Class] the type to test against
+      # @param allow_nil [true, false] allow nil as a value
       #
-      #   raise ArgumentError, ":score does not match type validation"
-      # end
+      # @return [void]
       #
-      def define_validate_type!(name, type, optional)
+      # @example
+      #   define_validate_type!(score, Integer, false) => def validate_score_type!(value) ...
+      # @example Generated method
+      #   def validate_score_type!(value)
+      #     return if Integer.nil? || false && value.nil?
+      #     return if value.is_a? Integer
+      #
+      #     raise ArgumentError, ":score does not match required type"
+      #   end
+      def define_validate_type!(name, type, allow_nil)
         lambda = type_validation(type)
         define_method :"validate_#{name}_type!" do |value|
-          return if type.nil? || optional && value.nil?
+          return if type.nil? || allow_nil && value.nil?
           return if lambda.call(value)
 
-          raise ArgumentError, ":#{name} does not match type validation"
+          raise ArgumentError, ":#{name} does not match required type"
         end
         private :"validate_#{name}_type!"
       end
 
-      # Define a lambda to be call to validate that value match the type
+      # Defines a lambda to be call to validate that value matches the type
+      #
+      # @param type [Class] the type to test against
       #
-      # ::type_validation(Integer)
-      # ----------------------------------------------
-      # ->(v) { v.is_a? Integer }
+      # @return [Proc] the lambda to use in order to test the value matches the type
       #
+      # @example
+      #   type_validation(Integer) #=> ->(v) { v.is_a? Integer }
+      # @example
+      #   type_validation([String, Symbol]) #=> ->(v) { [String, Symbol].any? { |t| v.is_a? t } }
       def type_validation(type)
         if type.is_a? Array
           ->(v) { type.any? { |t| v.is_a? t } }
@@ -80,85 +112,131 @@ module Otoroshi
         end
       end
 
-      # Define a private method that raises an error if validate block returns false
+      # Defines a private method that raises an error if validate block returns false
       #
-      # ::define_validate!("score", ->(v) { v >= 0 }, false)
-      # --------------------------------------------------
-      # def validate_score!(value)
-      #   return if false && value.nil?
-      #   return if value >= 0
+      # @param name [Symbol] the property name
+      # @param validate [Proc] a lambda processing the value and returning true or false
+      # @param allow_nil [true, false] allow nil as a value
       #
-      #   raise ArgumentError, ":score does not match validation"
-      # end
+      # @return [void]
       #
-      def define_validate!(name, validate, optional)
-        define_method :"validate_#{name}!" do |value|
-          return if optional && value.nil?
+      # @example
+      #   define_validate_lambda!("score", ->(v) { v >= 0 }, false) #=> def validate_score_lambda!(value) ...
+      # @example Generated instance method
+      #   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"
         end
-        private :"validate_#{name}!"
+        private :"validate_#{name}_lambda!"
       end
 
-      # Define a getter method for the property
+      # Defines a getter method for the property
+      #
+      # @param name [Symbol] the property name
       #
-      # ::define_getter("score")
-      # ----------------------
-      # def score
-      #   @score
-      # end
+      # @return [void]
       #
+      # @example
+      #   define_getter(:score) #=> def score ...
+      # @example Generated instance method
+      #     def score
+      #       instance_variable_get(@score)
+      #     end
       def define_getter(name)
         define_method(name) { instance_variable_get("@#{name}") }
       end
 
-      # Define a setter method for the property
+      # Defines a setter method for the property
       #
-      # ::define_setter("score")
-      # ----------------------
-      # def score=(value)
-      #   validate_score_type!(value)
-      #   validate_score!(value)
-      #   @score = value
-      # end
+      # @param name [Symbol] the property name
       #
+      # @return [void]
+      #
+      # @example
+      #   define_getter(:score) #=> def score=(value) ...
+      # @example Generated instance method
+      #   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}!", value)
+          __send__(:"validate_#{name}_lambda!", value)
           instance_variable_set("@#{name}", value)
         end
       end
-    end
 
-    # Initialize an instance and validate provided args
-    def initialize(args = {}) # rubocop:disable Style/OptionHash
-      validate_keys!(args.keys)
-      assign_values(args)
-    end
-
-    private
+      # Redefines initialize method
+      #
+      # @return [void]
+      #
+      # @note method is defined with `class_eval`
+      #
+      # @example Generated method
+      #   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
+      end
 
-    # validate that provided keys match class properties
-    def validate_keys!(keys)
-      errors = keys.reject { |key| self.class.properties.include? key }
-      return if errors.empty?
+      # Defines 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|
+            allow_nil, default = options.values
+            "#{key}:#{default_parameter_for(allow_nil, default)}"
+          end
+        parameters.join(', ')
+      end
 
-      message =
-        if errors.one?
-          ":#{errors[0]} is not a valid property"
-        else
-          ":#{errors.join(', :')} are not valid properties"
-        end
-      raise ArgumentError, message
-    end
+      # Defines the default value of a parameter depending on options
+      #
+      # @param options [Hash]
+      #
+      # @return [String]
+      #
+      # @example when nil is allowed and default is set
+      #   default_parameter_for(true, 0) #=> " 0"
+      # @example when nil is allowed and default is not set
+      #   default_parameter_for(true, nil) #=> " nil"
+      # @example when nil is not allowed
+      #   default_parameter_for(false, nil) #=> ""
+      def default_parameter_for(allow_nil, default)
+        return " #{default}" if default
+
+        allow_nil ? ' nil' : ''
+      end
 
-    # assign value to each property
-    def assign_values(args)
-      self.class.properties.each do |property|
-        value = args.key?(property) ? args[property] : __send__(:"default_#{property}")
-        public_send(:"#{property}=", value)
+      # Defines initialize method body
+      #
+      # @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_body
+        properties.keys.map { |key| "self.#{key} = #{key}" }.join("\n")
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: otoroshi
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.6
 platform: ruby
 authors:
 - Edouard Piron
@@ -10,7 +10,7 @@ bindir: bin
 cert_chain: []
 date: 2020-10-10 00:00:00.000000000 Z
 dependencies: []
-description: Help setting and validating instance arguments
+description: Help defining class properties
 email: ed.piron@gmail.com
 executables: []
 extensions: []