qonfig 0.10.0 → 0.11.0

data/lib/qonfig/data_set.rb

@@ -1,163 +1,211 @@
 # frozen_string_literal: true
 
-module Qonfig
+# @api public
+# @since 0.1.0
+class Qonfig::DataSet
+  require_relative 'data_set/class_builder'
+  require_relative 'data_set/validator'
+
+  # @since 0.1.0
+  extend Qonfig::DSL
+
+  # @return [Qonfig::Settings]
+  #
+  # @api private
+  # @since 0.1.0
+  attr_reader :settings
+
+  # @param options_map [Hash]
+  # @param configurations [Proc]
+  #
   # @api public
   # @since 0.1.0
-  class DataSet
-    # @since 0.1.0
-    extend Qonfig::DSL
-
-    # @return [Qonfig::Settings]
-    #
-    # @api private
-    # @since 0.1.0
-    attr_reader :settings
-
-    # @param options_map [Hash]
-    # @param configurations [Proc]
-    #
-    # @api public
-    # @since 0.1.0
-    def initialize(options_map = {}, &configurations)
-      @__access_lock__ = Mutex.new
-      @__definition_lock__ = Mutex.new
-
-      thread_safe_definition { load!(options_map, &configurations) }
-    end
+  def initialize(options_map = {}, &configurations)
+    @__access_lock__ = Mutex.new
+    @__definition_lock__ = Mutex.new
 
-    # @return [void]
-    #
-    # @api public
-    # @since 0.1.0
-    def freeze!
-      thread_safe_access { settings.__freeze__ }
-    end
+    thread_safe_definition { load!(options_map, &configurations) }
+  end
 
-    # @return [void]
-    #
-    # @api public
-    # @since 0.2.0
-    def frozen?
-      thread_safe_access { settings.__is_frozen__ }
-    end
+  # @return [void]
+  #
+  # @api public
+  # @since 0.1.0
+  def freeze!
+    thread_safe_access { settings.__freeze__ }
+  end
 
-    # @param options_map [Hash]
-    # @param configurations [Proc]
-    # @return [void]
-    #
-    # @raise [Qonfig::FrozenSettingsError]
-    #
-    # @api public
-    # @since 0.2.0
-    def reload!(options_map = {}, &configurations)
-      thread_safe_definition do
-        raise Qonfig::FrozenSettingsError, 'Frozen config can not be reloaded' if frozen?
-        load!(options_map, &configurations)
-      end
-    end
+  # @return [void]
+  #
+  # @api public
+  # @since 0.2.0
+  def frozen?
+    thread_safe_access { settings.__is_frozen__ }
+  end
 
-    # @param options_map [Hash]
-    # @return [void]
-    #
-    # @api public
-    # @since 0.1.0
-    def configure(options_map = {})
-      thread_safe_access do
-        settings.__apply_values__(options_map)
-        yield(settings) if block_given?
-      end
+  # @param options_map [Hash]
+  # @param configurations [Proc]
+  # @return [void]
+  #
+  # @raise [Qonfig::FrozenSettingsError]
+  #
+  # @api public
+  # @since 0.2.0
+  def reload!(options_map = {}, &configurations)
+    thread_safe_definition do
+      raise Qonfig::FrozenSettingsError, 'Frozen config can not be reloaded' if frozen?
+      load!(options_map, &configurations)
     end
+  end
 
-    # @return [Hash]
-    #
-    # @api public
-    # @since 0.1.0
-    def to_h
-      thread_safe_access { settings.__to_hash__ }
-    end
-    alias_method :to_hash, :to_h
-
-    # @param key [String, Symbol]
-    # @return [Object]
-    #
-    # @api public
-    # @since 0.2.0
-    def [](key)
-      thread_safe_access { settings[key] }
+  # @param options_map [Hash]
+  # @return [void]
+  #
+  # @api public
+  # @since 0.1.0
+  def configure(options_map = {})
+    thread_safe_access do
+      settings.__apply_values__(options_map)
+      yield(settings) if block_given?
     end
