sinclair 1.14.2 → 1.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6bd1d9896437c341e52648bac78c70d453a773c92a2fba06111d88d12be06a3
-  data.tar.gz: 5cb2ba761532e3db60ffc8a09b821509c1355949071c5346cef962b0d43dfe9d
+  metadata.gz: 54cfb901ecd8185d00862d7c0b5a99e9cb626d2bbadf45db59553ae980ef9dc1
+  data.tar.gz: 7f0f0a291a659fbc5eaa0d6b56a8bc0f2dfe08b3c0a0d290dad2a6136c7ccc53
 SHA512:
-  metadata.gz: bf2fd682ae8e6c57a8a173a5f78492bf6c7011dfef7734fd9c0c2d3d4d73fa599bac72a9317920dd0ebf5bb6c98f0f2f511c0fcc9fe5b683f766b5624359ccf3
-  data.tar.gz: db83a68fd9b11d0a227afca422f5a6e8e33bc64e3624a55c0d8f3b87d49235d8e17b1393c44b6ac2a67c8b9869e58d5780a3a06aad4f76429a4c4b0c48247f43
+  metadata.gz: d788efed427695e2b001e7b38cc7fa4ef41fb8f6e6b855d321e88f24cb7c97b71b7f4d2622041a5f36ed9921b88513bb26beb4d3b0f11c37a19425a2d1698d9b
+  data.tar.gz: 66f7170ee3a639fa43219f10f3c984369d72ac3e58f182ac00bf0fecf947efa0e5f25107cffa45db30048366085c7c329cd214b5ed5659d854af93f0588b264b

data/.rubocop.yml

@@ -31,6 +31,7 @@ RSpec/PredicateMatcher:
 RSpec/DescribedClass:
   Exclude:
     - 'spec/integration/yard/**/*_spec.rb'
+    - 'spec/integration/readme/**/*_spec.rb'
 
 RSpec/ExampleLength:
   Exclude:

data/README.md

@@ -15,13 +15,13 @@ create custom comparators, configure your application, create powerfull options,
 
 Employing Sinclair in your applications helps you streamline your development workflow and enhance your development process through more efficient, cleaner code
 
