qonfig 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62b74a92c4c74b79f222e029726296a63b51ba3a57886a00911a34ffbcbced25
-  data.tar.gz: 33fa91631b6554dec3547c9c31faddf805bc4a56becbe7042e1942c19c493f16
+  metadata.gz: c7f383ceef309126a60c17c1383cdfd3de9445aa5978ccb80374226dfd17e83c
+  data.tar.gz: 6f2f868550a9822b4feb8daff758a2a91d486903f9e57726c1045725fc658e55
 SHA512:
-  metadata.gz: 152acb89e834fccaaed1b4bfae379f8263d795b2e4e7b7913f6a2b98fd1bfebf984dec1c82a3568ddc08a3e16fdec2be7783f1f583ef09a3dc6b1386f9afb18f
-  data.tar.gz: c468d5a5c289dc8b4b7b337e62314dbbf9d388b5dd6df1248a14e957a97be9937d7f24c47aa8634ffe415dbd092ed4f3c5b447036770b171fb6d87454eceb4e8
+  metadata.gz: bf030ed32f26241ebe6a8717e02e3b705d5f31e666c1096f19776c14e2db92f251e08ee12e668831a69bea51ce2fb40288791dbc4d8dfd19bc9fdd10c0505db8
+  data.tar.gz: 67e3f1712357a8de30e651271b8ca2dd2590af18cedd42ee57d48b86a755bfe15a0ea7ae59fea448212ae5fa798b19a12364acaa2fde588fc5778c33ef4d25c1

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [0.13.0] - 2019-08-13
+### Added
+- Iteration over setting keys (`#each_setting { |key, value| }`, `#deep_each_setting { |key, value| }`);
+- Brand new `Validation API`;
+
+### Changed
+- Actualized development dependencies;
+
 ## [0.12.0] - 2019-07-19
 ### Added
 - Support for **TOML** (`.toml`) format

data/README.md

@@ -1,7 +1,8 @@
 # Qonfig · [![Gem Version](https://badge.fury.io/rb/qonfig.svg)](https://badge.fury.io/rb/qonfig) [![Build Status](https://travis-ci.org/0exp/qonfig.svg?branch=master)](https://travis-ci.org/0exp/qonfig) [![Coverage Status](https://coveralls.io/repos/github/0exp/qonfig/badge.svg?branch=master)](https://coveralls.io/github/0exp/qonfig?branch=master)
 
 Config. Defined as a class. Used as an instance. Support for inheritance and composition.
-Lazy instantiation. Thread-safe. Command-style DSL. Extremely simple to define. Extremely simple to use. That's all.
+Lazy instantiation. Thread-safe. Command-style DSL. Validation layer. Support for **YAML**, **TOML**, **JSON**, **\_\_END\_\_**, **ENV**.
+Extremely simple to define. Extremely simple to use. That's all? **NOT** :)
 
 ## Installation
 
@@ -21,27 +22,38 @@ require 'qonfig'
 
 ## Usage
 
