qonfig 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d774926f0d94544e9d256b7c3e06bbc51b16a51a1323fbcb1f020a1c377ffaf7
-  data.tar.gz: a3d2769d42ba24938db56bd853f65b041a7053af462644a6d4e3ac3109c3b121
+  metadata.gz: 364dfdc09c159ed886729491cc0d066f961b5be382b766d99d57705fca5f88d7
+  data.tar.gz: 9525458cf3d84fa9588ab48805cdb8a5ec0150278a7658986fb6325efcd2d191
 SHA512:
-  metadata.gz: 82ac7dd98fdccf5ab5ba846a9c733fbb8e3523676a23b390aca49c587e01b1cf9c76602d5909cda2736c7e4d572ffe219b85e3f7267f4499051c579a5bf59997
-  data.tar.gz: 747f86b8b8f8f2a348ae906e0e3e75a37f45afd896874ee1eb56aa7b66ee6a4c4581d48fbbe3d7d203879c345ff0894ca780f12a5bcbd660b421f7e202c29028
+  metadata.gz: 6cf8f8df874ebcb636f7862247ada545579f413c030b4d4dde51decb72ed18f38f5af3faa9c595e6cf741f25ab6fc8a09afef4c72133ced1448f12bbe76dbb96
+  data.tar.gz: 785f7e10238601b7f5be5c506d516004eee7d914b451e2a4c0a7e0aebf6257ca0003f19a52bad0c86f35c89713b4a837d5e175cbf71217cbd1f0de1a6950cc45

data/.rubocop.yml

@@ -5,8 +5,8 @@ AllCops:
   DisplayStyleGuide: true
   TargetRubyVersion: 2.5.1
   Include:
-    - lib/**/*
-    - spec/**/*
+    - lib/**/*.rb
+    - spec/**/*.rb
   Exclude:
     - bin/**/*
     - Gemfile
@@ -61,6 +61,9 @@ Lint/HandleExceptions:
 Metrics/MethodLength:
   Max: 20
 
+Style/DoubleNegation:
+  Enabled: false
+
 Style/EmptyCaseCondition:
   Enabled: false
 
@@ -70,5 +73,23 @@ RSpec/ExampleLength:
 RSpec/MultipleExpectations:
   Enabled: false
 
+Style/MultilineBlockChain:
+  Enabled: false
+
 Metrics/AbcSize:
-  Max: 17
+  Max: 19
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Lint/UnderscorePrefixedVariableName:
+  Enabled: false
+
+Security/YAMLLoad:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
-## [0.1.0] - 2018-05-xx
+## [0.2.0] - 2018-06-07
+### Added
+- Instant configuration via block `config = Config.new { |conf| <<your configuration code>> }`;
+- `.load_from_env` command - an ability to define config settings by loading them from ENV variable;
+- `.load_from_yaml` command - an ability to define config settings by loading them from a yaml file;
+- `.load_from_self` command - an ability to load config definitions form the YAML
+  instructions written in the file where the config class is defined (`__END__` section);
+- `#reload!` - an ability to reload config isntance after any config class changes and updates;
+- `#clear!` - an ability to set all options to `nil`;
+- `#dig` - an ability to fetch setting values in `Hash#dig` manner
+  (fails with `Qonfig::UnknownSettingError` when the required key does not exist);
+- Settings as Predicates - an ability to check the boolean nature of the config setting by appending
+  the question mark symbol (`?`) at the end of setting name:
+  - `nil` and `false` setting values indicates `false`;
+  - other setting values indicates `true`;
+  - setting roots always returns `true`;
+  - examples:
+    - `config.settings.database.user # => nil`;
+    - `config.settings.database.user? # => false`;
+    - `config.settings.database.host # => 'google.com'`;
+    - `config.settings.database.host? # => true`;
+    - `config.settings.database? # => true (setting with nested option (setting root))`
+- Support for ERB instructions in YAML;
+- Support for `HashWithIndifferentAccess`-like behaviour;
+- `Qonfig::Settings` instance method redefinition protection: the setting key can not
+  have a name that matches an any instance method name of `Qonfig::Settings`;
+- Added `Qonfig::Configurable` mixin - configuration behaviour for any classes and modules
+  and their instances:
+  - all `Qonfig`-related features;
+  - different class-level and instance-level config objects;
+  - working class-level inheritance :);
+- Full thread-safe implementation;
+
+### Changed
+- Superclass of `Qonfig::FrozenSettingsError` (it was `Qonfig::Error` before):
+  - `ruby >= 2.5` - inherited from `::FrozenError`;
+  - `ruby < 2.5` - inherited from `::RuntimeError`;
+- `.setting` will raise exceptions immediately:
+  - `.setting(key, ...) { ... }` - if setting key has incompatible type;
+  - `.compose(config_class)`- if composed config class is not a subtype of `Qonfig::DataSet`;
+
+### Fixed
+- Recoursive hash representation with deep nested `Qonfig::Settings` values (infinite loop);
+- Fixed re-assignment of the options with nested options (losing the nested options
+  due to the instance configuration). Now it causes `Qonfig::AmbigousSettingValueError`.
+
+## [0.1.0] - 2018-05-18
 - Release :)

