qonfig 0.19.1 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dab3b453c59fc8f9431ddeb3e0fb3cccd067947bf2275e94d2b75f8862e66c70
-  data.tar.gz: 7fb3387c500b3d9f738710ed5db17b3d594fffef048b06895498b8710b224257
+  metadata.gz: c0c47867d48b4170e321a53b70e527817db87b4dec1b7a4b464d352590501478
+  data.tar.gz: ddaa44855f051262fac8477a7ff736d43c896ade3c1c75ee4efa9a89d58ac555
 SHA512:
-  metadata.gz: 8317ded309d56239bbf763a4e72f6b0364981f6a2c87831f0dab396f9c9c2de61b8a062ec22f45b58a942731f46f0d171983e0f25cce2d07e2291f98049d8987
-  data.tar.gz: a06e95e78176a44c7de83548ee5e57f614442ecca6a42b681429cd26f4ef0489cf89ddfec716bf59b96bbd30d7a044a718a020bb9db98fcd5ee8d6f9a9629b86
+  metadata.gz: 220ba3ccc61ce56a09ef245b07c36a8a7e695688e57e98039882ecb8917fa83bca7fe5e075fd5b68d671639a04d7fe92ad600587c9a20717296675c6ecb8053b
+  data.tar.gz: 05cf1fcac1bdff9c4414530ab1561057b52cfc0903fd64c1af0962b49bd91702e662d2f0467494862ad0bda633842a05e3665d68a91fe61316760c97adbf8a31

data/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [0.20.0] - 2019-12-01
+### Added
+- Extended **Validation API**: you can define your own predefined validators via `.define_validator(name, &validation)` directive;
+- `re_setting` - a special DSL command method that fully redefines existing settings (redefines existing settings instead of reopening them);
+
 ## [0.19.1] - 2019-11-29
 ### Changed
 - Support for Ruby 2.3 has ended.

data/README.md