-Current Release: [1.14.2](https://github.com/darthjee/sinclair/tree/1.14.2)
+Current Release: [1.16.0](https://github.com/darthjee/sinclair/tree/1.16.0)
 
-[Next release](https://github.com/darthjee/sinclair/compare/1.14.2...master)
+[Next release](https://github.com/darthjee/sinclair/compare/1.16.0...master)
 
 Yard Documentation
 -------------------
-[https://www.rubydoc.info/gems/sinclair/1.14.2](https://www.rubydoc.info/gems/sinclair/1.14.2)
+[https://www.rubydoc.info/gems/sinclair/1.16.0](https://www.rubydoc.info/gems/sinclair/1.16.0)
 
 Installation
 ---------------
@@ -290,9 +290,9 @@ Block methods accepts, as option
 klass = Class.new
 instance = klass.new
 
-builder = Sinclair.new(klass)
-builder.add_method(:random_number) { Random.rand(10..20) }
-builder.build
+Sinclair.build(klass) do
+  add_method(:random_number) { Random.rand(10..20) }
+end
 
 instance.random_number # returns a number between 10 and 20
 ```
@@ -326,11 +326,11 @@ instance.random_number # returns a number between 10 and 20
 class MyClass
 end
 
-builder = described_class.new(MyClass)
-builder.add_class_method(
-  :function, 'a ** b + c', parameters: [:a], named_parameters: [:b, { c: 15 }]
-)
-builder.build
+Sinclair.build(MyClass) do
+  add_class_method(
+    :function, 'a ** b + c', parameters: [:a], named_parameters: [:b, { c: 15 }]
+  )
+end
 
 MyClass.function(10, b: 2) # returns 115
 ```

data/config/yardstick.yml

@@ -1,4 +1,4 @@
-threshold: 99.8
+threshold: 100
 require_exact_threshold: false
 rules:
   ApiTag::Presence:
@@ -18,6 +18,14 @@ rules:
     exclude:
       - Sinclair#add_method
       - Sinclair#add_class_method
+      - Sinclair.build
+      - Sinclair::Caster.cast
+      - Sinclair::Caster.cast_with
+      - Sinclair::Caster.caster_for
+      - Sinclair::Caster#initialize
+      - Sinclair::Caster::ClassMethods#cast
+      - Sinclair::Caster::ClassMethods#cast_with
+      - Sinclair::Caster::ClassMethods#caster_for
       - Sinclair::Configurable#config
       - Sinclair::Configurable#reset_config
       - Sinclair::Configurable#configure
@@ -34,6 +42,7 @@ rules:
   ReturnTag:
     enabled: true
     exclude:
+      - Sinclair.build
       - Sinclair::Matchers::AddClassMethodTo#raise_block_syntax_error
       - Sinclair::Matchers::AddInstanceMethodTo#raise_block_syntax_error
       - Sinclair::MethodBuilder#build_from_definition
@@ -42,6 +51,7 @@ rules:
   Summary::Presence:
     enabled: true
     exclude:
+      - Sinclair::Caster#initialize
       - Sinclair::Config::MethodsBuilder#initialize
       - Sinclair::ConfigFactory#initialize
       - Sinclair::EnvSettable::Builder#initialize

data/lib/sinclair/caster/class_methods.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+class Sinclair
+  class Caster
+    # @api public
+    # @author darhtjee
+    #
+    # Class methods for {Caster}
+    module ClassMethods
+      # (see Caster.master_caster!)
+      def master_caster!
+        @master_caster = true
+      end
+
+      # (see Caster.cast_with)
+      def cast_with(key, method_name = nil, &block)
+        caster = instance_for(method_name, &block)
+
+        return class_casters[key] = caster if key.is_a?(Class)
+
+        casters[key] = caster
+      end
+
+      # (see Caster.cast)
+      def cast(value, key, **opts)
+        caster_for(key).cast(value, **opts)
+      end
+
+      # (see Caster.caster_for)
+      def caster_for(key)
+        return casters[key] if casters.key?(key)
+
+        caster_for_class(key) || superclas_caster_for(key) || new { |value| value }
+      end
+
+      protected
+
+      # @api private
+      #
+      # Returns a caster from the superclass
+      #
+      # @param key [Symbol,Class] key to be checked
+      #
+      # @see caster_for
+      # @return [Caster]
+      def superclas_caster_for(key)
+        return if master_caster?
+
+        superclass.caster_for(key)
+      end
+
+      # @api private
+      #
+      # Returns a caster searching for using class as key
+      #
+      # This is called by {#caster_for} any time key is a class
+      #
+      # @param klass [Class] class to be used in the search
+      #
+      # When the given class is not registered, a caster for a parent
+      # class is returned
+      #
+      # @return [Caster]
+      def caster_for_class(klass)
+        return unless klass.is_a?(Class) || klass.is_a?(Module)
+
+        class_casters.find do |klazz, _|
+          klass <= klazz
+        end&.second
+      end
+
+      # @api private
+      #
+      # Returns a new instance {Caster}
+      #
+      # @overload instance_for(method_name, &block)
+      #   @param method_name [Symbol] method to be called in the model
+      #   @param block [Proc] block to perform the casting
+      #
+      #   When +method_name+ is not given, the block is used
+      #
+      # @overload instance_for(caster)
+      #   @param caster [Caster] instance of caster to be returned
+      #
+      # @return [Caster]
+      def instance_for(method_name, &block)
+        return new(&block) unless method_name
+        return method_name if method_name.is_a?(Caster)
+
+        new(&method_name)
+      end
+
+      private
+
+      # @api private
+      # @private
+      #
+      # Caster map stored by +Symbols+
+      #
+      # @return [Hash<Symbol,Caster>]
+      def casters
+        @casters ||= {}
+      end
+
+      # @api private
+      # @private
+      #
+      # Caster map stored by +Classs+
+      #
+      # @return [Hash<Class,Caster>]
+      def class_casters
+        @class_casters ||= {}
+      end
+
+      # @api private
+      # @private
+      #
+      # Chack if the caster class is a master
+      #
+      # A master caster never checks if a superclass has a caster
+      #
+      # @see master_caster!
+      # @return [TrueClass,FalseClass]
+      def master_caster?
+        @master_caster
+      end
+    end
+  end
+end

data/lib/sinclair/caster.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+class Sinclair
+  # @api public
+  # @author darhtjee
+  #
+  # Class responsible for defining how to and casting values
+  #
+  # First the class needs to be configured using {.cast_with} and later
+  # a value can be cast by using {.cast} or {.caster_for}
+  #
+  # Inheritance grants the hability to have different casting for different
+  # purposes / applications / gems
+  class Caster
+    autoload :ClassMethods, 'sinclair/caster/class_methods'
+    extend Caster::ClassMethods
+    master_caster!
+
+    # @method self.master_caster!
+    # @api public
+    #
+    # Changes the class to be the master caster
+    #
+    # The master caster never checks with its an
+    #
+    # @example
+    #   class BaseCaster < Sinclair::Caster
+    #     cast_with(:string, :to_s)
+    #   end
+    #
+    #   class MyCaster < BaseCaster
+    #   end
+    #
+    #   MyCaster.cast(10, :string) # returns '10'
+    #
+    #   MyCaster.master_caster!
+    #
+    #   MyCaster.cast(10, :string) # returns 10
+    #
+    # @see Caster::ClassMethods#master_caster!
+    #
+    # @return [TrueClass]
+
+    # @method self.cast_with
+    # @api public
+    #
+    # Register a caster under a key
+    #
+    # @overload cast_with(key, method_name)
+    #   @param key [Symbol] key where the caster will be store.
+    #   @param method_name [Symbol] method to be called on the
+    #     value that is being converted
+    #
+    #   @example Casting from pre registered symbol caster
+    #     class MyCaster < Sinclair::Caster
+    #       cast_with(:json, :to_json)
+    #     end
+    #
+    #     MyCaster.cast({ key: :value }, :json) # returns '{"key":"value"}'
+    #
+    # @overload cast_with(key, &block)
+    #   @param key [Symbol] key where the caster will be store.
+    #   @param block [Proc] block to be used when casting the value.
+    #
+    #   @example Casting from pre registered block caster
+    #     MyCaster.cast_with(:complex) do |hash|
+    #       real = hash[:real]
+    #       imaginary = hash[:imaginary]
+    #
+    #       "#{real.to_f} + #{imaginary.to_f} i"
+    #     end
+    #
+    #     value = { real: 10, imaginary: 5 }
+    #
+    #     MyCaster.cast(value, :complex) # returns '10.0 + 5.0 i'
+    #
+    # @overload cast_with(class_key, method_name)
+    #   @param class_key [Class] class to be used as key.
+    #     This will be used as parent class when the calling {Caster.cast}.
+    #   @param method_name [Symbol] method to be called on the
+    #     value that is being converted.
+    #
+    #   @example Casting from pre registered class
+    #     class MyCaster < Sinclair::Caster
+    #       cast_with(Numeric, :to_i)
+    #     end
+    #
+    #     MyCaster.cast('10', Integer) # returns 10
+    #
+    # @overload cast_with(class_key, &block)
+    #   @param class_key [Class] class to be used as key.
+    #     This will be used as parent class when the calling {Caster.cast}.
+    #   @param block [Proc] block to be used when casting the value.
+    #
+    #   @example Casting from pre registered block caster from a class
+    #     # hash_model.rb
+    #
+    #     class HashModel
+    #       def initialize(hash)
+    #         hash.each do |attribute, value|
+    #           method_name = "#{attribute}="
+    #
+    #           send(method_name, value) if respond_to?(method_name)
+    #         end
+    #       end
+    #     end
+    #
+    #     # hash_person.rb
+    #     class HashPerson < HashModel
+    #       attr_accessor :name, :age
+    #     end
+    #
+    #     # caster_config.rb
+    #     Caster.cast_with(HashModel) do |value, klass:|
+    #       klass.new(value)
+    #     end
+    #
+    #     Caster.cast_with(String, &:to_json)
+    #
+    #     # main.rb
+    #     values = [
+    #       { klass: String, value: { name: 'john', age: 20, country: 'BR' } },
+    #       { klass: HashPerson, value: { name: 'Mary', age: 22, country: 'IT' } }
+    #     ]
+    #
+    #     values.map! do |config|
+    #       value = config[:value]
+    #       klass = config[:klass]
+    #
+    #       Caster.cast(value, klass, klass: klass)
+    #     end
+    #
+    #     values[0] # returns '{"name":"john","age":20,"country":"BR"}'
+    #     values[1] # returns HashPerson.new(name: 'Mary', age: 22)
+    #
+    # @see Caster::ClassMethods#cast_with
+    # @see Caster.caster_for
+    # @see Caster.cast
+    #
+    # @return [Caster] the registered caster
+
+    # @method self.cast
+    # @api public
+    #
+    # Cast a value using the registered caster
+    #
+    # @overload cast(value, key, **opts)
+    #   @param value [Object] value to be cast
+    #   @param key [Symbol] key where the caster is registered under
+    #   @param opts [Hash] Options to be sent to the caster
+    #
+    #   @example Casts with a symbol key
+    #     # math_caster.rb
+    #     class MathCaster < Sinclair::Caster
+    #       cast_with(:float, :to_f)
+    #
+    #       cast_with(:log) do |value, base: 10|
+    #         value = MathCaster.cast(value, :float)
+    #
+    #         Math.log(value, base)
+    #       end
+    #
+    #       cast_with(:exp) do |value, base: 10|
+    #         value = MathCaster.cast(value, :float)
+    #
+    #         base**value
+    #       end
+    #     end
+    #
+    #     # main.rb
+    #     initial = Random.rand(10..20)
+    #     log = MathCaster.cast(initial, :log)
+    #     exp = MathCaster.cast(log, :exp)
+    #
+    #     # exp will be betwween initial - 0.0001 and initial + 0.0001
+    #
+    #   @example Casts passing parameter
+    #     base = Random.rand(3..6)
+    #     initial = Random.rand(10..20)
+    #     log = MathCaster.cast(initial, :log, base: base)
+    #     exp = MathCaster.cast(log, :exp, base: base)
+    #
+    #     # exp will be betwween initial - 0.0001 and initial + 0.0001
+    #
+    # @overload cast(value, class_key, **opts)
+    #   @param value [Object] value to be cast
+    #   @param class_key [Class] Class to used as key in the casters storage
+    #   @param opts [Hash] Options to be sent to the caster
+    #
+    #   When the +class_key+ does not match the stored key, but matches a superclass,
+    #   the registerd caster is returned.
+    #
+    #   @example Casts with class key
+    #     # ruby_string_caster.rb
+    #     class RubyStringCaster < Sinclair::Caster
+    #       master_caster!
+    #
+    #       cast_with(NilClass) { 'nil' }
+    #       cast_with(Symbol) { |value| ":#{value}" }
+    #       cast_with(String, :to_json)
+    #       cast_with(Object, :to_s)
+    #
+    #       def self.to_ruby_string(value)
+    #         cast(value, value.class)
+    #       end
+    #     end
+    #
+    #     # main.rb
+    #     hash = { a: 1, b: 2, 'c' => nil }
+    #     string = 'my string'
+    #     symbol = :the_symbol
+    #     number = 10
+    #     null = nil
+    #
+    #     <<-RUBY
+    #       hash_value = #{RubyStringCaster.to_ruby_string(hash)}
+    #       string_value = #{RubyStringCaster.to_ruby_string(string)}
+    #       symbol_value = #{RubyStringCaster.to_ruby_string(symbol)}
+    #       number = #{RubyStringCaster.to_ruby_string(number)}
+    #       null_value = #{RubyStringCaster.to_ruby_string(null)}
+    #     RUBY
+    #
+    #     # Generates the String
+    #     #
+    #     # <<-RUBY
+    #     #   hash_value = {:a=>1, :b=>2, "c"=>nil}
+    #     #   string_value = "my string"
+    #     #   symbol_value = :the_symbol
+    #     #   number = 10
+    #     #   null_value = nil
+    #     # RUBY
+    #
+    # @see Caster::ClassMethods#cast
+    # @see Caster.cast_with
+    # @see Caster.caster_for
+    # @see Caster#cast
+    #
+    # @return [Object] the value cast
+
+    # @method self.caster_for
+    # @api public
+    #
+    # Returns an instance of caster for the provided key
+    #
+    # When no registered caster is found one is requested for the parent class.
+    # If no caster is found, then a default caster is returned
+    #
+    # The default caster performs no casting returning the value itself
+    #
+    # @overload caster_for(key)
+    #   @param key [Symbol] key where the caster is registered under
+    #
+    #   @example Getting the caster with symbol key
+    #     # enum_caster.rb
+    #     class EnumCaster < Sinclair::Caster
+    #       cast_with(:hash, :to_h)
+    #       cast_with(:array, :to_a)
+    #     end
+    #
+    #     # enum_converter.rb
+    #     module EnumConverter
+    #       class << self
+    #         def to_hash(value)
+    #           return value if value.is_a?(Hash)
+    #
+    #           hash_caster.cast(value)
+    #         end
+    #
+    #         def to_array(value)
+    #           return value if value.is_a?(Array)
+    #
+    #           array_caster.cast(value)
+    #         end
+    #
+    #         private
+    #
+    #         def hash_caster
+    #           @hash_caster ||= EnumCaster.caster_for(:hash)
+    #         end
+    #
+    #         def array_caster
+    #           @array_caster ||= EnumCaster.caster_for(:array)
+    #         end
+    #       end
+    #     end
+    #
+    #     # main.rb
+    #     EnumConverter.to_array({ key: :value }) # returns [%i[key value]]
+    #     EnumConverter.to_hash([%i[key value]]) # returns { key: :value }
+    #
+    # @overload caster_for(class_key)
+    #   @param class_key [Class] Class to used as key in the casters storage
+    #
+    #   When the +class_key+ does not match the stored key, but matches a superclass,
+    #   the registerd caster is returned.
+    #
+    #   @example Getting the caster with class key'
+    #     # stringer_parser.rb
+    #     class StringParser < Sinclair::Caster
+    #       master_caster!
+    #
+    #       cast_with(JSON) { |value| JSON.parse(value) }
+    #       cast_with(Integer, :to_i)
+    #       cast_with(Float, :to_f)
+    #     end
+    #
+    #     # main.rb
+    #     StringParser.cast('{"key":"value"}', JSON) # returns { "key" => "value" }
+    #     StringParser.cast('10.2', Integer) # returns 10
+    #     StringParser.cast('10.2', Float) # returns 10.2
+    #
+    # @see Caster::ClassMethods#caster_for
+    # @see Caster.cast_with
+    # @see Caster.cast
+    #
+    # @return [Caster]
+
+    # @param block [Proc] Proc to be used when converting the value object
+    def initialize(&block)
+      @block = block.to_proc
+    end
+
+    # Cast a value using the given the set +block+
+    #
+    # @param value [Object] value to be converted
+    # @param opts [Hash] options to be sent to the block
+    #
+    # When the block does not accept options, those
+    # are not passed
+    #
+    # @example Casts from a selected caster
+    #   # math_caster.rb
+    #   class MathCaster < Sinclair::Caster
+    #     cast_with(:float, :to_f)
+    #
+    #     cast_with(:log) do |value, base: 10|
+    #       value = MathCaster.cast(value, :float)
+    #
+    #       Math.log(value, base)
+    #     end
+    #   end
+    #
+    #   # main.rb
+    #   caster = MathCaster.caster_for(:log)
+    #
+    #   caster.cast(100) # returns 2
+    #   caster.cast(8, base: 2) # returns 3
+    #
+    # @return [Object] the result of the converting block
+    def cast(value, **opts)
+      options = opts.select do |key, _|
+        options_keys.include?(key)
+      end
+
+      block.call(value, **options)
+    end
+
+    private
+
+    # @api private
+    # @private
+    #
+    # Keys of options accepted by the block
+    #
+    # @return [Array<Symbol>]
+    def options_keys
+      @options_keys ||= block.parameters.select do |(type, _)|
+        %i[key keyreq].include? type
+      end.map(&:second)
+    end
+
+    # @method block
+    # @api private
+    # @private
+    #
+    # Proc to be used when converting the value object
+    #
+    # @return [Proc]
+    attr_reader :block
+  end
+end

data/lib/sinclair/config_class.rb

@@ -69,22 +69,16 @@ class Sinclair
     #
     #   config = AppConfig.new
     #
-    #   config.secret
-    #   # return nil
-    #
-    #   config.app_name
-    #   # return 'MyApp'
+    #   config.secret # return nil
+    #   config.app_name # return 'MyApp'
     #
     #   config_builder = Sinclair::ConfigBuilder.new(config)
     #
     #   config_builder.secret '123abc'
     #   config_builder.app_name 'MySuperApp'
     #
-    #   config.secret
-    #   # return '123abc'
-    #
-    #   config.app_name
-    #   # return 'MySuperApp'
+    #   config.secret # return '123abc'
+    #   config.app_name # return 'MySuperApp'
     def add_configs(*args)
       Config::MethodsBuilder.new(self, *args).tap do |builder|
         builder.build

data/lib/sinclair/method_definition/stringifier.rb

@@ -8,7 +8,14 @@ class Sinclair
     # @author darthjee
     #
     # Stringgify a value for {StringDefinition}
-    class Stringifier
+    class Stringifier < Caster
+      master_caster!
+
+      cast_with(NilClass) { 'nil' }
+      cast_with(Symbol) { |value| ":#{value}" }
+      cast_with(String, :to_json)
+      cast_with(Object, :to_s)
+
       # Convert a value to a string format
       #
       # The returned string can be evaluated as code, returning the
@@ -18,12 +25,7 @@ class Sinclair
       #
       # @return [String]
       def self.value_string(value)
-        return 'nil' if value.nil?
-        return ":#{value}" if value.is_a?(Symbol)
-
-        return value.to_s if value.is_any?(Class, Hash, Array)
-
-        value.to_json
+        cast(value, value.class)
       end
     end
   end

data/lib/sinclair/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Sinclair
-  VERSION = '1.14.2'
+  VERSION = '1.16.0'
 end