⚙️ConfigX
ConfigX is a simple configuration library that you can use with your application or libraries.
ConfigX is NOT that kind of library that allows you configuring any Ruby object, instead it takes a different approach. It reads configuration from YAML files and environment variables and load it into a ruby object. It's highly influenced by the config gem, but it does not define a global objects and allows you having multiple independent configurations.
Installation
Install the gem and add to the application's Gemfile by executing:
$ bundle add configx
If bundler is not being used to manage dependencies, install the gem by executing:
$ gem install configx
Usage
Start using the library as simple as loading configuration from default locations:
config = ConfigX.load
It loads configuration from the following locations in the specified order:
config/settings.yml
config/settings/production.yml
config/settings.local.yml
config/settings/production.local.yml
- Environment variables
All the configuration source are merged an intuitive way. For instance,
- config/settings.yml
---
api:
enabled: false
endpoint: https://example.com
access_token:
- config/settings/production.yml
---
api:
enabled: true
- Environment Variables
export SETTINGS__API__ACCESS_TOKEN=
The resulting configuration will be:
config = ConfigX.load
config.api.enabled # => true
config.api.endpoint # => "https://example.com"
config.api.pretty_print # => "foobar"
Customizing Configuration
You can customize the configuration by passing optional arguments to the load
method:
ConfigX.load(
"development",
dir_name: 'settings',
file_name: 'settings',
config_root: 'config',
env_prefix: 'SETTINGS',
env_separator: '__'
)
The first four options, env
(positional), dir_name
, file_name
, and config_root
are used to specify
the configuration files to read:
{config_root}/{file_name}.yml
{config_root}/{file_name}/{env}.yml
{config_root}/{file_name}.local.yml
{config_root}/{file_name}/{env}.local.yml
The env_prefix
and env_separator
options are used to specify how the environment variables should be constructed. In
the above example, they start from SETTINGS
and use __
as a separator.
For instance, the following environment variable:
export SETTINGS__API__ACCESS_TOKEN=
corresponds to the following configuration:
---
api:
access_token: foobar
You can also pass boolean value to environment variables using convenient YAML syntax:
export SETTINGS__API__ENABLED=true
export SETTINGS__API__ENABLED=false
export SETTINGS__API__ENABLED=on
export SETTINGS__API__ENABLED=off
Environment variables have the highest priority and override the values from the configuration files.
Builder Interface
When you don't need to load configuration from the predefined default locations, you can use the builder interface which enables you to load configuration from any source:
- Plain ruby Hash
config = ConfigX.builder
.add_source({api: {enabled: true}})
.load
config.api.enabled # => true
- YAML file
config = ConfigX.builder
.add_source('config/settings.yml')
.load
- Environment variables
config = ConfigX.builder
.add_source(ENV, prefix: "SETTINGS", separator: "__")
.load
You can also use the builder interface to load configuration from multiple sources:
config = ConfigX.builder
.add_source({api: {enabled: true}})
.add_source('config/settings.yml')
.add_source(ENV, prefix: "SETTINGS", separator: "__")
.load
Sometimes you may want to just load configuration from a single source, for example, from for testing purposes:
config = ConfigX.from({api: {enabled: true}})
config.api.enabled # => true
Development
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.
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 the created tag, and push the .gem
file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/bolshakov/configx.
License
The gem is available as open source under the terms of the MIT License.