@@ -60,6 +60,7 @@ require 'qonfig'
   - [Proc-based validation](#proc-based-validation)
   - [Method-based validation](#method-based-validation)
   - [Predefined validations](#predefined-validations)
+  - [Custom predefined validators](#custom-predefined-validators)
   - [Validation of potential setting values](#validation-of-potential-setting-values)
 - [Work with files](#work-with-files)
   - **Setting keys definition**
@@ -98,6 +99,12 @@ require 'qonfig'
 
 ### Definition and Access
 
+- `setting(name, value)` - define setting with corresponding name and value;
+- `setting(name) { setting(name, value); ... }` - define nested settings OR reopen existing nested setting and define some new nested settings;
+- `re_setting(name, value)`, `re_setting(name) { ... }` - re-define existing setting (or define new if the original does not exist);
+- accessing: [access via method](#access-via-method), [access via index-method \[\]](#access-via-index-method-),
+  [.dig](#dig), [.slice](#slice), [.slice_value](#slice_value), [.subset](#subset);
+
 ```ruby
 # --- definition ---
 class Config < Qonfig::DataSet
@@ -106,14 +113,20 @@ class Config < Qonfig::DataSet
 
   # nested setting
   setting :vendor_api do
-    setting :host, 'app.service.com'
+    setting :host, 'vendor.service.com'
   end
 
   setting :enable_graphql, false
 
   # nested setting reopening
   setting :vendor_api do
-    setting :user, 'test_user'
+    setting :user, 'simple_user'
+  end
+
+  # re-definition of existing setting (drop the old - make the new)
+  re_setting :vendor_api do
+    setting :domain, 'api.service.com'
+    setting :login, 'test_user'
   end
 
   # deep nesting
@@ -133,8 +146,8 @@ config = Config.new # your configuration object instance
 ```ruby
 # get option value via method
 config.settings.project_id # => nil
-config.settings.vendor_api.host # => 'app.service.com'
-config.settings.vendor_api.user # => 'test_user'
+config.settings.vendor_api.domain # => 'app.service.com'
+config.settings.vendor_api.login # => 'test_user'
 config.settings.enable_graphql # => false
 ```
 
@@ -145,14 +158,14 @@ config.settings.enable_graphql # => false
 ```ruby
 # get option value via index (with indifferent (string / symbol / mixed) access)
 config.settings[:project_id] # => nil
-config.settings[:vendor_api][:host] # => 'app.service.com'
-config.settings[:vendor_api][:user] # => 'test_user'
+config.settings[:vendor_api][:domain] # => 'app.service.com'
+config.settings[:vendor_api][:login] # => 'test_user'
 config.settings[:enable_graphql] # => false
 
 # get option value via index (with indifferent (string / symbol / mixed) access)
 config.settings['project_id'] # => nil
-config.settings['vendor_api']['host'] # => 'app.service.com'
-config.settings['vendor_api']['user'] # => 'test_user'
+config.settings['vendor_api']['domain'] # => 'app.service.com'
+config.settings['vendor_api']['login'] # => 'test_user'
 config.settings['enable_graphql'] # => false
 
 # get option value directly via index (with indifferent access)
@@ -165,11 +178,11 @@ config[:enable_graphql] # => false
 - with dot-notation:
 
 ```ruby
-config.settings['vendor_api.host'] # => 'app.service.com'
-config.settings['vendor_api.user'] # => 'test_user'
+config.settings['vendor_api.domain'] # => 'app.service.com'
+config.settings['vendor_api.login'] # => 'test_user'
 
-config['vendor_api.host'] # => 'app.service.com'
-config['vendor_api.user'] # => 'test_user'
+config['vendor_api.domain'] # => 'app.service.com'
+config['vendor_api.login'] # => 'test_user'
 ```
 
 #### .dig
@@ -178,15 +191,15 @@ config['vendor_api.user'] # => 'test_user'
 
 ```ruby
 # get option value in Hash#dig manner (and fail when the required key does not exist);
-config.dig(:vendor_api, :host) # => 'app.service.com' # (key exists)
-config.dig(:vendor_api, :port) # => Qonfig::UnknownSettingError # (key does not exist)
+config.dig(:vendor_api, :domain) # => 'app.service.com' # (key exists)
+config.dig(:vendor_api, :login) # => Qonfig::UnknownSettingError # (key does not exist)
 ```
 
 - with dot-notation:
 
 ```ruby
-config.dig('vendor_api.host') # => 'app.service.com' # (key exists)
-config.dig('vendor_api.port') # => Qonfig::UnknownSettingError # (key does not exist)
+config.dig('vendor_api.domain') # => 'app.service.com' # (key exists)
+config.dig('vendor_api.login') # => Qonfig::UnknownSettingError # (key does not exist)
 ```
 
 #### .slice
@@ -195,8 +208,8 @@ config.dig('vendor_api.port') # => Qonfig::UnknownSettingError # (key does not e
 
 ```ruby
 # get a hash slice of setting options (and fail when the required key does not exist);
-config.slice(:vendor_api) # => { 'vendor_api' => { 'host' => 'app_service', 'user' => 'test_user' } }
-config.slice(:vendor_api, :user) # => { 'user' => 'test_user' }
+config.slice(:vendor_api) # => { 'vendor_api' => { 'domain' => 'app_service', 'login' => 'test_user' } }
+config.slice(:vendor_api, :login) # => { 'login' => 'test_user' }
 config.slice(:project_api) # => Qonfig::UnknownSettingError # (key does not exist)
 config.slice(:vendor_api, :port) # => Qonfig::UnknownSettingError # (key does not exist)
 ```
@@ -204,7 +217,7 @@ config.slice(:vendor_api, :port) # => Qonfig::UnknownSettingError # (key does no
 - with dot-notation:
 
 ```ruby
-config.slice('vendor_api.user') # => { 'user' => 'test_user' }
+config.slice('vendor_api.login') # => { 'loign' => 'test_user' }
 config.slice('vendor_api.port') # => Qonfig::UnknownSettingError # (key does not exist)
 ```
 
@@ -217,8 +230,8 @@ config.slice('vendor_api.port') # => Qonfig::UnknownSettingError # (key does not
 # get value from the slice of setting options using the given key set
 # (and fail when the required key does not exist) (works in slice manner);
 
-config.slice_value(:vendor_api) # => { 'host' => 'app_service', 'user' => 'test_user' }
-config.slice_value(:vendor_api, :user) # => 'test_user'
+config.slice_value(:vendor_api) # => { 'domain' => 'app_service', 'login' => 'test_user' }
+config.slice_value(:vendor_api, :login) # => 'test_user'
 config.slice_value(:project_api) # => Qonfig::UnknownSettingError # (key does not exist)
 config.slice_value(:vendor_api, :port) # => Qonfig::UnknownSettingError # (key does not exist)
 ```
@@ -226,7 +239,7 @@ config.slice_value(:vendor_api, :port) # => Qonfig::UnknownSettingError # (key d
 - with dot-notation:
 
 ```ruby
-config.slice_value('vendor_api.user') # => 'test_user'
+config.slice_value('vendor_api.login') # => 'test_user'
 config.slice_value('vendor_api.port') # => Qonfig::UnknownSettingError # (key does not exist)
 ```
 
@@ -239,17 +252,17 @@ config.slice_value('vendor_api.port') # => Qonfig::UnknownSettingError # (key do
 # - each key (or key set) represents a requirement of a certain setting key;
 
 config.subet(:vendor_api, :enable_graphql)
-# => { 'vendor_api' => { 'user' => ..., 'host' => ... }, 'enable_graphql' => false }
+# => { 'vendor_api' => { 'login' => ..., 'domain' => ... }, 'enable_graphql' => false }
 
-config.subset(:project_id, [:vendor_api, :host], [:credentials, :user, :login])
-# => { 'project_id' => nil, 'host' => 'app.service.com', 'login' => 'D@iVeR' }
+config.subset(:project_id, [:vendor_api, :domain], [:credentials, :user, :login])
+# => { 'project_id' => nil, 'domain' => 'app.service.com', 'login' => 'D@iVeR' }
 ```
 
 - with dot-notation:
 
 ```ruby
-config.subset('project_id', 'vendor_api.host', 'credentials.user.login')
-# => { 'project_id' => nil, 'host' => 'app.service.com', 'login' => 'D@iVeR' }
+config.subset('project_id', 'vendor_api.domain', 'credentials.user.login')
+# => { 'project_id' => nil, 'domain' => 'app.service.com', 'login' => 'D@iVeR' }
 ```
 
 ---
@@ -1024,6 +1037,19 @@ Sometimes the nesting of configs in your project is quite high, and it makes you
 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).
 
+You can use RabbitMQ-like pattern matching in setting key names:
+  - if the setting key name at the current nesting level does not matter - use `*`;
+  - if both the setting key name and nesting level does not matter - use `#`
+  - examples:
+    - `db.settings.user` - matches to `db.settings.user` setting;
+    - `db.settings.*` - matches to all setting keys inside `db.settings` group of settings;
+    - `db.*.user` - matches to all `user` setting keys at the first level of `db` group of settings;
+    - `#.user` - matches to all `user` setting keys;
+    - `service.#.password` - matches to all `password` setting keys at all levels of `service` group of settings;
+    - `#` - matches to ALL setting keys;
+    - `*` - matches to all setting keys at the root level;
+    - and etc;
+
 ---
 
 ### Import config settings
@@ -1055,6 +1081,8 @@ AppConfig = Qonfig::DataSet.build do
       end
     end
   end
+
+  setting :graphql_api, false
 end
 ```
 
@@ -1153,6 +1181,47 @@ service = ServiceObject.new
 service.credentials # => { "account" => { "login" => "D@iVeR", "auth_token" => "IAdkoa0@()1239uA"} }
 ```
 
+#### Immport with pattern-matching
+
+- import root keys only: `import_settings(config_object, '*')`;
+- import all keys: `import_settings(config_object, '#')`;
+- import the subset of keys: `import_settings(config_object, 'group.*.group.#')` (pattern-mathcing usage);
+
+```ruby
+class ServiceObject
+  include Qonfig::Imports
+
+  # import all settings from web_api.credentials subset
+  import_settings(AppConfig, 'web_api.credentials.#')
+  # generated instance methods:
+  #   => service.account
+  #   => service.login
+  #   => service.auth_token
+
+  # import only the root keys from web_api.credentials.account subset
+  import_settings(AppConfig, 'web_api.credentials.account.*')
+  # generated instance methods:
+  #   => service.login
+  #   => service.auth_token
+
+  # import only the root keys
+  import_settings(AppConfig, '*')
+  # generated instance methods:
+  #   => service.web_api
+  #   => service.graphql_api
+
+  # import ALL keys
+  import_Settings(AppConfig, '#')
+  # generated instance methods:
+  #   => service.web_api
+  #   => service.credentials
+  #   => service.account
+  #   => service.login
+  #   => service.auth_token
+  #   => service.graphql_api
+end
+```
+
 ---
 
 ### Export config settings
@@ -1179,6 +1248,8 @@ class Config < Qonfig::DataSet
       end
     end
   end
+
+  setting :graphql_api, false
 end
 
 class ServiceObject; end
@@ -1192,6 +1263,12 @@ service.config_account # => NoMethodError
 config.export_settings(service, 'web_api.credentials.account', prefix: 'config_')
 
 service.config_account # => { "login" => "D@iVeR", "auth_token" => "IAdkoa0@()1239uA" }
+
+# NOTE: export settings with pattern matching
+config.export_settings(service, '*') # export root settings
+
+service.web_api # => { 'credentials' => { 'account' => { ... } }, 'graphql_api' => false }
+service.graphql_api # => false
 ```
 
 ---
@@ -1203,6 +1280,7 @@ service.config_account # => { "login" => "D@iVeR", "auth_token" => "IAdkoa0@()12
 - [Proc-based validation](#proc-based-validation)
 - [Method-based validation](#method-based-validation)
 - [Predefined validations](#predefined-validations)
+- [Custom predefined validators](#custom-predefined-validators)
 - [Validation of potential setting values](#validation-of-potential-setting-values)
 
 ---
@@ -1224,7 +1302,7 @@ If you want to check the config object completely you can define a custom valida
   - `strict: false` ignores validations for settings with `nil` (allows `nil` value);
   - `strict: true` does not ignores validations for settings with `nil`;
   - `strict: false` is used by default;
-- provides special [key search pattern](#key-search-pattern) for matching setting key names;
+- provides a special [key search pattern](#key-search-pattern) for matching setting key names;
 - you can validate potential setting values without any assignment ([documentation](#validation-of-potential-setting-values))
 - uses the [key search pattern](#key-search-pattern) for definging what the setting key should be validated;
 - you can define your own custom validation logic and validate dataset instance completely;
@@ -1261,6 +1339,7 @@ If you want to check the config object completely you can define a custom valida
 - provides a **set of standard validations** ([documentation](#predefined-validations)):
   - DSL: `validate 'key.pattern', :predefned_validator`;
   - supports `strict` behavior;
+- you can define your own predefined validators (class-related and global-related) ([documentation](#custom-predefined-validators));
 
 ---
 
@@ -1477,6 +1556,67 @@ config.settings.ignorance = nil # => Qonfig::ValidationError (cant be nil)
 
 ---
 
+### Custom predefined validators
+
+- DSL: `.define_validator(name, &validation) { |value| ... }` - create your own predefined validator;
+- **class-level**: define validators related only to the concrete config class;
+- **global-level**: define validators related to all config classes (`Qonfig::DataSet.define_validator`);
+- you can re-define any global and inherited validator (at class level);
+- you can re-define any already registered global validator on `Qonfig::DataSet` (at global-level);
+
+#### Define your own class-level validator
+
+```ruby
+class Config < Qonfig::DataSet
+  # NOTE: definition
+  define_validator(:user_type) { |value| value.is_a?(User) }
+
+  setting :admin # some key
+
+  validate :admin, :user_type # NOTE: useage
+end
+```
+
+#### Defin new global validator
+
+```ruby
+Qonfig::DataSet.define_validator(:secured_value) do |value|
+  value == '***'
+end
+
+class Config < Qonfig::DataSet
+  setting :password
+  validate :password, :secured_value
+end
+```
+
+#### Re-definition of existing validators in child classes
+
+```ruby
+class Config < Qonfig::DataSet
+  # NOTE: redefine existing :text validator only in Config class
+  define_validator(:text) { |value| value.is_a?(String) }
+
+  # NOTE: some custom validator that can be redefined in child classes
+  define_validator(:user) { |value| value.is_a?(User) }
+end
+
+class SubConfig < Qonfig
+  define_validator(:user) { |value| value.is_a?(AdminUser) } # NOTE: redefine inherited :user validator
+end
+```
+
+#### Re-definition of existing global validators
+
+```ruby
+# NOTE: redefine already existing :numeric validator
+Qonfig::DataSet.define_validator(:numeric) do |value|
+  value.is_a?(Numeric) || (value.is_a?(String) && value.match?(/\A\d+\.*\d+\z/))
+end
+```
+
+---
+
 ### Validation of potential setting values
 
 - (**instance-level**) `#valid_with?(configurations = {})` - check that current config instalce will be valid with passed configurations;
@@ -2776,7 +2916,6 @@ config = Config.new
   - support for persistent data storages (we want to store configs in multiple databases and files);
   - Rails reload plugin;
 - **Minor**:
-  - custom global (and class-level) validators (with a special Validator Definition DSL);
 
 ## Contributing
 

data/lib/qonfig/commands/definition/re_define_option.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.20.0
+class Qonfig::Commands::Definition::ReDefineOption < Qonfig::Commands::Base
+  # @since 0.20.0
+  self.inheritable = true
+
+  # @return [Symbol, String]
+  #
+  # @api private
+  # @since 0.20.0
+  attr_reader :key
+
+  # @return [Object]
+  #
+  # @api private
+  # @since 0.20.0
+  attr_reader :value
+
+  # @return [Proc, NilClass]
+  #
+  # @api private
+  # @since 0.20.0
+  attr_reader :nested_data_set_klass
+
+  # @param key [Symbol, String]
+  # @param value [Object]
+  #
+  # @raise [Qonfig::ArgumentError]
+  # @raise [Qonfig::CoreMethodIntersectionError]
+  #
+  # @api private
+  # @since 0.20.0
+  def initialize(key, value, nested_definitions)
+    Qonfig::Settings::KeyGuard.prevent_incomparabilities!(key)
+
+    @key = key
+    @value = value
+    @nested_data_set_klass = Class.new(Qonfig::DataSet).tap do |data_set|
+      data_set.instance_eval(&nested_definitions)
+    end if nested_definitions
+  end
+
+  # @param data_set [Qonfig::DataSet]
+  # @param settings [Qonfig::Settings]
+  # @return [void]
+  #
+  # @api private
+  # @since 0.20.0
+  def call(data_set, settings)
+    if nested_data_set_klass
+      nested_settings = nested_data_set_klass.new.settings
+      nested_settings.__mutation_callbacks__.add(settings.__mutation_callbacks__)
+      settings.__define_setting__(key, nested_settings, with_redefinition: true)
+    else
+      settings.__define_setting__(key, value, with_redefinition: true)
+    end
+  end
+end

data/lib/qonfig/commands/definition.rb

@@ -5,6 +5,7 @@
 module Qonfig::Commands::Definition
   require_relative 'definition/add_option'
   require_relative 'definition/add_nested_option'
+  require_relative 'definition/re_define_option'
   require_relative 'definition/compose'
   require_relative 'definition/load_from_yaml'
   require_relative 'definition/load_from_json'

data/lib/qonfig/data_set/class_builder.rb

@@ -33,6 +33,8 @@ module Qonfig::DataSet::ClassBuilder
     def inherit(base_klass:, child_klass:)
       child_klass.definition_commands.concat(base_klass.definition_commands)
       child_klass.instance_commands.concat(base_klass.instance_commands, &:inheritable?)
+      child_klass.predefined_validators.merge(base_klass.predefined_validators)
+      child_klass.validators.concat(base_klass.validators)
     end
   end
 end

data/lib/qonfig/data_set.rb

@@ -7,11 +7,9 @@ class Qonfig::DataSet # rubocop:disable Metrics/ClassLength
   require_relative 'data_set/lock'
 
   # @since 0.1.0
+  # @version 0.20.0
   extend Qonfig::DSL
 
-  # @since 0.13.0
-  extend Qonfig::Validator::DSL
-
   class << self
     # @param base_dataset_klass [Class<Qonfig::DataSet>]
     # @param config_klass_definitions [Proc]
@@ -427,10 +425,11 @@ class Qonfig::DataSet # rubocop:disable Metrics/ClassLength
 
   private
 
-  # @return [Qonfig::Validator]
+  # @return [Qonfig::Validation::Validators::Composite]
   #
   # @api private
   # @since 0.13.0
+  # @version 0.20.0
   attr_reader :validator
 
   # @return [void]
@@ -448,8 +447,9 @@ class Qonfig::DataSet # rubocop:disable Metrics/ClassLength
   #
   # @api private
   # @since 0.13.0
+  # @version 0.20.0
   def build_validator
-    @validator = Qonfig::Validator.new(self)
+    @validator = Qonfig::Validation::Validators::Composite.new(self)
   end
 
   # @param settings_map [Hash]