README.md in anyway_config-2.0.0.pre vs README.md in anyway_config-2.0.0.pre2

- old
+ new

@@ -1,7 +1,8 @@ [![Cult Of Martians](http://cultofmartians.com/assets/badges/badge.svg)](http://cultofmartians.com) -[![Gem Version](https://badge.fury.io/rb/anyway_config.svg)](https://rubygems.org/gems/anyway_config) [![Build Status](https://travis-ci.org/palkan/anyway_config.svg?branch=master)](https://travis-ci.org/palkan/anyway_config) +[![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) # Anyway Config **NOTE:** this readme shows doc for the upcoming 2.0 version (`2.0.0.pre` is available on RubyGems). For version 1.x see [1-4-stable branch](https://github.com/palkan/anyway_config/tree/1-4-stable). @@ -22,34 +23,34 @@ - [and others](https://github.com/palkan/anyway_config/network/dependents). ## Installation -1) Adding to a gem: +Adding to a gem: ```ruby # my-cool-gem.gemspec Gem::Specification.new do |spec| # ... spec.add_dependency "anyway_config", "2.0.0.pre" # ... end ``` -2) Adding to your project: +Or adding to your project: ```ruby # Gemfile gem "anyway_config", "2.0.0.pre" ``` -3) Install globally: +## Supported Ruby versions -```sh -$ gem install anyway_config -``` +- Ruby (MRI) >= 2.5.0 +- JRuby >= 9.2.7 + ## Usage ### Pre-defined configuration Create configuration class: @@ -85,10 +86,11 @@ #### Config name Anyway Config relies on the notion of _config name_ to populate data. By default, Anyway Config uses the config class name to infer the config name using the following rules: + - 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. @@ -103,11 +105,11 @@ end ``` #### Customize env variable names prefix -By default, Anyway Config uses upcased config name as a prefix for env variable names (e.g. +By default, Anyway Config uses upper-cased config name as a prefix for env variable names (e.g. `config_name :my_app` will result to parsing `MY_APP_` prefix). You can set env prefix explicitly: ```ruby @@ -141,11 +143,11 @@ ```ruby # load data from config/my_app.yml, secrets.my_app (if using Rails), ENV["MY_APP_*"] # MY_APP_VALUE=42 config = Anyway::Config.for(:my_app) -config.value #=> 42 +config["value"] #=> 42 # you can specify the config file path or env prefix config = Anyway::Config.for(:my_app, config_path: "my_config.yml", env_prefix: "MYAPP") ``` @@ -183,10 +185,12 @@ ```yml my_cool_gem: host: secret.host ``` +**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_*']`. #### `app/configs` You can store application-level config classes in `app/configs` folder. @@ -200,12 +204,12 @@ ```ruby # This data is provided by Heroku Dyno Metadadata add-on. class HerokuConfig < Anyway::Config attr_config :app_id, :app_name, - :dyno_id, :release_version, - :slug_commit + :dyno_id, :release_version, + :slug_commit def hostname "#{app_name}.herokuapp.com" end end @@ -217,11 +221,11 @@ config.action_mailer.default_url_options = {host: HerokuConfig.new.hostname} ``` ### Using with Ruby -When you're using Anyway Config in non-Rails environment, we're looking for a YANL config file +When you're using Anyway Config in non-Rails environment, we're looking for a YAML config file at `./config/<config-name>.yml`. You can override this setting through special environment variable – 'MYCOOLGEM_CONF' – containing the path to the YAML file. **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: @@ -236,19 +240,20 @@ ### Local files It's useful to have 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 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"`). -**NOTE:** in Rails apps you can use `Rails.applicaiton.configuration.anyway_config.use_local_files`. +**NOTE:** in Rails apps you can use `Rails.application.configuration.anyway_config.use_local_files`. 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). @@ -310,31 +315,32 @@ Rails 4.2 introduced new feature: `Rails.application.config_for`. It looks very similar to `Anyway::Config.for`, but there are some differences: | 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 | +| ------------- |-------------:| -----:| +| 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 | <sub><sup>*</sup>make sure that ERB is loaded</sub> But the main advantage of Anyway::Config is that it can be used [without Rails](#using-with-ruby)!) ## How to set env vars -Environmental variables for your config should start with your config name, uppercased. +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 serialized: + - `"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. @@ -392,10 +398,10 @@ You can add it manually by requiring `"anyway/testing/helpers"` and including the `Anyway::Test::Helpers` module (into RSpec configuration or Minitest test class). ## Contributing -Bug reports and pull requests are welcome on GitHub at https://github.com/palkan/anyway_config. +Bug reports and pull requests are welcome on GitHub at [https://github.com/palkan/anyway_config](https://github.com/palkan/anyway_config). ## License The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).