knowledge 0.1.0

data/lib/knowledge/exceptions.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Knowledge
+  #
+  # === Description ===
+  #
+  # This error class should be considered as the lib's standard error.
+  # All error classes inherit from this one.
+  # The goal is to be able to rescue Knowledge::Error outside the lib and catch them all.
+  #
+  # === Usage ===
+  #
+  # You have many examples behind. Just inherit from this class and it's ok.
+  #
+  # @example:
+  #   class ::MyCustomKnowledgeError < Knowledge::Error; end
+  #
+  class Error < ::StandardError; end
+
+  #
+  # === Description ===
+  #
+  # This error is used when, at some point, we can't find the adapter we're looking for
+  #
+  class AdapterNotFound < Error; end
+
+  #
+  # === Description ===
+  #
+  # This error is used when an adapter has no #run method declared
+  #
+  class AdapterRunMethodNotImplemented < Error; end
+
+  #
+  # === Description ===
+  #
+  # This error is pretty generic and is meant to be used when we're not able to gather infos in order to set vars.
+  #
+  class LearnError < Error; end
+
+  #
+  # === Description ===
+  #
+  # This error is used when we fail registering an adapter.
+  #
+  class RegisterError < Error; end
+end

data/lib/knowledge/initializer.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Knowledge
+  #
+  # === Description ===
+  #
+  # We all need an initializer, here's this lib's initializer.
+  # Its role is to gather all informations and run the enabled adapters.
+  #
+  # === Usage ===
+  #
+  # @example:
+  #   Knowledge::Initializer.new(adapters: adapters, params: { foo: :bar }, setter: setter, variables: variables).run
+  #
+  #   Knowledge::Initializer.run(adapters: adapters, params: { foo: :bar }, setter: setter, variables: variables)
+  #
+  # === Attributes ===
+  #
+  # @attr_reader [Array<String | Symbol>] adapters
+  # @attr_reader [Hash] params
+  # @attr_reader [Class] setter
+  # @attr_reader [Hash] variables
+  #
+  class Initializer
+    # == Attributes ==================================================================================================
+    attr_reader :adapters, :params, :setter, :variables
+
+    # == Constructor =================================================================================================
+    #
+    # @option [Array<Class>] :adapters
+    # @option [Hash] :params
+    # @option [Class] :setter
+    # @option [Hash] :variables
+    #
+    def initialize(adapters:, params:, setter:, variables:)
+      @adapters = adapters
+      @params = params
+      @setter = setter
+      @variables = variables
+    end
+
+    # == Class methods ===============================================================================================
+    class << self
+      #
+      # === Description ===
+      #
+      # Instanciates the current class and runs all registered adapters.
+      #
+      # === Parameters ===
+      #
+      # @option [Hash{Symbol => Class}] :adapters
+      # @option [Hash] :params
+      # @option [Class] :setter
+      # @option [Hash] :variables
+      #
+      def run(adapters:, params:, setter:, variables: {})
+        new(adapters: adapters, params: params, setter: setter, variables: variables).run
+      end
+    end
+
+    # == Instance methods ============================================================================================
+    #
+    # === Description ===
+    #
+    # Runs all registered adapters.
+    #
+    def run
+      Hash(adapters).each do |name, adapter|
+        adapter.new(
+          params: params[name.to_sym] || params,
+          setter: setter,
+          variables: variables[name.to_sym] || variables
+        ).run
+      end
+    end
+  end
+end

