qonfig 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 985bd788cc637ab9a63a813e1a9a59510d4ea093c2d45101962fb28804688510
-  data.tar.gz: 39018ae2f6eedb1049736164f00bb34abffe64fa045858e3908054099e83b66a
+  metadata.gz: ec197a7e1d7185ff8c4e5906e244c5cbce610d1449dc60cfb1d2a167a2e79921
+  data.tar.gz: 47d2d394cfcc97cf5ab58a198865490ecd4c9494c7ee7096474ff7a6f0c5d7f2
 SHA512:
-  metadata.gz: 51aa8022ab1a25cafc4dd68f740b2aa4edcc63e8b1c58aa95863c12ce288d6da74c177f764cfc5a829cb0d46bff1699afb4a87d1df93ea780c345ad0e452b9b2
-  data.tar.gz: 0d946fc7542ac3816bbf3e00f73a386e3178195bb2281a26d52e75c7b3bd57fe810213d8109c5d45db3d6713bfacb65603bc6373e593572a70d012ff3cea8c40
+  metadata.gz: 87e2688f74aa2dba959c423ea79ec36686c1873e20654826ad4eefc599da6f0d9967066e8de605b0f0a83d58465ecdb3f061e193fedc1aef6223d03794ffff7f
+  data.tar.gz: 107ccfc0dfe0ee109765699c4af58d431edd572d6ea30dace2449ff87d991bc8dbb555dedf95ccf7d3101cac2fb728fd7e44dec5c8a04a74583b006926e8ec46

data/.rubocop.yml

@@ -21,3 +21,7 @@ RSpec/LeakyConstantDeclaration:
 # NOTE: support for old ruby versions
 Style/RedundantBegin:
   Enabled: false
+
+# NOTE: too situative
+Metrics/ParameterLists:
+  Enabled: false

data/CHANGELOG.md

@@ -1,7 +1,15 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [0.18.0] - 2019-11-04
+### Added
+- `#keys` - returns a list of all config keys in dot-notation format;
+- `#root_keys` - returns a list of root config keys;
+- Inroduce `Import API`:
+  - `.import_settings` - DSL method for importing configuration settings (from a config instance) as instance methods of a class;
+  - `#export_settings` - config's instance method that exports config settings to an arbitrary object as singelton methods;
+
+## [0.17.0] - 2019-10-30
 ### Added
 - Introduce `strict` validations: `strict: false` option ignores `nil` values and used by default;
 - Setting's key existence check methods: `#key?(*key_path)`, `#setting?(*key_path)`, `#option?(*key_path)`;

data/README.md

