⚙️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=foobar

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=foobar

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.