data/README.md

@@ -1,7 +1,7 @@
-# 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)](https://coveralls.io/github/0exp/qonfig)
+# 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. Command-style DSL. Extremely simple to define. Extremely simple to use. That's all.
+Lazy instantiation. Thread-safe. Command-style DSL. Extremely simple to define. Extremely simple to use. That's all.
 
 ## Installation
 
@@ -12,7 +12,7 @@ gem 'qonfig'
 ```shell
 $ bundle install
 # --- or ---
-gem install 'qonfig'
+$ gem install 'qonfig'
 ```
 
 ```ruby
@@ -27,6 +27,13 @@ require 'qonfig'
 - [Composition](#composition)
 - [Hash representation](#hash-representation)
 - [State freeze](#state-freeze)
+- [Config reloading](#config-reloading) (reload config definitions and option values)
+- [Clear options](#clear-options) (set to nil)
+- [Settings as Predicates](#settings-as-predicates)
+- [Load from YAML file](#load-from-yaml-file)
+- [Load from ENV](#load-from-env)
+- [Load from \_\_END\_\_](#load-from-__end__) (aka `load_from_self`)
+- [Smart Mixin](#smart-mixin) (`Qonfig::Configurable`)
 
 ---
 
@@ -40,7 +47,6 @@ class Config < Qonfig::DataSet
   # nested setting
   setting :vendor_api do
     setting :host, 'app.service.com'
-    setting :port, 12345
   end
 
   setting :enable_graphql, false
@@ -48,25 +54,38 @@ class Config < Qonfig::DataSet
   # nested setting reopening
   setting :vendor_api do
     setting :user, 'test_user'
-    setting :password, 'test_password'
   end
 end
 
 config = Config.new
 
+# get option value via method
 config.settings.project_id # => nil
-config.settings.vendor_api.host # => 'api.service.com'
-config.settings.vendor_api.port # => 12345
+config.settings.vendor_api.host # => 'app.service.com'
 config.settings.vendor_api.user # => 'test_user'
-config.settings.vendor_api.password # => 'test_password'
 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] # => 'api.service.com'
-config.settings[:vendor_api][:port] # => 12345
+config.settings[:vendor_api][:host] # => 'app.service.com'
 config.settings[:vendor_api][:user] # => 'test_user'
-config.settings[:vendor_api][:password] # => 'test_password'
 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['enable_graphql'] # => false
+
+# get option value directly via index (with indifferent access)
+config['project_id'] # => nil
+config['enable_graphql'] # => false
+config[:project_id] # => nil
+config[:enable_graphql] # => false
+
+# 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)
 ```
 
 ---
@@ -89,7 +108,7 @@ end
 
 config = Config.new
 
-# configure via block
+# configure via proc
 config.configure do |conf|
   conf.enable_middlewares = true
   conf.geo_api.provider = :yandex_maps
@@ -105,6 +124,13 @@ config.settings.testing.engine = :ultra_test
 config.settings[:enable_middlewares] = true
 config.settings[:geo_api][:provider] = :rambler_maps
 config.settings[:testing][:engine] = :mega_test