+  end
 
-    # @param keys [Array<String, Symbol>]
-    # @return [Object]
-    #
-    # @api public
-    # @since 0.2.0
-    def dig(*keys)
-      thread_safe_access { settings.__dig__(*keys) }
+  # @option key_transformer [Proc]
+  # @option value_transformer [Proc]
+  # @return [Hash]
+  #
+  # @api public
+  # @since 0.1.0
+  def to_h(
+    key_transformer: Qonfig::Settings::BASIC_SETTING_KEY_TRANSFORMER,
+    value_transformer: Qonfig::Settings::BASIC_SETTING_VALUE_TRANSFORMER
+  )
+    thread_safe_access do
+      settings.__to_hash__(
+        transform_key: key_transformer,
+        transform_value: value_transformer
+      )
     end
+  end
+  alias_method :to_hash, :to_h
 
-    # @param keys [Array<String, Symbol>]
-    # @return [Hash]
-    #
-    # @api public
-    # @since 0.9.0
-    def slice(*keys)
-      thread_safe_access { settings.__slice__(*keys) }
+  # @option path [String]
+  # @option options [Hash<Symbol|String,Any>] Native (ruby-stdlib) ::JSON#generate attributes
+  # @param value_processor [Block]
+  # @return [void]
+  #
+  # @api public
+  # @since 0.11.0
+  def save_to_json(path:, options: Qonfig::Uploaders::JSON::DEFAULT_OPTIONS, &value_processor)
+    thread_safe_access do
+      Qonfig::Uploaders::JSON.upload(settings, path: path, options: options, &value_processor)
     end
+  end
 
-    # @param keys [Array<String, Symbol>]
-    # @return [Hash,Any]
-    #
-    # @api public
-    # @since 0.10.0
-    def slice_value(*keys)
-      thread_safe_access { settings.__slice_value__(*keys) }
+  # @option path [String]
+  # @option symbolize_keys [Boolean]
+  # @option options [Hash<Symbol|String,Any>] Native (ruby-stdlib) ::YAML#dump attributes
+  # @param value_processor [Block]
+  # @return [void]
+  #
+  # @api public
+  # @since 0.11.0
+  def save_to_yaml(
+    path:,
+    symbolize_keys: false,
+    options: Qonfig::Uploaders::YAML::DEFAULT_OPTIONS,
+    &value_processor
+  )
+    thread_safe_access do
+      Qonfig::Uploaders::YAML.upload(
+        settings,
+        path: path,
+        options: options.merge(symbolize_keys: symbolize_keys),
+        &value_processor
+      )
     end
+  end
 
-    # @return [void]
-    #
-    # @api public
-    # @since 0.2.0
-    def clear!
-      thread_safe_access { settings.__clear__ }
-    end
+  # @param key [String, Symbol]
+  # @return [Object]
+  #
+  # @api public
+  # @since 0.2.0
+  def [](key)
+    thread_safe_access { settings[key] }
+  end
 
-    private
+  # @param keys [Array<String, Symbol>]
+  # @return [Object]
+  #
+  # @api public
+  # @since 0.2.0
+  def dig(*keys)
+    thread_safe_access { settings.__dig__(*keys) }
+  end
 
-    # @return [Qonfig::Settings]
-    #
-    # @api private
-    # @since 0.2.0
-    def build_settings
-      Qonfig::Settings::Builder.build(self.class.commands.dup)
-    end
+  # @param keys [Array<String, Symbol>]
+  # @return [Hash]
+  #
+  # @api public
+  # @since 0.9.0
+  def slice(*keys)
+    thread_safe_access { settings.__slice__(*keys) }
+  end
 