@@ -44,12 +44,16 @@ require 'qonfig'
   - [Instantiation without class definition](#instantiation-without-class-definition) (`Qonfig::DataSet.build(&definitions)`)
 - [Interaction](#interaction)
   - [Iteration over setting keys](#iteration-over-setting-keys) (`#each_setting`, `#deep_each_setting`)
+  - [List of config keys](#list-of-config-keys) (`#keys`, `#root_keys`)
   - [Config reloading](#config-reloading) (reload config definitions and option values)
   - [Clear options](#clear-options) (set to `nil`)
   - [State freeze](#state-freeze)
   - [Settings as Predicates](#settings-as-predicates)
   - [Setting key existence](#setting-key-existence) (`#key?`/`#option?`/`#setting?`)
-  - [Run arbitary code with temporary settings](#run-arbitary-code-with-temporary-settings) (`#with(configs = {}, &arbitary_code)`)
+  - [Run arbitrary code with temporary settings](#run-arbitrary-code-with-temporary-settings) (`#with(configs = {}, &arbitrary_code)`)
+- [Import settings / Export settings](#import-settings--export-settings)
+  - [Import config settings](#import-config-settings) (`as instance methods`)
+  - [Export config settings](#export-config-settings) (`as singleton methods`)
 - [Validation](#validation)
   - [Introduction](#introduction)
   - [Key search pattern](#key-search-pattern)
@@ -75,7 +79,7 @@ require 'qonfig'
     - [Save to JSON file](#save-to-json-file) (`#save_to_json`)
     - [Save to YAML file](#save-to-yaml-file) (`#save_to_yaml`)
 - [Plugins](#plugins)
-  - [toml](#plugins-toml) (provides `load_from_toml`, `save_to_toml`, `expose_toml`)
+  - [toml](#plugins-toml) (support for `TOML` format)
 - [Roadmap](#roadmap)
 ---
 
@@ -493,6 +497,8 @@ GeneralApplication.config.to_h
 
 ### Instantiation without class definition
 
+- without inheritance:
+
 ```ruby
 config = Qonfig::DataSet.build do
   setting :user, 'D@iVeR'
@@ -510,17 +516,35 @@ config.settings.password # => 'test123'
 config.custom_method # => 'custom_result'
 ```
 
+- with inheritance:
+
+```ruby
+class GeneralConfig < Qonfig::DataSet
+  setting :db_adapter, :postgresql
+end
+
+config = Qonfig::DataSet.build(GeneralConfig) do
+  setting :web_api, 'api.google.com'
+end
+
+config.is_a?(Qonfig::DataSet) # => true
+
+config.settings.db_adapter # => :postgresql
+config.settings.web_api # => "api.google.com"
+```
+
 ---
 
 ## Interaction
 
 - [Iteration over setting keys](#iteration-over-setting-keys) (`#each_setting`, `#deep_each_setting`)
+- [List of config keys](#list-of-config-keys) (`#keys`, `#root_keys`)
 - [Config reloading](#config-reloading) (reload config definitions and option values)
-- [Clear options](#clear-options) (set to nil)
+- [Clear options](#clear-options) (set to `nil`)
 - [State freeze](#state-freeze)
 - [Settings as Predicates](#settings-as-predicates)
 - [Setting key existence](#setting-key-existence) (`#key?`/`#option?`/`#setting?`)
-- [Run arbitary code with temporary settings](#run-arbitary-code-with-temporary-settings)
+- [Run arbitrary code with temporary settings](#run-arbitrary-code-with-temporary-settings)
 
 ---
 
@@ -576,8 +600,96 @@ config.deep_each_setting { |key, value| { key => value } }
 
 ---
 
+### List of config keys
+
+- `#keys` - returns a list of all config keys in dot-notation format;
+  - `all_variants:` - get all possible variants of the config's keys sequences (`false` by default);
+  - `only_root:` - get only the root config keys (`false` by default);
+- `#root_keys` - returns a list of root config keys (an alias for `#keys(only_root: true)`);
+
+```ruby
+# NOTE: suppose we have the following config
+
+class Config < Qonfig::DataSet
+  setting :credentials do
+    setting :social do
+      setting :service, 'instagram'
+      setting :login, '0exp'
+    end
+
+    setting :admin do
+      setting :enabled, true
+    end
+  end
+
+  setting :server do
+    setting :type, 'cloud'
+    setting :options do
+      setting :os, 'CentOS'
+    end
+  end
+end
+
+config = Config.new
+```
+
+#### Default behavior
+
+```ruby
+config.keys
+
+# the result:
+[
+  "credentials.social.service",
+  "credentials.social.login",
+  "credentials.admin.enabled",
+  "server.type",
+  "server.options.os"
+]
+```
+
+#### All key variants
+
+```ruby
+config.keys(all_variants: true)
+
+# the result:
+[
+  "credentials",
+  "credentials.social",
+  "credentials.social.service",
+  "credentials.social.login",
+  "credentials.admin",
+  "credentials.admin.enabled",
+  "server",
+  "server.type",
+  "server.options",
+  "server.options.os"
+]
+```
+
+#### Only root keys
+
+```ruby
+config.keys(only_root: true)
+
+# the result:
+['credentials', 'server']
+```
+
+```ruby
+config.root_keys
+
+# the result:
+['credentials', 'server']
+```
+
+---
+
 ### Config reloading
 
+- method signature: `#reload!(configurations = {}, &configuration)`;
+
 ```ruby
 class Config < Qonfig::DataSet
   setting :db do
@@ -624,6 +736,9 @@ config.settings.enable_api # => true # value from instant change
 
 ### Clear options
 
+- set all config's settings to `nil`;
+- method signature: `#clear!`;
+
 ```ruby
 class Config
   setting :database do
@@ -659,6 +774,8 @@ config.settings.web_api.endpoint # => nil
 
 ### State freeze
 
+- method signature: `#freeze!`;
+
 ```ruby
 class Config < Qonfig::DataSet
   setting :logger, Logger.new(STDOUT)
@@ -756,10 +873,10 @@ config.option?(:credentials, :password) # => true
 
 ---
 
-### Run arbitary code with temporary settings
+### Run arbitrary code with temporary settings
 
-- provides a way to run an arbitary code with temporarily specified settings;
-- your arbitary code can temporary change any setting too - all settings will be returned to the original state;
+- provides a way to run an arbitrary code with temporarily specified settings;
+- your arbitrary code can temporary change any setting too - all settings will be returned to the original state;
 - (it is convenient to run code samples by this way in tests (with substitued configs));
 - it is fully thread-safe `:)`;
 
@@ -791,6 +908,188 @@ config.settings.queue.options # => {}
 
 ---
 
+## Import settings / Export settings
+
+- [Import config settings](#import-config-settings) (`as instance methods`)
+- [Export config settings](#export-config-settings) (`as singleton methods`)
+
+Sometimes the nesting of configs in your project is quite high, and it makes you write the rather "cumbersome" code
+(`config.settings.web_api.credentials.account.auth_token` for example). Frequent access to configs in this way is inconvinient - so developers wraps
+such code by methods or variables. In order to make developer's life easer `Qonfig` provides a special Import API simplifies the config importing
+(gives you `.import_settings` DSL) and gives an ability to instant config setting export from a config object (gives you `#export_settings` config's method).
+
+---
+
+### Import config settings
+
+- `Qonfig::Imports` - a special mixin that provides the convenient DSL to work with config import features (`.import_settings` method);
+- `.import_settings` - DSL method for importing configuration settings (from a config instance) as instance methods of a class;
+- (**IMPORTANT**) `import_settings` imports config settings as access methods to config's settings (creates `attr_reader`s for your config);
+- signature: `.import_settings(config_object, *setting_keys, mappings: {}, prefix: '', raw: false)`
+  - `config_object` - an instance of `Qonfig::DataSet` whose config settings should be imported;
+  - `*setting_keys` - an array of dot-notaed config's setting keys that should be imported
+    (dot-notaed key is a key that describes each part of nested setting key as a string separated by `dot`-symbol);
+    - last part of dot-notated key will become a name of the setting access instance method;
+  - `mappings:` - a map of keys that describes custom method names for each imported setting;
+  - `prefix:` - prexifies setting access method name with custom prefix;
+  - `raw:` - use nested settings as objects or hashify them (`false` by default (means "hashify nested settings"));
+
+---
+
+Suppose we have a config with deeply nested keys:
+
+```ruby
+# NOTE: (Qonfig::DataSet.build creates a class and instantly instantiates it)
+AppConfig = Qonfig::DataSet.build do
+  setting :web_api do
+    setting :credentials do
+      setting :account do
+        setting :login, 'DaiveR'
+        setting :auth_token, 'IAdkoa0@()1239uA'
+      end
+    end
+  end
+end
+```
+
+Let's see what we can to do :)
+
+#### Import a set of setting keys (simple dot-noated key list)
+
+- last part of dot-notated key will become a name of the setting access instance method;
+
+```ruby
+class ServiceObject
+  include Qonfig::Imports
+
+  import_settings(AppConfig,
+    'web_api.credentials.account.login',
+    'web_api.credentials.account'
+  )
+end
+
+service = ServiceObject.new
+
+service.login # => "D@iVeR"
+service.account # => { "login" => "D@iVeR", "auth_token" => IAdkoa0@()1239uA" }
+```
+
+#### Import with custom method names (mappings)
+
+- `mappings:` defines a map of keys that describes custom method names for each imported setting;
+
+```ruby
+class ServiceObject
+  include Qonfig::Imports
+
+  import_settings(AppConfig, mappings: {
+    account_data: 'web_api.credentials.account', # NOTE: name access method with "account_data"
+    secret_token: 'web_api.credentials.account.auth_token' # NOTE: name access method with "secret_token"
+  })
+end
+
+service = ServiceObject.new
+
+service.account_data # => { "login" => "D@iVeR", "auth_token" => "IAdkoa0@()1239uA" }
+service.auth_token # => "IAdkoa0@()1239uA"
+```
+
+#### Prexify method name
+
+- `prefix:` - prexifies setting access method name with custom prefix;
+
+```ruby
+class ServiceObject
+  include Qonfig::Imports
+
+  import_settings(AppConfig,
+    'web_api.credentials.account',
+    mappings: { secret_token: 'web_api.credentials.account.auth_token' },
+    prefix: 'config_'
+  )
+end
+
+service = ServiceObject.new
+
+service.config_credentials # => { login" => "D@iVeR", "auth_token" => "IAdkoa0@()1239uA" }
+service.config_secret_token # => "IAdkoa0@()1239uA"
+```
+
+#### Import nested settings as raw Qonfig::Settings objects
+
+- `raw: false` is used by default (hashify nested settings)
+
+```ruby
+# NOTE: import nested settings as raw objects (raw: true)
+class ServiceObject
+  include Qonfig::Imports
+
+  import_settings(AppConfig, 'web_api.credentials', raw: true)
+end
+
+service = ServiceObject.new
+
+service.credentials # => <Qonfig::Settings:0x00007ff8>
+service.credentials.account.login # => "D@iVeR"
+service.credentials.account.auth_token # => "IAdkoa0@()1239uA"
+```
+
+```ruby
+# NOTE: import nested settings as converted-to-hash objects (raw: false) (default behavior)
+class ServiceObject
+  include Qonfig::Imports
+
+  import_settings(AppConfig, 'web_api.credentials', raw: false)
+end
+
+service = ServiceObject.new
+
+service.credentials # => { "account" => { "login" => "D@iVeR", "auth_token" => "IAdkoa0@()1239uA"} }
+```
+
+---
+
+### Export config settings
+
+- all config objects can export their settings to an arbitrary object as singleton methods;
+- (**IMPORTANT**) `export_settings` exports config settings as access methods to config's settings (creates `attr_reader`s for your config);
+- signature: `#export(exportable_object, *setting_keys, mappings: {}, prefix: '', raw: false)`:
+  - `exportable_object` - an arbitrary object for exporting;
+  - `*setting_keys` - an array of dot-notaed config's setting keys that should be exported
+    (dot-notaed key is a key that describes each part of nested setting key as a string separated by `dot`-symbol);
+    - last part of dot-notated key will become a name of the setting access instance method;
+  - `mappings:` - a map of keys that describes custom method names for each exported setting;
+  - `prefix:` - prexifies setting access method name with custom prefix;
+  - `raw:` - use nested settings as objects or hashify them (`false` by default (means "hashify nested settings"));
+- works in `.import_settings` manner [doc](#import-config-settings) (see examples and documentation above `:)`)
+
+```ruby
+class Config < Qonfig::DataSet
+  setting :web_api do
+    setting :credentials do
+      setting :account do
+        setting :login, 'DaiveR'
+        setting :auth_token, 'IAdkoa0@()1239uA'
+      end
+    end
+  end
+end
+
+class ServiceObject; end
+
+config = Config.new
+service = ServiceObject.new
+
+service.config_account # => NoMethodError
+
+# NOTE: export settings as access methods to config's settings
+config.export(service, 'web_api.credentials.account', prefix: 'config_')
+
+service.account # => { "login" => "D@iVeR", "auth_token" => "IAdkoa0@()1239uA" }
+```
+
+---
+
 ## Validation
 
 - [Introduction](#introduction)
@@ -1735,19 +2034,19 @@ config.settings.options.threads # => 10 (development keys subset)
 #### File does not exist
 
 ```ruby
-# strict behavior (default)
+# non-strict behavior (default)
 class Config < Qonfig::DataSet
   values_file 'sidekiq.yml'
 end
 
-config = Config.new # => Qonfig::FileNotFoundError
+config = Config.new # no error
 
-# non-strict behavior (strict: false)
+# strict behavior (strict: true)
 class Config < Qonfig::DataSet
-  values_file 'sidekiq.yml', strict: false
+  values_file 'sidekiq.yml', strict: true
 end
 
-config = Config.new # no error
+config = Config.new # => Qonfig::FileNotFoundError
 ```
 
 ---
@@ -2201,6 +2500,8 @@ enabled: true
 dynamic: 10
 ```
 
+---
+
 ### Plugins
 
 ```ruby
@@ -2250,8 +2551,6 @@ Qonfig.plugin(:toml)
 - **Minor**:
   - custom global (and class-level) validators (with a special Validator Definition DSL);
   - support for "dot notation" in `#key?`, `#option?`, `#setting?`, `#dig`, `#subset`, `#slice`, `#slice_value`;
-  - "load setting values from a file" (at instance level);
-  - config improts (and exports);
   - pretty print :)));
 
 ## Contributing

data/lib/qonfig/data_set.rb

@@ -21,7 +21,7 @@ class Qonfig::DataSet # rubocop:disable Metrics/ClassLength
     # @since 0.16.0
     def build(base_dataset_klass = self, &config_klass_definitions)
       unless base_dataset_klass <= Qonfig::DataSet
-        raise(Qonfig::ArgumentError, 'Base inherited class should be a type of Qonfig::DataSet')
+        raise(Qonfig::ArgumentError, 'Base class should be a type of Qonfig::DataSet')
       end
 
       Class.new(base_dataset_klass, &config_klass_definitions).new
@@ -309,6 +309,26 @@ class Qonfig::DataSet # rubocop:disable Metrics/ClassLength
     thread_safe_access { validator.validate! }
   end
 
+  # @option all_variants [Boolean]
+  # @option only_root [Boolean]
+  # @return [Array<String>]
+  #
+  # @api public
+  # @since 0.18.0
+  def keys(all_variants: false, only_root: false)
+    thread_safe_access do
+      only_root ? settings.__root_keys__ : settings.__keys__(all_variants: all_variants)
+    end
+  end
+
+  # @return [Array<String>]
+  #
+  # @api public
+  # @since 0.18.0
+  def root_keys
+    thread_safe_access { settings.__root_keys__ }
+  end
+
   # @param temporary_configurations [Hash<Symbol|String,Any>]
   # @param arbitary_code [Block]
   # @return [void]
@@ -344,6 +364,34 @@ class Qonfig::DataSet # rubocop:disable Metrics/ClassLength
     end
   end
 
+  # @param exportable_object [Object]
+  # @param exported_setting_keys [Array<String,Symbol>]
+  # @option mappings [Hash<String|Symbol,String|Symbol>]
+  # @option raw [Boolean]
+  # @option prefix [String, Symbol]
+  # @return [void]
+  #
+  # @api public
+  # @since 0.18.0
+  def export_settings(
+    exportable_object,
+    *exported_setting_keys,
+    mappings: Qonfig::Imports::Abstract::EMPTY_MAPPINGS,
+    raw: false,
+    prefix: Qonfig::Imports::Abstract::EMPTY_PREFIX
+  )
+    thread_safe_access do
+      Qonfig::Imports::Export.export!(
+        exportable_object,
+        self,
+        *exported_setting_keys,
+        prefix: prefix,
+        raw: raw,
+        mappings: mappings
+      )
+    end
+  end
+
   private
 
   # @return [Qonfig::Validator]

data/lib/qonfig/errors.rb

@@ -156,4 +156,28 @@ module Qonfig
   # @api public
   # @since 0.12.0
   UnresolvedPluginDependencyError = Class.new(PluginError)
+
+  # @see Qonfig::Imports::Abstract
+  #
+  # @api public
+  # @since 0.18.0
+  IncompatibleImportedConfigError = Class.new(ArgumentError)
+
+  # @see Qonfig::Imports::DirectKey
+  #
+  # @api public
+  # @since 0.18.0
+  IncorrectImportKeyError = Class.new(ArgumentError)
+
+  # @see Qonfig::Imports::Abstract
+  #
+  # @api public
+  # @since 0.18.0
+  IncorrectImportPrefixError = Class.new(ArgumentError)
+
+  # @see Qonfig::Imports::Mappings
+  #
+  # @api public
+  # @since 0.18.0
+  IncorrectImportMappingsError = Class.new(ArgumentError)
 end

data/lib/qonfig/imports/abstract.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.18.0
+class Qonfig::Imports::Abstract
+  # @return [String]
+  #
+  # @api private
+  # @since 0.18.0
+  EMPTY_PREFIX = ''
+
+  # @return [Boolean]
+  #
+  # @api private
+  # @since 0.18.0
+  DEFAULT_RAW_BEHAVIOR = false
+
+  # @param seeded_klass [Class]
+  # @param imported_config [Qonfig::DataSet]
+  # @option prefix [String, Symbol]
+  # @option raw [Boolean]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.18.0
+  def initialize(seeded_klass, imported_config, prefix: EMPTY_PREFIX, raw: DEFAULT_RAW_BEHAVIOR)
+    @seeded_klass = seeded_klass
+    @imported_config = imported_config
+    @prefix = prefix
+    @raw = !!raw
+  end
+
+  # @param settings_interface [Module]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.18.0
+  def import!(settings_interface = Module.new)
+    # :nocov:
+    raise NoMethodError
+    # :nocov:
+  end
+
+  private
+
+  # @return [Boolean]
+  #
+  # @api private
+  # @since 0.18.0
+  attr_reader :raw
+
+  # @return [String, Symbol]
+  #
+  # @api private
+  # @since 0.18.0
+  attr_reader :prefix
+
+  # @return [Class]
+  #
+  # @api private
+  # @since 0.18.0
+  attr_reader :seeded_klass
+
+  # @return [Qonfig::DataSet]
+  #
+  # @api private
+  # @since 0.18.0
+  attr_reader :imported_config
+
+  # @param imported_config [Qonfig::DataSet]
+  # @param prefix [String, Symbol]
+  # @return [void]
+  #
+  # @raise [Qonfig::IncompatibleImportedConfigError]
+  # @raise [Qonfig::IncorrectImportPrefixError]
+  #
+  # @api private
+  # @since 0.18.0
+  def prevent_incompatible_import_params!(imported_config, prefix)
+    raise(
+      Qonfig::IncompatibleImportedConfigError,
+      'Imported config object should be an isntance of Qonfig::DataSet'
+    ) unless imported_config.is_a?(Qonfig::DataSet)
+
+    raise(
+      Qonfig::IncorrectImportPrefixError,
+      'Import method prefix should be a type of string or symbol'
+    ) unless prefix.is_a?(String) || prefix.is_a?(Symbol)
+  end
+end

data/lib/qonfig/imports/direct_key.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.18.0
+class Qonfig::Imports::DirectKey < Qonfig::Imports::Abstract
+  # @param seeded_klass [Class]
+  # @param imported_config [Qonfig::DataSet]
+  # @param keys [Array<String,Symbol>]
+  # @option prefix [String, Symbol]
+  # @option raw [Boolean]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.18.8
+  def initialize(
+    seeded_klass,
+    imported_config,
+    *keys,
+    prefix: EMPTY_PREFIX,
+    raw: DEFAULT_RAW_BEHAVIOR
+  )
+    prevent_incompatible_import_params!(imported_config, prefix, keys)
+    super(seeded_klass, imported_config, prefix: prefix, raw: raw)
+    @keys = keys
+    @key_matchers = build_setting_key_matchers(keys)
+  end
+
+  # @param settings_interfcae [Module]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.18.0
+  def import!(settings_interface = Module.new) # rubocop:disable Metrics/AbcSize
+    key_matchers.each do |key_matcher|
+      raise(
+        Qonfig::UnknownSettingError,
+        "Setting with <#{key_matcher.scope_pattern}> key does not exist!"
+      ) unless (imported_config.keys(all_variants: true).any? do |setting_key|
+        key_matcher.match?(setting_key)
+      end)
+
+      imported_config.keys(all_variants: true).each do |setting_key|
+        next unless key_matcher.match?(setting_key)
+
+        setting_key_path_sequence = setting_key.split('.')
+        access_method_name = setting_key_path_sequence.last
+        access_method_name = "#{prefix}#{access_method_name}" unless prefix.empty?
+
+        settings_interface.module_exec(raw, imported_config) do |raw, imported_config|
+          unless raw
+            # NOTE: get setting value via slice_value
+            define_method(access_method_name) do
+              imported_config.slice_value(*setting_key_path_sequence)
+            end
+          else
+            # NOTE: get setting object (concrete value or Qonfig::Settings object)
+            define_method(access_method_name) do
+              imported_config.dig(*setting_key_path_sequence)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  private
+
+  # @return [Array<String,Symbol>]
+  #
+  # @api private
+  # @since 0.18.8
+  attr_reader :keys
+
+  # @return [Array<Qonfig::Settings::KeyMatcher>]
+  #
+  # @api private
+  # @since 0.18.0
+  attr_reader :key_matchers
+
+  # @param imported_config [Qonfig::DataSet]
+  # @param prefix [String, Symbol]
+  # @param keys [Array<String,Symbol>]
+  # @return [void]
+  #
+  # @raise [Qonfig::IncompatibleImportedConfigError]
+  # @raise [Qonfig::IncorrectImportPrefixError]
+  # @raise [Qonfig::IncorrectImportKeyError]
+  #
+  # @see Qonfig::Imports::Abstract#prevent_incompatible_import_params
+  #
+  # @api private
+  # @since 0.18.0
+  def prevent_incompatible_import_params!(imported_config, prefix, keys)
+    super(imported_config, prefix)
+
+    raise(
+      Qonfig::IncorrectImportKeyError,
+      'Imported config keys should be a type of string or symbol'
+    ) unless keys.all? { |key| key.is_a?(String) || key.is_a?(Symbol) }
+  end
+
+  # @param keys [Array<String,Symbol>]
+  # @return [Array<Qonfig::KeyMatcher>]
+  #
+  # @api private
+  # @since 0.18.0
+  def build_setting_key_matchers(keys)
+    keys.map { |key| Qonfig::Settings::KeyMatcher.new(key) }
+  end
+end

data/lib/qonfig/imports/dsl.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.18.0
+module Qonfig::Imports::DSL
+  class << self
+    # @param base_klass [Class]
+    # @return [void]
+    #
+    # @api private
+    # @since 0.18.0
+    def included(base_klass)
+      base_klass.extend(ClassMethods)
+    end
+  end
+
+  # @api private
+  # @since 0.18.0
+  module ClassMethods
+    # @param imported_config [Qonfig::DataSet]
+    # @param imported_setting_keys [Array<String,Symbol>]
+    # @option prefix [String, Symbol]
+    # @option raw [Boolean]
+    # @option mappings [Hash<String|Symbol,String|Symbol>]
+    # @return [void]
+    #
+    # @api public
+    # @since 0.18.0
+    def import_settings(
+      imported_config,
+      *imported_setting_keys,
+      prefix: Qonfig::Imports::Abstract::EMPTY_PREFIX,
+      raw: Qonfig::Imports::Abstract::DEFAULT_RAW_BEHAVIOR,
+      mappings: Qonfig::Imports::Mappings::EMPTY_MAPPINGS
+    )
+      Qonfig::Imports::General.import!(
+        self,
+        imported_config,
+        *imported_setting_keys,
+        prefix: prefix,
+        raw: raw,
+        mappings: mappings
+      )
+    end
+  end
+end

data/lib/qonfig/imports/export.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.18.0
+module Qonfig::Imports::Export
+  class << self
+    # @param exportable_object [Object]
+    # @param exported_config [Qonfig::DataSet]
+    # @param exported_setting_keys [Array<String,Symbol>]
+    # @option mappings [Hash<String|Symbol,String|Symbol>]
+    # @option raw [Boolean]
+    # @option prefix [String, Symbol]
+    # @return [void]
+    #
+    # @api private
+    # @since 0.18.0
+    def export!(
+      exportable_object,
+      exported_config,
+      *exported_setting_keys,
+      mappings: Qonfig::Imports::Abstract::EMPTY_MAPPINGS,
+      raw: false,
+      prefix: Qonfig::Imports::Abstract::EMPTY_PREFIX
+    )
+      unless exportable_object.is_a?(Module)
+        exportable_object = exportable_object.singleton_class
+      end
+
+      Qonfig::Imports::General.import!(
+        exportable_object,
+        exported_config,
+        *exported_setting_keys,
+        prefix: prefix,
+        raw: raw,
+        mappings: mappings
+      )
+    end
+  end
+end

data/lib/qonfig/imports/general.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.18.0
+class Qonfig::Imports::General
+  class << self
+    # @param seeded_klass [Class, Object]
+    # @param imported_config [Qonfig::DataSet]
+    # @param imported_keys [Array<String, Symbol>]
+    # @option mappings [Hash<String|Symbol,String|Symbol>]
+    # @option prefix [String, Symbol]
+    # @option raw [Boolean]
+    # @return void]
+    #
+    # @api private
+    # @since 0.18.0
+    def import!(
+      seeded_klass,
+      imported_config,
+      *imported_keys,
+      mappings: EMPTY_MAPPINGS,
+      prefix: EMPTY_PREFIX,
+      raw: false
+    )
+      new(
+        seeded_klass,
+        imported_config,
+        *imported_keys,
+        mappings: mappings,
+        prefix: prefix,
+        raw: raw
+      ).import!
+    end
+  end
+
+  # @param seeded_klass [Class, Object]
+  # @param imported_config [Qonfig::DataSet]
+  # @param imported_keys [Array<String, Symbol>]
+  # @option mappings [Hash<String|Symbol,String|Symbol>]
+  # @option prefix [String, Symbol]
+  # @option raw [Boolean]
+  # @return void]
+  #
+  # @api private
+  # @since 0.18.0
+  def initialize(
+    seeded_klass,
+    imported_config,
+    *imported_keys,
+    mappings: EMPTY_MAPPINGS,
+    prefix: EMPTY_PREFIX,
+    raw: false
+  )
+    @seeded_klass = seeded_klass
+    @direct_key_importer = build_direct_key_importer(
+      seeded_klass, imported_config, *imported_keys, prefix: prefix, raw: raw
+    )
+    @mappings_importer = build_mappings_importer(
+      seeded_klass, imported_config, mappings: mappings, prefix: prefix, raw: raw
+    )
+  end
+
+  # @param settings_interface [Module]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.18.0
+  def import!(settings_interface = Module.new)
+    direct_key_importer.import!(settings_interface)
+    mappings_importer.import!(settings_interface)
+    seeded_klass.include(settings_interface)
+  end
+
+  private
+
+  # @return [Class]
+  #
+  # @api private
+  # @since 0.18.0
+  attr_reader :seeded_klass
+
+  # @return [Qonfig::Imports::DirectKey]
+  #
+  # @api private
+  # @since 0.18.0
+  attr_reader :direct_key_importer
+
+  # @return [Qonfig::Imports::Mappings]
+  #
+  # @api private
+  # @since 0.18.0
+  attr_reader :mappings_importer
+
+  # @param seeded_klass [Class]
+  # @param imported_config [Qonfig::DataSet]
+  # @param imported_keys [Array<String,Symbol>]
+  # @option prefix [String, Symbol]
+  # @option raw [Boolean]
+  # @return [Qonfig::Imports::DirectKey]
+  #
+  # @api private
+  # @since 0.18.0
+  def build_direct_key_importer(seeded_klass, imported_config, *imported_keys, prefix:, raw:)
+    Qonfig::Imports::DirectKey.new(
+      seeded_klass,
+      imported_config,
+      *imported_keys,
+      prefix: prefix,
+      raw: raw
+    )
+  end
+
+  # @param seeded_klass [Class]
+  # @param imported_config [Qonfig::DataSet]
+  # @option mappings [Hash<Symbol|String,Symbol|String>]
+  # @option prefix [String, Symbol]
+  # @option raw [Boolean]
+  # @return [Qonfig::Imports::Mappings]
+  #
+  # @api private
+  # @since 0.18.0
+  def build_mappings_importer(seeded_klass, imported_config, mappings:, prefix:, raw:)
+    Qonfig::Imports::Mappings.new(
+      seeded_klass,
+      imported_config,
+      mappings: mappings,
+      prefix: prefix,
+      raw: raw
+    )
+  end
+end

data/lib/qonfig/imports/mappings.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.18.0
+class Qonfig::Imports::Mappings < Qonfig::Imports::Abstract
+  # @return [Hash]
+  #
+  # @api private
+  # @since 0.18.0
+  EMPTY_MAPPINGS = {}.freeze
+
+  # @param seeded_klass [Class]
+  # @param imported_config [Qonfig::DataSet]
+  # @option prefix [String, Symbol]
+  # @option raw [Boolean]
+  # @option mappings [Hash<Symbol|String,Symbol|String>]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.18.0
+  def initialize(
+    seeded_klass,
+    imported_config,
+    mappings: EMPTY_MAPPINGS,
+    prefix: EMPTY_PREFIX,
+    raw: DEFAULT_RAW_BEHAVIOR
+  )
+    prevent_incompatible_import_params!(imported_config, prefix, mappings)
+    super(seeded_klass, imported_config, prefix: prefix, raw: raw)
+    @mappings = mappings
+    @key_matchers = build_setting_key_matchers(mappings)
+  end
+
+  # @param settings_interface [Module]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.18.0
+  def import!(settings_interface = Module.new) # rubocop:disable Metrics/AbcSize
+    key_matchers.each_pair do |(mapped_method_name, key_matcher)|
+      raise(
+        Qonfig::UnknownSettingError,
+        "Setting with <#{key_matcher.scope_pattern}> key does not exist!"
+      ) unless (imported_config.keys(all_variants: true).any? do |setting_key|
+        key_matcher.match?(setting_key)
+      end)
+
+      imported_config.keys(all_variants: true).each do |setting_key|
+        next unless key_matcher.match?(setting_key)
+
+        setting_key_path_sequence = setting_key.split('.')
+        mapped_method_name = "#{prefix}#{mapped_method_name}" unless prefix.empty?
+
+        settings_interface.module_exec(raw, imported_config) do |raw, imported_config|
+          unless raw
+            # NOTE: get setting value via slice_value
+            define_method(mapped_method_name) do
+              imported_config.slice_value(*setting_key_path_sequence)
+            end
+          else
+            # NOTE: get setting object (concrete value or Qonfig::Settings object)
+            define_method(mapped_method_name) do
+              imported_config.dig(*setting_key_path_sequence)
+            end
+          end
+        end
+      end
+    end
+  end
+
+  private
+
+  # @return [Hash<Symbol|String,Symbol|String>]
+  #
+  # @api private
+  # @since 0.18.0
+  attr_reader :mappings
+
+  # @return [Hash<String|Symbol,Qonfig::Settings::KeyMatcher>]
+  #
+  # @api private
+  # @since 0.18.0
+  attr_reader :key_matchers
+
+  # @param imported_config [Qonfig::DataSet]
+  # @param prefix [String, Symbol]
+  # @param mappings [Hash<Symbol|String,Symbol|String>]
+  # @return [void]
+  #
+  # @raise [Qonfig::IncompatibleImportedConfigError]
+  # @raise [Qonfig::IncorrectImportPrefixError]
+  # @raise [Qonfig::IncorrectImportMappingsError]
+  #
+  # @see Qonfig::Imports::Abstract#prevent_incompatible_import_params!
+  #
+  # @api private
+  # @since 0.18.0
+  def prevent_incompatible_import_params!(imported_config, prefix, mappings)
+    super(imported_config, prefix)
+
+    raise(
+      Qonfig::IncorrectImportMappingsError,
+      'Import mappings should be a type of hash with String-or-Symbol keys and values'
+    ) unless mappings.is_a?(Hash) && (mappings.each_pair.all? do |(mapping_key, mapping_value)|
+      (mapping_key.is_a?(String) || mapping_key.is_a?(Symbol)) &&
+      (mapping_value.is_a?(String) || mapping_value.is_a?(Symbol))
+    end)
+  end
+
+  # @param mappings [Hash<Symbol|String,Symbol|String>]
+  # @return [Hash<String|Symbol,Qonfig::Settings::KeyMatcher>]
+  #
+  # @api private
+  # @since 0.18.0
+  def build_setting_key_matchers(mappings)
+    mappings.each_with_object({}) do |(mapped_method_name, required_setting_key), matchers|
+      matchers[mapped_method_name] = Qonfig::Settings::KeyMatcher.new(required_setting_key)
+    end
+  end
+end

data/lib/qonfig/imports.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# @api public
+# @since 0.18.0
+module Qonfig::Imports
+  require_relative 'imports/abstract'
+  require_relative 'imports/direct_key'
+  require_relative 'imports/mappings'
+  require_relative 'imports/general'
+  require_relative 'imports/dsl'
+  require_relative 'imports/export'
+
+  class << self
+    # @param base_klass [Class]
+    # @return [void]
+    #
+    # @api private
+    # @since 0.18.0
+    def included(base_klass)
+      base_klass.include(Qonfig::Imports::DSL)
+    end
+  end
+end

data/lib/qonfig/settings/key_matcher.rb

@@ -39,7 +39,13 @@ class Qonfig::Settings::KeyMatcher
   # @since 0.13.0
   INFINITE_REGEXP_PATTERN = '\.*.*'
 
-  # @param scope_pattern [String]
+  # @return [String]
+  #
+  # @api private
+  # @since 0.13.0
+  attr_reader :scope_pattern
+
+  # @param scope_pattern [String, Symbol]
   # @return [void]
   #
   # @raise [Qonfig::ArgumentError]
@@ -47,9 +53,10 @@ class Qonfig::Settings::KeyMatcher
   # @api private
   # @since 0.13.0
   def initialize(scope_pattern)
+    scope_pattern = scope_pattern.to_s if scope_pattern.is_a?(Symbol)
     raise Qonfig::ArgumentError unless scope_pattern.is_a?(String)
 
-    @scope_pattern      = scope_pattern
+    @scope_pattern      = scope_pattern.dup.freeze
     @scope_pattern_size = count_scope_pattern_size(scope_pattern)
     @pattern_matcher    = build_pattern_matcher(scope_pattern)
   end
@@ -72,12 +79,6 @@ class Qonfig::Settings::KeyMatcher
   # @since 0.13.0
   attr_reader :pattern_matcher
 
-  # @return [String]
-  #
-  # @api private
-  # @since 0.13.0
-  attr_reader :scope_pattern
-
   # @return [Integer, Float::INFINITY]
   #
   # @api private

data/lib/qonfig/settings.rb

@@ -194,11 +194,11 @@ class Qonfig::Settings # NOTE: Layout/ClassStructure is disabled only for CORE_M
   # rubocop:disable Metrics/LineLength
   def __to_hash__(transform_key: BASIC_SETTING_KEY_TRANSFORMER, transform_value: BASIC_SETTING_VALUE_TRANSFORMER)
     unless transform_key.is_a?(Proc)
-      ::Kernel.raise(Qonfig::IncorrectKeyTransformerError, 'Key transformer should be a proc')
+      ::Kernel.raise(Qonfig::IncorrectKeyTransformerError, 'Key transformer should be a type of proc')
     end
 
     unless transform_value.is_a?(Proc)
-      ::Kernel.raise(Qonfig::IncorrectValueTransformerError, 'Value transformer should be a proc')
+      ::Kernel.raise(Qonfig::IncorrectValueTransformerError, 'Value transformer should be a type of proc')
     end
 
     __lock__.thread_safe_access do
@@ -208,6 +208,23 @@ class Qonfig::Settings # NOTE: Layout/ClassStructure is disabled only for CORE_M
   # rubocop:enable Metrics/LineLength
   alias_method :__to_h__, :__to_hash__
 
+  # @option all_variants [Boolean]
+  # @return [Array<String>]
+  #
+  # @api private
+  # @since 0.18.0
+  def __keys__(all_variants: false)
+    __lock__.thread_safe_access { __setting_keys__(all_variants: all_variants) }
+  end
+
+  # @return [Array<String>]
+  #
+  # @api private
+  # @since 0.18.0
+  def __root_keys__
+    __lock__.thread_safe_access { __root_setting_keys__ }
+  end
+
   # @return [void]
   #
   # @api private
@@ -289,6 +306,51 @@ class Qonfig::Settings # NOTE: Layout/ClassStructure is disabled only for CORE_M
   # @since 0.2.0
   attr_reader :__lock__
 
+  # @option all_variants [Boolean]
+  # @return [Array<String>]
+  #
+  # @api private
+  # @since 0.18.0
+  def __setting_keys__(all_variants: false)
+    # NOTE: generate a set of keys return simple 'a.b.c.d'
+    setting_keys_set = Set.new.tap do |setting_keys|
+      __deep_each_key_value_pair__ do |setting_key, _setting_value|
+        setting_keys << setting_key
+      end
+    end
+
+    if all_variants
+      # NOTE:
+      #   We have { a: { b: { c: { d : 1 } } } }
+      #   Its mean that we have these keys:
+      #     - 'a' # => returns { b: { c: { d: 1 } } }
+      #     - 'a.b' # => returns { c: { d: 1 } }
+      #     - 'a.b.c' # => returns { d: 1 }
+      #     - 'a.b.c.d' # => returns 1
+      #   So, get them all :)
+
+      setting_keys_set.each_with_object(Set.new) do |setting_key, varianted_setting_keys|
+        setting_key_paths = setting_key.split('.')
+        combination_size  = setting_key_paths.size
+
+        combination_size.times do |merged_key_patterns_count|
+          sub_setting_key = setting_key_paths.slice(0..merged_key_patterns_count).join('.')
+          varianted_setting_keys << sub_setting_key
+        end
+      end
+    else
+      setting_keys_set
+    end
+  end
+
+  # @return [Array<String>]
+  #
+  # @api private
+  # @since 0.18.0
+  def __root_setting_keys__
+    __options__.keys
+  end
+
   # @param key_path [Array<String, Symbol>]
   # @return [Boolean]
   #
@@ -302,7 +364,7 @@ class Qonfig::Settings # NOTE: Layout/ClassStructure is disabled only for CORE_M
   end
 
   # @param block [Proc]
-  # @return [Enumerable]
+  # @return [Enumerator]
   #
   # @yield [setting_key, setting_value]
   # @yieldparam key [String]
@@ -316,7 +378,7 @@ class Qonfig::Settings # NOTE: Layout/ClassStructure is disabled only for CORE_M
 
   # @param initial_setting_key [String, NilClass]
   # @param block [Proc]
-  # @return [Enumerable]
+  # @return [Enumerator]
   #
   # @yield [setting_key, setting_value]
   # @yieldparam setting_key [String]

data/lib/qonfig/version.rb

@@ -5,5 +5,5 @@ module Qonfig
   #
   # @api public
   # @since 0.1.0
-  VERSION = '0.17.0'
+  VERSION = '0.18.0'
 end

data/lib/qonfig.rb

@@ -15,6 +15,7 @@ module Qonfig
   require_relative 'qonfig/dsl'
   require_relative 'qonfig/data_set'
   require_relative 'qonfig/configurable'
+  require_relative 'qonfig/imports'
   require_relative 'qonfig/plugins'
 
   # @api public

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qonfig
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-30 00:00:00.000000000 Z
+date: 2019-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: coveralls
@@ -158,6 +158,13 @@ files:
 - lib/qonfig/data_set/lock.rb
 - lib/qonfig/dsl.rb
 - lib/qonfig/errors.rb
+- lib/qonfig/imports.rb
+- lib/qonfig/imports/abstract.rb
+- lib/qonfig/imports/direct_key.rb
+- lib/qonfig/imports/dsl.rb
+- lib/qonfig/imports/export.rb
+- lib/qonfig/imports/general.rb
+- lib/qonfig/imports/mappings.rb
 - lib/qonfig/loaders.rb
 - lib/qonfig/loaders/basic.rb
 - lib/qonfig/loaders/dynamic.rb