qonfig 0.0.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 640c084d4fd0dc167cfb9b52d12ae4d2f70382ec4d2f576703fc8be3a748fc08
-  data.tar.gz: a36a0d612d46c542e9e20609a57c6fcf9ea244fce30fdbf295af8bc130ac9223
+  metadata.gz: 62b74a92c4c74b79f222e029726296a63b51ba3a57886a00911a34ffbcbced25
+  data.tar.gz: 33fa91631b6554dec3547c9c31faddf805bc4a56becbe7042e1942c19c493f16
 SHA512:
-  metadata.gz: 3922f86f65e5d9486074c9ca425821a1d6d6ccb8e9655089c20e95696ece61a99a00e18aa19078b6fa71f069acad5558dcf3a622944c2b72348996774a8e79fc
-  data.tar.gz: f71c819eafab31c35d1faa5cfeaa6a28c9fcee4898d2dc492385391c04e4c50c7376ca2f5a45560d86b25fa98bfab486122f970d9d86c70c77b318a98ab79ccb
+  metadata.gz: 152acb89e834fccaaed1b4bfae379f8263d795b2e4e7b7913f6a2b98fd1bfebf984dec1c82a3568ddc08a3e16fdec2be7783f1f583ef09a3dc6b1386f9afb18f
+  data.tar.gz: c468d5a5c289dc8b4b7b337e62314dbbf9d388b5dd6df1248a14e957a97be9937d7f24c47aa8634ffe415dbd092ed4f3c5b447036770b171fb6d87454eceb4e8

data/.gitignore

@@ -6,6 +6,10 @@
 /pkg/
 /spec/reports/
 /tmp/
-
-# rspec failure tracking
 .rspec_status
+Gemfile.lock
+/.idea
+.ruby-version
+/.vscode/
+/spec/artifacts/
+/gemfiles/*.gemfile.lock

data/.jrubyrc

@@ -0,0 +1 @@
+debug.fullTrace=true

data/.rspec

@@ -1,3 +1,3 @@
---format documentation
 --color
+--format progress
 --require spec_helper

data/.rubocop.yml

@@ -0,0 +1,15 @@
+inherit_gem:
+  armitage-rubocop:
+    - lib/rubocop.general.yml
+    - lib/rubocop.rspec.yml
+
+AllCops:
+  TargetRubyVersion: 2.6.3
+  Include:
+    - lib/**/*.rb
+    - spec/**/*.rb
+    - Gemfile
+    - Rakefile
+    - qonfig.gemspec
+    - bin/console
+    - bin/rspec

data/.travis.yml

@@ -1,5 +1,44 @@
-sudo: false
 language: ruby