-    # @param options_map [Hash]
-    # @param configurations [Proc]
-    # @return [void]
-    #
-    # @api private
-    # @since 0.2.0
-    def load!(options_map = {}, &configurations)
-      @settings = build_settings
-      configure(options_map, &configurations)
-    end
+  # @param keys [Array<String, Symbol>]
+  # @return [Hash,Any]
+  #
+  # @api public
+  # @since 0.10.0
+  def slice_value(*keys)
+    thread_safe_access { settings.__slice_value__(*keys) }
+  end
 
-    # @param instructions [Proc]
-    # @return [Object]
-    #
-    # @api private
-    # @since 0.2.0
-    def thread_safe_access(&instructions)
-      @__access_lock__.synchronize(&instructions)
-    end
+  # @return [void]
+  #
+  # @api public
+  # @since 0.2.0
+  def clear!
+    thread_safe_access { settings.__clear__ }
+  end
 
-    # @param instructions [Proc]
-    # @return [Object]
-    #
-    # @api private
-    # @since 0.2.0
-    def thread_safe_definition(&instructions)
-      @__definition_lock__.synchronize(&instructions)
-    end
+  private
+
+  # @return [Qonfig::Settings]
+  #
+  # @api private
+  # @since 0.2.0
+  def build_settings
+    Qonfig::Settings::Builder.build(self.class.commands.dup)
+  end
+
+  # @param options_map [Hash]
+  # @param configurations [Proc]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.2.0
+  def load!(options_map = {}, &configurations)
+    @settings = build_settings
+    configure(options_map, &configurations)
+  end
+
+  # @param instructions [Proc]
+  # @return [Object]
+  #
+  # @api private
+  # @since 0.2.0
+  def thread_safe_access(&instructions)
+    @__access_lock__.synchronize(&instructions)
+  end
+
+  # @param instructions [Proc]
+  # @return [Object]
+  #
+  # @api private
+  # @since 0.2.0
+  def thread_safe_definition(&instructions)
+    @__definition_lock__.synchronize(&instructions)
   end
 end

data/lib/qonfig/dsl.rb

@@ -1,124 +1,122 @@
 # frozen_string_literal: true
 
-module Qonfig
-  # @api private
-  # @since 0.1.0
-  module DSL
-    class << self
-      # @param child_klass [Qonfig::DataSet]
-      # @return [void]
-      #
-      # @api private
-      # @since 0.1.0
-      def extended(child_klass)
-        child_klass.instance_variable_set(:@commands, Qonfig::CommandSet.new)
-
-        child_klass.singleton_class.prepend(Module.new do
-          def inherited(child_klass)
-            child_klass.instance_variable_set(:@commands, Qonfig::CommandSet.new)
-            child_klass.commands.concat(commands)
-            super
-          end
-        end)
-      end
-    end
-
-    # @return [Qonfig::CommandSet]
+# @api private
+# @since 0.1.0
+module Qonfig::DSL
+  class << self
+    # @param child_klass [Qonfig::DataSet]
+    # @return [void]
     #
     # @api private
     # @since 0.1.0
-    def commands
-      @commands
-    end
+    def extended(child_klass)
+      child_klass.instance_variable_set(:@commands, Qonfig::CommandSet.new)
 
-    # @param key [Symbol, String]
-    # @param initial_value [Object]
-    # @param nested_settings [Proc]
-    # @return [void]
-    #
-    # @see Qonfig::Commands::AddNestedOption
-    # @see Qonfig::Commands::AddOption
-    #
-    # @api public
-    # @since 0.1.0
-    def setting(key, initial_value = nil, &nested_settings)
-      if block_given?
-        commands << Qonfig::Commands::AddNestedOption.new(key, nested_settings)
-      else
-        commands << Qonfig::Commands::AddOption.new(key, initial_value)
-      end
+      child_klass.singleton_class.prepend(Module.new do
+        def inherited(child_klass)
+          child_klass.instance_variable_set(:@commands, Qonfig::CommandSet.new)
+          child_klass.commands.concat(commands)
+          super
+        end
+      end)
     end
+  end
 
