otoroshi 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cec895aa30d2fb89c0b824b38c2b0b710558419aa7ef1308769b8550969924ba
-  data.tar.gz: a8f06adce33632af173d95282440685ab009c6095f6db889e21b25ffd4cccb40
+  metadata.gz: 22e2b21cfce2f6c2a95ef146e1d06b54d6c94d517069045262027de1e3511627
+  data.tar.gz: 6fe3ced425d76d05fd9e214871fadf8211b7b18d00d2c5fc5c20274cce9eb925
 SHA512:
-  metadata.gz: 581a9bb26d5c1f861fa5f3c0e60d554c9a4f0e2f47c17df3856d957202ab1909ec74da411b2f0878c7ab0f0e59e904c1220b77e71f67dc1543a5959da0aa3f77
-  data.tar.gz: 7811ee410f737e3f53d133eee22d62d0ed1e6b140d45801cad33aff475ced6a2e6b1e91acd92b4047f4c38c12b53ce64256dd935a3571e49758fa41f760d2e75
+  metadata.gz: 8aa7cd811fb08539425530d17c3633142b52a7602894708291cdeaea609c669340d43a8b645fd32a8b3b8679c2782a8ff2ef1cca8edfcaf6eb9dede7db36c2f8
+  data.tar.gz: ec5a6f08aece81a5be8b7db5e3ad5d2b10cf73800fd308f29cae84ad6650d21911f06fbe267a04a930a0b0f05c0900f816916d78bd6c4822e93576777899933f

data/lib/otoroshi/sanctuary.rb

@@ -1,29 +1,38 @@
 # frozen_string_literal: true
 
 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 :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
-    # 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
-      #
+      # 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)
@@ -33,36 +42,37 @@ module Otoroshi
         redefine_initialize
       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
+      # @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
-      #
-      # / Examples
-      #
-      # ::define_validate_type!("score", Integer, false) --> will define:
-      #
-      # def validate_score_type!(value)
-      #   return if allow_nil && value.nil?
-      #   return if value.is_a?(Integer)
-      #
-      #   raise ArgumentError, ":score does not match required type"
-      # end
-      #
+      # Defines a private method that raises an error if type is not respected
+      # @param name [Symbol] the property name
+      # @param type [Class] the type to test against
+      # @param allow_nil [true, false] allow nil as a value
+      # @return [void]
+      # @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|
@@ -74,17 +84,13 @@ module Otoroshi
         private :"validate_#{name}_type!"
       end
 
-      # Define a lambda to be call to validate that value match the type
-      # ----------------------------------------------------------------
-      #
-      # / Examples
-      #
-      # ::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 } }
-      #
+      # Defines a lambda to be call to validate that value matches the type
+      # @param type [Class] the type to test against
+      # @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 } }
@@ -93,20 +99,20 @@ module Otoroshi
         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
-      #
+      # Defines a private method that raises an error if validate block returns false
+      # @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
+      # @return [void]
+      # @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?
@@ -117,34 +123,30 @@ module Otoroshi
         private :"validate_#{name}_lambda!"
       end
 
-      # Define a getter method for the property
-      # ---------------------------------------
-      #
-      # / Examples
-      #
-      # ::define_getter("score") --> will define:
-      #
-      # def score
-      #   @score
-      # end
-      #
+      # Defines a getter method for the property
+      # @param name [Symbol] the property name
+      # @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
-      # ---------------------------------------
-      #
-      # / Examples
-      #
-      # ::define_setter("score") --> will define:
-      #
-      # def score=(value)
-      #   validate_score_type!(value)
-      #   validate_score!(value)
-      #   @score = value
-      # end
-      #
+      # Defines a setter method for the property
+      # @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)
@@ -153,22 +155,14 @@ module Otoroshi
         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
-      #
+      # 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})
@@ -177,54 +171,38 @@ module Otoroshi
         RUBY
       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 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
-        properties.map { |key, options| "#{key}:#{default_parameter_for(options)}" }.join(', ')
+        parameters =
+          properties.map do |key, options|
+            allow_nil, default = options.values
+            "#{key}:#{default_parameter_for(allow_nil, default)}"
+          end
+        parameters.join(', ')
       end
 
-      # Define the default value of a parameter depending on options
-      # ------------------------------------------------------------
-      #
-      # / Examples
-      #
-      # default_parameter_for(allow_nil: true, default: 0) --> will return
-      #   ' 0'
-      #
-      # 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' : ''
+      # 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
 
-      # Define initialize method body
-      # -----------------------------
-      #
-      # / Examples
-      #
-      # Given the properties:
-      #   :foo, :bar
-      #
-      # ::initialize_body --> will return:
-      #   "self.foo = foo
-      #    self.bar = bar"
-      #
+      # 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: otoroshi
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Edouard Piron