Anyway Config
Rails/Ruby plugin/application configuration tool which allows you to load parameters from different sources: YAML, Rails secrets, environment.
Allows you to easily follow the twelve-factor application principles and adds zero complexity to your development process.
Libraries using Anyway Config:
Installation
1) Adding to a gem:
# my-cool-gem.gemspec
Gem::Specification.new do |spec|
...
spec.add_dependency "anyway_config", "~> 1.0"
...
end
2) Adding to your project:
# Gemfile
gem "anyway_config", "~> 1.0"
3) Install globally:
$ gem install anyway_config
Usage
Pre-defined configuration
Create configuration class:
require 'anyway'
module MyCoolGem
class Config < Anyway::Config
attr_config user: 'root', password: 'root', host: 'localhost'
end
end
attr_config
creates accessors and default values. If you don't need default values just write:
attr_config :user, :password, host: 'localhost'
Then create an instance of the config class and use it:
module MyCoolGem
def self.config
@config ||= Config.new
end
end
MyCoolGem.config.user #=> 'root'
Customize name
By default, Anyway Config uses the namespace (the outer module name) as the config name, but you can set it manually:
module MyCoolGem
class Config < Anyway::Config
config_name :cool
attr_config user: 'root', password: 'root', host: 'localhost', options: {}
end
end
Customize env variable names prefix
By default, Anyway Config will use config name with stripped underscores as a prefix for env variable names (e.g.
config_name :my_app
will result to parsing MYAPP_HOST
variable, not MY_APP_HOST
). You can set env prefix
explicitly, and it will be used as is:
module MyCoolGem
class Config < Anyway::Config
config_name :cool_gem
env_prefix :really_cool # now variables, starting wih `REALLY_COOL_`, will be parsed
attr_config user: 'root', password: 'root', host: 'localhost', options: {}
end
end
DEPRECATION WARNING In the 1.4 version no stripping will be applied on config_names by default, so if you use explicit config names with
underscores and use env variables, your app will be broken. In this case it is recommended to start using env_prefix
now.
Provide explicit values
Sometimes it's useful to set some parameters explicitly during config initialization.
You can do that using overrides
option:
config = MyCoolGem::Config.new(
overrides: {
user: 'john',
password: 'rubyisnotdead'
}
)
# The value would not be overriden from other sources (such as YML file, env)
config.user == 'john'
Dynamic configuration
You can also create configuration objects without pre-defined schema (just like Rails.application.config_for
but more powerful):
# load data from config/my_app.yml, secrets.my_app (if using Rails), ENV["MYAPP_*"]
config = Anyway::Config.for(:my_app)
Using with Rails
Your config will be filled up with values from the following sources (ordered by priority from low to high):
RAILS_ROOT/config/my_cool_gem.yml
(for the currentRAILS_ENV
, supportsERB
)Rails.application.secrets.my_cool_gem
ENV['MYCOOLGEM_*']
.
Using with Ruby
By default, Anyway Config is looking for a config YAML at ./config/<config-name>.yml
. You can override this setting
through special environment variable – 'MYGEM_CONF' – containing the path to the YAML file.
Environmental variables work the same way as with Rails.
Config clear and reload
There are #clear
and #reload
functions on your config (which do exactly what they state).
Note: #reload
also accepts overrides
key to provide explicit values (see above).
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:
Feature | Rails | Anyway Config |
---|---|---|
load data from config/app.yml |
yes | yes |
load data from secrets |
no | yes |
load data from environment | 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 |
*make sure that ERB is loaded
But the main advantage of Anyway::Config is that it can be used without Rails!)
How to set env vars
Environmental variables for your config should start with your config name, uppercased and underscore-free.
For example, if your module is called "MyCoolGem" then the env var "MYCOOLGEM_PASSWORD" is used as config.password
.
Environment variables are type-casted (case-insensitive).
Examples:
"True"
,"t"
and"yes"
totrue
;"False"
,"f"
and"no"
tofalse
;"nil"
and"null"
tonil
(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.
For example, "MYCOOLGEM_OPTIONS__VERBOSE" is parsed as config.options["verbose"]
.
Array values are also supported:
# 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:
MYCOOLGEM="Nif-Nif, Naf-Naf and Nouf-Nouf"
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request