anyway_config 2.0.0.pre2 → 2.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 540aa91321939a31eb3982143a12cc17621bdcb23c61d2d24686f999ae28a144
-  data.tar.gz: 3215663dd3722892f0635d13163dc02521f515ce31f5c310402893f304387b2d
+  metadata.gz: 0c4661661a2d8cbce7e35a4eef45520a290855af228b1d20d69367708b11be3f
+  data.tar.gz: 97f07abb3e194f490069d6dc1ef7076a88f3775f5b06a3cc99d15314da845c54
 SHA512:
-  metadata.gz: a629cdb9ba784714cff8df41814a6520745b9f1a6fdce272da2a56fd9d6635d46365767c4ce1289c93fdb0f3c5e4d9167b9b617830ff719c555a2a5a6e19f915
-  data.tar.gz: '009fd89edf49b814bde0fa2c7d846fa3f086fe606386c067bc447f4f8c990853a580257cb943e07692b57b49674912fd041f29cc9dbbb9eb652aaa3ee3857776'
+  metadata.gz: 9897240812d5ae7522b99c0d4ac2ec1c3e2ec5759ef481ff3db6d9fbeb1c46312a895ed64fd94fc6b3c1a416a3ccee9325458c1aeacd0ff7dbc9a10593fabf89
+  data.tar.gz: c590c11acb69e99ff0ada09fa7ebb4ae44f777da626f2f9dd053935d9d201fa6b3d6296642271e7d56260b9258d0baca65ade78fd10c9397e5205a03d8551b1a

data/CHANGELOG.md