-    # @param data_set_klass [Class{Qonfig::DataSet}]
-    # @return [void]
-    #
-    # @see Qonfig::Comamnds::Compose
-    #
-    # @api private
-    # @sine 0.1.0
-    def compose(data_set_klass)
-      commands << Qonfig::Commands::Compose.new(data_set_klass)
-    end
+  # @return [Qonfig::CommandSet]
+  #
+  # @api private
+  # @since 0.1.0
+  def commands
+    @commands
+  end
 
-    # @param file_path [String]
-    # @option strict [Boolean]
-    # @return [void]
-    #
-    # @see Qonfig::Commands::LoadFromYAML
-    #
-    # @api public
-    # @since 0.2.0
-    def load_from_yaml(file_path, strict: true)
-      commands << Qonfig::Commands::LoadFromYAML.new(file_path, strict: strict)
+  # @param key [Symbol, String]
+  # @param initial_value [Object]
+  # @param nested_settings [Proc]
+  # @return [void]
+  #
+  # @see Qonfig::Commands::AddNestedOption
+  # @see Qonfig::Commands::AddOption
+  #
+  # @api public
+  # @since 0.1.0
+  def setting(key, initial_value = nil, &nested_settings)
+    if block_given?
+      commands << Qonfig::Commands::AddNestedOption.new(key, nested_settings)
+    else
+      commands << Qonfig::Commands::AddOption.new(key, initial_value)
     end
+  end
 
-    # @return [void]
-    #
-    # @see Qonfig::Commands::LoadFromSelf
-    #
-    # @api public
-    # @since 0.2.0
-    def load_from_self
-      caller_location = caller(1, 1).first
-      commands << Qonfig::Commands::LoadFromSelf.new(caller_location)
-    end
+  # @param data_set_klass [Class{Qonfig::DataSet}]
+  # @return [void]
+  #
+  # @see Qonfig::Comamnds::Compose
+  #
+  # @api private
+  # @sine 0.1.0
+  def compose(data_set_klass)
+    commands << Qonfig::Commands::Compose.new(data_set_klass)
+  end
 
-    # @option convert_values [Boolean]
-    # @option prefix [NilClass, String, Regexp]
-    # @return [void]
-    #
-    # @see Qonfig::Commands::LoadFromENV
-    #
-    # @api public
-    # @since 0.2.0
-    def load_from_env(convert_values: false, prefix: nil, trim_prefix: false)
-      commands << Qonfig::Commands::LoadFromENV.new(
-        convert_values: convert_values,
-        prefix: prefix,
-        trim_prefix: trim_prefix
-      )
-    end
+  # @param file_path [String]
+  # @option strict [Boolean]
+  # @return [void]
+  #
+  # @see Qonfig::Commands::LoadFromYAML
+  #
+  # @api public
+  # @since 0.2.0
+  def load_from_yaml(file_path, strict: true)
+    commands << Qonfig::Commands::LoadFromYAML.new(file_path, strict: strict)
+  end
 
-    # @param file_path [String]
-    # @option strict [Boolean]
-    # @return [void]
-    #
-    # @api public
-    # @since 0.5.0
-    def load_from_json(file_path, strict: true)
-      commands << Qonfig::Commands::LoadFromJSON.new(file_path, strict: strict)
-    end
+  # @return [void]
+  #
+  # @see Qonfig::Commands::LoadFromSelf
+  #
+  # @api public
+  # @since 0.2.0
+  def load_from_self
+    caller_location = caller(1, 1).first
+    commands << Qonfig::Commands::LoadFromSelf.new(caller_location)
+  end
 
