Skip to content
A more elegant approach to creating and accessing configuration values.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



  • Overview

  • Installation

  • Usage

  • Usage (within frameworks)

  • Locking

  • Bugs

  • Contributors


Configr aims to provide a clean interface for configuring and reading a set of configuration values. The idea evolved from using a standard hash as a configuration store into a more elegant way to declare and read values from within a hash.


The project is hosted on Getting it is simple:

gem install configr


There are a variety of ways in which you can use Configr:

  • Standalone block

  • From inline YAML

  • From a YAML file

  • A mixture of a YAML and block configuration

The following examples can also be found and run in examples/all.rb.

Standalone Block

configuration = Configr::Configuration.configure do |config|
  config.example_one = "One"
  config.example_two = "Two"

puts configuration.example_one
puts configuration.example_two

Conceptually you could continue to nest configuration blocks as far as you wish. They exist to enable you to separate your configuration values into contexts. Take for example a set of email configuration values:

Configr::Configuration.configure do |config|  = ""     = "My Company" = ""


From an inline YAML string

yaml = <<YAML

example_one: "Hello"
example_two: "It loads from YAML too!"


configuration = Configr::Configuration.configure(yaml)

puts configuration.example_one
puts configuration.example_two

From a YAML file

configuration = Configr::Configuration.configure("/path/to/file.yml")

puts configuration.value_one
puts configuration.value_two

A mixture of any of the above

yaml = <<YAML

example_three: "three"
example_four: "four"


configuration = Configr::Configuration.configure(yaml) do |config|
  config.example_one = "one"
  config.example_two = "two"

puts configuration.example_one
puts configuration.example_two
puts configuration.example_three
puts configuration.example_four

Asserting key presence

Sometimes when using configuration values you might want to assert whether the value exists before using it. Configr allows you to do this with the #key_name? syntax:

puts configuration.example_one? # => true
puts configuration.doesnt_exist? # => false

Usage (within frameworks)

Configr is intended to be framework agnostic, but it's easy to get it going inside of Rails/Sinatra.


You can use Configr within Rails quite easily. I don't plan to provide any “out of the box” way to hook Configr into Rails but it's easy to implement:

# In config/configuration.rb
yaml_file = Rails.root.join("config", "environments", "#{Rails.env}.yml")

Configuration = Configr::Configuration.configure(yaml_file) do |config| = "value"

# In config/initializers/configuration.rb
require Rails.root.join("config", "configuration.rb")

# Anywhere in your Rails app

By requiring a different YAML file based on the environment it is easy to override global values with environment specific values.


A quick and dirty solution would be to pop it in a configure block:

configure do
  Configuration = Configr::Configuration.configure("config/file.yml") do |config|
    config.something = "value"

Again, by requiring a different YAML file based on the environment it is easy to override global values with environment specific values.

A note about locking

By design a configuration value is not meant to be edited or created after the configuration block has been run (if you do you will run into a Configr::ConfigurationLocked error). In my opinion configurations such as those created by Configr are meant to be read-only during the lifetime of the application. Configr could however be altered to allow this with a simple patch should it be required.


If you have any problems with Configr, please file an issue at


  • Thomas Williams for the concept of nested configuration blocks.

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.


Copyright © 2010 Josh Nesbitt <>. See LICENSE for details.

Something went wrong with that request. Please try again.