Configru
YAML configuration file loader
Usage
Install the gem or add it to your Gemfile
:
gem 'configru', '~> 3.6.0'
Next, require it and load a configuration:
require 'configru'
config = Configru::Config.new('config.yml')
This example loads config.yml
if it exists. Or at least it would, if
we told Configru the configuration options we wanted to load.
Options
Configru provides a DSL for specifying the options that should be
loaded. The main method to specify configuration options is option
.
config = Configru::Config.new('config.yml') do
option :username, String, 'example_user', /^[A-Za-z1-9_]+$/
end
option
takes 4 arguments: the configuration key, the type of value,
the default value, and a validation check. The type defaults to
Object
, the default value defaults to nil
and the validation check
defaults to nothing. Note that a value of nil
will be treated as the
correct type regardless of the specified type.
The configuration option above can then be accessed in two ways:
config.username
config['username']
If the value in config.yml
is not a String
, a
Configru::OptionTypeError
will be raised. If the value does not pass
the validation check, a Configru::OptionValidationError
will be
raised.
Validation
Validations are checked against the value of the option using the ===
operator. This allows validations to be Procs, Regexps and Ranges. If
the validation is an Array, the value is checked using include?
.
option
can also be passed a block which can be used to set the
validation for the option. This allows a more convenient way to write
Proc validations.
config = Configru::Config.new('config.yml') do
option :username, String, 'example_user' do
validate {|o| o.length < 255 }
end
end
Transformation
Configru also allows options to be transformed (using a Proc) as they are loaded.
config = Configru::Config.new('config.yml') do
option :username, String, 'example' do
transform {|o| o + '_user' }
end
end
In the above example, if the username set in config.yml
is
"winnifred", it will be transformed using the Proc and config.username
will be "winnifred_user"
.
Required options
For configuration options that have no default and must be set in the
loaded configuration file, there is option_required
. It takes the same
arguments as option
, except for a default value.
config = Configru::Config.new('config.yml') do
option_required :username, String
end
If a required option is not set in the loaded file, a
Configru::OptionRequiredError
will be raised.
Array options
For options whose value should be a list, there is option_array
. It
takes the same arguments as option
, except the default value is
optional and defaults to an empty array. It behaves in the same way as
option
except each element of the array is checked against the type
and the validation, and each element is transformed using the
transformation Proc.
config = Configru::Config.new('config.yml') do
option_array :users, String, ['user1', 'user2']
end
Boolean options
Since Ruby's true
and false
do not share a class such as Boolean
,
Configru provides a convenience method for boolean options,
option_bool
. It takes only an option key and a default value as
arguments.
config = Configru::Config.new('config.yml') do
option_bool :debug, false
end
The above example is equivalent to the following:
config = Configru::Config.new('config.yml') do
option :debug, Object, false, [true, false]
end
(This works because Array validations are checked using include?
)
Option groups
Configru allows nesting options in groups.
config = Configru::Config.new('config.yml') do
option_group :user do
option_required :name, String
option_required :password, String
end
end
The format for the configuration file would be:
user:
name: example
password: example
The above options can then be accessed using either method described above:
config.user.name
config.user.password
config['user']['name']
config['user']['password']
Option groups can, of course, be nested in other option groups.
Loading multiple files
Multiple files can be passed to Configru::Config.new
and each will be
loaded sequentially, replacing any values from previous files with new
ones. This allows for loading a global configuration file and a user
configuration file that can override the global configuration.
config = Configru::Config.new('/etc/config.yml', File.expand_path('~/config.yml')) do
option :username, String, 'example_user'
end
Reloading
To reload configuration files, call the reload
method on the
Configru::Config
object. Note that the entire DSL block will be
re-evaluated.
config = Configru::Config.new('config.yml') do
option :username, String, 'example_user'
end
config.reload
Global loading
Since it can be tedious to pass around the config
object all over an
application in order to have access to the configuration, the Configru
module itself can be used as a Configru::Config
object with the load
method.
Configru.load('config.yml') do
option :username, String, 'example_user'
end
Option values can then be accessed on the Configru
module in the same
way as on a Configru::Config
object:
Configru.username
Configru['username']
The global configuration can also be reloaded in the same way:
Configru.reload
Access to the underlying Configru::Config
object of the global
configuration is provided:
Configru.config
License
Copyright © 2011-2013, Curtis McEnroe programble@gmail.com
Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.