-    # @param file_path [String]
-    # @option strict [Boolean]
-    # @option via [Symbol]
-    # @option env [Symbol, String]
-    # @return [void]
-    #
-    # @api public
-    # @since 0.7.0
-    def expose_yaml(file_path, strict: true, via:, env:)
-      commands << Qonfig::Commands::ExposeYAML.new(file_path, strict: strict, via: via, env: env)
-    end
+  # @option convert_values [Boolean]
+  # @option prefix [NilClass, String, Regexp]
+  # @return [void]
+  #
+  # @see Qonfig::Commands::LoadFromENV
+  #
+  # @api public
+  # @since 0.2.0
+  def load_from_env(convert_values: false, prefix: nil, trim_prefix: false)
+    commands << Qonfig::Commands::LoadFromENV.new(
+      convert_values: convert_values,
+      prefix: prefix,
+      trim_prefix: trim_prefix
+    )
+  end
+
+  # @param file_path [String]
+  # @option strict [Boolean]
+  # @return [void]
+  #
+  # @api public
+  # @since 0.5.0
+  def load_from_json(file_path, strict: true)
+    commands << Qonfig::Commands::LoadFromJSON.new(file_path, strict: strict)
+  end
+
+  # @param file_path [String]
+  # @option strict [Boolean]
+  # @option via [Symbol]
+  # @option env [Symbol, String]
+  # @return [void]
+  #
+  # @api public
+  # @since 0.7.0
+  def expose_yaml(file_path, strict: true, via:, env:)
+    commands << Qonfig::Commands::ExposeYAML.new(file_path, strict: strict, via: via, env: env)
   end
 end

data/lib/qonfig/{error.rb → exceptions.rb}

@@ -7,7 +7,19 @@ module Qonfig
 
   # @api public
   # @since 0.1.0
-  ArgumentError = Class.new(Error)
+  ArgumentError = Class.new(ArgumentError)
+
+  # @api public
+  # @since 0.11.0
+  IncorrectHashTransformationError = Class.new(ArgumentError)
+
+  # @api public
+  # @since 0.11.0
+  IncorrectKeyTransformerError = Class.new(IncorrectHashTransformationError)
+
+  # @api public
+  # @since 0.11.0
+  IncorrectValueTransformerError = Class.new(IncorrectHashTransformationError)
 
   # @see Qonfig::Settings
   #

data/lib/qonfig/loaders/basic.rb

@@ -1,40 +1,38 @@
 # frozen_string_literal: true
 
-module Qonfig
-  module Loaders
+# @api private
+# @since 0.2.0
+class Qonfig::Loaders::Basic
+  class << self
+    # @param data [String]
+    # @return [void]
+    #
     # @api private
-    # @sicne 0.5.0
-    module Basic
-      # @param data [String]
-      # @return [void]
-      #
-      # @api private
-      # @since 0.5.0
-      def load(data)
-        nil
-      end
+    # @since 0.5.0
+    def load(data)
+      nil # NOTE: consciously return nil (for clarity)
+    end
 
-      # @return [void]
-      #
-      # @api private
-      # @since 0.5.0
-      def load_empty_data
-        nil
-      end
+    # @return [void]
+    #
+    # @api private
+    # @since 0.5.0
+    def load_empty_data
+      nil # NOTE: consciously return nil (for clarity)
+    end
 
-      # @param file_path [String]
-      # @option fail_on_unexist [Boolean]
-      # @return [Object]
-      #
-      # @raise [Qonfig::FileNotFoundError]
-      #
-      # @api private
-      # @since 0.5.0
-      def load_file(file_path, fail_on_unexist: true)
-        load(::File.read(file_path))
-      rescue Errno::ENOENT => error
-        fail_on_unexist ? (raise Qonfig::FileNotFoundError, error.message) : load_empty_data
-      end
+    # @param file_path [String]
+    # @option fail_on_unexist [Boolean]
+    # @return [Object]
+    #
+    # @raise [Qonfig::FileNotFoundError]
+    #
+    # @api private
+    # @since 0.5.0
+    def load_file(file_path, fail_on_unexist: true)
+      load(::File.read(file_path))
+    rescue Errno::ENOENT => error
+      fail_on_unexist ? (raise Qonfig::FileNotFoundError, error.message) : load_empty_data
     end
   end
 end