+
+# instant configuration via proc
+config = Config.new do |conf|
+  conf.enable_middlewares = false
+  conf.geo_api.provider = :amazon_maps
+  conf.testing.engine = :crypto_test
+end
 ```
 
 ---
@@ -191,7 +217,7 @@ class Config < Qonfig::DataSet
   end
 
   setting :adapter do
-    setting :default: :memory_sync
+    setting :default, :memory_sync
   end
 
   setting :logger, Logger.new(STDOUT)
@@ -200,23 +226,107 @@ end
 Config.new.to_h
 
 {
-  serializers: {
-    json: { engine: :ok },
-    hash: { engine: :native },
+  "serializers": {
+    "json" => { "engine" => :ok },
+    "hash" => { "engine" => :native },
   },
-  adapter: { default: :memory_sync },
-  logger: #<Logger:0x4b0d79fc>
+  "adapter" => { "default" => :memory_sync },
+  "logger" => #<Logger:0x4b0d79fc>
 }
 ```
 
 ---
 
+### Config reloading
+
+```ruby
+class Config < Qonfig::DataSet
+  setting :db do
+    setting :adapter, 'postgresql'
+  end
+
+  setting :logger, Logger.new(STDOUT)
+end
+
+config = Config.new
+
+config.settings.db.adapter # => 'postgresql'
+config.settings.logger # => #<Logger:0x00007ff9>
+
+config.configure { |conf| conf.logger = nil } # redefine some settings (will be reloaded)
+
+# re-define and append settings
+class Config
+  setting :db do
+    setting :adapter, 'mongoid' # re-define defaults
+  end
+
+  setting :enable_api, false # append new setting
+end
+
+# reload settings
+config.reload!
+
+config.settings.db.adapter # => 'mongoid'
+config.settings.logger # => #<Logger:0x00007ff9> (reloaded from defaults)
+config.settings.enable_api # => false (new setting)
+
+# reload with instant configuration
+config.reload! do |conf|
+  conf.enable_api = true # changed instantly
+end
+
+config.settings.db.adapter # => 'mongoid'
+config.settings.logger = # => #<Logger:0x00007ff9>
+config.settings.enable_api # => true # value from instant change
+```
+
+---
+
+### Clear options
+
+```ruby
+class Config
+  setting :database do
+    setting :user
+    setting :password
+  end
+
+  setting :web_api do
+    setting :endpoint
+  end
+end
+
+config = Config.new do |conf|
+  conf.database.user = '0exp'
+  conf.database.password = 'test123'
+
+  conf.web_api.endpoint = '/api/'
+end
+
+config.settings.database.user # => '0exp'
+config.settings.database.password # => 'test123'
+config.settings.web_api.endpoint # => '/api'
+
+# clear all options
+config.clear!
+
+config.settings.database.user # => nil
+config.settings.database.password # => nil
+config.settings.web_api.endpoint # => nil
+```
+
+---
+
 ### State freeze
 
 ```ruby
 class Config < Qonfig::DataSet
   setting :logger, Logger.new(STDOUT)
   setting :worker, :sidekiq
+  setting :db do
+    setting :adapter, 'postgresql'
+  end
 end
 
 config = Config.new
@@ -224,14 +334,357 @@ config.freeze!
 
 config.settings.logger = Logger.new(StringIO.new) # => Qonfig::FrozenSettingsError
 config.settings.worker = :que # => Qonfig::FrozenSettingsError
+config.settings.db.adapter = 'mongoid' # => Qonfig::FrozenSettingsError
+
+config.reload! # => Qonfig::FrozenSettingsError
+```
+
+---
+
+### Settings as Predicates
+
+- predicate form: `?` at the end of setting name;
+- `nil` and `false` setting values indicates `false`;
+- other setting values indicates `true`;
+- setting roots always returns `true`;
+
+```ruby
+class Config < Qonfig::DataSet
+  setting :database do
+    setting :user
+    setting :host, 'google.com'
+
+    setting :engine do
+      setting :driver, 'postgres'
+    end
+  end
+end
+
+config = Config.new
+
+# predicates
+config.settings.database.user? # => false (nil => false)
+config.settings.database.host? # => true ('google.com' => true)
+config.settings.database.engine.driver? # => true ('postgres' => true)
+
+# setting roots always returns true
+config.settings.database? # => true
+config.settings.database.engine? # => ture
+
+config.configure do |conf|
+  conf.database.user = '0exp'
+  conf.database.host = false
+  conf.database.engine.driver = true
+end
+
+# predicates
+config.settings.database.user? # => true ('0exp' => true)
+config.settings.database.host? # => false (false => false)
+config.settings.database.engine.driver? # => true (true => true)
 ```
 
 ---
 