-rvm:
-  - 2.5.1
-before_install: gem install bundler -v 1.16.1
+matrix:
+  fast_finish: true
+  include:
+  - rvm: 2.3.8
+    gemfile: gemfiles/with_external_deps.gemfile
+    env: TEST_PLUGINS=true
+  - rvm: 2.4.6
+    gemfile: gemfiles/with_external_deps.gemfile
+    env: TEST_PLUGINS=true
+  - rvm: 2.5.5
+    gemfile: gemfiles/with_external_deps.gemfile
+    env: TEST_PLUGINS=true
+  - rvm: 2.6.3
+    gemfile: gemfiles/with_external_deps.gemfile
+    env: TEST_PLUGINS=true
+  - rvm: ruby-head
+    gemfile: gemfiles/with_external_deps.gemfile
+    env: TEST_PLUGINS=true
+  - rvm: jruby-head
+    gemfile: gemfiles/with_external_deps.gemfile
+    env: TEST_PLUGINS=true
+  - rvm: 2.3.8
+    gemfile: gemfiles/without_external_deps.gemfile
+  - rvm: 2.4.6
+    gemfile: gemfiles/without_external_deps.gemfile
+  - rvm: 2.5.5
+    gemfile: gemfiles/without_external_deps.gemfile
+  - rvm: 2.6.3
+    gemfile: gemfiles/without_external_deps.gemfile
+  - rvm: ruby-head
+    gemfile: gemfiles/without_external_deps.gemfile
+  - rvm: jruby-head
+    gemfile: gemfiles/without_external_deps.gemfile
+  allow_failures:
+  - rvm: ruby-head
+  - rvm: jruby-head
+sudo: false
+cache: bundler
+before_install: gem install bundler
+script: bundle exec rspec
+notifications:
+  slack:
+    secure: I03SDv+IrKy3IkeGjjHUJ9VneFMiYpLzIgPOixGFO5zGVXgulwmun82KsrPSW5HkK1UEQCahfoXt1hNECPwxcdsY01q6LBYJQx1jD0q17bXHllN/q0C6lx3peRN0KqNAAOU3/mHZxLt3HFV+N3HsSnoxDMuSYJgKbjCL/QVG2L2UYT9vi+JRNM/thj8R6MWKWlOHemik40GbLr2anCOCqiALzxnJzh5nJyGj+9SGvjhHfQq/fAIrg1+Scu+UchG8d+1yS5JWsGTt1/JF08i+Ux4ceTQ7GNBNeA5cj/xuUzvRx6A85renxyTiZMKIL0+jeceUm8c+/46XFcq0F7/kJB36lwjFhX1JRphcu/VouRdEwW/BvH74wnyHtygqOpk0LH4shp7A1DIS1DlnBbeJxrR5hdMDnmV85kTU6w6H0BbncsYY/pH1fji1kgH6jCsdwqDlq4wLB8x8I+eZABBsfb/r55z/HnBmmxlvR7Rt3X5/yR3gJrsgRrDBBZ5LwYy1RSCDu76vMQqWGJKG03FdfqSNqmC5V4MC5Ez8yjGDW0Yle09mwvsL2c6fDXyDPCeB/gwNk+FvgLRXnv7C4BaBNEoG4JnCL/dwauoJNg0lB6uF34BEmYAhZIrdY1CI6BqPWnaVMJfcJSYekBVXDIELDnTFRWjaGU1y8dM6lNzDmYE=

data/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+## [0.12.0] - 2019-07-19
+### Added
+- Support for **TOML** (`.toml`) format
+  - realized as a plugin (`Qonfig.plugin(:toml)`);
+  - provides `#save_to_toml`, `#load_from_toml`, `#expose_toml` methods and works in `#*_yaml`-like manner);
+- Custom `bin/rspec` command:
+  - `bin/rspec -n` - run tests without plugin tests;
+  - `bin/rspec -w` - run all tests;
+- Added more convinient aliases for `Qonfig::DataSet` instances:
+  - `#save_to_yaml` => `#dump_to_yaml`;
+  - `#save_to_json` => `#dump_to_json`;
+  - `#save_to_toml` => `#dump_to_toml`;
+### Changed
+- Actualized development dependencies;
+
+## [0.11.0] - 2019-05-15
+### Added
+- `#save_to_json` - save configurations to a json file (uses native `::JSON.generate` under the hood);
+- `#save_to_yaml` - save configurations to a yaml file (uses native `::Psych.dump` under the hood);
+
+### Changed
+- new `#to_h` signature: `#to_h(key_transformer:, value_transformer:)`
+  - `:key_transformer` - proc object used for key pre-processing (`-> (key) { key }` by default);
+  - `:value_transformer` - proc object used for value pre-processing (`-> (value) { value }` by default);
+
+## [0.10.0] - 2019-02-26
+### Added
+- `#slice_value` - get a slice of config options as a hash set and fetch the required value using the given key set;
+
+## [0.9.0] - 2018-11-28
+### Added
+- `#slice` - get a slice of config options as a hash set (works in a `#dig` manner);
+
+## [0.8.0] - 2018-11-21
+### Changed
+- `expose_yaml`, `load_from_yaml`, `load_from_json` and `load_from_self` treats empty hash (`{}`)
+  as an option with empty hash value (previously treated as a nested setting without options);
+
+## [0.7.0] - 2018-10-20
+### Added
+- `expose_yaml` - a command that provides an ability to define config settings
+  by loading them from a yaml file where the concrete settings depends on the chosen environment;
+
+## [0.6.0] - 2018-08-22
+### Added
+- `#shared_config` - instance method that provides an access to the class level config
+  object from `Qonfig::Configurable` instances;
+
+## [0.5.0] - 2018-07-27
+### Added
+- `load_from_json`- a command that provides an ability to define config settings
+  by loading them from a json file (in `load_from_yaml` manner);
+
+### Changed
+- Support for Ruby 2.2 has ended;
+
+## [0.4.0] - 2018-06-24
+### Added
+- Introduce Plugin Ecosystem (`Qonfig::Plugins`):
+  - load plugin: `Qonfig.plugin('plugin_name')` or `Qonfig.plugin(:plugin_name)`;
+  - get registered plugins: `Qonfig.plugins #=> array of strings`
+
+## [0.3.0] - 2018-06-13
+### Added
+- Improved configuration process: `#configure` can take a hash as a configuration `[option key => option]`
+  map of values;
+
+### Changed
+- `#clear!` causes `Qonfig::FrozenSettingsError` if config object is frozen;
+
+## [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/Gemfile

