anyway_config 2.0.5 → 2.2.1

data/README.md

@@ -1,4 +1,4 @@
-[![Cult Of Martians](http://cultofmartians.com/assets/badges/badge.svg)](http://cultofmartians.com)
+[![Cult Of Martians](http://cultofmartians.com/assets/badges/badge.svg)](https://cultofmartians.com/tasks/anyway-config-options-parse.html#task)
 [![Gem Version](https://badge.fury.io/rb/anyway_config.svg)](https://rubygems.org/gems/anyway_config) [![Build](https://github.com/palkan/anyway_config/workflows/Build/badge.svg)](https://github.com/palkan/anyway_config/actions)
 [![JRuby Build](https://github.com/palkan/anyway_config/workflows/JRuby%20Build/badge.svg)](https://github.com/palkan/anyway_config/actions)
 
@@ -42,12 +42,14 @@ For version 1.x see the [1-4-stable branch](https://github.com/palkan/anyway_con
   - [Generators](#generators)
 - [Using with Ruby applications](#using-with-ruby)
 - [Environment variables](#environment-variables)
+- [Type coercion](#type-coercion)
 - [Local configuration](#local-files)
 - [Data loaders](#data-loaders)
 - [Source tracing](#tracing)
 - [Pattern matching](#pattern-matching)
 - [Test helpers](#test-helpers)
 - [OptionParser integration](#optionparser-integration)
+- [RBS support](#rbs-support)
 
 ## Main concepts
 
@@ -94,7 +96,7 @@ Or adding to your project:
 
 ```ruby
 # Gemfile
-gem "anyway_config", "~> 2.0.0"
+gem "anyway_config", "~> 2.0"
 ```
 
 ### Supported Ruby versions
@@ -269,6 +271,7 @@ This feature is similar to `Rails.application.config_for` but more powerful:
 | Load data from environment | ❌ | ✅ |
 | Load data from [custom sources](#data-loaders) | ❌ | ✅ |
 | Local config files | ❌ | ✅ |
+| Type coercion | ❌ | ✅ |
 | [Source tracing](#tracing) | ❌ | ✅ |
 | Return Hash with indifferent access | ❌ | ✅ |
 | Support ERB\* within `config/app.yml` | ✅ | ✅ |
@@ -329,7 +332,9 @@ and then use [Rails generators](#generators) to make your application Anyway Con
 
 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`):
+1) **YAML configuration files**: `RAILS_ROOT/config/my_cool_gem.yml`.
+
+Rails environment is used as the namespace (required); supports `ERB`:
 
 ```yml
 test:
@@ -341,9 +346,51 @@ development:
   port: 3000
 ```
 
-**NOTE:** you can override the default YML lookup path by setting `MYCOOLGEM_CONF` env variable.
+### Multi-env configuration
+
+_⚡️ This feature will be turned on by default in the future releases. You can turn it on now via `config.anyway_config.future.use :unwrap_known_environments`._
 
-- `Rails.application.secrets.my_cool_gem` (if `secrets.yml` present):
+If the YML does not have keys that are one of the "known" Rails environments (development, production, test)—the same configuration will be available in all environments, similar to non-Rails behavior:
+
+```yml
+host: localhost
+port: 3002
+# These values will be active in all environments
+```
+
+To extend the list of known environments, use the setting in the relevant part of your Rails code:
+
+```ruby
+Rails.application.config.anyway_config.known_environments << "staging"
+```
+
+If your YML defines at least a single "environmental" top-level, you _have_ to separate all your settings per-environment. You can't mix and match:
+
+```yml
+staging:
+  host: localhost # This value will be loaded when Rails.env.staging? is true
+
+port: 3002 # This value will not be loaded at all
+```
+
+You can specify the lookup path for YAML files in one of the following ways:
+
+- By setting `config.anyway_config.default_config_path` to a target directory path:
+
+```ruby
+config.anyway_config.default_config_path = "/etc/configs"
+config.anyway_config.default_config_path = Rails.root.join("etc", "configs")
+```
+
+- By setting `config.anyway_config.default_config_path` to a Proc, which accepts a config name and returns the path:
+
+```ruby
+config.anyway_config.default_config_path = ->(name) { Rails.root.join("data", "configs", "#{name}.yml") }
+```
+
+- By overriding a specific config YML file path via the `<NAME>_CONF` env variable, e.g., `MYCOOLGEM_CONF=path/to/cool.yml`
+
+2) **Rails secrets**: `Rails.application.secrets.my_cool_gem` (if `secrets.yml` present).
 
 ```yml
 # config/secrets.yml
@@ -352,7 +399,7 @@ development:
     port: 4444
 ```
 
-- `Rails.application.credentials.my_cool_gem` (if supported):
+3) **Rails credentials**: `Rails.application.credentials.my_cool_gem` (if supported):
 
 ```yml
 my_cool_gem:
@@ -361,7 +408,7 @@ my_cool_gem:
 
 **NOTE:** You can backport Rails 6 per-environment credentials to Rails 5.2 app using [this patch](https://gist.github.com/palkan/e27e4885535ff25753aefce45378e0cb).
 
-- `ENV['MYCOOLGEM_*']`.
+4) **Environment variables**: `ENV['MYCOOLGEM_*']`.
 
 See [environment variables](#environment-variables).
 
@@ -407,6 +454,22 @@ 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"`.
 
+**NOTE 2**: Since _static_ configs are loaded before initializers, it's not possible to use custom inflection Rules (usually defined in `config/initializers/inflections.rb`) to resolve constant names from files. If you rely on custom inflection rules (see, for example, [#81](https://github.com/palkan/anyway_config/issues/81)), we recommend configuration Rails inflector before initialization as well:
+
+```ruby
+# config/application.rb
+
+# ...
+
+require_relative "initializers/inflections"
+
+module SomeApp
+  class Application < Rails::Application
+    # ...
+  end
+end
+```
+
 ### Generators
 
 Anyway Config provides Rails generators to create new config classes:
@@ -444,7 +507,7 @@ Alternatively, you can call `rails g anyway:app_config name param1 param2 ...`.
 
 The default data loading mechanism for non-Rails applications is the following (ordered by priority from low to high):
 
-- `./config/<config-name>.yml` (`ERB` is supported if `erb` is loaded)
+1) **YAML configuration files**: `./config/<config-name>.yml`.
 
 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:
 
@@ -453,9 +516,25 @@ host: localhost
 port: 3000
 ```
 
-**NOTE:** you can override the default YML lookup path by setting `MYCOOLGEM_CONF` env variable.
+`ERB` is supported if `erb` is loaded (thus, you need to call `require "erb"` somewhere before loading configuration).
+
+You can specify the lookup path for YAML files in one of the following ways:
+
+- By setting `Anyway::Settings.default_config_path` to a target directory path:
+
+```ruby
+Anyway::Settings.default_config_path = "/etc/configs"
+```
+
+- By setting `Anyway::Settings.default_config_path` to a Proc, which accepts a config name and returns the path:
+
+```ruby
+Anyway::Settings.default_config_path = ->(name) { Rails.root.join("data", "configs", "#{name}.yml") }
+```
 
-- `ENV['MYCOOLGEM_*']`.
+- By overriding a specific config YML file path via the `<NAME>_CONF` env variable, e.g., `MYCOOLGEM_CONF=path/to/cool.yml`
+
+2) **Environment variables**: `ENV['MYCOOLGEM_*']`.
 
 See [environment variables](#environment-variables).
 
@@ -465,13 +544,15 @@ Environmental variables for your config should start with your config name, uppe
 
 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:
+By default, 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.
 
+\* See below for coercion customization.
+
 *Anyway Config* supports nested (_hashed_) env variables—just separate keys with double-underscore.
 
 For example, "MYCOOLGEM_OPTIONS__VERBOSE" is parsed as `config.options["verbose"]`.
@@ -489,6 +570,94 @@ If you want to provide a text-like env variable which contains commas then wrap
 MYCOOLGEM = "Nif-Nif, Naf-Naf and Nouf-Nouf"
 ```
 
+## Type coercion
+
+> 🆕 v2.2.0
+
+You can define custom type coercion rules to convert string data to config values. To do that, use `.coerce_types` method:
+
+```ruby
+class CoolConfig < Anyway::Config
+  config_name :cool
+  attr_config port: 8080,
+    host: "localhost",
+    user: {name: "admin", password: "admin"}
+
+  coerce_types port: :string, user: {dob: :date}
+end
+
+ENV["COOL_USER__DOB"] = "1989-07-01"
+
+config = CoolConfig.new
+config.port == "8080" # Even though we defined the default value as int, it's converted into a string
+config.user["dob"] == Date.new(1989, 7, 1) #=> true
+```
+
+Type coercion is especially useful to deal with array values:
+
+```ruby
+# To define an array type, provide a hash with two keys:
+#  - type — elements type
+#  - array: true — mark the parameter as array
+coerce_types list: {type: :string, array: true}
+```
+
+You can use `type: nil` in case you don't want to coerce values, just convert a value into an array:
+
+```ruby
+# From AnyCable config (sentinels could be represented via strings or hashes)
+coerce_types redis_sentinels: {type: nil, array: true}
+```
+
+It's also could be useful to explicitly define non-array types (to avoid confusion):
+
+```ruby
+coerce_types non_list: :string
+```
+
+Finally, it's possible to disable auto-casting for a particular config completely:
+
+```ruby
+class CoolConfig < Anyway::Config
+  attr_config port: 8080,
+    host: "localhost",
+    user: {name: "admin", password: "admin"}
+
+  disable_auto_cast!
+end
+
+ENV["COOL_PORT"] = "443"
+
+CoolConfig.new.port == "443" #=> true
+```
+
+**IMPORTANT**: Values provided explicitly (via attribute writers) are not coerced. Coercion is only happening during the load phase.
+
+The following types are supported out-of-the-box: `:string`, `:integer`, `:float`, `:date`, `:datetime`, `:uri`, `:boolean`.
+
+You can use custom deserializers by passing a callable object instead of a type name:
+
+```ruby
+COLOR_TO_HEX = lambda do |raw|
+  case raw
+  when "red"
+    "#ff0000"
+  when "green"
+    "#00ff00"
+  when "blue"
+    "#0000ff"
+  end
+end
+
+class CoolConfig < Anyway::Config
+  attr_config :color
+
+  coerce_types color: COLOR_TO_HEX
+end
+
+CoolConfig.new({color: "red"}).color #=> "#ff0000"
+```
+
 ## Local files
 
 It's useful to have a personal, user-specific configuration in development, which extends the project-wide one.
@@ -550,7 +719,7 @@ In order to support [source tracing](#tracing), you need to wrap the resulting H
 
 ```ruby
 def call(name:, **_opts)
-  trace!(source: :chamber) do
+  trace!(:chamber) do
     Chamber.env.to_h[name] || {}
   end
 end
@@ -666,7 +835,7 @@ If you want to delete the env var, pass `nil` as the value.
 
 This helper is automatically included to RSpec if `RAILS_ENV` or `RACK_ENV` env variable is equal to "test". It's only available for the example with the tag `type: :config` or with the path `spec/configs/...`.
 
-You can add it manually by requiring `"anyway/testing/helpers"` and including the `Anyway::Test::Helpers` module (into RSpec configuration or Minitest test class).
+You can add it manually by requiring `"anyway/testing/helpers"` and including the `Anyway::Testing::Helpers` module (into RSpec configuration or Minitest test class).
 
 ## OptionParser integration
 
@@ -730,6 +899,62 @@ describe_options(
 )
 ```
 
+## RBS support
+
+Anyway Config comes with Ruby type signatures (RBS).
+
+To use them with Steep, add `library "anyway_config"` to your Steepfile.
+
+We also provide an API to generate a type signature for your config class:
+
+```ruby
+class MyGem::Config < Anyway::Config
+  attr_config :host, port: 8080, tags: [], debug: false
+
+  coerce_types host: :string, port: :integer,
+    tags: {type: :string, array: true}
+
+  required :host
+end
+```
+
+Then calling `MyGem::Config.to_rbs` will return the following signature:
+
+```rbs
+module MyGem
+  interface _Config
+    def host: () -> String
+    def host=: (String) -> void
+    def port: () -> String?
+    def port=: (String) -> void
+    def tags: () -> Array[String]?
+    def tags=: (Array[String]) -> void
+    def debug: () -> bool
+    def debug?: () -> bool
+    def debug=: (bool) -> void
+  end
+
+  class Config < Anyway::Config
+    include _Config
+  end
+end
+```
+
+### Handling `on_load`
+
+When we use `on_load` callback with a block, we switch the context (via `instance_eval`), and we need to provide type hints for the type checker. Here is an example:
+
+```ruby
+class MyConfig < Anyway::Config
+  on_load do
+    # @type self : MyConfig
+    raise_validation_error("host is invalid") if host.start_with?("localhost")
+  end
+end
+```
+
+Yeah, a lot of annotations 😞 Welcome to the type-safe world!
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/palkan/anyway_config](https://github.com/palkan/anyway_config).