-- [Definition and Settings Access](#definition-and-access)
-- [Configuration](#configuration)
-- [Inheritance](#inheritance)
-- [Composition](#composition)
-- [Hash representation](#hash-representation)
-- [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)
-- [Load from YAML file](#load-from-yaml-file)
-- [Expose YAML](#expose-yaml) (`Rails`-like environment-based YAML configs)
-- [Load from JSON file](#load-from-json-file)
-- [Load from ENV](#load-from-env)
-- [Load from \_\_END\_\_](#load-from-__end__) (aka `load_from_self`)
-- [Save to JSON file](#save-to-json-file) (`save_to_json`)
-- [Save to YAML file](#save-to-yaml-file) (`save_to_yaml`)
-- [Smart Mixin](#smart-mixin) (`Qonfig::Configurable`)
+- [Definition](#definition)
+  - [Definition and Settings Access](#definition-and-access)
+  - [Configuration](#configuration)
+  - [Inheritance](#inheritance)
+  - [Composition](#composition)
+  - [Hash representation](#hash-representation)
+  - [Smart Mixin](#smart-mixin) (`Qonfig::Configurable`)
+- [Interaction](#interaction)
+  - [Iteration over setting keys](#iteration-over-setting-keys) (`#each_setting`, `#deep_each_setting`)
+  - [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)
+- [Validation](#validation)
+  - [Key search pattern](#key-search-pattern)
+  - [Proc-based validation](#proc-based-validation)
+  - [Method-based validation](#method-based-validation)
+  - [Predefined validations](#predefined-validations)
+- [Work with files](#work-with-files)
+  - [Load from YAML file](#load-from-yaml-file)
+  - [Expose YAML](#expose-yaml) (`Rails`-like environment-based YAML configs)
+  - [Load from JSON file](#load-from-json-file)
+  - [Load from ENV](#load-from-env)
+  - [Load from \_\_END\_\_](#load-from-__end__) (aka `load_from_self`)
+  - [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](#plugin-toml) (provides `load_from_toml`, `save_to_toml`, `expose_toml`)
+  - [toml](#plugins-toml) (provides `load_from_toml`, `save_to_toml`, `expose_toml`)
 ---
 
+## Definition
+
 ### Definition and Access
 
 ```ruby
@@ -274,6 +286,164 @@ Config.new.to_h
 
 ---
 
+### Smart Mixin
+
+- class-level:
+  - `.configuration` - settings definitions;
+  - `.configure` - configuration;
+  - `.config` - config object;
+  - settings definitions are inheritable;
+- instance-level:
+  - `#configure` - configuration;
+  - `#config` - config object;
+  - `#shared_config` - class-level config object;
+
+```ruby
+# --- usage ---
+
+class Application
+  # make configurable
+  include Qonfig::Configurable
+
+  configuration do
+    setting :user
+    setting :password
+  end
+end
+
+app = Application.new
+
+# class-level config
+Application.config.settings.user # => nil
+Application.config.settings.password # => nil
+
+# instance-level config
+app.config.settings.user # => nil
+app.config.settings.password # => nil
+
+# access to the class level config from an instance
+app.shared_config.settings.user # => nil
+app.shared_config.settings.password # => nil
+
+# class-level configuration
+Application.configure do |conf|
+  conf.user = '0exp'
+  conf.password = 'test123'
+end
+
+# instance-level configuration
+app.configure do |conf|
+  conf.user = 'admin'
+  conf.password = '123test'
+end
+
+# class has own config object
+Application.config.settings.user # => '0exp'
+Application.config.settings.password # => 'test123'
+
+# instance has own config object
+app.config.settings.user # => 'admin'
+app.config.settings.password # => '123test'
+
+# access to the class level config from an instance
+app.shared_config.settings.user # => '0exp'
+app.shared_config.settings.password # => 'test123'
+
+# and etc... (all Qonfig-related features)
+```
+
+```ruby
+# --- inheritance ---
+
+class BasicApplication
+  # make configurable
+  include Qonfig::Configurable
+
+  configuration do
+    setting :user
+    setting :pswd
+  end
+
+  configure do |conf|
+    conf.user = 'admin'
+    conf.pswd = 'admin'
+  end
+end
+
+class GeneralApplication < BasicApplication
+  # extend inherited definitions
+  configuration do
+    setting :db do
+      setting :adapter
+    end
+  end
+
+  configure do |conf|
+    conf.user = '0exp' # .user inherited from BasicApplication
+    conf.pswd = '123test' # .pswd inherited from BasicApplication
+    conf.db.adapter = 'pg'
+  end
+end
+
+BasicApplication.config.to_h
+{ 'user' => 'admin', 'pswd' => 'admin' }
+
+GeneralApplication.config.to_h
+{ 'user' => '0exp', 'pswd' => '123test', 'db' => { 'adapter' => 'pg' } }
+
+# and etc... (all Qonfig-related features)
+```
+
+---
+
+
+## Interaction
+
+---
+
+### Iteration over setting keys
+
+- `#each_setting { |key, value| }`
+  - iterates over the root setting keys;
+- `#deep_each_setting { |key, value| }`
+  - iterates over all setting keys (deep inside);
+  - key object is represented as a string of `.`-joined keys;
+
+```ruby
+class Config < Qonfig::DataSet
+  setting :db do
+    setting :creds do
+      setting :user, 'D@iVeR'
+      setting :password, 'test123',
+      setting :data, test: false
+    end
+  end
+
+  setting :telegraf_url, 'udp://localhost:8094'
+  setting :telegraf_prefix, 'test'
+end
+
+config = Config.new
+
+# 1. #each_setting
+config.each_setting { |key, value| { key => value } }
+# result of each step:
+{ 'db' => <Qonfig::Settings:0x00007ff8> }
+{ 'telegraf_url' => 'udp://localhost:8094' }
+{ 'telegraf_prefix' => 'test' }
+
+# 2. #deep_each_setting
+config.deep_each_setting { |key, value| { key => value } }
+# result of each step:
+{ 'db.creds.user' => 'D@iveR' }
+{ 'db.creds.password' => 'test123' }
+{ 'db.creds.data' => { test: false } }
+{ 'telegraf_url' => 'udp://localhost:8094' }
+{ 'telegraf_prefix' => 'test' }
+```
+
+---
+
 ### Config reloading
 
 ```ruby
@@ -423,6 +593,264 @@ config.settings.database.engine.driver? # => true (true => true)
 
 ---
 
+## Validation
+
+Qonfig provides a lightweight DSL for defining validations and works in all cases when setting values are initialized or mutated.
+Settings are validated as keys (matched with a [specific string pattern](#key-search-patern)).
+You can validate both a set of keys and each key separately.
+If you want to check the config object completely you can define a custom validation.
+
+**Features**:
+
+- is invoked on any mutation of any setting key
+  - during dataset instantiation;
+  - when assigning new values;
+  - when calling `#reload!`;
+  - when calling `#clear!`;
+
+- provides special [key search pattern](#key-search-pattern) for matching setting key names;
+- 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;
+- validation logic should return **truthy** or **falsy** value;
+
+- supprots two validation techniques (**proc-based** and **dataset-method-based**)
+  - **proc-based** (`setting validation`)
+    ```ruby
+      validate 'db.user' do |value|
+        value.is_a?(String)
+      end
+    ```
+  - **proc-based** (`dataset validation`)
+    ```ruby
+      validate do
+        settings.user == User[1]
+      end
+    ```
+  - **dataset-method-based** (`setting validation`)
+    ```ruby
+      validate 'db.user', by: :check_user
+
+      def check_user(value)
+        value.is_a?(String)
+      end
+    ```
+  - **dataset-method-based** (`dataset validation`)
+    ```ruby
+      validate by: :check_config
+
+      def check_config
+        settings.user == User[1]
+      end
+    ```
+
+- provides a set of standard validations:
+  - `integer`
+  - `float`
+  - `numeric`
+  - `big_decimal`
+  - `boolean`
+  - `string`
+  - `symbol`
+  - `text` (string or symbol)
+  - `array`
+  - `hash`
+  - `proc`
+  - `class`
+  - `module`
+  - `not_nil`
+
+---
+
+### Key search pattern
+
+**Key search pattern** works according to the following rules:
+
+- works in `RabbitMQ`-like key pattern ruleses;
+- has a string format;
+- nested configs are defined by a set of keys separated by `.`-symbol;
+- 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;
+
+---
+
+### Proc-based validation
+
+- your proc should return truthy value or falsy value;
+- how to validate setting keys:
+  - define proc with attribute: `validate 'your.setting.path' do |value|; end`
+  - proc will receive setting value;
+- how to validate dataset instance:
+  - define proc without setting key pattern: `validate do; end`
+
+```ruby
+class Config < Qonfig::DataSet
+  setting :db do
+    setting :user, 'D@iVeR'
+    setting :password, 'test123'
+  end
+
+  setting :service do
+    setting :address, 'google.ru'
+    setting :protocol, 'https'
+
+    setting :creds do
+      seting :admin, 'D@iVeR'
+    end
+  end
+
+  setting :enabled, false
+
+  # validates:
+  #   - db.password
+  validate 'db.password' do |value|
+    value.is_a?(String)
+  end
+
+  # validates:
+  #   - service.address
+  #   - service.protocol
+  #   - service.creds.user
+  validate 'service.#' do |value|
+    value.is_a?(String)
+  end
+
+  # validates:
+  #   - dataset instance
+  validate do # NOTE: no setting key pattern
+    settings.enabled == false
+  end
+end
+
+config = Config.new
+config.settings.db.password = 123 # => Qonfig::ValidationError (should be a string)
+config.settings.service.address = 123 # => Qonfig::ValidationError (should be a string)
+config.settings.service.protocol = :http # => Qonfig::ValidationError (should be a string)
+config.settings.service.creds.admin = :billikota # => Qonfig::ValidationError (should be a string)
+config.settings.enabled = true # => Qonfig::ValidationError (isnt `true`)
+```
+
+---
+
+### Method-based validation
+
+- method should return truthy value or falsy value;
+- how to validate setting keys:
+  - define validation: `validate 'db.*.user', by: :your_custom_method`;
+  - define your method with attribute: `def your_custom_method(setting_value); end`
+- how to validate config instance
+  - define validation: `validate by: :your_custom_method`
+  - define your method without attributes: `def your_custom_method; end`
+
+```ruby
+class Config < Qonfig::DataSet
+  setting :services do
+    setting :counts do
+      setting :google, 2
+      setting :rambler, 3
+    end
+
+    setting :minimals do
+      setting :google, 1
+      setting :rambler, 0
+    end
+  end
+
+  setting :enabled, true
+
+  # validates:
+  #   - services.counts.google
+  #   - services.counts.rambler
+  #   - services.minimals.google
+  #   - services.minimals.rambler
+  validate 'services.#', by: :check_presence
+
+  # validates:
+  #   - dataset instance
+  validate by: :check_state # NOTE: no setting key pattern
+
+  def check_presence(value)
+    value.is_a?(Numeric) && value > 0
+  end
+
+  def check_state
+    settings.enabled.is_a?(TrueClass) || settings.enabled.is_a?(FalseClass)
+  end
+end
+
+config = Config.new
+
+config.settings.counts.google = 0 # => Qonfig::ValidationError (< 0)
+config.settings.counts.rambler = nil # => Qonfig::ValidationError (should be a numeric)
+config.settings.minimals.google = -1 # => Qonfig::ValidationError (< 0)
+config.settings.minimals.rambler = 'no' # => Qonfig::ValidationError (should be a numeric)
+config.settings.enabled = nil # => Qonfig::ValidationError (should be a boolean)
+```
+
+---
+
+### Predefined validations
+
+- DSL: `validate 'key.pattern', :predefned_validator`
+- predefined validators:
+  - `:not_nil`
+  - `:integer`
+  - `:float`
+  - `:numeric`
+  - `:big_decimal`
+  - `:array`
+  - `:hash`
+  - `:string`
+  - `:symbol`
+  - `:text` (`string` or `symbol`)
+  - `:boolean`
+  - `:class`
+  - `:module`
+  - `:proc`
+
+```ruby
+class Config < Qonfig::DataSet
+  setting :user
+  setting :password
+
+  setting :service do
+    setting :provider
+    setting :protocol
+    setting :on_fail, -> { puts 'atata!' }
+  end
+
+  setting :ignorance, false
+
+  validate 'user', :string
+  validate 'password', :string
+  validate 'service.provider', :text
+  validate 'service.protocol', :text
+  validate 'service.on_fail', :proc
+  validate 'ignorance', :not_nil
+end
+
+config = Config.new do |conf|
+  conf.user = 'D@iVeR'
+  conf.password = 'test123'
+  conf.service.provider = :google
+  conf.service.protocol = :https
+end # NOTE: all right :)
+
+config.settings.ignorance = nil # => Qonfig::ValidationError (cant be nil)
+```
+
+---
+
+## Work with files
+
 ### Load from YAML file
 
 - supports `ERB`;
@@ -922,116 +1350,6 @@ dynamic: 10
 
 ---
 
-### Smart Mixin
-
-- class-level:
-  - `.configuration` - settings definitions;
-  - `.configure` - configuration;
-  - `.config` - config object;
-  - settings definitions are inheritable;
-- instance-level:
-  - `#configure` - configuration;
-  - `#config` - config object;
-  - `#shared_config` - class-level config object;
-
-```ruby
-# --- usage ---
-
-class Application
-  # make configurable
-  include Qonfig::Configurable
-
-  configuration do
-    setting :user
-    setting :password
-  end
-end
-
-app = Application.new
-
-# class-level config
-Application.config.settings.user # => nil
-Application.config.settings.password # => nil
-
-# instance-level config
-app.config.settings.user # => nil
-app.config.settings.password # => nil
-
-# access to the class level config from an instance
-app.shared_config.settings.user # => nil
-app.shared_config.settings.password # => nil
-
-# class-level configuration
-Application.configure do |conf|
-  conf.user = '0exp'
-  conf.password = 'test123'
-end
-
-# instance-level configuration
-app.configure do |conf|
-  conf.user = 'admin'
-  conf.password = '123test'
-end
-
-# class has own config object
-Application.config.settings.user # => '0exp'
-Application.config.settings.password # => 'test123'
-
-# instance has own config object
-app.config.settings.user # => 'admin'
-app.config.settings.password # => '123test'
-
-# access to the class level config from an instance
-app.shared_config.settings.user # => '0exp'
-app.shared_config.settings.password # => 'test123'
-
-# and etc... (all Qonfig-related features)
-```
-
-```ruby
-# --- inheritance ---
-
-class BasicApplication
-  # make configurable
-  include Qonfig::Configurable
-
-  configuration do
-    setting :user
-    setting :pswd
-  end
-
-  configure do |conf|
-    conf.user = 'admin'
-    conf.pswd = 'admin'
-  end
-end
-
-class GeneralApplication < BasicApplication
-  # extend inherited definitions
-  configuration do
-    setting :db do
-      setting :adapter
-    end
-  end
-
-  configure do |conf|
-    conf.user = '0exp' # .user inherited from BasicApplication
-    conf.pswd = '123test' # .pswd inherited from BasicApplication
-    conf.db.adapter = 'pg'
-  end
-end
-
-BasicApplication.config.to_h
-{ 'user' => 'admin', 'pswd' => 'admin' }
-
-GeneralApplication.config.to_h
-{ 'user' => '0exp', 'pswd' => '123test', 'db' => { 'adapter' => 'pg' } }
-
-# and etc... (all Qonfig-related features)
-```
-
----
-
 ### Plugins
 
 ```ruby
@@ -1047,23 +1365,25 @@ Qonfig.plugin(:plugin_name) # or Qonfig.plugin('plugin_name')
 ### Plugins: toml
 
 - adds support for `toml` format ([specification](https://github.com/toml-lang/toml));
-- depends on `toml-rb` gem;
-- provides `load_from_toml` (works in `load_from_yaml` manner [doc](#load-from-yaml-file));
-- provides `save_to_toml` (works in `save_to_yaml` manner [doc](#save-to-yaml-file)) (`toml-rb` has no native options);
-- provides `expose_toml` (works in `expose_yaml` manner [doc](#expose-yaml));
+- depends on `toml-rb` gem ([link](https://github.com/emancu/toml-rb));
+- supports TOML `0.4.0` format (dependency lock);
+- provides `load_from_toml` (works in `load_from_yaml` manner ([doc](#load-from-yaml-file)));
+- provides `save_to_toml` (works in `save_to_yaml` manner ([doc](#save-to-yaml-file))) (`toml-rb` has no native options);
+- provides `expose_toml` (works in `expose_yaml` manner ([doc](#expose-yaml)));
 
 ```ruby
+# 1) require external dependency
 require 'toml-rb'
+
+# 2) enable plugin
 Qonfig.plugin(:toml)
-# and use :)
+
+# 3) use :)
 ```
 ---
 
 ## Roadmap
 
-- support for TOML format;
-- explicit "settings" object;
-- validation layer;
 - distributed configuration server;
 - support for Rails-like secrets;
 

data/lib/qonfig/command_set.rb

@@ -3,12 +3,18 @@
 # @api private
 # @since 0.1.0
 class Qonfig::CommandSet
+  # @api private
+  # @since 0.13.0
+  include Enumerable
+
   # @return [Array<Qonfig::Commands::Base>]
   #
   # @api private
   # @since 0.1.0
   attr_reader :commands
 
+  # @return [void]
+  #
   # @api private
   # @since 0.1.0
   def initialize
@@ -57,7 +63,7 @@ class Qonfig::CommandSet
   private
 
   # @param block [Proc]
-  # @return [Object]
+  # @return [Any]
   #
   # @api private
   # @since 0.2.0