Configr¶ ↑

• Overview

• Installation

• Usage

• Usage (within frameworks)

• Locking

• Bugs

• Contributors

Overview¶ ↑

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.

Installation¶ ↑

The project is hosted on rubygems.org. Getting it is simple:

gem install configr

Usage¶ ↑

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"
end

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|
  config.email.from_address  = "[email protected]"
  config.email.from_name     = "My Company"
  config.email.reply_address = "[email protected]"
end

puts configuration.email.from_address
puts configuration.email.from_name
puts configuration.email.reply_address

From an inline YAML string¶ ↑

yaml = <<YAML

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

YAML

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"

YAML

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

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.

Rails¶ ↑

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|
  config.my.configuration.value = "value"
end

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

# Anywhere in your Rails app
Configuration.my.configuration.value

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

Sinatra¶ ↑

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"
  end
end

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 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.

Bugs¶ ↑

If you have any problems with Configr, please file an issue at github.com/joshnesbitt/configr/issues.

Contributors¶ ↑

• 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¶ ↑

Copyright © 2010 Josh Nesbitt <[email protected]>. See LICENSE for details.