sinclair 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19c1884db0b54297baef8febbc49ed4ed07e97603af7553ddfa90ab02c2fa836
-  data.tar.gz: 880bf1db3d2b09f95d0103622a6ab42b62cbed746447c9435168eaaa18359042
+  metadata.gz: bca1f4b9666c1916f4131d87e1f2acb9d417b0190bad68502299b0aa597dd19c
+  data.tar.gz: 329ca4de9e7ed56c10c6306801fd001a4a10eb890a9e145cb2a5db7009afbf75
 SHA512:
-  metadata.gz: 6e2e7c8f8c0488e75d23ced4234c796da41cddba29e0f26087fc3522f232ccabfae08d1ac30a4eb1223463579fb371aa4e9ba7f3e4b9d1c6d05eaaae26b1d2ab
-  data.tar.gz: 4e9dbdb362d045182d4b28075153d08b708f01f3697dc8550fb29715dad135b245544a94f6a2db605f7e814460ab24126825e6d3c49c08a69e674b28cfa08902
+  metadata.gz: b5b81908de91bc67ad5aa309d212ed5f3250f2ff01b78c0549ba1bb137f07955462ef6f4b48f998fbb36917cc0a739b2befe80b9798906d4ca00c1d5cdd71468
+  data.tar.gz: a53161407bbafb1a1150b4a6643af49bbab613290bbbcdd7fe839575384a4b954d3bc17feeb7943b409a09db7a74a690184590d59d5452b2e00769c1e4e9826c

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: [2.0.1](https://github.com/darthjee/sinclair/tree/2.0.1)
+Current Release: [2.1.0](https://github.com/darthjee/sinclair/tree/2.1.0)
 
-[Next release](https://github.com/darthjee/sinclair/compare/2.0.1...master)
+[Next release](https://github.com/darthjee/sinclair/compare/2.1.0...master)
 
 Yard Documentation
 -------------------
-[https://www.rubydoc.info/gems/sinclair/2.0.1](https://www.rubydoc.info/gems/sinclair/2.0.1)
+[https://www.rubydoc.info/gems/sinclair/2.1.0](https://www.rubydoc.info/gems/sinclair/2.1.0)
 
 Installation
 ---------------

data/config/check_specs.yml

@@ -8,4 +8,6 @@ ignore:
   - lib/sinclair/matchers/change_method_on.rb
   - lib/sinclair/matchers/method_to.rb
   - lib/sinclair/model/builder_options.rb
+  - lib/sinclair/settable/class_methods.rb
+  - lib/sinclair/settable/caster.rb
   - lib/sinclair/version.rb

data/config/yardstick.yml

@@ -1,4 +1,4 @@
-threshold: 100
+threshold: 99.9
 require_exact_threshold: false
 rules:
   ApiTag::Presence:
@@ -39,6 +39,8 @@ rules:
       - Sinclair::Matchers#change_class_method
       - Sinclair::Model.for
       - Sinclair::Model.initialize_with
+      - Sinclair::Settable#setting_with_options
+      - Sinclair::Settable::Builder#read_block
   ReturnTag:
     enabled: true
     exclude:
@@ -48,6 +50,7 @@ rules:
       - Sinclair::MethodBuilder#build_from_definition
       - Sinclair::Matchers::ChangeClassMethodOn#raise_block_syntax_error
       - Sinclair::Matchers::ChangeInstanceMethodOn#raise_block_syntax_error
+      - Sinclair::Settable::Builder#read_block
   Summary::Presence:
     enabled: true
     exclude:
@@ -79,6 +82,7 @@ rules:
       - Sinclair::Model::Builder#initialize
       - Sinclair::Options#initialize
       - Sinclair::Options::Builder#initialize
+      - Sinclair::Settable::Builder#initialize
   Summary::Length:
     enabled: true
     exclude: []

data/lib/sinclair/chain_settable.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+class Sinclair
+  # @api public
+  # @author darthjee
+  #
+  # Settable that recovers data from other settables
+  #
+  # Each setting obeys a settable order and when a setting value is not found,
+  # the next is checked
+  module ChainSettable
+    include Sinclair::Settable
+    extend Sinclair::Settable::ClassMethods
+
+    read_with do |key, sources: nil, sources_map: {}|
+      sources.map_and_find do |source|
+        sources_map[source].public_send(key)
+      end
+    end
+
+    private
+
+    # @private
+    # @api public
+    # @visibility public
+    #
+    # Register a setting source
+    #
+    # @param key [Symbol] key identifying the setting
+    # @param source [Class<Settable>] Setting source class
+    #
+    # @return [Class<Settable>]
+    def source(key, source)
+      sources_map[key] = source
+    end
+
+    # @private
+    # @api public
+    # @visibility public
+    #
+    # Defines the order of the settings
+    #
+    # @param sources [Array<Symbol>] lis of sources in order
+    #
+    # @return [Array<Symbol>]
+    def sources(*sources)
+      @sources = sources
+    end
+
+    # @private
+    # @api private
+    #
+    # Hash with all Setting classes defined
+    #
+    # @return [Hash<Symbol,Settable>]
+    def sources_map
+      @sources_map ||= {}
+    end
+
+    # @private
+    # @api private
+    #
+    # Order of sources to be checked by default
+    #
+    # @return [Hash<Symbol,Settable>]
+    def sources_order
+      @sources || sources_map.keys
+    end
+
+    # @private
+    # @api private
+    #
+    # Returns default options passed to {read_block}
+    #
+    # @return [Hash<Symbol,Object>]
+    def default_options
+      {
+        sources: sources_order,
+        sources_map: sources_map
+      }
+    end
+  end
+end

data/lib/sinclair/core_ext/object.rb

@@ -23,4 +23,43 @@ class Object
     classes.any?(method(:is_a?))
   end
   # rubocop:enable Naming/PredicateName
+
+  # Maps the elements into a new value, returning only one
+  #
+  # The result to be returned is
+  # the first mapping that is evaluated to true
+  #
+  # This method is equivalent to #map#find but
+  # only calling the map block up to when a value
+  # is found
+  #
+  # @yield (*args) mappig block
+  #
+  # @example Using an array of keys to remove remove elements of a hash
+  #
+  #   service_map = {
+  #     a: nil,
+  #     b: false,
+  #     c: 'found me',
+  #     d: nil,
+  #     e: 'didnt find me'
+  #   }
+  #
+  #   keys = %i[a b c d e]
+  #
+  #   keys.map_and_find do |key|   #
+  #     service_values.delete(key) #
+  #   end                          # returns 'found me'
+  #
+  #   service_map # has lost only 3 keys returning
+  #               # { d: nil, e: 'didnt find me' }
+  #
+  # @return [::Object]
+  def map_and_find
+    mapped = nil
+    find do |*args|
+      mapped = yield(*args)
+    end
+    mapped || nil
+  end
 end

data/lib/sinclair/env_settable.rb

@@ -13,20 +13,25 @@ class Sinclair
   #     settings_prefix 'MY_APP'
   #
   #     with_settings :username, :password, host: 'my-host.com'
+  #     setting_with_options :port, type: :integer
   #   end
   #
   #   ENV['MY_APP_USERNAME'] = 'my_login'
+  #   ENV['MY_APP_PORT']     = '8080'
   #
   #   MyAppClient.username # returns 'my_login'
   #   MyAppClient.password # returns nil
   #   MyAppClient.host     # returns 'my-host.com'
-  #
-  #   ENV['MY_APP_HOST'] = 'other-host.com'
-  #
-  #   MyAppClient.host     # returns 'other-host.com'
-  #
+  #   MyAppClient.port     # returns 8080
   module EnvSettable
-    autoload :Builder, 'sinclair/env_settable/builder'
+    include Sinclair::Settable
+    extend Sinclair::Settable::ClassMethods
+
+    read_with do |key, prefix: nil|
+      env_key = [prefix, key].compact.join('_').to_s.upcase
+
+      ENV[env_key]
+    end
 
     private
 
@@ -41,25 +46,38 @@ class Sinclair
     # @return [String]
     #
     # @example (see EnvSettable)
-    def settings_prefix(prefix)
+    def settings_prefix(prefix = nil)
+      return @settings_prefix || superclass_prefix unless prefix
+
       @settings_prefix = prefix
     end
 
     # @private
-    # @api public
-    # @visibility public
+    # @api private
     #
-    # Adds settings
+    # Default options when creating the method
     #
-    # @param settings_name [Array<Symbol,String>] Name of all settings
-    #   to be added
-    # @param defaults [Hash] Settings with default values
+    # Prefix is included in default options
     #
-    # @return (see Sinclair#build)
+    # @return [Hash]
+    def default_options
+      super.merge(
+        prefix: settings_prefix
+      )
+    end
+
+    # @private
+    # @api private
     #
-    # @example (see EnvSettable)
-    def with_settings(*settings_name, **defaults)
-      Builder.new(self, @settings_prefix, *settings_name, **defaults).build
+    # Returns the prefix set up for a superclass
+    #
+    # This ensures that an inherited class also has a prefix
+    #
+    # @return [String]
+    def superclass_prefix
+      return unless superclass.is_a?(Sinclair::EnvSettable)
+
+      superclass.settings_prefix
     end
   end
 end

data/lib/sinclair/settable/builder.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+class Sinclair
+  module Settable
+    # @api private
+    # @author darthjee
+    #
+    # Env setting methods builder
+    #
+    # This builder does the magic of adding methods
+    # that will fetch variables from env or a default value
+    class Builder < Sinclair
+      # @param klass [Class] Setting class where the methods will be added to
+      # @param settings_name [Array<Symbol>] list of all settings to be added
+      # @param options [Hash] Options of setting.
+      #
+      #   Each settable might have their own set options defined in
+      #   {Sinclair::Settable::ClassMethods#read_with Settable.read_with},
+      #   and then passed to the buildr on
+      #   {Sinclair::Settable#setting_with_options Settable#setting_with_options}
+      #
+      # @option options type [Symbol] type to cast the value fetched
+      # @option options default [Object] Default value
+      def initialize(klass, *settings_name, **options)
+        super(klass, **options)
+
+        @settings = settings_name
+
+        add_all_methods
+      end
+
+      private
+
+      delegate :type, to: :options_object
+      # @method type
+      # @private
+      # @api private
+      #
+      # Returns the type to cast the retrieved value
+      #
+      # @return [Symbol]
+
+      delegate :settable_module, to: :klass
+      # @method settable_module
+      # @private
+      # @api private
+      #
+      # Module of settable that the class extends
+      #
+      # @return [Module]
+
+      delegate :read_with, to: :settable_module
+      # @method read_with
+      # @private
+      # @api private
+      #
+      # Returns proc for extracting values when reading a setting
+      #
+      # @see add_setting_method
+      # @see Settable::ClassMethods#read_with
+      # @return [Proc]
+      alias read_block read_with
+
+      attr_reader :settings
+      # @method settings
+      # @private
+      # @api private
+      #
+      # Name of all settings to be added
+      #
+      # @return [Array<Symbol>]
+
+      # @private
+      # @api private
+      #
+      # Process all settings adding the methods
+      #
+      # @return (see settings)
+      def add_all_methods
+        settings.each do |name|
+          add_setting_method(name)
+        end
+      end
+
+      # @private
+      #
+      # Add one setting class method to settings class
+      #
+      # @return (see Sinclair#add_class_method)
+      def add_setting_method(name)
+        options   = call_options
+        block     = read_block
+        caster    = caster_class.caster_for(type)
+        default   = options_object.default
+
+        add_class_method(name, cached: :full) do
+          value = instance_exec(name, **options, &block)
+
+          value ? caster.cast(value) : default
+        end
+      end
+
+      # @private
+      #
+      # Options that will be accepted by {read_block}
+      #
+      # The given options are sliced based on the accepted parameters
+      # from read_blocks
+      #
+      # @see read_block_options
+      # @see Settable::ClassMethods#read_with
+      # @return [Hash<Symbol, Object>]
+      def call_options
+        @call_options ||= options.slice(*read_block_options)
+      end
+
+      # @private
+      #
+      # List all keys accepted by {read_block}
+      #
+      # @see call_options
+      # @see Settable::ClassMethods#read_with
+      # @return [Array<Symbol>]
+      def read_block_options
+        read_block.parameters.select do |(type, _name)|
+          type == :key
+        end.map(&:second)
+      end
+
+      # @private
+      #
+      # Returns caster configured for casting the returning values
+      #
+      # @return [Class<Settable::Caster>]
+      def caster_class
+        settable_module::Caster
+      end
+    end
+  end
+end

data/lib/sinclair/settable/caster.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+class Sinclair
+  module Settable
+    # @api public
+    #
+    # Class responsible for casting the values
+    #
+    # New types can be added
+    #
+    # @example Adding a casting type to {Sinclair::Settable::Caster Sinclair::Settable::Caster}
+    #   class Sinclair
+    #     module Settable
+    #       class Caster
+    #         cast_with(:squared) { |value| value.to_f**2 }
+    #       end
+    #     end
+    #   end
+    #
+    #   class MathEnvSettings
+    #     extend Sinclair::EnvSettable
+    #
+    #     settings_prefix 'MATH'
+    #
+    #     setting_with_options :value, type: :squared
+    #   end
+    #
+    #   ENV['MATH_VALUE'] = '80'
+    #
+    #   settable.value # returns 6400.0
+    #
+    # @example Creating a new caster
+    #   module JsonEnvSettable
+    #     include Sinclair::EnvSettable
+    #     extend Sinclair::Settable::ClassMethods
+    #
+    #     class Caster < Sinclair::Settable::Caster
+    #       cast_with(:json) { |value| JSON.parse(value) }
+    #     end
+    #   end
+    #
+    #   class JsonEnvSettings
+    #     extend JsonEnvSettable
+    #
+    #     settings_prefix 'JSON'
+    #
+    #     setting_with_options :config, type: :json
+    #   end
+    #
+    #   hash = { key: 'value' }
+    #
+    #   ENV['JSON_CONFIG'] = hash.to_json
+    #
+    #   settable.config # returns { 'key' => 'value' }
+    class Caster < Sinclair::Caster
+      cast_with(:integer, &:to_i)
+      cast_with(:string, &:to_s)
+      cast_with(:float, &:to_f)
+    end
+  end
+end

data/lib/sinclair/settable/class_methods.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+class Sinclair
+  module Settable
+    # @api public
+    # @author darthjee
+    #
+    # Class methods availabe inside a Settable module
+    #
+    # The methods should help configuring the settable
+    #
+    # @see #read_with
+    module ClassMethods
+      # Register and return a block for reading a setting
+      #
+      # @param read_block [Proc] the block that will be used when
+      #   reading a setting key
+      #
+      # When the block is called, it will receive the key and any
+      # given options
+      #
+      # @return [Proc]
+      #
+      # @example
+      #   # config.yml
+      #   # timeout: 10
+      #
+      #   # yaml_file_settable.rb
+      #
+      #   module YamlFileSettable
+      #     include Sinclair::Settable
+      #     extend Sinclair::Settable::ClassMethods
+      #
+      #     read_with do |key, default: nil|
+      #       loaded_yaml[key.to_s] || default
+      #     end
+      #
+      #     def loaded_yaml
+      #       YAML.load_file(setting_file)
+      #     end
+      #
+      #     def setting_file(file_path = @setting_file)
+      #       @setting_file = file_path
+      #     end
+      #   end
+      #
+      #   # yaml_file_settings.rb
+      #
+      #   class YamlFileSettings
+      #     extend YamlFileSettable
+      #
+      #     setting_file 'config.yml'
+      #
+      #     setting_with_options :timeout, default: 30
+      #   end
+      #
+      #   YamlFileSettings.timeout # returns 10
+      def read_with(&read_block)
+        return @read_block = read_block if read_block
+        return @read_block if @read_block
+
+        superclass_settable&.read_with
+      end
+
+      private
+
+      # @private
+      # @api private
+      #
+      # Returns a {Settable} module representing a superclass
+      #
+      # @return [Module]
+      def superclass_settable
+        included_modules.find do |modu|
+          modu <= Sinclair::Settable
+        end
+      end
+    end
+  end
+end

data/lib/sinclair/settable.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+class Sinclair
+  # @api public
+  # @author darthjee
+  #
+  # Module to be extended or included, allowing settings to be read from a source
+  #
+  # @see Sinclair::EnvSettable
+  #
+  # @example Creating a custom settable
+  #
+  #   module HashSettable
+  #     extend Sinclair::Settable::ClassMethods
+  #     include Sinclair::Settable
+  #
+  #     read_with do |key, default: nil|
+  #       self::HASH[key] || default
+  #     end
+  #   end
+  #
+  #   class HashAppClient
+  #     extend HashSettable
+  #
+  #     HASH = {}
+  #
+  #     with_settings :username, :password, host: 'my-host.com'
+  #     setting_with_options :port, type: :integer
+  #   end
+  #
+  #   ENV[:username] = 'my_login'
+  #   ENV[:port]     = '8080'
+  #
+  #   HashAppClient.username # returns 'my_login'
+  #   HashAppClient.password # returns nil
+  #   HashAppClient.host     # returns 'my-host.com'
+  #   HashAppClient.port     # returns 8080
+  module Settable
+    autoload :Builder,      'sinclair/settable/builder'
+    autoload :Caster,       'sinclair/settable/caster'
+    autoload :ClassMethods, 'sinclair/settable/class_methods'
+
+    extend Sinclair::Settable::ClassMethods
+
+    # @api private
+    #
+    # returns the settable module that the class extends
+    #
+    # This is used in order to find out what is the read block used
+    # by the settable
+    #
+    # @return [Module] a +Sinclair::Settable+
+    def settable_module
+      @settable_module ||= singleton_class.included_modules.find do |modu|
+        modu <= Sinclair::Settable
+      end
+    end
+
+    private
+
+    # @private
+    # @api public
+    # @visibility public
+    #
+    # Adds settings
+    #
+    # @param settings_name [Array<Symbol,String>] Name of all settings
+    #   to be added
+    # @param defaults [Hash] Settings with default values
+    #
+    # @example (see Settable)
+    # @example (see EnvSettable)
+    #
+    # @see setting_with_options
+    #
+    # @return [Hash<Symbol, Object>]
+    def with_settings(*settings_name, **defaults)
+      setting_with_options(*settings_name)
+
+      defaults.each do |key, default|
+        setting_with_options(key, default: default)
+      end
+    end
+
+    # @private
+    # @api public
+    # @visibility public
+    #
+    # Add setting with options
+    #
+    # @param settings_name [Array<Symbol,String>] Name of all settings
+    #   to be added
+    # @param options [Hash<Symbol, Object>] setting exposition options
+    # @option options type [Symbol] type to cast the value fetched
+    # @option options default [Object] Default value
+    #
+    # @see with_settings
+    # @return (see Sinclair#build)
+    def setting_with_options(*settings_name, **options)
+      opts = default_options.merge(options)
+
+      Builder.build(self, *settings_name, **opts)
+    end
+
+    # @private
+    # @api private
+    #
+    # Default options when creating the method
+    #
+    # @return [Hash]
+    def default_options
+      {}
+    end
+  end
+end

data/lib/sinclair/version.rb

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

data/lib/sinclair.rb

@@ -85,6 +85,7 @@ class Sinclair
   autoload :VERSION,           'sinclair/version'
   autoload :Caster,            'sinclair/caster'
   autoload :ClassMethods,      'sinclair/class_methods'
+  autoload :ChainSettable,     'sinclair/chain_settable'
   autoload :Config,            'sinclair/config'
   autoload :ConfigBuilder,     'sinclair/config_builder'
   autoload :ConfigClass,       'sinclair/config_class'
@@ -100,6 +101,7 @@ class Sinclair
   autoload :MethodDefinitions, 'sinclair/method_definitions'
   autoload :Model,             'sinclair/model'
   autoload :Options,           'sinclair/options'
+  autoload :Settable,          'sinclair/settable'
 
   include OptionsParser
   extend ClassMethods