sinclair 1.14.1 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4984ad62935fbe5a85e51b846b5124b72153b94cf9433a8a668f824c11e5eeaf
-  data.tar.gz: 336e7c54378ccd676f59eb92fe2a1bf32de84ff9a8bc2a91c8a6dd1e6494b46d
+  metadata.gz: bd10c98e0ec9983e0bd34a8b438126cc391ae667c9e7d5b7ca62f473c5296aea
+  data.tar.gz: f1bffcf49524f9dc05ee27e7510c4e0a76be23b674642fcfa2b10cfdb9f43a82
 SHA512:
-  metadata.gz: f3a84c2a80644b15e31991cb99a314378453e642c29c9864080e96f28bd34234f2476735284291ba56dd48ab9d67883a5b16709a1aa67b31116ef262dd6b1df1
-  data.tar.gz: d1405b56826158314eb4d304b33c02dc18015e63fe58e716371f5a58c7a8f417652ea1026d5b533c844e7c5a89ffeae7990f70334e61dbf4019006f412359dfe
+  metadata.gz: f3afe247b25b8b10f692227c3d5c031e4d6fd04f8aa00e021d0aa8d5813d9cba75c05b4a7d8aae6cc5b6be96d7de404becf35e9391db92c3ceadfc2804f72ce5
+  data.tar.gz: c80cee176cd24ecce3410fa6a64789ca3f52789bce24d558b421751fb6c74a4bf5c86eb1246e48d09abbad962e3bc6f965f1dcf09beae9eca68a198d4e969771

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.1](https://github.com/darthjee/sinclair/tree/1.14.1)
+Current Release: [1.15.0](https://github.com/darthjee/sinclair/tree/1.15.0)
 
-[Next release](https://github.com/darthjee/sinclair/compare/1.14.1...master)
+[Next release](https://github.com/darthjee/sinclair/compare/1.15.0...master)
 
 Yard Documentation
 -------------------
-[https://www.rubydoc.info/gems/sinclair/1.14.1](https://www.rubydoc.info/gems/sinclair/1.14.1)
+[https://www.rubydoc.info/gems/sinclair/1.15.0](https://www.rubydoc.info/gems/sinclair/1.15.0)
 
 Installation
 ---------------
@@ -79,20 +79,20 @@ puts "One Hundred => #{Clazz.one_hundred_twenty}" # One Hundred Twenty => 120
 <summary>Builder in class method</summary>
 
 ```ruby
+# http_json_model.rb
+
 class HttpJsonModel
   attr_reader :json
 
   class << self
     def parse(attribute, path: [])
-      builder = Sinclair.new(self)
-
       keys = (path + [attribute]).map(&:to_s)
 
-      builder.add_method(attribute) do
-        keys.inject(hash) { |h, key| h[key] }
+      Sinclair.build(self) do
+        add_method(attribute) do
+          keys.inject(hash) { |h, key| h[key] }
+        end
       end
-
-      builder.build
     end
   end
 
@@ -104,6 +104,10 @@ class HttpJsonModel
     @hash ||= JSON.parse(json)
   end
 end
+```
+
+```ruby
+# http_person.rb
 
 class HttpPerson < HttpJsonModel
   parse :uid
@@ -112,7 +116,9 @@ class HttpPerson < HttpJsonModel
   parse :username, path: [:digital_information]
   parse :email,    path: [:digital_information]
 end
+```
 
+```ruby
 json = <<-JSON
   {
     "uid": "12sof511",
@@ -284,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
 ```
@@ -320,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
 ```
@@ -675,6 +681,15 @@ You can use the provided matcher to check that your builder is adding a method c
 <summary>Sample of specs over adding methods</summary>
 
 ```ruby
+# spec_helper.rb
+
+RSpec.configure do |config|
+  config.include Sinclair::Matchers
+end
+```
+
+```ruby
+# default_value.rb
 class DefaultValue
   delegate :build, to: :builder
   attr_reader :klass, :method, :value, :class_method
@@ -698,8 +713,12 @@ class DefaultValue
     end
   end
 end
+```
+
+```ruby
+# default_value_spec.rb
 
-RSpec.describe Sinclair::Matchers do
+RSpec.describe DefaultValue do
   subject(:builder_class) { DefaultValue }
 
   let(:klass)         { Class.new }

data/config/yardstick.yml

@@ -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,127 @@
+# 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)
+        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 MyCaster < Sinclair::Caster
+    #   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
+
+    cast_with(:string, :to_s)
+    cast_with(:integer, :to_i)
+    cast_with(:float, :to_f)
+  end
+end