data/lib/knowledge/learner.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+require 'knowledge/initializer'
+require 'knowledge/adapters'
+require 'knowledge/setter'
+
+module Knowledge
+  #
+  # === Description ===
+  #
+  # Knowledge is something that needs some learning.
+  #
+  # === Usage ===
+  #
+  # @example:
+  #
+  #   learner = Knowledge::Learner.new
+  #
+  # === Attributes ===
+  #
+  # @attr_reader [Hash] additionnal_params
+  # @attr_reader [Hash{Symbol => Class}] available_adapters
+  # @attr_reader [Hash{Symbol => Class}] enabled_adapters
+  # @attr [Class] setter
+  # @attr_reader [Hash] variables
+  #
+  class Learner
+    # == Attributes ====================================================================================================
+    attr_accessor :setter
+    attr_reader :additionnal_params, :available_adapters, :enabled_adapters, :variables
+
+    # == Constructor ===================================================================================================
+    def initialize
+      @additionnal_params = {}
+      @available_adapters = {}
+      @enabled_adapters = {}
+      @setter = ::Knowledge::Setter.new
+      @variables = {}
+    end
+
+    # == Class methods =================================================================================================
+    class << self
+      attr_reader :adapters
+
+      def register_default_adapter(names:, klass:)
+        @adapters ||= {}
+
+        names.each { |name| @adapters[name.to_sym] = klass }
+      end
+    end
+
+    # == Instance methods ==============================================================================================
+    #
+    # === Description ===
+    #
+    # Gathers all the knowledge and put it into your app.
+    #
+    # === Usage ===
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   # Do some config (add adapters, define your setter, etc.)
+    #   learner.gather!
+    #
+    def gather!
+      ::Knowledge::Initializer.new(
+        adapters: enabled_adapters,
+        params: additionnal_params,
+        setter: setter,
+        variables: variables
+      ).run
+    end
+
+    # == Adapters methods ============================================================================================
+    #
+    # === Description ===
+    #
+    # Sets additional params to be passed to the adapter through params option.
+    #
+    # === Usage ===
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   learner.add_adapter_param(adapter: :custom, name: :base_path, value: '/base/path')
+    #
+    # === Parameters ===
+    #
+    # @option [String | Symbol] :adapter
+    # @option [String | Symbol] :name
+    # @option [any] :value
+    #
+    def add_adapter_param(adapter:, name:, value:)
+      @additionnal_params[adapter.to_sym] ||= {}
+      @additionnal_params[adapter.to_sym][name] = value
+    end
+
+    #
+    # === Description ===
+    #
+    # Sets additional params to be passed to the adapter through params option.
+    #
+    # === Usage ===
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   learner.add_adapter_param(name: :base_path, value: '/base/path')
+    #
+    # === Parameters ===
+    #
+    # @option [String | Symbol] :adapter
+    # @option [any] :params
+    #
+    def add_adapter_params(adapter:, params:)
+      @additionnal_params[adapter.to_sym] = params
+    end
+
+    #
+    # === Description ===
+    #
+    # Disables an adapter.
+    #
+    # === Usage ===
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   learner.register_adapter(name: :my_adapter, klass: MyAdapter, enable: true)
+    #   # Somewhere else in the code
+    #   learner.disable_adapter(name: :my_adapter) if should_disable_custom_adapter?
+    #
+    # === Parameters ===
+    #
+    # @option [String | Symbol] :name
+    #
+    def disable_adapter(name:)
+      @enabled_adapters.delete(name.to_sym)
+    end
+
+    #
+    # === Description ===
+    #
+    # Enables an adapter.
+    #
+    # === Usage ===
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   learner.register_adapter(name: :my_adapter, klass: MyAdapter)
+    #   learner.enable_adapter(name: :my_adapter)
+    #
+    # === Errors ===
+    #
+    # @raises [Knowledge::AdapterNotFound] if adapter is not available
+    #
+    # === Parameters ===
+    #
+    # @option [String | Symbol] :name
+    # @option [Hash | String | nil] :variables
+    #
+    def enable_adapter(name:, variables: nil)
+      _key, klass = available_adapters.find { |key, _klass| key.to_sym == name.to_sym }
+
+      raise Knowledge::AdapterNotFound, "Cannot find \"#{name}\" in available adapters" if klass.nil?
+
+      @enabled_adapters[name.to_sym] = klass
+      set_adapter_variables(name: name, variables: variables)
+    end
+
+    #
+    # === Description ===
+    #
+    # Registers an adapter and enable it if asked.
+    #
+    # === Usage ===
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   learner.register_adapter(name: :my_adapter, klass: MyAdapter, enable: true)
+    #
+    # === Parameters ===
+    #
+    # @option [String | Symbol] :name
+    # @option [Class] :klass
+    # @option [Boolean] :enable
+    # @option [Hash | String | nil] :variables
+    #
+    def register_adapter(name:, klass:, enable: false, variables: nil)
+      @available_adapters[name.to_sym] = klass
+      enable_adapter(name: name) if enable
+      set_adapter_variables(name: name, variables: variables)
+    end
+
+    #
+    # === Description ===
+    #
+    # Sets variables for a given adapter
+    #
+    # === Usage ===
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   learner.set_adapter_variables(name: :default, variables: { foo: :bar })
+    #
+    # === Attributes ===
+    #
+    # @option [String | Symbol] :name
+    # @option [Hash | nil] :variables
+    #
+    def set_adapter_variables(name:, variables: nil)
+      return unless variables
+
+      case variables
+      when Hash
+        set_adapter_variables_by_hash(name: name, variables: variables)
+      when String
+        set_adapter_variables(name: name, variables: yaml_content(variables))
+      else
+        raise "Unknown variables type #{variables.class}"
+      end
+    rescue StandardError => e
+      raise ::Knowledge::LearnError, e.message
+    end
+
+    #
+    # === Description ===
+    #
+    # Sets variables as a hash for a given adapter
+    #
+    # === Usage ===
+    #
+    # @example
+    #   learner = Knowledge::Learner.new
+    #   learner.set_adapter_variables_by_hash(name: :default, variables: { foo: :bar })
+    #
+    # === Attributes ===
+    #
+    # @option [String | Symbol] :name
+    # @option [Hash] :variables
+    #
+    def set_adapter_variables_by_hash(name:, variables:)
+      variables = variables[name.to_s] if variables.key?(name.to_s)
+      variables = variables[name.to_sym] if variables.key?(name.to_sym)
+      @variables[name.to_sym] = variables
+    end
+
+    #
+    # === Description ===
+    #
+    # Unregisters an adapter and disable it.
+    #
+    # === Usage ===
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   learner.register_adapter(name: :my_adapter, klass: MyAdapter)
+    #   # somewhere else in the code
+    #   learner.unregister_adapter(name: :my_adapter)
+    #
+    # === Parameters ===
+    #
+    # @option [String | Symbol] :name
+    #
+    def unregister_adapter(name:)
+      disable_adapter(name: name)
+      @available_adapters.delete(name.to_sym)
+    end
+
+    #
+    # === Description ===
+    #
+    # Registers & enables one of the lib's adapters.
+    #
+    # === Usage ===
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   learner.use(name: :ssm)
+    #
+    # === Parameters ===
+    #
+    # @option [String | Symbol] name
+    # @option [Boolean] enable
+    #
+    def use(name:, enable: true)
+      adapter = self.class.adapters[name.to_sym]
+
+      raise ::Knowledge::RegisterError, "Unable to register following: #{name}" if adapter.nil?
+
+      register_adapter(name: name.to_sym, klass: adapter, enable: enable)
+    end
+
+    # == Variables config ==============================================================================================
+    #
+    # === Description ===
+    #
+    # Setter for the variables config.
+    #
+    # === Usage ===
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   learner.variables = { name: 'value' }
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   learner.use(name: :env)
+    #   learner.variables = { name: 'ENV_KEY' }
+    #
+    # @example:
+    #   learner = Knowledge::Learner.new
+    #   learner.variables = 'path/to/vars/config/file.yml'
+    #
+    # === Errors ===
+    #
+    # @raise [Knowledge::LearnError] if parameter isn't a hash or a string
+    #
+    # === Parameters
+    #
+    # @param [String | Hash] path_or_descriptor
+    #
+    def variables=(path_or_descriptor)
+      case path_or_descriptor
+      when Hash
+        @variables = path_or_descriptor
+      when String
+        fetch_variables_config(path_or_descriptor)
+      else
+        raise ::Knowledge::LearnError, "Unable to understand following path or descriptor: #{path_or_descriptor}"
+      end
+    end
+
+    protected
+
+    #
+    # === Description ===
+    #
+    # Opens the config file and sets the variable config.
+    #
+    # === Parameters ===
+    #
+    # @param [String] path
+    #
+    def fetch_variables_config(path)
+      descriptor = yaml_content(path)
+      @variables = descriptor[::Knowledge.config.environment.to_s] || descriptor
+    end
+
+    #
+    # === Description ===
+    #
+    # Loads YAML file content
+    #
+    # === Parameters ===
+    #
+    # @param [String] path
+    #
+    # @return [Hash]
+    #
+    def yaml_content(path)
+      ::YAML.safe_load(::File.open(path))
+    end
+  end
+end
+
+# Registering default adapters
+
+Knowledge::Learner.register_default_adapter(
+  klass: Knowledge::Adapters::Environment,
+  names: %i[env environment env_vars]
+)
+
+Knowledge::Learner.register_default_adapter(
+  klass: Knowledge::Adapters::KeyValue,
+  names: %i[default keyval key_value]
+)
+
+Knowledge::Learner.register_default_adapter(
+  klass: Knowledge::Adapters::File,
+  names: %i[config file config_file]
+)