This gem is used to simplify specifying and reading configuration.

You can define what you expect to be configured, and this can be read from ini files, yaml files or environment variables.

Add this line to your application's Gemfile:

gem 'confuse'

And then execute:

$ bundle

Or install it yourself as:

$ gem install configuration

config = Confuse.config do |conf|
  conf.add_item :foo
end

config[:foo]

or

config.foo

You can choose where and your config is stored by passing a :path variable to Confuse.config:

config = Confuse.config :path => 'config.ini' do |conf|
  conf.add_item :foo
end

Confuse will attempt to work out the type of file from the extension (Supports .ini for ini files, and .yml or .yaml for yaml files). You can override this by passing in a :type option:

config = Confuse.config :path => 'foo.conf' :type => :yaml do |conf|
  conf.add_item :foo
end

If no type or path is given, it will default to environment variables. Environment variables have an an extra option, which is the ability to provide a prefix:

config = Confuse.config :prefix => 'FOO' do |conf|
  conf.add_item :foo
end

This means Confuse will lookup environment varialbles with that prefix with an underscore followed by the configuration name. If none is given, it will lookup environment variables as is.

You can give a config item a default value, which will be used in cases where none is set in the source.

config = Confuse.config do |conf|
  conf.add_item :foo, :default => 1
end

This can also be a proc that takes the config as an argument. This allows you to set a value based on what another item is set to.

config = Confuse.config do |conf|
  conf.add_item :foo, :default => 'foo'
  conf.add_item :bar, :default => proc { |c| "#{c.foo}_bar" }
end

You can separate your configuration into different namespaces:

config = Confuse.config :type => :env do |conf|
  conf.add_namespace :foo do |ns|
    ns.add_item :foo
  end
end

For simplicity, you can fetch these items using a single []:

config[:foo_bar]

Or a method call:

config.foo_bar

However, beware of adding an item at the top level with the same name.

You can specify the type of a configuration item.

config = Confuse.config do |conf|
  conf.add_item :foo, :type => Fixnum
end

This will ensure that any value is converted to the correct class when asked for, or an error raised if it is the wrong type and it can't be converted.

If a default is given, the type will be derived from the class of the default, unless the default is a Proc.

The following types are supported:

• String
• Fixnum
• Float
• Array
• :bool (a special case, because TrueClass and FalseClass do not share a unique common ancestor.)

Arrays can be used in sources that don't support arrays by supplying a comma separated list.

If you wish to add support for another type, or even custom types. You can register your own types if you wish:

Confuse::Converter.register <type> do |item|
  ...
end

The type can be anything, but it can only be derived from the default if a class is used.

If you want to make sure all your configuration items are in place before running the program you can call .check on it.

config = Confuse.config do |conf|
  conf.add_item :foo
end

config.check

If any of the items haven't been set, and don't have a default value, or if an item is the incorrect type, an exception will be thrown. If you don't care about certain variables, you can pass :required => false to them (or give them a default value).

If you want to use a source that isn't an ini file or yaml file, or environment variable. It is very easy to create your own one. It simply needs to be a class that has an initialize that takes a hash, and a [] method that takes a namespace and a key argument.

class MyOwnSource
  def initialize(options = {})
    ...
  end

  def [](namespace, key)
    ...
  end
end

Confuse::Source.register(:foo, MyOwnSource)

definition = Confuse.config, :type => :foo do |conf|
  conf.add_item :foo
end

config = Confuse::Config.new(definition, my_own_source)

If your class takes a :path variable, it will autodetect the extension for whatever you register. You can register more than one extension if you wish.

You could use this to store data in whatever fancy file format you like, or perhaps even a database table, or one of those fancy NoSQL datastores, you could even write your config in Ruby code.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request