clean_config
A simple configuration library for Ruby projects.
Installation
Add this line to your application's Gemfile:
gem 'clean_config'
And then execute:
$ bundle install
Or install it yourself as:
$ gem install 'clean_config'
Usage
By convention, configuration lives in a single file: config/config.yml
.
You can put any data you want in this file and access that data in one of three ways:
# config/config.yml
:foo:
:bar: 'baz'
require 'clean_config'
class MyClass
include CleanConfig::Configurable
def initialize()
config = CleanConfig::Configuration.instance
config[:foo][:bar] # 'baz'
config.foo. # 'baz'
config.parse_key('foo.bar') # 'baz'
end
end
Conventions
Loading configuration data in Ruby is easy. In fact, it is so easy that if you look at several different Ruby projects, you'll likely find several different implementations for loading configuration. We decided to standardize how we would load our configuration across all our gems.
This library requires your configuration be stored in a single yml file, located at
config/config.yml
Loading Configuration
Including the Configurable
module is what initializes the Configuration
object with the data from config/config.yml
.
Simply include this module and your configuration will be available via CleanConfig::Configuration.instance
.
If you are using the CleanConfig outside of a module or class, there are a few methods available to you to point CleanConfig to your configuration directory.
add!
allows you to change the directory/file name for your configuration files.
load!
looks for the default directory/file name (config/config.yml
) but at the same level as the calling code.
merge!
allows you to pass in a hash of additional configuration to add to your CleanConfig.
Accessing Configuration
After include CleanConfig::Configurable
you can access your config with: CleanConfig::Configuration.instance
.
This will have all of your project's configuration and any configuration defined in dependencies.
To get access to the underlying Hash
methods prefix them with to_hash
or to_h
, e.g. config.to_h.values
.
Note: We have added a #keys
method also.
As a result, if you have a field called :keys:
in your config file the only way to access it is config.to_h[:keys]
Layering Configuration
If you depend on gems that are using clean_config, you can override their key-value pairs in your own config/config.yml
.
Also, it's a good idea to nest your configuration under some top-level, project-specific key to prevent accidental
configuration collisions.
Contributing
Contacts
- Adrian Cazacu
- CivJ
- Crystal Hsiung
Process
- 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 new Pull Request