@@ -1,6 +1,8 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
 
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
 # Specify your gem's dependencies in qonfig.gemspec
 gemspec

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2018 Rustam Ibragimov
+Copyright (c) 2018-2019 Rustam Ibragimov
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,43 +1,1084 @@
-# 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)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/qonfig`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+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.
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
 gem 'qonfig'
 ```
 
-And then execute:
+```shell
+$ bundle install
+# --- or ---
+$ gem install 'qonfig'
+```
+
+```ruby
+require 'qonfig'
+```
+
+## Usage
 
-    $ bundle
+- [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`)
+- [Plugins](#plugins)
+  - [toml](#plugin-toml) (provides `load_from_toml`, `save_to_toml`, `expose_toml`)
+---
 
-Or install it yourself as:
+### Definition and Access
 
-    $ gem install qonfig
+```ruby
+# --- definition ---
+class Config < Qonfig::DataSet
+  # nil by default
+  setting :project_id
 
-## Usage
+  # nested setting
+  setting :vendor_api do
+    setting :host, 'app.service.com'
+  end
+
+  setting :enable_graphql, false
+
+  # nested setting reopening
+  setting :vendor_api do
+    setting :user, 'test_user'
+  end
+end
+
+config = Config.new # your configuration object instance
+
+# --- setting access ---
+
+# 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.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 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)
+
+# 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(:project_api) # => Qonfig::UnknownSettingError # (key does not exist)
+config.slice(:vendor_api, :port) # => Qonfig::UnknownSettingError # (key does not exist)
+
+# 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(:project_api) # => Qonfig::UnknownSettingError # (key does not exist)
+config.slice_value(:vendor_api, :port) # => Qonfig::UnknownSettingError # (key does not exist)
+```
+
+---
+
+### Configuration
+
+```ruby
+class Config < Qonfig::DataSet
+  setting :testing do
+    setting :engine, :rspec
+    setting :parallel, true
+  end
+
+  setting :geo_api do
+    setting :provider, :google_maps
+  end
+
+  setting :enable_middlewares, false
+end
+
+config = Config.new
+
+# configure via proc
+config.configure do |conf|
+  conf.enable_middlewares = true
+  conf.geo_api.provider = :yandex_maps
+  conf.testing.engine = :mini_test
+end
+
+# configure via settings object (by option name)
+config.settings.enable_middlewares = false
+config.settings.geo_api.provider = :apple_maps
+config.settings.testing.engine = :ultra_test
+
+# configure via settings object (by setting key)
+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
+
+# using a hash
+config = Config.new(
+  testing: { engine: :mini_test, parallel: false },
+  geo_api: { provider: :rambler_maps },
+  enable_middlewares: true
+)
+config.configure(enable_middlewares: false)
+
+# using both hash and proc (proc has higher priority)
+config = Config.new(enable_middlewares: true) do |conf|
+  conf.testing.parallel = true
+end
+
+config.configure(geo_api: { provider: nil }) do |conf|
+  conf.testing.engine = :rspec
+end
+```
+
+---
+
+### Inheritance
+
+```ruby
+class CommonConfig < Qonfig::DataSet
+  setting :uploader, :fog
+end
+
+class ProjectConfig < CommonConfig
+  setting :auth_provider, :github
+end
+
+project_config = ProjectConfig.new
+
+# inherited setting
+project_config.settings.uploader # => :fog
+
+# own setting
+project_config.settings.auth_provider # => :github
+```
+
+---
+
+### Composition
+
+```ruby
+class SharedConfig < Qonfig::DataSet
+  setting :logger, Logger.new
+end
+
+class ServerConfig < Qonfig::DataSet
+  setting :port, 12345
+  setting :address, '0.0.0.0'
+end
+
+class DatabaseConfig < Qonfig::DataSet
+  setting :user, 'test'
+  setting :password, 'testpaswd'
+end
+
+class ProjectConfig < Qonfig::DataSet
+  compose SharedConfig
+
+  setting :server do
+    compose ServerConfig
+  end
+
+  setting :db do
+    compose DatabaseConfig
+  end
+end
+
+project_config = ProjectConfig.new
+
+# fields from SharedConfig
+project_config.settings.logger # => #<Logger:0x66f57048>
+
+# fields from ServerConfig
+project_config.settings.server.port # => 12345
+project_config.settings.server.address # => '0.0.0.0'
+
+# fields from DatabaseConfig
+project_config.settings.db.user # => 'test'
+project_config.settings.db.password # => 'testpaswd'
+```
+
+---
+
+### Hash representation
+
+```ruby
+class Config < Qonfig::DataSet
+  setting :serializers do
+    setting :json do
+      setting :engine, :ok
+    end
+
+    setting :hash do
+      setting :engine, :native
+    end
+  end
+
+  setting :adapter do
+    setting :default, :memory_sync
+  end
+
+  setting :logger, Logger.new(STDOUT)
+end
+
+Config.new.to_h
+
+{
+  "serializers": {
+    "json" => { "engine" => :ok },
+    "hash" => { "engine" => :native },
+  },
+  "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!(db: { adapter: 'oracle' }) do |conf|
+  conf.enable_api = true # changed instantly
+end
+
+config.settings.db.adapter # => 'oracle'
+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
+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
+config.clear! # => 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
+
+- supports `ERB`;
+- `: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 'nonexistent_yaml.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 'nonexistent_yaml.yml', strict: false
+  end
+
+  setting :another_key
+end
+
+Config.new.to_h # => { "nonexistent_yaml" => {}, "another_key" => nil }
+```
+
+---
+
+### Expose YAML
+
+- load configurations from YAML file in Rails-like manner (with environments);
+- works in `load_from_yaml` manner;
+- `via:` - how an environment will be determined:
+    - `:file_name`
+        - load configuration from YAML file that have an `:env` part in it's name;
+    - `:env_key`
+        - load configuration from YAML file;
+        - concrete configuration should be defined in the root key with `:env` name;
+- `env:` - your environment name (must be a type of `String`, `Symbol` or `Numeric`);
+- `strict:` - requires the existence of the file and/or key with the name of the used environment:
+    - `true`:
+        - file should exist;
+        - root key with `:env` name should exist (if `via: :env_key` is used);
+        - raises `Qonfig::ExposeError` if file does not contain the required env key (if `via: :env` key is used);
+        - raises `Qonfig::FileNotFoundError` if the required file does not exist;
+    - `false`:
+        - file is not required;
+        - root key with `:env` name is not required (if `via: :env_key` is used);
+
+#### Environment is defined as a root key of YAML file
+
+```yaml
+# config/project.yml
+
+default: &default
+  enable_api_mode: true
+  google_key: 12345
+  window:
+    width: 100
+    height: 100
 
-TODO: Write usage instructions here
+development:
+  <<: *default
 
-## Development
+test:
+  <<: *default
+  sidekiq_instrumentation: false
+
+staging:
+  <<: *default
+  google_key: 777
+  enable_api_mode: false
+
+production:
+  google_key: asd1-39sd-55aI-O92x
+  enable_api_mode: true
+  window:
+    width: 50
+    height: 150
+```
+
+```ruby
+class Config < Qonfig::DataSet
+  expose_yaml 'config/project.yml', via: :env_key, env: :production # load from production env
+
+  # NOTE: in rails-like application you can use this:
+  expose_yaml 'config/project.yml', via: :env_key, env: Rails.env
+end
+
+config = Config.new
+
+config.settings.enable_api_mode # => true (from :production subset of keys)
+config.settings.google_key # => asd1-39sd-55aI-O92x (from :production subset of keys)
+config.settings.window.width # => 50 (from :production subset of keys)
+config.settings.window.height # => 150 (from :production subset of keys)
+```
+
+#### Environment is defined as a part of YAML file name
+
+```yaml
+# config/sidekiq.staging.yml
+
+web:
+  username: staging_admin
+  password: staging_password
+```
+
+```yaml
+# config/sidekiq.production.yml
+
+web:
+  username: urj1o2
+  password: u192jd0ixz0
+```
+
+```ruby
+class SidekiqConfig < Qonfig::DataSet
+  # NOTE: file name should be described WITHOUT environment part (in file name attribute)
+  expose_yaml 'config/sidekiq.yml', via: :file_name, env: :staging # load from staging env
+
+  # NOTE: in rails-like application you can use this:
+  expose_yaml 'config/sidekiq.yml', via: :file_name, env: Rails.env
+end
+
+config = SidekiqConfig.new
+
+config.settings.web.username # => staging_admin (from sidekiq.staging.yml)
+config.settings.web.password # => staging_password (from sidekiq.staging.yml)
+```
+
+---
+
+### Load from JSON file
+
+- `:strict` mode (fail behaviour when the required yaml file doesnt exist):
+  - `true` (by default) - causes `Qonfig::FileNotFoundError`;
+  - `false` - do nothing, ignore current command;
+
+```json
+// options.json
+
+{
+  "user": "0exp",
+  "password": 12345,
+  "rubySettings": {
+    "allowedVersions": ["2.3", "2.4.2", "1.9.8"],
+    "gitLink": null,
+    "withAdditionals": false
+  }
+}
+```
+
+```ruby
+class Config < Qonfig::DataSet
+  load_from_json 'options.json'
+end
+
+config = Config.new
+
+config.settings.user # => '0exp'
+config.settings.password # => 12345
+config.settings.rubySettings.allowedVersions # => ['2.3', '2.4.2', '1.9.8']
+config.settings.rubySettings.gitLink # => nil
+config.settings.rubySettings.withAdditionals # => false
+```
+
+```ruby
+# --- strict mode ---
+class Config < Qonfig::DataSet
+  setting :nonexistent_json do
+    load_from_json 'nonexistent_json.json', strict: true # true by default
+  end
+
+  setting :another_key
+end
+
+Config.new # => Qonfig::FileNotFoundError
+
+# --- non-strict mode ---
+class Config < Qonfig::DataSet
+  settings :nonexistent_json do
+    load_from_json 'nonexistent_json.json', strict: false
+  end
+
+  setting :another_key
+end
+
+Config.new.to_h # => { "nonexistent_json" => {}, "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 :nested 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
+```
+
+---
+
+### Save to JSON file
+
+- `#save_to_json` - represents config object as a json structure and saves it to a file:
+  - uses native `::JSON.generate` under the hood;
+  - writes new file (or rewrites existing file);
+  - attributes:
+    - `:path` - (required) - file path;
+    - `:options` - (optional) - native `::JSON.generate` options (from stdlib):
+      - `:indent` - `" "` by default;
+      - `:space` - `" "` by default/
+      - `:object_nl` - `"\n"` by default;
+    - `&value_preprocessor` - (optional) - value pre-processor;
+
+#### Without value preprocessing (standard usage)
+
+```ruby
+class AppConfig < Qonfig::DataSet
+  setting :server do
+    setting :address, 'localhost'
+    setting :port, 12_345
+  end
+
+  setting :enabled, true
+end
+
+config = AppConfig.new
+
+# NOTE: save to json file
+config.save_to_json(path: 'config.json')
+```
+
+```json
+{
+ "sentry": {
+  "address": "localhost",
+  "port": 12345
+ },
+ "enabled": true
+}
+```
+
+#### With value preprocessing and custom options
+
+```ruby
+class AppConfig < Qonfig::DataSet
+  setting :server do
+    setting :address, 'localhost'
+    setting :port, 12_345
+  end
+
+  setting :enabled, true
+  setting :dynamic, -> { 1 + 2 }
+end
+
+config = AppConfig.new
+
+# NOTE: save to json file with custom options (no spaces / no new line / no indent; call procs)
+config.save_to_json(path: 'config.json', options: { indent: '', space: '', object_nl: '' }) do |value|
+  value.is_a?(Proc) ? value.call : value
+end
+```
+
+```json
+// no spaces / no new line / no indent / calculated "dynamic" setting key
+{"sentry":{"address":"localhost","port":12345},"enabled":true,"dynamic":3}
+```
+
+---
+
+### Save to YAML file
+
+- `#save_to_yaml` - represents config object as a yaml structure and saves it to a file:
+  - uses native `::Psych.dump` under the hood;
+  - writes new file (or rewrites existing file);
+  - attributes:
+    - `:path` - (required) - file path;
+    - `:options` - (optional) - native `::Psych.dump` options (from stdlib):
+      - `:indentation` - `2` by default;
+      - `:line_width` - `-1` by default;
+      - `:canonical` - `false` by default;
+      - `:header` - `false` by default;
+      - `:symbolize_keys` - (non-native option) - `false` by default;
+    - `&value_preprocessor` - (optional) - value pre-processor;
+
+#### Without value preprocessing (standard usage)
+
+```ruby
+class AppConfig < Qonfig::DataSet
+  setting :server do
+    setting :address, 'localhost'
+    setting :port, 12_345
+  end
+
+  setting :enabled, true
+end
+
+config = AppConfig.new
+
+# NOTE: save to yaml file
+config.save_to_yaml(path: 'config.yml')
+```
+
+```yaml
+---
+server:
+  address: localhost
+  port: 12345
+enabled: true
+```
+
+#### With value preprocessing and custom options
+
+```ruby
+class AppConfig < Qonfig::DataSet
+  setting :server do
+    setting :address, 'localhost'
+    setting :port, 12_345
+  end
+
+  setting :enabled, true
+  setting :dynamic, -> { 5 + 5 }
+end
+
+config = AppConfig.new
+
+# NOTE: save to yaml file with custom options (add yaml version header; call procs)
+config.save_to_yaml(path: 'config.yml', options: { header: true }) do |value|
+  value.is_a?(Proc) ? value.call : value
+end
+```
+
+```yaml
+# yaml version header / calculated "dynamic" setting key
+%YAML 1.1
+---
+server:
+  address: localhost
+  port: 12345
+enabled: true
+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
+# --- show names of registered plugins ---
+Qonfig.plugins # => array of strings
+
+# --- load specific plugin ---
+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));
+
+```ruby
+require 'toml-rb'
+Qonfig.plugin(:toml)
+# and use :)
+```
+---
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+## Roadmap
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- support for TOML format;
+- explicit "settings" object;
+- validation layer;
+- distributed configuration server;
+- support for Rails-like secrets;
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/qonfig. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+- Fork it ( https://github.com/0exp/qonfig/fork )
+- Create your feature branch (`git checkout -b feature/my-new-feature`)
+- 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
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Released under MIT License.
 
-## Code of Conduct
+## Authors
 
-Everyone interacting in the Qonfig project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/qonfig/blob/master/CODE_OF_CONDUCT.md).
+[Rustam Ibragimov](https://github.com/0exp)