@@ -0,0 +1,350 @@
+# Change log
+
+## master
+
+## 2.0.0.rc1 (2020-03-31)
+
+- Add predicate methods for attributes with boolean defaults. ([@palkan][])
+
+  For example:
+
+  ```ruby
+  class MyConfig < Anyway::Config
+    attr_config :key, :secret, debug: false
+  end
+
+  MyConfig.new.debug? #=> false
+  MyConfig.new(debug: true).debug? #=> true
+  ```
+
+- Add `Config#deconstruct_keys`. ([@palkan][])
+
+  Now you can use configs in pattern matching:
+
+  ```ruby
+  case AWSConfig.new
+  in bucket:, region: "eu-west-1"
+    setup_eu_storage(bucket)
+  in bucket:, region: "us-east-1"
+    setup_us_storage(bucket)
+  end
+  ```
+
+- Add pretty_print support. ([@palkan][])
+
+  Whenever you use `pp`, the output would contain pretty formatted config information
+  including the sources.
+
+  Example:
+
+  ```ruby
+  pp CoolConfig.new
+
+  # #<CoolConfig
+  #   config_name="cool"
+  #   env_prefix="COOL"
+  #   values:
+  #     port => 3334 (type=load),
+  #     host => "test.host" (type=yml path=./config/cool.yml),
+  #     user =>
+  #       name => "john" (type=env key=COOL_USER__NAME),
+  #       password => "root" (type=yml path=./config/cool.yml)>
+  ```
+
+- Add source tracing support. ([@palkan][])
+
+  You can get the information on where a particular parameter value came from
+  (which loader) through via `#to_source_trace` method:
+
+  ```ruby
+  conf = MyConfig.new
+  conf.to_source_trace
+  # {
+  #  "host" => {value: "test.host", source: {type: :user, called_from: "/rails/root/config/application.rb:21"}},
+  #  "user" => {
+  #    "name" => {value: "john", source: {type: :env, key: "COOL_USER__NAME"}},
+  #    "password" => {value: "root", source: {type: :yml, path: "config/cool.yml"}}
+  #  },
+  #  "port" => {value: 9292, source: {type: :defaults}}
+  # }
+  ```
+
+- Change the way Rails configs autoloading works. ([@palkan][])
+
+  In Rails 6, autoloading before initialization is [deprecated](https://github.com/rails/rails/commit/3e66ba91d511158e22f90ff96b594d61f40eda01). We can still
+  make it work by using our own autoloading mechanism (custom Zeitwerk loader).
+
+  This forces us to use a custom directory (not `app/`) for configs required at the boot time.
+  By default, we put _static_ configs into `config/configs` but you can still use `app/configs` for
+  _dynamic_ (runtime) configs.
+
+  **NOTE:** if you used `app/configs` with 2.0.0.preX and relied on configs during initialization,
+  you can set static configs path to `app/configs`:
+
+  ```ruby
+  config.anyway_config.autoload_static_config_path = "app/configs"
+  ```
+
+  You can do this by running the generator:
+
+  ```sh
+  rails g anyway:install --configs-path=app/configs
+  ```
+
+- Add Rails generators. ([@palkan][])
+
+  You can create config classes with the predefined attributes like this:
+
+  ```sh
+  rails generate config aws access_key_id secret_access_key region
+  ```
+
+- **BREAKING** The accessors generated by `attr_config` are not longer `attr_accessor`-s. ([@palkan][])
+
+  You cannot rely on instance variables anymore. Instead, you can use `super` when overriding accessors or
+  `values[name]`:
+
+  ```ruby
+  attr_config :host, :port, :url, :meta
+
+  # override writer to handle type coercion
+  def meta=(val)
+    super JSON.parse(val)
+  end
+
+  # or override reader to handle missing values
+  def url
+    values[:url] ||= "#{host}:#{port}"
+  end
+
+  # in <2.1 it's still possible to read instance variables,
+  # i.e. the following would also work
+  def url
+    @url ||= "#{host}:#{port}"
+  end
+  ```
+
+  **NOTE**: we still set instance variables in writers (for backward compatibility), but that would
+  be removed in 2.1.
+
+- Add `Config#dig` method. ([@palkan][])
+
+- Add ability to specify types for OptionParser options. ([@palkan][])
+
+  ```ruby
+  describe_options(
+    concurrency: {
+      desc: "number of threads to use",
+      type: String
+    }
+  )
+  ```
+
+- Add param presence validation. ([@palkan][])
+
+  You can specify some params as required, and the validation
+  error would be raised if they're missing or empty (only for strings):
+
+  ```ruby
+  class MyConfig < Anyway::Config
+    attr_config :api_key, :api_secret, :debug
+
+    required :api_key, :api_secret
+  end
+
+  MyConfig.new(api_secret: "") #=> raises Anyway::Config::ValidationError
+  ```
+
+  You can change the validation behaviour by overriding the `#validate!` method in your config class.
+
+- Validate config attribute names. ([@palkan][])
+
+  Do not allow using reserved names (`Anyway::Config` method names).
+  Allow only alphanumeric names (matching `/^[a-z_]([\w]+)?$/`).
+
+- Add Loaders API. ([@palkan][])
+
+  All config sources have standardized via _loaders_ API. It's possible to define
+  custom loaders or change the sources order.
+
+## 2.0.0.pre2 (2019-04-26)
+
+- Fix bug with loading from credentials when local credentials are missing. ([@palkan][])
+
+## 2.0.0.pre (2019-04-26)
+
+- **BREAKING** Changed the way of providing explicit values. ([@palkan][])
+
+  ```ruby
+  # BEFORE
+  Config.new(overrides: data)
+
+  # AFTER
+  Config.new(data)
+  ```
+
+- Add Railtie. ([@palkan][])
+
+  `Anyway::Railtie` provides `Anyway::Settings` access via `Rails.applicaiton.configuration.anyway_config`.
+
+  It also adds `app/configs` path to autoload paths (low-level, `ActiveSupport::Dependencies`) to
+  make it possible to use configs in the app configuration files.
+
+- Add test helpers. ([@palkan][])
+
+  Added `with_env` helper to test code in the context of the specified
+  environment variables.
+
+  Included automatically in RSpec for examples with the `type: :config` meta
+  or with the `spec/configs` path.
+
+- Add support for _local_ files. ([@palkan][])
+
+  Now users can store their personal configurations in _local_ files:
+  - `<config_name>.local.yml`
+  - `config/credentials/local.yml.enc` (for Rails 6).
+
+  Local configs are meant for using in development and only loaded if
+  `Anyway::Settings.use_local_files` is `true` (which is true by default if
+  `RACK_ENV` or `RAILS_ENV` env variable is equal to `"development"`).
+
+- Add Rails credentials support. ([@palkan][])
+
+  The data from credentials is loaded after the data from YAML config and secrets,
+  but before environmental variables (i.e. env variables are _stronger_)
+
+- Update config name inference logic. ([@palkan][])
+
+  Config name is automatically inferred only if:
+  - the class name has a form of `<Module>::Config` (`SomeModule::Config => "some_module"`)
+  - the class name has a form of `<Something>Config` (`SomeConfig => "some"`)
+
+- Fix config classes inheritance. ([@palkan][])
+
+  Previously, inheritance didn't work due to the lack of proper handling of class-level
+  configuration (naming, option parses settings, defaults).
+
+  Now it's possible to extend config classes without breaking the original classes functionality.
+
+  Noticeable features:
+  - if `config_name` is explicitly defined on class, it's inherited by subclasses:
+
+  ```ruby
+  class MyAppBaseConfig < Anyway::Config
+    config_name :my_app
+  end
+
+  class MyServiceConfig < MyAppBaseConfig
+  end
+
+  MyServiceConfig.config_name #=> "my_app"
+  ```
+
+  - defaults are merged leaving the parent class defaults unchanged
+  - option parse extension are not overriden, but added to the parent class extensions
+
+- **Require Ruby >= 2.5.0.**
+
+## 1.4.3 (2019-02-04)
+
+- Add a temporary fix for JRuby regression [#5550](https://github.com/jruby/jruby/issues/5550). ([@palkan][])
+
+## 1.4.2 (2018-01-05)
+
+- Fix: detect Rails by presence of `Rails::VERSION` (instead of just `Rails`). ([@palkan][])
+
+## 1.4.1 (2018-10-30)
+
+- Add `.flag_options` to mark some params as flags (value-less) for OptionParse. ([@palkan][])
+
+## 1.4.0 (2018-10-29)
+
+- Add OptionParse integration ([@jastkand][])
+
+  See more [PR#18](https://github.com/palkan/anyway_config/pull/18).
+
+- Use underscored config name as an env prefix. ([@palkan][])
+
+  For a config class:
+
+  ```ruby
+  class MyApp < Anyway::Config
+  end
+  ```
+
+  Before this change we use `MYAPP_` prefix, now it's `MY_APP_`.
+
+  You can specify the prefix explicitly:
+
+  ```ruby
+  class MyApp < Anyway::Config
+    env_prefix "MYAPP_"
+  end
+  ```
+
+## 1.3.0 (2018-06-15)
+
+- Ruby 2.2 is no longer supported.
+
+- `Anyway::Config.env_prefix` method is introduced. ([@charlie-wasp][])
+
+## 1.2.0 (2018-02-19)
+
+Now works on JRuby 9.1+.
+
+## 1.1.3 (2017-12-20)
+
+- Allow to pass raw hash with explicit values to `Config.new`. ([@dsalahutdinov][])
+
+  Example:
+
+  ```ruby
+  Sniffer::Config.new(
+    overrides: {
+      enabled: true,
+      storage: {capacity: 500}
+    }
+  )
+  ```
+
+  See more [PR#10](https://github.com/palkan/anyway_config/pull/10).
+
+## 1.1.2 (2017-11-19)
+
+- Enable aliases for YAML. ([@onemanstartup][])
+
+## 1.1.1 (2017-10-21)
+
+- Return deep duplicate of a Hash in `Env#fetch`. ([@palkan][])
+
+## 1.1.0 (2017-10-06)
+
+- Add `#to_h` method. ([@palkan][])
+
+  See [#4](https://github.com/palkan/anyway_config/issues/4).
+
+- Make it possible to extend configuration parameters. ([@palkan][])
+
+## 1.0.0 (2017-06-20)
+
+- Lazy load and parse ENV configuration. ([@palkan][])
+
+- Add support for ERB in YML configuration. ([@palkan][])
+
+## 0.5.0 (2017-01-20)
+
+- Drop `active_support` dependency. ([@palkan][])
+
+  Use custom refinements instead of requiring `active_support`.
+
+  No we're dependency-free!
+
+## 0.1.0 (2015-01-20)
+
+  Initial version.
+
+[@palkan]: https://github.com/palkan
+[@onemanstartup]: https://github.com/onemanstartup
+[@dsalahutdinov]: https://github.com/dsalahutdinov
+[@charlie-wasp]: https://github.com/charlie-wasp
+[@jastkand]: https://github.com/jastkand

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2015-2019 Vladimir Dementyev
+Copyright (c) 2015-2020 Vladimir Dementyev
 
 MIT License
 

data/README.md

@@ -4,23 +4,70 @@
 
 # Anyway Config
 
-**NOTE:** this readme shows doc for the upcoming 2.0 version (`2.0.0.pre` is available on RubyGems).
+> One configuration to rule all data sources
+
+Anyway Config is a configuration library for Ruby gems and applications.
+
+As a library author, you can benefit from using Anyway Config by providing a better UX for your end-users:
+
+- **Zero-code configuration** — no more boilerplate initializers.
+- **Per-environment and local** settings support out-of-the-box.
+
+For application developers, Anyway Config could be useful to:
+
+- **Keep configuration organized** and use _named configs_ instead of bloated `.env`/`settings.yml`/whatever.
+- **Free code of ENV/credentials/secrets dependency** and use configuration classes instead—your code should not rely on configuration data sources.
+
+**NOTE:** this readme shows documentation for the upcoming 2.0 version (`2.0.0.rc1` is available on RubyGems).
 For version 1.x see [1-4-stable branch](https://github.com/palkan/anyway_config/tree/1-4-stable).
 
-Rails/Ruby plugin/application configuration tool which allows you to load parameters from different sources: YAML, Rails secrets/credentials, environment.
+## Table of contents
+
+- [Main concepts](#main-concepts)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Configuration classes](#configuration-classes)
+  - [Dynamic configuration](#dynamic-configuration)
+  - [Validation & Callbacks](#validation-and-callbacks)
+- [Using with Rails applications](#using-with-rails)
+  - [Data population](#data-population)
+  - [Organizing configs](#organizing-configs)
+  - [Generators](#generators)
+- [Using with Ruby applications](#using-with-ruby)
+- [Environment variables](#environment-variables)
+- [Local configuration](#local-files)
+- [Data loaders](#data-loaders)
+- [Source tracing](#tracing)
+- [Pattern matching](#pattern-matching)
+- [Test helpers](#test-helpers)
+- [OptionParser integration](#optionparser-integration)
+
+## Main concepts
+
+Anyway Config abstractize the configuration layer by introducing **configuration classes** which describe available parameters and their defaults. For [example](https://github.com/palkan/influxer/blob/master/lib/influxer/config.rb):
 
-Allows you to easily follow the [twelve-factor application](https://12factor.net/config) principles and adds zero complexity to your development process.
+```ruby
+module Influxer
+  class Config < Anyway::Config
+    attr_config(
+      host: "localhost",
+      username: "root",
+      password: "root"
+    )
+  end
+end
+```
 
-Libraries using Anyway Config:
+Using Ruby classes to represent configuration allows you to add helper methods and computed parameters easily, makes the configuration **testable**.
 
-- [Influxer](https://github.com/palkan/influxer)
+The `anyway_config` gem takes care of loading parameters from **different sources** (YAML, credentials/secrets, environment variables, etc.). Internally, we use a _pipeline pattern_ and provide the [Loaders API](#data-loaders) to manage and [extend](#custom-loaders) its functionality.
 
-- [AnyCable](https://github.com/anycable/anycable)
+Check out the libraries using Anyway Config for more examples:
 
+- [Influxer](https://github.com/palkan/influxer)
+- [AnyCable](https://github.com/anycable/anycable)
 - [Sniffer](https://github.com/aderyabin/sniffer)
-
 - [Blood Contracts](https://github.com/sclinede/blood_contracts)
-
 - [and others](https://github.com/palkan/anyway_config/network/dependents).
 
 ## Installation
@@ -31,7 +78,7 @@ Adding to a gem:
 # my-cool-gem.gemspec
 Gem::Specification.new do |spec|
   # ...
-  spec.add_dependency "anyway_config", "2.0.0.pre"
+  spec.add_dependency "anyway_config", "2.0.0.rc1"
   # ...
 end
 ```
@@ -40,23 +87,25 @@ Or adding to your project:
 
 ```ruby
 # Gemfile
-gem "anyway_config", "2.0.0.pre"
+gem "anyway_config", "2.0.0.rc1"
 ```
 
-## Supported Ruby versions
+### Supported Ruby versions
 
 - Ruby (MRI) >= 2.5.0
-
-- JRuby >= 9.2.7
+- JRuby >= 9.2.9
 
 ## Usage
 
-### Pre-defined configuration
+### Configuration classes
+
+Using configuration classes allows you to make configuration data a bit more than a bag of values:
+you can define a schema for your configuration, provide defaults, add validations and additional helper methods.
 
-Create configuration class:
+Anyway Config provides a base class to inherit from with a few DSL methods:
 
 ```ruby
-require "anyway"
+require "anyway_config"
 
 module MyCoolGem
   class Config < Anyway::Config
@@ -65,22 +114,66 @@ module MyCoolGem
 end
 ```
 
-`attr_config` creates accessors and default values. If you don't need default values just write:
+Here `attr_config` creates accessors and populates the default values. If you don't need default values you can write:
 
 ```ruby
 attr_config :user, :password, host: "localhost", options: {}
 ```
 
-Then create an instance of the config class and use it:
+**NOTE**: it's safe to use non-primitive default values (like Hashes or Arrays) without worrying about their mutation: the values would be deeply duplicated for each config instance.
+
+Then, create an instance of the config class and use it:
 
 ```ruby
-module MyCoolGem
-  def self.config
-    @config ||= Config.new
+MyCoolGem::Config.new.user #=> "root"
+```
+
+**Bonus:**: if you define attributes with boolean default values (`false` or `true`), Anyway Config would automatically add a corresponding predicate method. For example:
+
+```ruby
+attr_config :user, :password, debug: false
+
+MyCoolGem::Config.new.debug? #=> false
+MyCoolGem::Config.new(debug: true).debug? #=> true
+```
+
+**NOTE**: since v2.0 accessors created by `attr_config` are not `attr_accessor`, i.e. they do not populate instance variables. If you used instance variables before to override readers, you must switch to using `super` or `values` store:
+
+```ruby
+class MyConfig < Anyway::Config
+  attr_config :host, :port, :url, :meta
+
+  # override writer to handle type coercion
+  def meta=(val)
+    super JSON.parse(val)
+  end
+
+  # or override reader to handle missing values
+  def url
+    super || (self.url = "#{host}:#{port}")
+  end
+
+  # untill v2.1, it will still be possible to read instance variables,
+  # i.e. the following code would also work
+  def url
+    @url ||= "#{host}:#{port}"
   end
 end
+```
+
+We recommend to add a feature check and support both v1.x and v2.0 in gems for the time being:
 
-MyCoolGem.config.user #=> "root"
+```ruby
+# Check for the class method added in 2.0, e.g., `.on_load`
+if respond_to?(:on_load)
+  def url
+    super || (self.url = "#{host}:#{port}")
+  end
+else
+  def url
+    @url ||= "#{host}:#{port}"
+  end
+end
 ```
 
 #### Config name
@@ -92,9 +185,9 @@ By default, Anyway Config uses the config class name to infer the config name us
 - if the class name has a form of `<Module>::Config` then use the module name (`SomeModule::Config => "somemodule"`)
 - if the class name has a form of `<Something>Config` then use the class name prefix (`SomeConfig => "some"`)
 
-**NOTE:** in both cases the config name is a **downcased** module/class prefix, not underscored.
+**NOTE:** in both cases, the config name is a **downcased** module/class prefix, not underscored.
 
-You can also specify the config name explicitly (it's required in cases when you class name doesn't match any of the patterns above):
+You can also specify the config name explicitly (it's required in cases when your class name doesn't match any of the patterns above):
 
 ```ruby
 module MyCoolGem
@@ -122,7 +215,7 @@ module MyCoolGem
 end
 ```
 
-#### Provide explicit values
+#### Explicit values
 
 Sometimes it's useful to set some parameters explicitly during config initialization.
 You can do that by passing a Hash into `.new` method:
@@ -133,17 +226,25 @@ config = MyCoolGem::Config.new(
   password: "rubyisnotdead"
 )
 
-# The value would not be overriden from other sources (such as YML file, env)
+# The value would not be overridden from other sources (such as YML file, env)
 config.user == "john"
 ```
 
+#### Reload configuration
+
+There are `#clear` and `#reload` methods that do exactly what they state.
+
+**NOTE**: `#reload` also accepts an optional Hash for [explicit values](#explicit-values).
+
 ### Dynamic configuration
 
-You can also create configuration objects without pre-defined schema (just like `Rails.application.config_for` but more [powerful](#railsapplicationconfig_for-vs-anywayconfigfor)):
+You can also fetch configuration without pre-defined schema:
 
 ```ruby
-# load data from config/my_app.yml, secrets.my_app (if using Rails), ENV["MY_APP_*"]
-# MY_APP_VALUE=42
+# load data from config/my_app.yml,
+# credentials.my_app, secrets.my_app (if using Rails), ENV["MY_APP_*"]
+#
+# Given MY_APP_VALUE=42
 config = Anyway::Config.for(:my_app)
 config["value"] #=> 42
 
@@ -151,11 +252,75 @@ config["value"] #=> 42
 config = Anyway::Config.for(:my_app, config_path: "my_config.yml", env_prefix: "MYAPP")
 ```
 
-### Using with Rails
+This feature is similar to `Rails.application.config_for` but more powerful:
+
+| Feature | Rails | Anyway Config |
+| ------------- |-------------:| -----:|
+| Load data from `config/app.yml` | ✅ | ✅ |
+| Load data from `secrets` | ❌ | ✅ |
+| Load data from `credentials` | ❌ | ✅ |
+| Load data from environment | ❌ | ✅ |
+| Load data from [custom sources](#data-loaders) | ❌ | ✅ |
+| Local config files | ❌ | ✅ |
+| [Source tracing](#tracing) | ❌ | ✅ |
+| Return Hash with indifferent access | ❌ | ✅ |
+| Support ERB\* within `config/app.yml` | ✅ | ✅ |
+| Raise if file doesn't exist | ✅ | ❌ |
+| Works without Rails | 😀 | ✅ |
+
+\* Make sure that ERB is loaded
+
+### Validation and callbacks
+
+Anyway Config provides basic ways of ensuring that the configuration is valid.
+
+There is a built-in `required` class method to define the list of parameters that must be present in the
+configuration after loading (where present means non-`nil` and non-empty for strings):
+
+```ruby
+class MyConfig < Anyway::Config
+  attr_config :api_key, :api_secret, :debug
+
+  required :api_key, :api_secret
+end
+
+MyConfig.new(api_secret: "") #=> raises Anyway::Config::ValidationError
+```
+
+If you need more complex validation or need to manipulate with config state right after it has been loaded, you can use _on load callbacks_ and `#raise_validation_error` method:
+
+```ruby
+class MyConfig < Anyway::Config
+  attr_config :api_key, :api_secret, :mode
+
+  # on_load macro accepts symbol method names
+  on_load :ensure_mode_is_valid
+
+  # or block
+  on_load do
+    # the block is evaluated in the context of the config
+    raise_validation_error("API key and/or secret could be blank") if
+      api_key.blank? || api_secret.blank?
+  end
+
+  def ensure_mode_is_valid
+    unless %w[production test].include?(mode)
+      raise_validation_error "Unknown mode; #{mode}"
+    end
+  end
+end
+```
+
+## Using with Rails
 
 **NOTE:** version 2.x supports Rails >= 5.0; for Rails 4.x use version 1.x of the gem.
 
-Your config will be filled up with values from the following sources (ordered by priority from low to high):
+We recommend going through [Data population](#data-population) and [Organizing configs](#organizing-configs) sections first,
+and then use [Rails generators](#generators) to make your application Anyway Config-ready.
+
+### Data population
+
+Your config is filled up with values from the following sources (ordered by priority from low to high):
 
 - `RAILS_ROOT/config/my_cool_gem.yml` (for the current `RAILS_ENV`, supports `ERB`):
 
@@ -180,7 +345,7 @@ development:
     port: 4444
 ```
 
-- `Rails.application.credentials` (if supported):
+- `Rails.application.credentials.my_cool_gem` (if supported):
 
 ```yml
 my_cool_gem:
@@ -191,14 +356,18 @@ my_cool_gem:
 
 - `ENV['MYCOOLGEM_*']`.
 
-#### `app/configs`
+See [environment variables](#environment-variables).
+
+### Organizing configs
+
+You can store application-level config classes in `app/configs` folder just like any other Rails entities.
 
-You can store application-level config classes in `app/configs` folder.
+However, in that case you won't be able to use them during the application initialization (i.e., in `config/**/*.rb` files).
 
-Anyway Config automatically adds this folder to Rails autoloading system to make it possible to
-autoload configs even during the configuration phase.
+Since that's a pretty common scenario, we provide a way to do that via a custom autoloader for `config/configs` folder.
+That means, that you can put your configuration classes into `config/configs` folder, use them anywhere in your code without explicitly requiring them.
 
-Consider an example: setting the Action Mailer host name for Heroku review apps.
+Consider an example: setting the Action Mailer hostname for Heroku review apps.
 
 We have the following config to fetch the Heroku provided [metadata](https://devcenter.heroku.com/articles/dyno-metadata):
 
@@ -221,32 +390,108 @@ Then in `config/application.rb` you can do the following:
 config.action_mailer.default_url_options = {host: HerokuConfig.new.hostname}
 ```
 
-### Using with Ruby
+You can configure the configs folder path:
+
+```ruby
+# The path must be relative to Rails root
+config.anyway_config.autoload_static_config_path = "path/to/configs"
+```
+
+**NOTE:** Configs loaded from the `autoload_static_config_path` are **not reloaded in development**. We call them _static_. So, it makes sense to keep only configs necessary for initialization in this folder. Other configs, _dynamic_, could be stored in `app/configs`.
+Or you can store everything in `app/configs` by setting `config.anyway_config.autoload_static_config_path = "app/configs"`.
+
+### Generators
+
+Anyway Config provides Rails generators to create new config classes:
+
+- `rails g anyway:install`—creates an `ApplicationConfig` class (the base class for all config classes) and updates `.gitignore`
+
+You can specify the static configs path via the `--configs-path` option:
+
+```sh
+rails g anyway:install --configs-path=config/settings
+
+# or to keep everything in app/configs
+rails g anyway:install --configs-path=app/configs
+```
+
+- `rails g anyway:config <name> param1 param2 ...`—creates a named configuration class and optionally the corresponding YAML file; creates `application_config.rb` is missing.
+
+The generator command for the Heroku example above would be:
+
+```sh
+$ rails g anyway:config heroku app_id app_name dyno_id release_version slug_commit
+
+    generate  anyway:install
+       rails  generate anyway:install
+      create  config/configs/application_config.rb
+      append  .gitignore
+      create  config/configs/heroku_config.rb
+Would you like to generate a heroku.yml file? (Y/n) n
+```
+
+You can also specify the `--app` option to put the newly created class into `app/configs` folder.
+Alternatively, you can call `rails g anyway:app_config name param1 param2 ...`.
 
-When you're using Anyway Config in non-Rails environment, we're looking for a YAML config file
-at `./config/<config-name>.yml`.
+## Using with Ruby
 
-You can override this setting through special environment variable – 'MYCOOLGEM_CONF' – containing the path to the YAML file.
+The default data loading mechanism for non-Rails applications is the following (ordered by priority from low to high):
 
-**NOTE:** in pure Ruby apps we have no knowledge of _environments_ (`test`, `development`, `production`, etc.); thus we assume that the YAML contains values for a single environment:
+- `./config/<config-name>.yml` (`ERB` is supported if `erb` is loaded)
+
+In pure Ruby apps, we do not know about _environments_ (`test`, `development`, `production`, etc.); thus, we assume that the YAML contains values for a single environment:
 
 ```yml
 host: localhost
 port: 3000
 ```
 
-Environmental variables work the same way as with Rails.
+**NOTE:** you can override the default YML lookup path by setting `MYCOOLGEM_CONF` env variable.
+
+- `ENV['MYCOOLGEM_*']`.
+
+See [environment variables](#environment-variables).
+
+## Environment variables
+
+Environmental variables for your config should start with your config name, upper-cased.
+
+For example, if your config name is "mycoolgem", then the env var "MYCOOLGEM_PASSWORD" is used as `config.password`.
+
+Environment variables are automatically type cast:
+
+- `"True"`, `"t"` and `"yes"` to `true`;
+- `"False"`, `"f"` and `"no"` to `false`;
+- `"nil"` and `"null"` to `nil` (do you really need it?);
+- `"123"` to 123 and `"3.14"` to 3.14.
+
+*Anyway Config* supports nested (_hashed_) env variables—just separate keys with double-underscore.
 
-### Local files
+For example, "MYCOOLGEM_OPTIONS__VERBOSE" is parsed as `config.options["verbose"]`.
 
-It's useful to have personal, user-specific configuration in development, which extends the project-wide one.
+Array values are also supported:
+
+```ruby
+# Suppose ENV["MYCOOLGEM_IDS"] = '1,2,3'
+config.ids #=> [1,2,3]
+```
+
+If you want to provide a text-like env variable which contains commas then wrap it into quotes:
+
+```ruby
+MYCOOLGEM = "Nif-Nif, Naf-Naf and Nouf-Nouf"
+```
+
+## Local files
+
+It's useful to have a personal, user-specific configuration in development, which extends the project-wide one.
 
 We support this by looking at _local_ files when loading the configuration data:
 
 - `<config_name>.local.yml` files (next to\* the _global_ `<config_name>.yml`)
 - `config/credentials/local.yml.enc` (for Rails >= 6, generate it via `rails credentials:edit --environment local`).
 
-\* If the YAML config path is not default (i.e. set via `<CONFIG_NAME>_CONF`), we lookup the local
+\* If the YAML config path is not a default one (i.e., set via `<CONFIG_NAME>_CONF`), we look up the local
 config at this location, too.
 
 Local configs are meant for using in development and only loaded if `Anyway::Settings.use_local_files` is `true` (which is true by default if `RACK_ENV` or `RAILS_ENV` env variable is equal to `"development"`).
@@ -255,110 +500,128 @@ Local configs are meant for using in development and only loaded if `Anyway::Set
 
 Don't forget to add `*.local.yml` (and `config/credentials/local.*`) to your `.gitignore`.
 
-**NOTE:** local YAML configs for Rails app must be environment-free (i.e. you shouldn't have top-level `development:` key).
-
-### Reload configuration
+**NOTE:** local YAML configs for a Rails app must be environment-free (i.e., you shouldn't have top-level `development:` key).
 
-There are `#clear` and `#reload` methods which do exactly what they state.
+## Data loaders
 
-Note: `#reload` also accepts `overrides` key to provide explicit values (see above).
-
-### OptionParser integration
-
-It's possible to use config as option parser (e.g. for CLI apps/libraries). It uses
-[`optparse`](https://ruby-doc.org/stdlib-2.5.1/libdoc/optparse/rdoc/OptionParser.html) under the hood.
-
-Example usage:
+You can provide your own data loaders or change the existing ones using the Loaders API (which is very similar to Rack middleware builder):
 
 ```ruby
-class MyConfig < Anyway::Config
-  attr_config :host, :log_level, :concurrency, :debug, server_args: {}
+# remove env loader => do not load params from ENV
+Anyway.loaders.delete :env
 
-  # specify which options shouldn't be handled by option parser
-  ignore_options :server_args
-
-  # provide description for options
-  describe_options(
-    concurrency: "number of threads to use"
-  )
+# add custom loader before :env (it's better to keep the ENV loader the last one)
+Anyway.loaders.insert_before :env, :my_loader, MyLoader
+```
 
-  # mark some options as flag
-  flag_options :debug
+Loader is a _callable_ Ruby object (module/class responding to `.call` or lambda/proc), which `call` method
+accepts the following keyword arguments:
 
-  # extend an option parser object (i.e. add banner or version/help handlers)
-  extend_options do |parser, config|
-    parser.banner = "mycli [options]"
+```ruby
+def call(
+  name:, # config name
+  env_prefix:, # prefix for env vars if any
+  config_path:, # path to YML config
+  local: # true|false, whether to load local configuration
+)
+  #=> must return Hash with configuration data
+end
+```
 
-    parser.on("--server-args VALUE") do |value|
-      config.server_args = JSON.parse(value)
-    end
+You can use `Anyway::Loaders::Base` as a base class for your loader and define a `#call` method.
+For example, the [Chamber](https://github.com/thekompanee/chamber) loader could be written as follows:
 
-    parser.on_tail "-h", "--help" do
-      puts parser
-    end
+```ruby
+class ChamberConfigLoader < Anyway::Loaders::Base
+  def call(name:, **_opts)
+    Chamber.env.to_h[name] || {}
   end
 end
+```
 
-config = MyConfig.new
-
-config.parse_options!(%w[--host localhost --port 3333 --log-level debug])
-
-config.host # => "localhost"
-config.port # => 3333
-config.log_level # => "debug"
+In order to support [source tracing](#tracing), you need to wrap the resulting Hash via the `#trace!` method with metadata:
 
-# Get the instance of OptionParser
-config.option_parser
+```ruby
+def call(name:, **_opts)
+  trace!(source: :chamber) do
+    Chamber.env.to_h[name] || {}
+  end
+end
 ```
 
-## `Rails.application.config_for` vs `Anyway::Config.for`
-
-Rails 4.2 introduced new feature: `Rails.application.config_for`. It looks very similar to
-`Anyway::Config.for`, but there are some differences:
+## Tracing
 
-| Feature       | Rails         | Anyway Config |
-| ------------- |-------------:| -----:|
-| load data from `config/app.yml`      | yes  | yes  |
-| load data from `secrets`      | no       |   yes  |
-| load data from `credentials`  | no       |   yes  |
-| load data from environment    | no       |   yes  |
-| local config files            | no       |   yes  |
-| return Hash with indifferent access | no | yes  |
-| support ERB within `config/app.yml` | yes | yes* |
-| raise errors if file doesn't exist | yes | no |
+Since Anyway Config loads data from multiple source, it could be useful to know where a particular value came from.
 
-<sub><sup>*</sup>make sure that ERB is loaded</sub>
+Each `Anyway::Config` instance contains _tracing information_ which you can access via `#to_source_trace` method:
 
-But the main advantage of Anyway::Config is that it can be used [without Rails](#using-with-ruby)!)
+```ruby
+conf = ExampleConfig.new
+conf.to_source_trace
+
+# returns the following hash
+{
+  "host" => {value: "test.host", source: {type: :yml, path: "config/example.yml"}},
+  "user" => {
+    "name" => {value: "john", source: {type: :env, key: "EXAMPLE_USER__NAME"}},
+    "password" => {value: "root", source: {type: :credentials, store: "config/credentials/production.enc.yml"}}
+  },
+  "port" => {value: 9292, source: {type: :defaults}}
+}
+
+# if you change the value manually in your code,
+# that would be reflected in the trace
+
+conf.host = "anyway.host"
+conf.to_source_trace["host"]
+#=> {type: :user, called_from: "/path/to/caller.rb:15"}
+```
 
-## How to set env vars
+You can disable tracing functionality by setting `Anyway::Settings.tracing_enabled = false` or `config.anyway_config.tracing_enabled = false` in Rails.
 
-Environmental variables for your config should start with your config name, upper-cased.
+### Pretty print
 
-For example, if your config name is "mycoolgem" then the env var "MYCOOLGEM_PASSWORD" is used as `config.password`.
+You can use `pp` to print a formatted information about the config including the sources trace.
 
-Environment variables are automatically serialized:
+Example:
 
-- `"True"`, `"t"` and `"yes"` to `true`;
-- `"False"`, `"f"` and `"no"` to `false`;
-- `"nil"` and `"null"` to `nil` (do you really need it?);
-- `"123"` to 123 and `"3.14"` to 3.14.
+```ruby
+pp CoolConfig.new
+
+# #<CoolConfig
+#   config_name="cool"
+#   env_prefix="COOL"
+#   values:
+#     port => 3334 (type=load),
+#     host => "test.host" (type=yml path=./config/cool.yml),
+#     user =>
+#       name => "john" (type=env key=COOL_USER__NAME),
+#       password => "root" (type=yml path=./config/cool.yml)>
+```
 
-*Anyway Config* supports nested (_hashed_) env variables. Just separate keys with double-underscore.
+## Pattern matching
 
-For example, "MYCOOLGEM_OPTIONS__VERBOSE" is parsed as `config.options["verbose"]`.
-
-Array values are also supported:
+You can use config instances in Ruby 2.7+ pattern matching:
 
 ```ruby
-# Suppose ENV["MYCOOLGEM_IDS"] = '1,2,3'
-config.ids #=> [1,2,3]
+case AWSConfig.new
+in bucket:, region: "eu-west-1"
+  setup_eu_storage(bucket)
+in bucket:, region: "us-east-1"
+  setup_us_storage(bucket)
+end
 ```
 
-If you want to provide a text-like env variable which contains commas then wrap it into quotes:
+If the attribute wasn't populated, the key won't be returned for pattern matching, i.e. you can do something line:
 
 ```ruby
-MYCOOLGEM = "Nif-Nif, Naf-Naf and Nouf-Nouf"
+aws_configured =
+  case AWSConfig.new
+  in access_key_id:, secret_access_key:
+    true
+  else
+    false
+  end
 ```
 
 ## Test helpers
@@ -398,6 +661,68 @@ This helper is automatically included to RSpec if `RAILS_ENV` or `RACK_ENV` env
 
 You can add it manually by requiring `"anyway/testing/helpers"` and including the `Anyway::Test::Helpers` module (into RSpec configuration or Minitest test class).
 
+## OptionParser integration
+
+It's possible to use config as option parser (e.g., for CLI apps/libraries). It uses
+[`optparse`](https://ruby-doc.org/stdlib-2.5.1/libdoc/optparse/rdoc/OptionParser.html) under the hood.
+
+Example usage:
+
+```ruby
+class MyConfig < Anyway::Config
+  attr_config :host, :log_level, :concurrency, :debug, server_args: {}
+
+  # specify which options shouldn't be handled by option parser
+  ignore_options :server_args
+
+  # provide description for options
+  describe_options(
+    concurrency: "number of threads to use"
+  )
+
+  # mark some options as flag
+  flag_options :debug
+
+  # extend an option parser object (i.e. add banner or version/help handlers)
+  extend_options do |parser, config|
+    parser.banner = "mycli [options]"
+
+    parser.on("--server-args VALUE") do |value|
+      config.server_args = JSON.parse(value)
+    end
+
+    parser.on_tail "-h", "--help" do
+      puts parser
+    end
+  end
+end
+
+config = MyConfig.new
+
+config.parse_options!(%w[--host localhost --port 3333 --log-level debug])
+
+config.host # => "localhost"
+config.port # => 3333
+config.log_level # => "debug"
+
+# Get the instance of OptionParser
+config.option_parser
+```
+
+**NOTE:** values are automatically type cast using the same rules as for [environment variables](#environment-variables).
+If you want to specify the type explicitly, you can do that using `describe_options`:
+
+```ruby
+describe_options(
+  # In this case, you should specify a hash with `type`
+  # and (optionally) `desc` keys
+  concurrency: {
+    desc: "number of threads to use",
+    type: String
+  }
+)
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/palkan/anyway_config](https://github.com/palkan/anyway_config).