+### Load from YAML file
+
+- `:strict` mode (fail behaviour when the required yaml file doesnt exist):
+  - `true` (by default) - causes `Qonfig::FileNotFoundError`;
+  - `false` - do nothing, ignore current command;
+
+```yaml
+<!-- travis.yml -->
+sudo: false
+language: ruby
+rvm:
+  - ruby-head
+  - jruby-head
+```
+
+```yaml
+<!-- project.yml -->
+enable_api: false
+Sidekiq/Scheduler:
+  enable: true
+```
+
+```yaml
+<!-- ruby_data.yml -->
+version: <%= RUBY_VERSION %>
+platform: <%= RUBY_PLATFORM %>
+```
+
+```ruby
+class Config < Qonfig::DataSet
+  setting :ruby do
+    load_from_yaml 'ruby_data.yml'
+  end
+
+  setting :travis do
+    load_from_yaml 'travis.yml'
+  end
+
+  load_from_yaml 'project.yml'
+end
+
+config = Config.new
+
+config.settings.travis.sudo # => false
+config.settings.travis.language # => 'ruby'
+config.settings.travis.rvm # => ['ruby-head', 'jruby-head']
+config.settings.enable_api # => false
+config.settings['Sidekiq/Scheduler']['enable'] #=> true
+config.settings.ruby.version # => '2.5.1'
+config.settings.ruby.platform # => 'x86_64-darwin17'
+```
+
+```ruby
+# --- strict mode ---
+class Config < Qonfig::DataSet
+  setting :nonexistent_yaml do
+    load_from_yaml 'unexistent_file.yml', strict: true # true by default
+  end
+
+  setting :another_key
+end
+
+Config.new # => Qonfig::FileNotFoundError
+
+# --- non-strict mode ---
+class Config < Qonfig::DataSet
+  settings :nonexistent_yaml do
+    load_from_yaml 'unexistent_file.yml', strict: false
+  end
+
+  setting :another_key
+end
+
+Config.new.to_h # => { "nonexistent_yaml" => {}, "another_key" => nil }
+```
+
+---
+
+### Load from ENV
+
+- `:convert_values` (`false` by default):
+  - `'t'`, `'T'`, `'true'`, `'TRUE'` - covnerts to `true`;
+  - `'f'`, `'F'`, `'false'`, `'FALSE'` - covnerts to `false`;
+  - `1`, `23` and etc - converts to `Integer`;
+  - `1.25`, `0.26` and etc - converts to `Float`;
+  - `1, 2, test`, `FALSE,Qonfig` (strings without quotes that contains at least one comma) -
+    converts to `Array` with recursively converted values;
+  - `'"please, test"'`, `"'test, please'"` (quoted strings) - converts to `String` without quotes;
+- `:prefix` - load ENV variables which names starts with a prefix:
+  - `nil` (by default) - empty prefix;
+  - `Regexp` - names that match the regexp pattern;
+  - `String` - names which starts with a passed string;
+- `:trim_prefix` (`false` by default);
+
+```ruby
+# some env variables
+ENV['QONFIG_BOOLEAN'] = 'true'
+ENV['QONFIG_INTEGER'] = '0'
+ENV['QONFIG_STRING'] = 'none'
+ENV['QONFIG_ARRAY'] = '1, 2.5, t, f, TEST'
+ENV['QONFIG_MESSAGE'] = '"Hello, Qonfig!"'
+ENV['RUN_CI'] = '1'
+
+class Config < Qonfig::DataSet
+  # nested
+  setting :qonfig do
+    load_from_env convert_values: true, prefix: 'QONFIG' # or /\Aqonfig.*\z/i
+  end
+
+  setting :trimmed do
+    load_from_env convert_values: true, prefix: 'QONFIG_', trim_prefix: true # trim prefix
+  end
+
+  # on the root
+  load_from_env
+end
+
+config = Config.new
+
+# customized
+config.settings['qonfig']['QONFIG_BOOLEAN'] # => true ('true' => true)
+config.settings['qonfig']['QONFIG_INTEGER'] # => 0 ('0' => 0)
+config.settings['qonfig']['QONFIG_STRING'] # => 'none'
+config.settings['qonfig']['QONFIG_ARRAY'] # => [1, 2.5, true, false, 'TEST']
+config.settings['qonfig']['QONFIG_MESSAGE'] # => 'Hello, Qonfig!'
+config.settings['qonfig']['RUN_CI'] # => Qonfig::UnknownSettingError
+
+# trimmed (and customized)
+config.settings['trimmed']['BOOLEAN'] # => true ('true' => true)
+config.settings['trimmed']['INTEGER'] # => 0 ('0' => 0)
+config.settings['trimmed']['STRING'] # => 'none'
+config.settings['trimmed']['ARRAY'] # => [1, 2.5, true, false, 'TEST']
+config.settings['trimmed']['MESSAGE'] # => 'Hello, Qonfig!'
+config.settings['trimmed']['RUN_CI'] # => Qonfig::UnknownSettingError
+
+# default
+config.settings['QONFIG_BOOLEAN'] # => 'true'
+config.settings['QONFIG_INTEGER'] # => '0'
+config.settings['QONFIG_STRING'] # => 'none'
+config.settings['QONFIG_ARRAY'] # => '1, 2.5, t, f, TEST'
+config.settings['QONFIG_MESSAGE'] # => '"Hello, Qonfig!"'
+config.settings['RUN_CI'] # => '1'
+```
+
+---
+
+### Load from \_\_END\_\_
+
+- aka `load_from_self`
+
+```ruby
+class Config < Qonfig::DataSet
+  load_from_self # on the root
+
+  setting :clowd do
+    load_from_self # nested
+  end
+end
+
+config = Config.new
+
+# on the root
+config.settings.ruby_version # => '2.5.1'
+config.settings.secret_key # => 'top-mega-secret'
+config.settings.api_host # => 'super.puper-google.com'
+config.settings.connection_timeout.seconds # => 10
+config.settings.connection_timeout.enabled # => false
+
+# nested
+config.settings.nested.ruby_version # => '2.5.1'
+config.settings.nested.secret_key # => 'top-mega-secret'
+config.settings.nested.api_host # => 'super.puper-google.com'
+config.settings.nested.connection_timeout.seconds # => 10
+config.settings.nested.connection_timeout.enabled # => false
+
+__END__
+
+ruby_version: <%= RUBY_VERSION %>
+secret_key: top-mega-secret
+api_host: super.puper-google.com
+connection_timeout:
+  seconds: 10
+  enabled: false
+```
+
+---
+
+### Smart Mixin
+
+- class-level:
+  - `.configuration` - settings definitions;
+  - `.configure` - configuration;
+  - `.config` - config object;
+  - settings definitions are inheritable;
+- instance-level:
+  - `#configure` - configuration;
+  - `#config` - 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
+
+# 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'
+
+# 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)
+```
+
+---
+
+## Contributing
+
+- Fork it ( https://github.com/0exp/qonfig/fork )
+- Create your feature branch (`git checkout -b feature/my-new-feature development`)
+- Commit your changes (`git commit -am 'Add some feature'`)
+- Push to the branch (`git push origin feature/my-new-feature`)
+- Create new Pull Request
+
 ## License
 
 Released under MIT License.
 
 ## Authors
 
-Rustam Ibragimov.
+[Rustam Ibragimov](https://github.com/0exp)